Add event callbacks to wifi.sta.config() and wifi.ap.config() and more (

nodemcu#1903) * Add event callbacks to wifi.sta.config() and wifi.ap.config() and more Added option to register event callbacks during configuration of both station and AP. Added option to register event callbacks to `wifi.sta.connect()` and `wifi.sta.disconnect()` * Add note about event registration to wifi module documentation Other minor changes to wifi documentation are also included * Add more detail to documentation for wifi.sta.config()
eiselekd · Jan 7, 2018 · 8fc57a5 · 8fc57a5
1 parent 1d01608
commit 8fc57a5
Show file tree

Hide file tree

Showing 4 changed files with 224 additions and 7 deletions.
diff --git a/app/modules/wifi.c b/app/modules/wifi.c
@@ -833,6 +833,102 @@ static int wifi_station_config( lua_State* L )
     }
     lua_pop(L, 1);
 
+#ifdef WIFI_SDK_EVENT_MONITOR_ENABLE
+
+    lua_State* L_temp = NULL;
+
+    lua_getfield(L, 1, "connect_cb");
+    if (!lua_isnil(L, -1))
+    {
+      if (lua_isfunction(L, -1))
+      {
+          L_temp = lua_newthread(L);
+          lua_pushnumber(L, EVENT_STAMODE_CONNECTED);
+          lua_pushvalue(L, -3);
+          lua_xmove(L, L_temp, 2);
+          wifi_event_monitor_register(L_temp);
+      }
+      else
+      {
+        return luaL_argerror(L, 1, "connect_cb:not function");
+      }
+    }
+    lua_pop(L, 1);
+
+    lua_getfield(L, 1, "disconnect_cb");
+    if (!lua_isnil(L, -1))
+    {
+      if (lua_isfunction(L, -1))
+      {
+          L_temp = lua_newthread(L);
+          lua_pushnumber(L, EVENT_STAMODE_DISCONNECTED);
+          lua_pushvalue(L, -3);
+          lua_xmove(L, L_temp, 2);
+          wifi_event_monitor_register(L_temp);
+      }
+      else
+      {
+        return luaL_argerror(L, 1, "disconnect_cb:not function");
+      }
+    }
+    lua_pop(L, 1);
+
+    lua_getfield(L, 1, "authmode_change_cb");
+    if (!lua_isnil(L, -1))
+    {
+      if (lua_isfunction(L, -1))
+      {
+          L_temp = lua_newthread(L);
+          lua_pushnumber(L, EVENT_STAMODE_AUTHMODE_CHANGE);
+          lua_pushvalue(L, -3);
+          lua_xmove(L, L_temp, 2);
+          wifi_event_monitor_register(L_temp);
+      }
+      else
+      {
+        return luaL_argerror(L, 1, "authmode_change_cb:not function");
+      }
+    }
+    lua_pop(L, 1);
+
+    lua_getfield(L, 1, "got_ip_cb");
+    if (!lua_isnil(L, -1))
+    {
+      if (lua_isfunction(L, -1))
+      {
+          L_temp = lua_newthread(L);
+          lua_pushnumber(L, EVENT_STAMODE_GOT_IP);
+          lua_pushvalue(L, -3);
+          lua_xmove(L, L_temp, 2);
+          wifi_event_monitor_register(L_temp);
+      }
+      else
+      {
+        return luaL_argerror(L, 1, "gotip_cb:not function");
+      }
+    }
+    lua_pop(L, 1);
+
+    lua_getfield(L, 1, "dhcp_timeout_cb");
+    if (!lua_isnil(L, -1))
+    {
+      if (lua_isfunction(L, -1))
+      {
+          L_temp = lua_newthread(L);
+          lua_pushnumber(L, EVENT_STAMODE_DHCP_TIMEOUT);
+          lua_pushvalue(L, -3);
+          lua_xmove(L, L_temp, 2);
+          wifi_event_monitor_register(L_temp);
+      }
+      else
+      {
+        return luaL_argerror(L, 1, "dhcp_timeout_cb:not function");
+      }
+    }
+    lua_pop(L, 1);
+
+#endif
+
   }
   else //to be deprecated
   {
@@ -930,13 +1026,27 @@ static int wifi_station_config( lua_State* L )
 // Lua: wifi.sta.connect()
 static int wifi_station_connect4lua( lua_State* L )
 {
+#ifdef WIFI_SDK_EVENT_MONITOR_ENABLE
+  if(lua_isfunction(L, 1)){
+    lua_pushnumber(L, EVENT_STAMODE_CONNECTED);
+    lua_pushvalue(L, 1);
+    wifi_event_monitor_register(L);
+  }
+#endif
   wifi_station_connect();
   return 0;  
 }
 
 // Lua: wifi.sta.disconnect()
 static int wifi_station_disconnect4lua( lua_State* L )
 {
+#ifdef WIFI_SDK_EVENT_MONITOR_ENABLE
+  if(lua_isfunction(L, 1)){
+    lua_pushnumber(L, EVENT_STAMODE_DISCONNECTED);
+    lua_pushvalue(L, 1);
+    wifi_event_monitor_register(L);
+  }
+#endif
   wifi_station_disconnect();
   return 0;  
 }
@@ -1509,6 +1619,65 @@ static int wifi_ap_config( lua_State* L )
   }
   lua_pop(L, 1);
 
