Redesign ESP8266WiFiMulti.[cpp|h]

Fixed critical issues WiFiMulti library:
- WiFi scan timeout implemented to prevent endless connect loop
- Fallback implemented on WiFi connect failure to prevent endless loop
- Fast WiFi connection at startup
- Improved debug prints
- Doxygen added
- Code maturing
- Example update

Make functions not related to ESP8266WiFiMulti class static
Revert static functions startScan and printWiFiScan()
Use PolledTimeout.h to protect while loops
Move static functions beginning of the file
Add connect timeout to example

Author: Erriez

libraries/ESP8266WiFi/examples/WiFiMulti/WiFiMulti.ino

@@ -1,33 +1,49 @@
 /*
-    This sketch trys to Connect to the best AP based on a given list
+    This sketch shows how to use multiple WiFi networks.
 
+    In this example, ESP8266 works in AP mode.
+    It demonstrates:
+    - Fast connect to previous WiFi network at startup
+    - Registering multiple networks (at least 1)
+    - Connect to WiFi with strongest signal (RSSI)
+    - Fall back to connect to next WiFi when a connection failed or lost
+
+    To enable debugging output, select in the Arduino iDE:
+    - Tools | Debug Port: Serial
+    - Tools | Debug Level: WiFi
 */
 
-#include <ESP8266WiFi.h>
 #include <ESP8266WiFiMulti.h>
 
 ESP8266WiFiMulti wifiMulti;
 
+// WiFi connect timeout per AP. Increase when connecting takes longer.
+const uint32_t connectTimeoutMs = 5000;
+
 void setup() {
   Serial.begin(115200);
+  Serial.println("\nESP8266 Multi WiFi example");
 
+  // Set WiFi to station mode
   WiFi.mode(WIFI_STA);
+
+  // Register multi WiFi networks
   wifiMulti.addAP("ssid_from_AP_1", "your_password_for_AP_1");
   wifiMulti.addAP("ssid_from_AP_2", "your_password_for_AP_2");
   wifiMulti.addAP("ssid_from_AP_3", "your_password_for_AP_3");
-
-  Serial.println("Connecting Wifi...");
-  if (wifiMulti.run() == WL_CONNECTED) {
-    Serial.println("");
-    Serial.println("WiFi connected");
-    Serial.println("IP address: ");
-    Serial.println(WiFi.localIP());
-  }
+  // More is possible
 }
 
 void loop() {
-  if (wifiMulti.run() != WL_CONNECTED) {
+  // Maintain WiFi connection
+  if (wifiMulti.run(connectTimeoutMs) == WL_CONNECTED) {
+    Serial.print("WiFi connected: ");
+    Serial.print(WiFi.SSID());
+    Serial.print(" ");
+    Serial.println(WiFi.localIP());
+  } else {
     Serial.println("WiFi not connected!");
-    delay(1000);
   }
+
+  delay(1000);
 }