Add more description for WiFi modem sleep in document and example.

Author: TimXia

docs/en/api-guides/wifi.rst

@@ -1201,11 +1201,11 @@ By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and t
 
 ESP32 Wi-Fi Power-saving Mode
 -----------------------------------
-Currently, ESP32 Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and doze state periodically. In doze state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode.
+Currently, ESP32 Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode.
 
-Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP. In maximum power save mode, station wakes up every listen interval to receive beacon. Broadcast data may be lost because station may be in doze state at DTIM time. If listen interval is longer, more power is saved but broadcast data is more easy to lose. Listen interval can be configured by calling API esp_wifi_set_config() before connecting to AP.
+Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP. In maximum power save mode, station wakes up every listen interval to receive beacon. Broadcast data may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power is saved but broadcast data is more easy to lose. Listen interval can be configured by calling API :cpp:func:`esp_wifi_set_config` before connecting to AP.
 
-Call esp_wifi_set_ps(WIFI_PS_MIN_MODEM) to enable Modem-sleep minimum power save mode or esp_wifi_set_ps(WIFI_PS_MAX_MODEM) to enable Modem-sleep maximum power save mode after calling esp_wifi_init(). When station connects to AP, Modem-sleep will start. When station disconnects from AP, Modem-sleep will stop.
+Call ``esp_wifi_set_ps(WIFI_PS_MIN_MODEM)`` to enable Modem-sleep minimum power save mode or ``esp_wifi_set_ps(WIFI_PS_MAX_MODEM)`` to enable Modem-sleep maximum power save mode after calling :cpp:func:`esp_wifi_init`. When station connects to AP, Modem-sleep will start. When station disconnects from AP, Modem-sleep will stop.
 
 ESP32 Wi-Fi Connect Crypto
 -----------------------------------

examples/wifi/power_save/README.md

@@ -2,10 +2,12 @@
 
 This example shows how to use power save mode of wifi.
 
-Power save mode only works in sta mode.
+Power save mode only works in station mode. If the modem sleep mode is enabled, station will switch between active and sleep state periodically after connecting to AP successfully. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem sleep mode.
 
 * No power save: This is default mode. And the esp32 will work with full power.
 
-* modem sleep: If you set power save mode as modem sleep, 10s later after connecting to AP, esp32 will wake up and sleep(turn off RF and PHY) periodically.
+* Minimum modem sleep: In minimum modem sleep mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP.
+
+* Maximum modem sleep: In maximum modem sleep mode, station wakes up every listen interval to receive beacon. Broadcast data may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power is saved but broadcast data is more easy to lose. 
 
 * others: not supported yet.

examples/wifi/power_save/main/Kconfig.projbuild

@@ -16,13 +16,21 @@ config WIFI_LISTEN_INTERVAL
     int "WiFi listen interval"
     default 3
     help
-	WiFi listen interval for station to receive beacon from AP.
+	Interval for station to listen to beacon from AP. The unit of listen interval is one beacon interval. 
+	For example, if beacon interval is 100 ms and listen interval is 3, the interval for station to listen 
+	to beacon is 300 ms.
 
 choice POWER_SAVE_MODE
     prompt "power save mode"
     default POWER_SAVE_MIN_MODEM
     help
-	Power save mode for the esp32 to use.
+	Power save mode for the esp32 to use. Modem sleep mode includes minimum and maximum power save modes. 
+	In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be 
+	lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short 
+	for DTIM is determined by AP. 
+	In maximum power save mode, station wakes up every listen interval to receive beacon. Broadcast data 
+	may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power 
+	is saved but broadcast data is more easy to lose. 
 
 config POWER_SAVE_NONE
     bool "none"