+#ifdef WIFI_SDK_EVENT_MONITOR_ENABLE
+
+    lua_State* L_temp = NULL;
+
+    lua_getfield(L, 1, "staconnected_cb");
+    if (!lua_isnil(L, -1))
+    {
+      if (lua_isfunction(L, -1))
+      {
+          L_temp = lua_newthread(L);
+          lua_pushnumber(L, EVENT_SOFTAPMODE_STACONNECTED);
+          lua_pushvalue(L, -3);
+          lua_xmove(L, L_temp, 2);
+          wifi_event_monitor_register(L_temp);
+      }
+      else
+      {
+        return luaL_argerror(L, 1, "staconnected_cb:not function");
+      }
+    }
+    lua_pop(L, 1);
+
+    lua_getfield(L, 1, "stadisconnected_cb");
+    if (!lua_isnil(L, -1))
+    {
+      if (lua_isfunction(L, -1))
+      {
+          L_temp = lua_newthread(L);
+          lua_pushnumber(L, EVENT_SOFTAPMODE_STADISCONNECTED);
+          lua_pushvalue(L, -3);
+          lua_xmove(L, L_temp, 2);
+          wifi_event_monitor_register(L_temp);
+      }
+      else
+      {
+        return luaL_argerror(L, 1, "stadisconnected_cb:not function");
+      }
+    }
+    lua_pop(L, 1);
+
+    lua_getfield(L, 1, "probereq_cb");
+    if (!lua_isnil(L, -1))
+    {
+      if (lua_isfunction(L, -1))
+      {
+          L_temp = lua_newthread(L);
+          lua_pushnumber(L, EVENT_SOFTAPMODE_PROBEREQRECVED);
+          lua_pushvalue(L, -3);
+          lua_xmove(L, L_temp, 2);
+          wifi_event_monitor_register(L_temp);
+      }
+      else
+      {
+        return luaL_argerror(L, 1, "probereq_cb:not function");
+      }
+    }
+    lua_pop(L, 1);
+
+#endif
 
 #if defined(WIFI_DEBUG)
   char debug_temp[sizeof(config.password)+1];

diff --git a/app/modules/wifi_common.h b/app/modules/wifi_common.h
@@ -64,6 +64,7 @@ enum wifi_suspension_state
 #ifdef WIFI_SDK_EVENT_MONITOR_ENABLE
   extern const LUA_REG_TYPE wifi_event_monitor_map[];
   void wifi_eventmon_init();
+  int wifi_event_monitor_register(lua_State* L);
 #endif
 
 #endif /* APP_MODULES_WIFI_COMMON_H_ */
diff --git a/app/modules/wifi_eventmon.c b/app/modules/wifi_eventmon.c
@@ -32,7 +32,7 @@ static evt_queue_t *wifi_event_queue_tail; //pointer to end of queue
 static int wifi_event_cb_ref[EVENT_MAX+1] = { [0 ... EVENT_MAX] = LUA_NOREF}; //holds references to registered Lua callbacks
 
 // wifi.eventmon.register()
