Redesign ESP8266WiFiMulti.[cpp|h]

[Erriez]

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

The API is identical.

[Erriez]

Regression test 1:

#include <ESP8266WiFiMulti.h>

ESP8266WiFiMulti wifiMulti;

void setup() 
{
    Serial.begin(115200);
  
    WiFi.mode(WIFI_STA);

    // Set incorrect WiFi password of best RSSI WiFi (close to the ESP8266)
    wifiMulti.addAP("MySSID1", "wrong_password");
    // Set correct WiFi password second WiFi (further away weaker signal)
    wifiMulti.addAP("MySSID2", "correct_password");
  
    Serial.println("Connecting Wifi...");
    if (wifiMulti.run() == WL_CONNECTED) {
        Serial.println("");
        Serial.println("WiFi connected");
        Serial.println("IP address: ");
        Serial.println(WiFi.localIP());
    }
}

void loop() 
{
    if (wifiMulti.run() != WL_CONNECTED) {
        Serial.println("WiFi not connected!");
        delay(1000);
    }
}

Before fix:
This results always in connecting to the first WiFi network in an endless loop without connecting to other registered WiFi networks.

After fix:
It tries to connect to the best registered RSSI WiFi. When a connection failed protected with a timeout (for example password is incorrect), it connects to the next WiFi.

Regression test 2:

A scan completed may not be returned from WiFi.scanComplete() (Return value >= 0) and requires a timeout handling as mentioned in doc/esp8266wifi/scan-examples.rst.

Before fix:
This results in an endless loop when WiFi.scanComplete() always returns a negative value in run().

After fix:
run() returns WL_NO_SSID_AVAIL after a WiFi scan timeout of 5000ms.

Regression test 3:

Connect to a WiFi network with the example. After a successful connection, press the reset button.

Before fix:
A complete new scan is executed which is power and time consuming.

After fix:
Connection is restored within a 100ms. A new scan is executed only when the first connect failed or no previous saved WiFi connection.

[devyte]

Overall good work, but requires some smoothing.

[Erriez]

@devyte I've resolved most of your requests and squashed it. The build passed and looks like ready to merge.

[devyte]

Minor change, then I'm good.

[Erriez]

@devyte Completed and build passed.

After 24 hours burn-in with random connects/disconnects to several WiFi access points everything works stable, including knolleary/pubsubclient MQTT connects / disconnects.

I noticed that the default 5000ms WiFi connect timeout may be too short when the distance between ESP8266 is far away from the AP, or the AP is busy. So I've included the variable connectTimeoutMs for function run() to the example with a short note.

Do you want me to include documentation in doc/esp8266wifi/readme.rst (https://arduino-esp8266.readthedocs.io/en/latest/esp8266wifi/readme.html#class-description)?

[devyte]

Do you want me to include documentation in doc/esp8266wifi/readme.rst

Yes please, (real) doc additions/updates are welcome!

[Erriez]

Yes please, (real) doc additions/updates are welcome!

Ok, I see multiple items to be fixed in the documentation. I'll create a new pull request for it in a few days. Stay tuned and thanks for your review.

[devyte]

In that case, I'm merging this as-is.

[devyte]

@Erriez You did good work here. There are additional things pending for Multi, would you be interested in taking it further?

[Erriez]

@Erriez You did good work here. There are additional things pending for Multi, would you be interested in taking it further?

Thanks! Well, I've 100% code understand now. Can you point me to some issues to look at?

[devyte]

Great! Let's discuss in our gitter channel, so that we don't go offtopic here. Just @ devyte in there and I'll see it.