From f5fac7a19e5285ccfa4a48e5b5b48fbefa2230b4 Mon Sep 17 00:00:00 2001
From: dnc40085 <dnc40085@users.noreply.github.com>
Date: Mon, 24 Apr 2017 00:59:30 -0700
Subject: [PATCH] Updated documentation and example for wps.start() (#1933)

---
 docs/en/modules/wps.md | 109 +++++++++++++++++++++++++++++++++++------
 1 file changed, 93 insertions(+), 16 deletions(-)

diff --git a/docs/en/modules/wps.md b/docs/en/modules/wps.md
index 72089ace..8aca670a 100644
--- a/docs/en/modules/wps.md
+++ b/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)
-  if status == wps.SUCCESS then
-    print("SUCCESS!")
-  elseif status == wps.FAILED then
-    print("Failed")
-  elseif status == wps.TIMEOUT then
-    print("Timeout")
-  elseif status == wps.WEP then
-    print("WEP not supported")
-  elseif status == wps.SCAN_ERR then
-    print("WPS AP not found")
-  else
-    print(status)
+  --Basic example
+  wifi.setmode(wifi.STATION)
+  wps.enable()
+  wps.start(function(status)
+    if status == wps.SUCCESS then
+      wps.disable()
+      print("WPS: Success, connecting to AP...")
+      wifi.sta.connect()
+      return
+    elseif status == wps.FAILED then
+      print("WPS: Failed")
+    elseif status == wps.TIMEOUT then
+      print("WPS: Timeout")
+    elseif status == wps.WEP then
+      print("WPS: WEP not supported")
+    elseif status == wps.SCAN_ERR then
+      print("WPS: AP not found")
+    else
+      print(status)
+    end
+    wps.disable()
+  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
-  wps.disable()
-end)
+  
 ```