-static int wifi_event_monitor_register(lua_State* L)
+int wifi_event_monitor_register(lua_State* L)
 {
   uint8 id = (uint8)luaL_checknumber(L, 1);
   if ( id > EVENT_MAX ) //Check if user is trying to register a callback for a valid event.

diff --git a/docs/en/modules/wifi.md b/docs/en/modules/wifi.md
@@ -389,6 +389,9 @@ none
 
 Sets the WiFi station configuration.
 
+!!! note
+	It is not advised to assume that the WiFi is connected at any time during initialization start-up. WiFi connection status should be validated either by using a WiFi event callback or by polling the status on a timer.
+
 #### Syntax
 `wifi.sta.config(station_config)`
 
@@ -408,7 +411,30 @@ Sets the WiFi station configuration.
 			- "DE AD BE EF 7A C0"
 	- `save` Save station configuration to flash. 
 		- `true` configuration **will** be retained through power cycle. 
-		- `false` configuration **will not** be retained through power cycle. (Default)
+		- `false` configuration **will not** be retained through power cycle. (Default).
+	- Event callbacks will only be available if `WIFI_SDK_EVENT_MONITOR_ENABLE` is uncommented in `user_config.h`
+		- Please note: To ensure all station events are handled at boot time, all relevant callbacks must be registered as early as possible in `init.lua` with either `wifi.sta.config()` or `wifi.eventmon.register()`.     
+		- `connected_cb`: Callback to execute when station is connected to an access point. (Optional)
+			- Items returned in table :
+				- `SSID`: SSID of access point.  (format: string)
+				- `BSSID`: BSSID of access point.  (format: string)
+				- `channel`: The channel the access point is on.  (format: number)
+		- `disconnected_cb`: Callback to execute when station is disconnected from an access point. (Optional)
+			- Items returned in table :
+				- `SSID`: SSID of access point.   (format: string)
+				- `BSSID`: BSSID of access point. (format: string) 
+				- `REASON`: See [wifi.eventmon.reason](#wifieventmonreason) below. (format: number)  
+		- `authmode_change_cb`: Callback to execute when the access point has changed authorization mode. (Optional)    
+			- Items returned in table :
+			- `old_auth_mode`: Old wifi authorization mode. (format: number)  
+			- `new_auth_mode`: New wifi authorization mode. (format: number)
+		- `got_ip_cb`: Callback to execute when the station received an IP address from the access point. (Optional)
+			- Items returned in table :
+				- `IP`: The IP address assigned to the station.  (format: string)
+				- `netmask`: Subnet mask.  (format: string)
+				- `gateway`: The IP address of the access point the station is connected to. (format: string)  
+		- `dhcp_timeout_cb`: Station DHCP request has timed out. (Optional)
+			- Blank table is returned.  
 
 #### Returns
 - `true`  Success
@@ -457,10 +483,14 @@ wifi.sta.config(station_cfg)
 Connects to the configured AP in station mode. You only ever need to call this if auto-connect was disabled in [`wifi.sta.config()`](#wifistaconfig).
 
 #### Syntax
-`wifi.sta.connect()`
+`wifi.sta.connect([connected_cb])`
 
 #### Parameters
-none
+- `connected_cb`: Callback to execute when station is connected to an access point. (Optional)
+	- Items returned in table :
+		- `SSID`: SSID of access point.  (format: string)
+		- `BSSID`: BSSID of access point.  (format: string)
+		- `channel`: The channel the access point is on.  (format: number)
 
 #### Returns
 `nil`
@@ -477,10 +507,14 @@ Disconnects from AP in station mode.
 	Please note that disconnecting from Access Point does not reduce power consumption. If power saving is your goal, please refer to the description for `wifi.NULLMODE` in the function [`wifi.setmode()`](#wifisetmode) for more details.
 
 #### Syntax
-`wifi.sta.disconnect()`
+`wifi.sta.disconnect([disconnected_cb])`
 
 #### Parameters
-none
+- `disconnected_cb`: Callback to execute when station is disconnected from an access point. (Optional)
+	- Items returned in table :
+		- `SSID`: SSID of access point.   (format: string)
+		- `BSSID`: BSSID of access point. (format: string) 
+		- `REASON`: See [wifi.eventmon.reason](#wifieventmonreason) below. (format: number)  
 
 #### Returns
 `nil`
@@ -1011,7 +1045,20 @@ Sets SSID and password in AP mode. Be sure to make the password at least 8 chara
 	- `save` save configuration to flash.
 		- `true` configuration **will** be retained through power cycle. (Default)
 		- `false` configuration **will not** be retained through power cycle.
-
+	- Event callbacks will only be available if `WIFI_SDK_EVENT_MONITOR_ENABLE` is uncommented in `user_config.h`
+		- Please note: To ensure all SoftAP events are handled at boot time, all relevant callbacks must be registered as early as possible in `init.lua` with either `wifi.ap.config()` or `wifi.eventmon.register()`.     
+ 		- `staconnected_cb`: Callback executed when a new client has connected to the access point. (Optional)
+			- Items returned in table :
+				- `MAC`: MAC address of client that has connected.  
+				- `AID`: SDK provides no details concerning this return value.  
+		- `stadisconnected_cb`: Callback executed when a client has disconnected from the access point. (Optional)  
+			- Items returned in table :
+				- `MAC`: MAC address of client that has disconnected.  
+				- `AID`: SDK provides no details concerning this return value.  
+		- `probereq_cb`: Callback executed when a probe request was received. (Optional)
+			- Items returned in table :
+				- `MAC`: MAC address of the client that is probing the access point.  
+				- `RSSI`: Received Signal Strength Indicator of client.  
 
 #### Returns
 - `true`  Success