From 8c50428d8f244f21fa6a35302ffb67be9826e93a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20P=C3=B6ttgen?= Date: Sun, 14 Feb 2021 17:50:15 +0100 Subject: [PATCH 1/6] Improve resume speed by passing in last known BSSID --- libraries/ESP8266WiFi/src/ESP8266WiFiGeneric.cpp | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/libraries/ESP8266WiFi/src/ESP8266WiFiGeneric.cpp b/libraries/ESP8266WiFi/src/ESP8266WiFiGeneric.cpp index fb23b35e85..e583cb2318 100644 --- a/libraries/ESP8266WiFi/src/ESP8266WiFiGeneric.cpp +++ b/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) { From 334e5fd3168ce110d83d86dcccbfea28c39e391b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20P=C3=B6ttgen?= Date: Sun, 14 Feb 2021 17:51:21 +0100 Subject: [PATCH 2/6] Move WiFiShutdown example to ESP8266WiFi library --- .../examples/WiFiShutdown/WiFiShutdown.ino | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename libraries/{esp8266 => ESP8266WiFi}/examples/WiFiShutdown/WiFiShutdown.ino (100%) diff --git a/libraries/esp8266/examples/WiFiShutdown/WiFiShutdown.ino b/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino similarity index 100% rename from libraries/esp8266/examples/WiFiShutdown/WiFiShutdown.ino rename to libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino From 2a3fccb74edd1dfb8f11ccce564e08ac5ab2fc5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20P=C3=B6ttgen?= Date: Sun, 14 Feb 2021 17:53:05 +0100 Subject: [PATCH 3/6] Provide a simpler example for WIFI_SHUTDOWN/WIFI_RESUME --- .../examples/WiFiShutdown/WiFiShutdown.ino | 291 ++++-------------- 1 file changed, 61 insertions(+), 230 deletions(-) diff --git a/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino b/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino index 1c0624fd60..063a307d0f 100644 --- a/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino +++ b/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino @@ -1,8 +1,8 @@ -// demonstrate the use of WiFi.mode(SHUTDOWN/RESUME) -// released to public domain +// 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): +// Current on WEMOS D1 mini (including: LDO, usbserial chip): // ~85mA during normal operations // ~30mA during wifi shutdown // ~5mA during deepsleep @@ -12,247 +12,78 @@ #define STAPSK "mynetworkpasswd" #endif -#define WAIT_NTP 0 // define this to 1 for NTP check too +#ifndef RTC_USER_DATA_SLOT_WIFI_STATE +#define RTC_USER_DATA_SLOT_WIFI_STATE 33u +#endif #include -#include // crc32() #include // WiFiState structure details -enum state_e { - e_initial, - e_start_resume, - e_start_normal, - e_off_restart, - e_wait_connected, - e_wait_ntp, - e_shutdown, - e_wait_shutdown, - e_wait_off -}; - -static state_e step = e_initial; // step -static int wifi_timeout = 0; // wifi timeout counter -static bool time_is_set = false; // WAIT_NTP=1: wait for network - dhcp packet must have ntp server - -// non volatile data -struct nv_s { - WiFiState wss; // core's wifi save state +WiFiState state; - uint32_t crc; - struct { - int rstcounter[7]; - } data; -}; -static nv_s* nv = (nv_s*)RTC_USER_MEM; // user non volatile area - -#define SEP "###### " -#define EV "!!!!!! " -#define NFO "------ " - -void resetUserCrc() { - nv->crc = crc32(&nv->data, sizeof(nv->data)); -} +const char* ssid = STASSID; +const char* password = STAPSK; -void printNv() { - Serial.printf(NFO "nfo1/2 wifi-nv-state: valid=%d, " - "persistent=%d, " - "mode=%d, " - "channel=%d, " - "ip=%s, " - "dns=%s, " - "ntp=%s\n", - WiFi.shutdownValidCRC(&nv->wss), - nv->wss.state.persistent, - nv->wss.state.mode, - nv->wss.state.channel, - IPAddress(&nv->wss.state.ip.ip).toString().c_str(), - IPAddress(&nv->wss.state.dns[0]).toString().c_str(), - IPAddress(&nv->wss.state.ntp[0]).toString().c_str()); - - Serial.printf(NFO "nfo2/2 rst reason counters: default:%d wdt:%d exception:%d softwdt:%d reset:%d deepsleep:%d extsys:%d\n", - nv->data.rstcounter[0], - nv->data.rstcounter[1], - nv->data.rstcounter[2], - nv->data.rstcounter[3], - nv->data.rstcounter[4], - nv->data.rstcounter[5], - nv->data.rstcounter[6]); -} - -void timeset_cb() { - time_is_set = true; - - static bool first = true; - if (first) { - first = false; - } -} - -decltype(millis()) startup; - - -WiFiEventHandler evOff = WiFi.onWiFiModeChange([](const WiFiEventModeChange& event) { - Serial.printf(EV "mode changed event: ev:%d->%d getMode=%d\n", event.oldMode, event.newMode, wifi_get_opmode()); -}); - -void preinit() { +void preinit(void) +{ + // Make sure, wifi stays off after boot. ESP8266WiFiClass::preinitWiFiOff(); } void setup() { - WiFi.persistent(false); - startup = millis(); - Serial.begin(115200); - settimeofday_cb(timeset_cb); - - // prepare non volatile user structure - if (crc32(&nv->data, sizeof(nv->data)) != nv->crc) { - memset(&nv->data, 0, sizeof(nv->data)); - Serial.printf(SEP "reset NV user data\n"); - } - // update reset reason - nv->data.rstcounter[system_get_rst_info()->reason]++; - // recalculate crc - resetUserCrc(); - // nfo - printNv(); - - Serial.println("setup()"); -} - -#define TEST(x...) ({ auto v = x; Serial.printf(SEP "'%s': result = %d\n", #x, v); v; }) - -void loop() { - - static int prev = 255; - if (step != prev) { - prev = step; - Serial.printf(NFO "step %d - wifi getMode=%d=%d heap=%d freeheap=%d\n", - prev, - WiFi.getMode(), - wifi_get_opmode(), - ESP.getFreeHeap(), - ESP.getFreeHeap()); - printNv(); + 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(&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(); + delay(50); + ESP.deepSleep(10e6, RF_DISABLED); + return; + } } - switch (step) { - - case e_initial: { - if (WiFi.shutdownValidCRC(&nv->wss)) { - step = e_start_resume; - } else { - step = e_start_normal; - } - break; - } - - - case e_start_resume: - Serial.println(SEP "CRC valid => WIFI_RESUME"); - startup = millis(); - - if (!TEST(WiFi.mode(WIFI_RESUME, &nv->wss))) { - Serial.printf(SEP "issue resuming WiFi\n"); - step = e_off_restart; - } else { - Serial.printf(SEP "waiting for connected\\n"); - step = e_wait_connected; - } - break; - - - case e_start_normal: - Serial.printf(SEP "CRC NOT valid, begin/WIFI_STA (current mode = %d)\n", wifi_get_opmode()); - startup = millis(); - if (!TEST(WiFi.mode(WIFI_STA)) || !TEST(WiFi.begin(STASSID, STAPSK))) { - Serial.printf(SEP "issue setting up STA\n"); - step = e_off_restart; - } else { - Serial.printf(SEP "waiting for connected\n"); - step = e_wait_connected; - } - break; - - - case e_wait_connected: - if (WiFi.status() == WL_CONNECTED) { - Serial.printf(SEP "connected! ---- startup time: %ld ms ----\n\n\n", millis() - startup); - wifi_timeout = 0; - if (WAIT_NTP) { - step = e_wait_ntp; - Serial.printf(SEP "wait for NTP\n"); - } else { - step = e_shutdown; - } - } else if ((millis() - startup > 10000)) { - Serial.printf(SEP "connected TIMEOUT! status=%d\n", WiFi.status()); - wifi_timeout++; - step = e_off_restart; - } - break; + 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. + // --- - case e_off_restart: - Serial.printf(SEP "OFF -> wait 2s\n"); - (void)TEST(WiFi.mode(WIFI_OFF)); - delay(2000); // test - mad wifi loop until :oom if delay not there - to verify - step = e_initial; - break; + WiFi.mode(WIFI_SHUTDOWN, &state); + ESP.rtcUserMemoryWrite(RTC_USER_DATA_SLOT_WIFI_STATE, reinterpret_cast(&state), sizeof(state)); + // --- + // Here you can do whatever you need to do that doesn't need a WiFi connection anymore. + // --- - case e_wait_ntp: - // check when NTP has set time - if (time_is_set) { - Serial.printf(SEP "NTP is set\n"); - time_is_set = false; - step = e_shutdown; - } - break; - - - case e_shutdown: { - static int deepsleep = 0; - switch (++deepsleep) { - case 1: { - Serial.println(SEP "WIFI_OFF for 5s"); - TEST(WiFi.mode(WIFI_OFF)); - step = e_wait_off; - break; - } - case 2: // several loop on shutdown - case 3: // to check if it affects - case 4: { // reconnection duration - Serial.println(SEP "WIFI_SHUTDOWN for 5s"); - TEST(WiFi.mode(WIFI_SHUTDOWN, &nv->wss)); - step = e_wait_shutdown; - break; - } - default: { - Serial.println(SEP "DEEPSLEEP for 5s (bind GPIO16 <=> RST)"); - TEST(WiFi.mode(WIFI_SHUTDOWN, &nv->wss)); - Serial.flush(); - ESP.deepSleep(5000000); - // will reboot, GPIO16 must be connected to reset - } - } - - startup = millis(); - break; - } - - - case e_wait_shutdown: - if (millis() - startup > 5000) { - step = e_start_resume; - } - break; - - - case e_wait_off: - if (millis() - startup > 5000) { - step = e_start_normal; - } - break; - } + Serial.println("Done."); + Serial.flush(); + delay(50); + ESP.deepSleep(10e6, RF_DISABLED); } + +void loop() { + // Nothing to do here. +} \ No newline at end of file From 007b27f24cca5fa89af225357be0fce039b67c5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20P=C3=B6ttgen?= Date: Sun, 14 Feb 2021 18:20:21 +0100 Subject: [PATCH 4/6] Fix formatting and remove unnecessary delays. --- .../examples/WiFiShutdown/WiFiShutdown.ino | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino b/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino index 063a307d0f..d34e393b4b 100644 --- a/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino +++ b/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino @@ -24,8 +24,7 @@ WiFiState state; const char* ssid = STASSID; const char* password = STAPSK; -void preinit(void) -{ +void preinit(void) { // Make sure, wifi stays off after boot. ESP8266WiFiClass::preinitWiFiOff(); } @@ -46,18 +45,16 @@ void setup() { unsigned long start = millis(); if (!WiFi.mode(WIFI_RESUME, &state) - || (WiFi.waitForConnectResult(10000) != WL_CONNECTED)) - { + || (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.waitForConnectResult(10000) != WL_CONNECTED)) { WiFi.mode(WIFI_OFF); Serial.println("Cannot connect!"); Serial.flush(); - delay(50); ESP.deepSleep(10e6, RF_DISABLED); return; } @@ -80,7 +77,6 @@ void setup() { Serial.println("Done."); Serial.flush(); - delay(50); ESP.deepSleep(10e6, RF_DISABLED); } From 0fc60e5363c2504a2a80bf464de4f067dc74427c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20P=C3=B6ttgen?= Date: Sun, 14 Feb 2021 18:26:02 +0100 Subject: [PATCH 5/6] Sorry, more style fixes. --- .../ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino b/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino index d34e393b4b..34f26a8b50 100644 --- a/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino +++ b/libraries/ESP8266WiFi/examples/WiFiShutdown/WiFiShutdown.ino @@ -45,13 +45,13 @@ void setup() { unsigned long start = millis(); if (!WiFi.mode(WIFI_RESUME, &state) - || (WiFi.waitForConnectResult(10000) != WL_CONNECTED)) { + || (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.begin(ssid, password) + || (WiFi.waitForConnectResult(10000) != WL_CONNECTED)) { WiFi.mode(WIFI_OFF); Serial.println("Cannot connect!"); Serial.flush(); From ad82de11f8696ca2adc17f79d64bd3879033eced Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20P=C3=B6ttgen?= Date: Sun, 14 Feb 2021 21:32:21 +0100 Subject: [PATCH 6/6] Add documentation for WIFI_SHUTDOWN and WIFI_RESUME. --- doc/esp8266wifi/generic-class.rst | 42 +++++++++++++++++++++++++------ doc/libraries.rst | 4 +-- 2 files changed, 36 insertions(+), 10 deletions(-) diff --git a/doc/esp8266wifi/generic-class.rst b/doc/esp8266wifi/generic-class.rst index a26f925858..c75ae231f3 100644 --- a/doc/esp8266wifi/generic-class.rst +++ b/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: `__ dedicated specifically to the Generic Class.. -Alternatively, check the example sketch `WiFiEvents.ino `__ available inside examples folder of the ESP8266WiFi library. +Alternatively, check the example sketch `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 `__). -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) `__ mode. +- ``WIFI_AP``: switch to `Access Point (AP) `__ 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 `__ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/libraries.rst b/doc/libraries.rst index cf860231ec..bfdc05d950 100644 --- a/doc/libraries.rst +++ b/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 `__. 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.