add Low-Power demo

esp8266 · devyte · Feb 2, 2020 · Jan 6, 2020 · Jan 6, 2020 · Jan 9, 2020
commit 47b73a2ccda37541563f440190c1beb81c46b800
diff --git a/libraries/esp8266/examples/LowPowerDemo/README.md b/libraries/esp8266/examples/LowPowerDemo/README.md
@@ -22,9 +22,9 @@ The table below is an expanded version of Table 1.1 from the Low-Power Solutions
 
 Notes: 
 
-(1) setting a sleep time of 0 for Deep Sleep turns off the RTC, requiring an external RESET to wake it
+(1) setting a sleep time of 0 for Deep Sleep turns off or disconnects 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
+(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
 
 The Average Current with different DTIM settings is unverified, and will likely be higher in a real-world environment.  All of the currents listed in this README are for the ESP8266 chip only.  Modules that have voltage regulators, USB chips, LEDs or other hardware will draw additional current.
 
@@ -46,52 +46,52 @@ 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 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.
+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 during the tests 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 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.
+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 your program spends time in delay() frequently.  Any delay() time works as long as it happens frequently.  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 Automatic Modem Sleep is 15 mA minimum.  Without a 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 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.
+Like Automatic Modem Sleep, with similar 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.  With delay() times shorter than the DTIM beacon interval (100 mS for these tests) the modem only goes into Automatic Modem Sleep, and with a longer delay() it will go into Automatic Light 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.1 mS, but WiFi was turned off to enter Forced Light Sleep so you may need to re-initialize it.
+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 energy efficient.  The chip wakes after an interrupt in about 5.1 mS, but WiFi was turned off to enter Forced Light Sleep so you will need to re-initialize it if you are using WiFi.
 
 ### 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.  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.
+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 begins.  Deep Sleep ends with a RESET, and the boot time after that is ~ 120 mS.  Any Deep Sleep less than ~ 2 seconds is wasting energy due to the modem shut-off and boot times, 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 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.
+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 avoid 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 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.
+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 270 mS 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.
+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 modes 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 the RTC memory.  See the **RTCUserMemory** example for more information 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.
+The maximum Deep Sleep interval is 71.58 minutes (2^32 -1 microseconds), although the actual interval may be slightly less than that.
 
-If you need a longer sleep period than 72 minutes, you can pass zero as the time variable to Deep Sleep and it turns off the RTC.  The only way to wake it at that point is an external RESET; D0 can't do it.  Both Forced Light Sleep and Deep Sleep(0) are woken by an external signal, so short delays under 2 seconds are more efficient with Forced Light Sleep, and longer delays are more power efficient with Deep Sleep.
+If you need a longer sleep time than 72 minutes, you can pass zero as the time variable to Deep Sleep and it turns off the RTC.  The only way to wake it at that point is an external RESET; D0 can't do it.  Both Forced Light Sleep and Deep Sleep(0) are woken by an external signal, so short delays are more efficient with Forced Light Sleep, and longer delays are more energy efficient with Deep Sleep.
 
 
 ---
 
-### Lower Power without the WiFi library:
+### Lower Power without the WiFi library (Forced Modem Sleep):
 
 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
@@ -102,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 code you to shut down the modem *without* loading the WiFi library, dropping your average current by 50 mA, or ~ 1/5th of the initial power.  You have to add it as shown (preferably in **setup()** or **preinit()**), 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 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.
+You can also use the Deep Sleep modes without loading the WiFi library, as they use ESP API functions.  The Deep Sleep tests above bring the WiFi up to show you the differences after the 4 reset modes.  With the modem turned off (Forced Modem Sleep) you **always** get an instant Deep Sleep; doing WiFi.mode(WIFI_OFF) doesn't help, as the SDK still spends 270 mS of time shutting the modem down before going into Deep Sleep.