add Low-Power demo

esp8266 · devyte · Feb 2, 2020 · Jan 6, 2020 · Jan 6, 2020 · Jan 9, 2020
commit 2f2c5086f2e03349c0b555e9df62a7accba2c66c
diff --git a/libraries/esp8266/examples/LowPowerDemo/LowPowerDemo.ino b/libraries/esp8266/examples/LowPowerDemo/LowPowerDemo.ino
@@ -139,7 +139,7 @@ void loop() {
     // 3rd test - Forced Modem Sleep
     Serial.println(F("\n3rd test - Forced Modem Sleep"));
     WiFi.forceSleepBegin();
-    delay(10);  // it doesn't always go to sleep unless you delay(10)
+    delay(10);  // it doesn't always go to sleep unless you delay(10), yield() may also work
     volts = ESP.getVcc();
     Serial.printf("The internal VCC reads %1.3f volts\n", volts / 1000);
     Serial.println(F("press the button to continue"));
@@ -173,13 +173,13 @@ void loop() {
     volts = ESP.getVcc();
     Serial.printf("The internal VCC reads %1.3f volts\n", volts / 1000);
     Serial.println(F("CPU going to sleep, pull WAKE_UP_PIN low to wake it (press the button)"));
-    delay(100);  // needs a brief delay after the print or it may print the whole message
+    delay(100);  // needs a delay() after the print or it may not print the whole message
     wifi_fpm_set_sleep_type(LIGHT_SLEEP_T);
     gpio_pin_wakeup_enable(GPIO_ID_PIN(WAKE_UP_PIN), GPIO_PIN_INTR_LOLEVEL);
     // only LOLEVEL or HILEVEL interrupts work, no edge, that's an SDK or CPU limitation
     wifi_fpm_set_wakeup_cb(wakeupCallback); // Set wakeup callback (optional)
     wifi_fpm_open();
-    wifi_fpm_do_sleep(0xFFFFFFF);  // only 0xFFFFFFF allowed; any other value and it won't sleep
+    wifi_fpm_do_sleep(0xFFFFFFF);  // only 0xFFFFFFF works; any other value and it won't sleep
     delay(10);  // it goes to sleep some time during this delay() and waits for an interrupt
     Serial.println(F("Woke up!"));  // the interrupt callback hits before this is executed
 
@@ -210,7 +210,7 @@ void loop() {
 
   // 7th test - Deep Sleep for 10 seconds, wake with RFCAL
   if (resetCount < 4) {
-    init_WiFi();  // need to reinitialize WiFi due to Deep Sleep resets
+    init_WiFi();  // need to reinitialize WiFi due to Deep Sleep reset
   }
   if (resetCount == 1) {  // second reset loop since power on
     resetCount = 2;  // advance to the next Deep Sleep test after the reset
@@ -278,12 +278,12 @@ void waitPushbutton(bool usesDelay, unsigned int delayTime) {  // loop until the
       if (blinkLED) {
         digitalWrite(LED, !digitalRead(LED));  // toggle the activity LED
       }
-      yield();
+      yield();  // this would be a good spot for ArduinoOTA.handle();
     }
   } else {  // long delay() for the 2 AUTOMATIC modes, but it misses quick button presses
     while (digitalRead(WAKE_UP_PIN)) {  // wait for a button press
       digitalWrite(LED, !digitalRead(LED));  // toggle the activity LED
-      delay(delayTime);
+      delay(delayTime);  // another good spot for ArduinoOTA.handle();
     }
   }
   delay(50);  // debounce time for the switch, button pressed
@@ -294,7 +294,7 @@ void waitPushbutton(bool usesDelay, unsigned int delayTime) {  // loop until the
 }
 
 void updateRTC() {
-  rtcData.data[3] = resetCount;  // save the loop count for the next reset
+  rtcData.data[3] = resetCount;  // save the reset count for the next test run
   // Update CRC32 of data
   rtcData.crc32 = crc32((uint8_t*) &rtcData.data[0], sizeof(rtcData.data));
   if (resetCount == 5) {  // wipe the CRC in RTC memory when we're done with all tests

diff --git a/libraries/esp8266/examples/LowPowerDemo/README.md b/libraries/esp8266/examples/LowPowerDemo/README.md
@@ -21,6 +21,7 @@ The table below is an expanded version of Table 1.1 from the Low-Power Solutions
 | Avg Current DTIM = 10 |        15.2 mA        |                    |       (0.55 mA)       |                    |                    |
 
 Notes: 
+
 (1) setting a sleep time of 0 for Deep Sleep turns off the RTC, requiring an external RESET to wake it
 
 (2) due to a bug in SDK 2, the minimum current will never be less than 2 mA and is frequently 15 mA between DTIM beacons
@@ -45,43 +46,43 @@ The Average Current with different DTIM settings is unverified, and will likely
 
 ### Test 1 - Unconfigured modem
 
-This is typical for programs that don't use WiFi, and is a high current drain of at least 67 mA continuous.
+This is typical for programs that don't use WiFi, and is a high current drain of at least 67 mA continuous.  This isn't a test as much as it sets a baseline or reference point for comparing the power savings.  You can stop any time the CPU is halted or the LED is blinking to measure the current.
 
 ### Test 2 - Automatic Modem Sleep
 
-This is the default power saving mode when you have an active WiFi connection.  You don't need to add anything to your code to get it.  The only time the modem sleeps is when you spend a long time in delay(), with delay times over 50mS.  The LED blinks more slowly during this test as it's doing delay(350) to get the modem to sleep.  While in delay() your sketch isn't doing anything worthwhile.  Average current during long delay()s is 15 mA minimum.  Without the delay() the average current is 67 mA with short spikes above 250 mA as transmissions occur.  When the WiFi has traffic (even a couple of pings), the modem can turn on for over 2 seconds continuous at 67 mA, and it may stay on for a second after the traffic.  In a high traffic environment you won't get any power savings with either of the 2 Automatic modes.  Automatic Modem Sleep turns on 7-8 seconds after an active connection is established.
+This is the default power saving mode when you have an active WiFi connection.  You don't need to add anything to your code to get it.  The only time the modem sleeps is when you spend a long time in delay(), with delay times over 50mS.  The LED blinks more slowly during this test as it's doing delay(350) to get the modem to sleep.  While in delay() your sketch isn't doing anything worthwhile.  Average current during a long delay() is 15 mA minimum.  Without the delay() the average current is 67 mA with short spikes above 250 mA as transmissions occur.  When the WiFi has traffic (even a couple of pings), the modem can turn on for over 2 seconds continuous at 67 mA, and it may stay on for a second after the traffic.  In a high traffic environment you won't get any power savings with either of the 2 Automatic modes.  Automatic Modem Sleep turns on 7-8 seconds after an active connection is established.
 
 ### Test 3 - Forced Modem Sleep
 
-Turns off the modem (losing the connection), and dropping the current by 50 mA.  This uses the WiFi library function.  It's good if there is a long interval with no expected WiFi traffic, as you can do other things while only drawing 15 mA.
+Turns off the modem (losing the connection), and reducing the current by 50 mA.  This test uses the WiFi library function.  It's good if there is a long interval with no expected WiFi traffic, as you can do other things while only drawing 15 mA.
 
 ### Test 4 - Automatic Light Sleep
 
 Like Automatic Modem Sleep, with the same restrictions.  Once configured it's immediately active when a connection is established.  During periods of long delay() the average current can drop to ~2 mA.  In a network with sparse traffic you might get something near 2-5 mA average current.  The LED blinks more slowly during this test as it's doing delay(350) to get the modem to sleep.
 
 ### Test 5 - Forced Light Sleep
 
-Similar to Deep Sleep, but without the timer.  The chip sleeps at 0.4 mA current until it is woken by an external interrupt.  The only allowed interrupts are high level and low level; edge interrupts won't work.  If you have a design that needs to be woken frequently (more often than every 2 seconds) then you should consider using Forced Light Sleep.  For sleep periods longer than 2 seconds, Deep Sleep will be more efficient.  The chip wakes after an interrupt in about 5.1mS.
+Similar to Deep Sleep, but without the timer.  The chip sleeps at 0.4 mA current until it is woken by an external interrupt.  The only allowed interrupts are high level and low level; edge interrupts won't work.  If you have a design that needs to be woken frequently (more often than every 2 seconds) then you should consider using Forced Light Sleep.  For sleep periods longer than 2 seconds, Deep Sleep will be more efficient.  The chip wakes after an interrupt in about 5.1 mS, but WiFi was turned off to enter Forced Light Sleep so you may need to re-initialize it.
 
 ### Test 6 - Deep Sleep, wake with RF_DEFAULT
 
-In Deep Sleep almost everything is turned off, and the chip draws ~20 uA.  If you have D0/GPIO16 connected to RST, you can use the RTC timer to wake the chip up at a timed interval.  You can also wake it with an external RESET.  Waking with RF_DEFAULT means it will do an RFCAL if it needs to.  These first two Deep Sleep tests use the standard Deep Sleep function, so the WiFi connection is closed and the modem turned off, which takes about 270mS before Deep Sleep begins.  Deep Sleep ends with a RESET, and the boot time after that is around 120mS.  Any Deep Sleep less than ~2 seconds is wasting power due to the modem shut-off and boot time, and Forced Light Sleep will be a better choice as it recovers in 5.1mS from the previous state.
+In Deep Sleep almost everything is turned off, and the chip draws ~ 20 uA.  If you have D0/GPIO16 connected to RST, you can use the RTC timer to wake the chip up at a timed interval.  You can also wake it with an external RESET.  Waking with RF_DEFAULT means it will do an RFCAL if it needs to.  Doing ESP.deepSleep(time) without the mode variable uses this wake mode.  These first two Deep Sleep tests use the standard Deep Sleep function, so the WiFi connection is closed and the modem turned off, which takes about 270 mS before the Deep Sleep will begin.  Deep Sleep ends with a RESET, and the boot time after that is ~ 120 mS.  Any Deep Sleep less than ~ 2 seconds is wasting power due to the modem shut-off and boot time, and Forced Light Sleep will be a better choice as it recovers in 5.1 mS from the previous state.
 
 ### Test 7 - Deep Sleep, wake with RFCAL
 
-Identical to the test above, but the modem does a power calibration when booting.  In normal use, most people would do WAKE_RF_DEFAULT instead to minimize the extra RFCAL power burst if it's not needed.
+Identical to the test above, but the modem does an RF power calibration when booting.  In normal use, most people would do WAKE_RF_DEFAULT instead to minimize the extra RFCAL power burst if it's not needed.
 
 ### Test 8 - Deep Sleep Instant, wake with NO_RFCAL
 
-This variation doesn't do an automatic RF calibration, so power requirements will be slightly less.  Additionally, *most* of the time it immediately goes into Deep Sleep without turning off the modem (that's the INSTANT part).  There's another bug in SDK 2, and the SDK functions the WiFi-class calls occasionally do a modem shut-down before Deep Sleep; it's not always Instant.  When it doesn't do the modem shut-down it saves an extra 270mS of power.
+This variation doesn't do an automatic RF calibration on return, so power requirements will be slightly less.  Additionally, *most* of the time it immediately goes into Deep Sleep without turning off the modem (that's the INSTANT part).  There's another bug in SDK 2, and the SDK functions the WiFi-class calls occasionally do a modem shut-down before Deep Sleep; it's not always Instant.  When it doesn't do the modem shut-down it saves an extra 270mS of power.
 
 ### Test 9 - Deep Sleep Instant, wake with RF_DISABLED
 
 This last variation also uses Deep Sleep Instant, but it wakes up with the modem disabled so current after Deep Sleep is only 15 mA.  Each of the 4 WAKE styles has their own use, depending on what you need.
 
 ---
 
-All of the Deep Sleep modes end with a RESET, so you must re-initialize everything.  You can store *some* information in the RTC memory to survive a Deep Sleep reset, which was done in this demo to illustrate it.  See the **RTCUserMemory** example for more on this feature.  
+All of the Deep Sleep modes end with a RESET, so you must re-initialize everything.  You can store *some* information in the RTC memory to survive a Deep Sleep reset, which was done in this demo to illustrate the RTC memory.  See the **RTCUserMemory** example for more information on this feature.  
 
 The maximum Deep Sleep interval is 71.58 minutes (2^32 -1 microseconds), although the actual interval may be something less than that.
 
@@ -92,7 +93,7 @@ If you need a longer sleep period than 72 minutes, you can pass zero as the time
 
 ### Lower Power without the WiFi library:
 
-If all you want to do is reduce power for a sketch that doesn't need WiFi, add these SDK 2 functions to your code:
+If all you want to do is reduce power for a sketch that doesn't need WiFi, add these SDK 2 functions anywhere in your code:
 ```c
   wifi_station_disconnect();
   wifi_set_opmode(NULL_MODE);
@@ -101,7 +102,7 @@ If all you want to do is reduce power for a sketch that doesn't need WiFi, add t
   wifi_fpm_do_sleep(0xFFFFFFF);
   delay(1);
 ```
-That allows you to shut down the modem *without* loading the WiFi library, dropping your average current by 50 mA, or around 1/5th of the initial power.  You have to add it as shown preferably in setup(), although the delay() can be longer.  It doesn't time out at 71 minutes, as you might think from the (0xFFFFFFF).  The Forced Modem Sleep test does the same thing with a WiFi library call that essentially encapsulates the code above.
+That allows you to shut down the modem *without* loading the WiFi library, dropping your average current by 50 mA, or around 1/5th of the initial power.  You have to add it as shown (preferably in setup()), although the delay() can be longer.  It doesn't time out at 71 minutes, as you might think from the (0xFFFFFFF).  The Forced Modem Sleep test does the same thing with a WiFi library call that essentially encapsulates the code above.
 
-You can also use the Deep Sleep modes without loading the WiFi library, as they use ESP API functions.  The tests above try to bring the WiFi up to show you the differences after the 4 reset modes.
+You can also use the Deep Sleep modes without loading the WiFi library, as they use ESP API functions.  The Deep Sleep tests above try to bring the WiFi up to show you the differences after the 4 reset modes.  With the WiFi turned off you always get an instant Deep Sleep.