Updated documentation and example for wps.start() (#1933)

docs/en/modules/wps.md

@@ -34,6 +34,9 @@ none
 ## wps.start()
 Start WiFi WPS function. WPS must be enabled prior calling this function.
 
+!!! note
+	This function only configures the station with the AP's info, it does not connect to AP automatically.
+
 #### Syntax
 `wps.start([function(status)])`
 
@@ -45,21 +48,95 @@ Start WiFi WPS function. WPS must be enabled prior calling this function.
 
 #### Example
 ```lua
-wps.enable()
-wps.start(function(status)
+  --Basic example
+  wifi.setmode(wifi.STATION)
+  wps.enable()
+  wps.start(function(status)
     if status == wps.SUCCESS then
-    print("SUCCESS!")
+      wps.disable()
+      print("WPS: Success, connecting to AP...")
+      wifi.sta.connect()
+      return
     elseif status == wps.FAILED then
-    print("Failed")
+      print("WPS: Failed")
     elseif status == wps.TIMEOUT then
-    print("Timeout")
+      print("WPS: Timeout")
     elseif status == wps.WEP then
-    print("WEP not supported")
+      print("WPS: WEP not supported")
     elseif status == wps.SCAN_ERR then
-    print("WPS AP not found")
+      print("WPS: AP not found")
     else
       print(status)
     end
     wps.disable()
-end)
+  end)
+  
+  --Full example
+  do
+    -- Register wifi station event callbacks
+    wifi.eventmon.register(wifi.eventmon.STA_CONNECTED, function(T)
+      print("\n\tSTA - CONNECTED".."\n\tSSID: "..T.SSID.."\n\tBSSID: "..
+      T.BSSID.."\n\tChannel: "..T.channel)
+    end)
+    wifi.eventmon.register(wifi.eventmon.STA_GOT_IP, function(T)
+      print("\n\tSTA - GOT IP".."\n\tStation IP: "..T.IP.."\n\tSubnet mask: "..
+      T.netmask.."\n\tGateway IP: "..T.gateway)
+    end)
+
+    wifi.setmode(wifi.STATION)
+  
+    wps_retry_func = function() 
+      if wps_retry_count == nil then wps_retry_count = 0 end
+      if wps_retry_count < 3 then 
+        wps.disable()
+        wps.enable()
+        wps_retry_count = wps_retry_count + 1
+        wps_retry_timer = tmr.create()
+        wps_retry_timer:alarm(3000, tmr.ALARM_SINGLE, function() wps.start(wps_cb) end)
+        print("retry #"..wps_retry_count)
+      else
+        wps_retry_count = nil
+        wps_retry_timer = nil
+        wps_retry_func = nil
+        wps_cb = nil
+      end
+    end
+  
+    wps_cb = function(status)
+      if status == wps.SUCCESS then
+        wps.disable()
+        print("WPS: success, connecting to AP...")
+        wifi.sta.connect()
+        wps_retry_count = nil
+        wps_retry_timer = nil
+        wps_retry_func = nil
+        wps_cb = nil
+        return
+      elseif status == wps.FAILED then
+        print("WPS: Failed")
+        wps_retry_func()
+        return
+      elseif status == wps.TIMEOUT then
+        print("WPS: Timeout")
+        wps_retry_func()
+        return
+      elseif status == wps.WEP then
+        print("WPS: WEP not supported")
+      elseif status == wps.SCAN_ERR then
+        print("WPS: AP not found")
+        wps_retry_func()
+        return
+      else
+        print(status)
+      end
+      wps.disable()
+      wps_retry_count = nil
+      wps_retry_timer = nil
+      wps_retry_func = nil
+      wps_cb = nil
+    end
+    wps.enable()
+    wps.start(wps_cb)
+  end
+  
 ```