WIFI_RESUME improve speed and example (#7877)

Improve resume speed by passing in last known BSSID
Provide a simpler example for WIFI_SHUTDOWN/WIFI_RESUME
Add documentation for WIFI_SHUTDOWN and WIFI_RESUME.

doc/esp8266wifi/generic-class.rst

@@ -32,7 +32,7 @@ For the SoftAP interface, when the interface is brought up, any servers should b
 
 A detailed explanation of ``WiFiEventHandler`` can be found in the section with `examples :arrow\_right: <generic-examples.rst>`__ dedicated specifically to the Generic Class..
 
-Alternatively, check the example sketch `WiFiEvents.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiEvents/WiFiEvents.ino>`__ available inside examples folder of the ESP8266WiFi library.
+Alternatively, check the example sketch `WiFiEvents.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiEvents/WiFiEvents.ino>`__ available in the examples folder of the ESP8266WiFi library.
 
 
 persistent
@@ -42,30 +42,56 @@ persistent
 
     WiFi.persistent(persistent)
 
-ESP8266 is able to reconnect to the last used Wi-Fi network or establishes the same Access Point upon power up or reset.
+ESP8266 is able to reconnect to the last used WiFi network or establishes the same Access Point upon power up or reset.
 By default, these settings are written to specific sectors of flash memory every time they are changed in ``WiFi.begin(ssid, passphrase)`` or ``WiFi.softAP(ssid, passphrase, channel)``, and when ``WiFi.disconnect`` or ``WiFi.softAPdisconnect`` is invoked.
 Frequently calling these functions could cause wear on the flash memory (see issue `#1054 <https://github.com/esp8266/Arduino/issues/1054>`__).
 
-Once ``WiFi.persistent(false)`` is called, ``WiFi.begin``, ``WiFi.disconnect``, ``WiFi.softAP``, or ``WiFi.softAPdisconnect`` only changes the current in-memory Wi-Fi settings, and does not affect the Wi-Fi settings stored in flash memory.
+Once ``WiFi.persistent(false)`` is called, ``WiFi.begin``, ``WiFi.disconnect``, ``WiFi.softAP``, or ``WiFi.softAPdisconnect`` only changes the current in-memory WiFi settings, and does not affect the WiFi settings stored in flash memory.
 
 mode
 ~~~~
 
+Regular WiFi modes
+__________________
+
 .. code:: cpp
 
-    WiFi.mode(m)
+    bool mode(WiFiMode_t m)
+
+Switches to one of the regular WiFi modes, where ``m`` is one of:
+
+-  ``WIFI_OFF``: turn WiFi off.
+-  ``WIFI_STA``: switch to `Station (STA) <readme.rst#station>`__ mode.
+-  ``WIFI_AP``: switch to `Access Point (AP) <readme.rst#soft-access-point>`__ mode.
+-  ``WIFI_AP_STA``: enable both Station (STA) and Access Point (AP) mode.
+
+Pseudo-modes
+____________
+
+.. code:: cpp
+
+    bool mode(WiFiMode_t m, WiFiState* state)
+
+Used with the following pseudo-modes, where ``m`` is one of:
+
+-  ``WIFI_SHUTDOWN``: Fills in the provided ``WiFiState`` structure, switches to ``WIFI_OFF`` mode and puts WiFi into forced sleep, preserving energy.
+-  ``WIFI_RESUME``: Turns WiFi on and tries to re-establish the WiFi connection stored in the ``WiFiState`` structure.
+
+These modes are used in low-power scenarios, e.g. where ESP.deepSleep is used between actions to preserve battery power.
+
+It is the user's responsibility to preserve the WiFiState between ``WIFI_SHUTDOWN`` and ``WIFI_RESUME``, e.g. by storing it
+in RTC user data and/or flash memory.
 
--  ``WiFi.mode(m)``: set mode to ``WIFI_AP``, ``WIFI_STA``,
-   ``WIFI_AP_STA`` or ``WIFI_OFF``
+There is an example sketch `WiFiShutdown.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino>`__ available in the examples folder of the ESP8266WiFi library.
 
 getMode
 ~~~~~~~
 
 .. code:: cpp
 
-    WiFiMode_t WiFi.getMode()
+    WiFiMode_t getMode()
 
--  ``WiFi.getMode()``: return current Wi-Fi mode (one out of four modes above)
+Gets the current WiFi mode (one out of four regular modes above).
 
 WiFi power management, DTIM
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/libraries.rst

@@ -1,8 +1,8 @@
 Libraries
 =========
 
-WiFi(ESP8266WiFi library)
--------------------------
+WiFi (ESP8266WiFi library)
+--------------------------
 
 ESP8266WiFi library has been developed basing on ESP8266 SDK, using naming convention and overall functionality philosophy of the `Arduino WiFi Shield library <https://www.arduino.cc/en/Reference/WiFi>`__. Over time the wealth Wi-Fi features ported from ESP8266 SDK to this library outgrew the APIs of WiFi Shield library and it became apparent that we need to provide separate documentation on what is new and extra.
 

libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino

@@ -0,0 +1,85 @@
+
+// Demonstrate the use of WiFi.mode(WIFI_SHUTDOWN)/WiFi.mode(WIFI_RESUME)
+// Released to public domain
+
+// Current on WEMOS D1 mini (including: LDO, usbserial chip):
+// ~85mA during normal operations
+// ~30mA during wifi shutdown
+//  ~5mA during deepsleep
+
+#ifndef STASSID
+#define STASSID "mynetwork"
+#define STAPSK "mynetworkpasswd"
+#endif
+
+#ifndef RTC_USER_DATA_SLOT_WIFI_STATE
+#define RTC_USER_DATA_SLOT_WIFI_STATE 33u
+#endif
+
+#include <ESP8266WiFi.h>
+#include <include/WiFiState.h> // WiFiState structure details
+
+WiFiState state;
+
+const char* ssid = STASSID;
+const char* password = STAPSK;
+
+void preinit(void) {
+  // Make sure, wifi stays off after boot.
+  ESP8266WiFiClass::preinitWiFiOff();
+}
+
+void setup() {
+  Serial.begin(74880);
+  //Serial.setDebugOutput(true);  // If you need debug output
+  Serial.println("Trying to resume WiFi connection...");
+
+  // May be necessary after deepSleep. Otherwise you may get "error: pll_cal exceeds 2ms!!!" when trying to connect
+  delay(1);
+
+  // ---
+  // Here you can do whatever you need to do that doesn't need a WiFi connection.
+  // ---
+
+  ESP.rtcUserMemoryRead(RTC_USER_DATA_SLOT_WIFI_STATE, reinterpret_cast<uint32_t *>(&state), sizeof(state));
+  unsigned long start = millis();
+
+  if (!WiFi.mode(WIFI_RESUME, &state)
+      || (WiFi.waitForConnectResult(10000) != WL_CONNECTED)) {
+    Serial.println("Cannot resume WiFi connection, connecting via begin...");
+    WiFi.persistent(false);
+
+    if (!WiFi.mode(WIFI_STA)
+        || !WiFi.begin(ssid, password)
+        || (WiFi.waitForConnectResult(10000) != WL_CONNECTED)) {
+      WiFi.mode(WIFI_OFF);
+      Serial.println("Cannot connect!");
+      Serial.flush();
+      ESP.deepSleep(10e6, RF_DISABLED);
+      return;
+    }
+  }
+
+  unsigned long duration = millis() - start;
+  Serial.printf("Duration: %f", duration * 0.001);
+  Serial.println();
+
+  // ---
+  // Here you can do whatever you need to do that needs a WiFi connection.
+  // ---
+
+  WiFi.mode(WIFI_SHUTDOWN, &state);
+  ESP.rtcUserMemoryWrite(RTC_USER_DATA_SLOT_WIFI_STATE, reinterpret_cast<uint32_t *>(&state), sizeof(state));
+
+  // ---
+  // Here you can do whatever you need to do that doesn't need a WiFi connection anymore.
+  // ---
+
+  Serial.println("Done.");
+  Serial.flush();
+  ESP.deepSleep(10e6, RF_DISABLED);
+}
+
+void loop() {
+  // Nothing to do here.
+}

libraries/ESP8266WiFi/src/ESP8266WiFiGeneric.cpp

@@ -826,11 +826,10 @@ bool ESP8266WiFiGenericClass::resumeFromShutdown (WiFiState* state)
                 }
             }
         }
-        // state->state.fwconfig.bssid is not real bssid (it's what user may have provided when bssid_set==1)
         auto beginResult = WiFi.begin((const char*)state->state.fwconfig.ssid,
                        (const char*)state->state.fwconfig.password,
                        state->state.channel,
-                       nullptr/*(const uint8_t*)state->state.fwconfig.bssid*/,  // <- try with gw's mac address?
+                       state->state.fwconfig.bssid,
                        true);
         if (beginResult == WL_CONNECT_FAILED)
         {