Prefer Lua booleans over 1/nil or 1/0

Document preference and also provide easy-to-use backwards compatible
interface.

components/lua/lua-5.1/lauxlib.h

@@ -179,6 +179,7 @@ LUALIB_API int  (luaL_posttask) ( lua_State* L, int prio );
 #define  LUA_TASK_LOW    0
 #define  LUA_TASK_MEDIUM 1
 #define  LUA_TASK_HIGH   2
+LUALIB_API int (luaL_totoggle) (lua_State *L, int idx);
 
 /* }====================================================== */
 

components/lua/lua-5.1/lnodemcu.c

@@ -257,3 +257,20 @@ LUA_API int lua_pushlfsindex (lua_State *L) {
   return p ? LUA_TFUNCTION : LUA_TNIL;
 }
 #endif
+
+
+/* luaL_totoggle provides lenient boolean interpretation for feature toggles
+ * true, 1 => true
+ * false, 0, nil => false
+ */
+LUALIB_API int luaL_totoggle(lua_State *L, int idx)
+{
+  if (lua_isboolean(L, idx))
+    return lua_toboolean(L, idx);
+  else if (lua_isnoneornil(L, idx))
+    return 0;
+  else if (lua_isnumber(L, idx))
+    return lua_tonumber(L, idx) != 0;
+  else
+    return luaL_error(L, "unexpected type");
+}

components/lua/lua-5.3/lauxlib.c

@@ -1177,3 +1177,20 @@ LUALIB_API int luaL_pcallx (lua_State *L, int narg, int nres) {
   return status;
 }
 #endif
+
+
+/* luaL_totoggle provides lenient boolean interpretation for feature toggles
+ * true, 1 => true
+ * false, 0, nil => false
+ */
+LUALIB_API bool luaL_totoggle(lua_State *L, int idx)
+{
+  if (lua_isboolean(L, idx))
+    return lua_toboolean(L, idx);
+  else if (lua_isnoneornil(L, idx))
+    return false;
+  else if (lua_isnumber(L, idx))
+    return lua_tonumber(L, idx) != 0;
+  else
+    return luaL_error(L, "unexpected type");
+}

components/lua/lua-5.3/lauxlib.h

@@ -295,6 +295,7 @@ LUALIB_API void (luaL_lfsreload) (lua_State *L);
 LUALIB_API int  (luaL_posttask) (lua_State* L, int prio);
 LUALIB_API int  (luaL_pcallx) (lua_State *L, int narg, int nres);
 #define luaL_pushlfsmodule(l) lua_pushlfsfunc(L)
+LUALIB_API bool (luaL_totoggle) (lua_State *L, int idx);
 
 /* }============================================================ */
 

components/modules/wifi_sta.c

@@ -344,15 +344,15 @@ static int wifi_sta_config (lua_State *L)
   lua_pop(L, 1);
 
   lua_getfield(L, 1, "rm");
-  cfg.sta.rm_enabled = lua_tointeger(L, -1);
+  cfg.sta.rm_enabled = luaL_totoggle(L, -1);
   lua_pop(L, 1);
 
   lua_getfield(L, 1, "btm");
-  cfg.sta.btm_enabled = lua_tointeger(L, -1);
+  cfg.sta.btm_enabled = luaL_totoggle(L, -1);
   lua_pop(L, 1);
 
   lua_getfield(L, 1, "mbo");
-  cfg.sta.mbo_enabled = lua_tointeger(L, -1);
+  cfg.sta.mbo_enabled = luaL_totoggle(L, -1);
   lua_pop(L, 1);
 
   lua_getfield(L, 1, "sae_pwe");
@@ -449,13 +449,13 @@ static int wifi_sta_getconfig (lua_State *L)
   lua_pushinteger(L, cfg.sta.threshold.authmode);
   lua_setfield(L, -2, "threshold_authmode");
 
-  lua_pushinteger(L, cfg.sta.rm_enabled);
+  lua_pushboolean(L, cfg.sta.rm_enabled);
   lua_setfield(L, -2, "rm");
 
-  lua_pushinteger(L, cfg.sta.btm_enabled);
+  lua_pushboolean(L, cfg.sta.btm_enabled);
   lua_setfield(L, -2, "btm");
 
-  lua_pushinteger(L, cfg.sta.mbo_enabled);
+  lua_pushboolean(L, cfg.sta.mbo_enabled);
   lua_setfield(L, -2, "mbo");
 
   lua_pushinteger(L, cfg.sta.sae_pwe_h2e);

docs/modules/wifi.md

@@ -161,9 +161,9 @@ being removed in the SDK/IDF. After start-up it is necessary to call
     - `sort_by` optional string value for preferential selection of AP. Must be one of `"rssi"` or `"authmode"` if present.
     - `threshold_rssi` optional integer value to limit APs to only those which have a signal stronger than this value.
     - `threshold_authmode` optional value to limit APs to those with an authentication mode of at least this settings. One of `wifi.AUTH_OPEN`, `wifi.AUTH_WEP`, `wifi.AUTH_WPA_PSK`, `wifi.AUTH_WPA2_PSK`, `wifi.AUTH_WPA_WPA2_PSK`, `wifi.AUTH_WPA2_ENTERPRISE`, `wifi.AUTH_WPA3_PSK`, `wifi.AUTH_WPA2_WPA3_PSK`, `wifi.AUTH_WAPI_PSK`.
-    - `rm` optional integer value, set to 1 to enable Radio Measurements
+    - `rm` optional boolean, set to `true` to enable Radio Measurements
-    - `btm` optional integer value, set to 1 to enable BSS Transition Management
+    - `btm` optional boolean, set to `true` to enable BSS Transition Management
-    - `mbo` optional integer value, set to 1 to enable Multi-Band Operation
+    - `mbo` optional boolean, set to `true` to enable Multi-Band Operation
     - `sae_pwe` optional, configures WPA3 SAE Password Element setting. One of `wifi.SAE_PWE_UNSPECIFIED`, `wifi.SAE_PWE_HUNT_AND_PECK`, `wifi.SAE_PWE_HASH_TO_ELEMENT` or `wifi.SAE_PWE_BOTH`.
 
 - `save` Save station configuration to flash. 

docs/nodemcu-lrm.md

@@ -231,6 +231,17 @@ Equivalent to `luaL_newmetatable()` for ROTable metatables.  Adds key / ROTable
 
 This macro executes `luaL_unref(L, t, r)` and then assigns `r = LUA_NOREF`.
 
+#### luaL_totoggle
+
+`  bool luaL_totoggle(lua_State *L, int idx)`
+
+There are several ways of indicating a configuration toggle value:
+  - The modern Lua way, with a boolean (`true`/`false`)
+  - The "classic" Lua way, with `1`/`nil`
+  - The "C" way, with `1`/`0`
+
+When implementing C modules for NodeMCU and needing to indicate an on/off setting, the preference is to do it as a boolean. In the interest of ease of use on the other hand, it is however nice to also support the other styles. The `luaL_totoggle` function provides just that.
+
 ### Declaring modules and ROTables in NodeMCU
 
 All NodeMCU C library modules should include the standard header "`module.h`".  This internally includes `lnodemcu.h` and these together provide the macros to enable declaration of NodeMCU modules and ROTables within them.  All ROtable support macros are either prefixed by `LRO_` (Lua Read Only) or in the case of table entries `LROT_`.