PowerManagement support

.github/workflows/push.yml

@@ -248,6 +248,8 @@ jobs:
           . ${IDF_PATH}/export.sh
           idf.py create-project test
           echo CONFIG_FREERTOS_HZ=1000 > test/sdkconfig.defaults
+          echo CONFIG_PM_ENABLE=y >> test/sdkconfig.defaults
+          echo CONFIG_FREERTOS_USE_TICKLESS_IDLE=y >> test/sdkconfig.defaults
           idf.py -C test -DEXTRA_COMPONENT_DIRS=$PWD/components build
 
   # Save artifacts to gh-pages

cores/esp32/esp32-hal-cpu.c

@@ -18,6 +18,7 @@
 #include "freertos/task.h"
 #include "esp_attr.h"
 #include "esp_log.h"
+#include "esp_pm.h"
 #include "soc/rtc.h"
 #if !defined(CONFIG_IDF_TARGET_ESP32C2) && !defined(CONFIG_IDF_TARGET_ESP32C6) && !defined(CONFIG_IDF_TARGET_ESP32H2)
 #include "soc/rtc_cntl_reg.h"
@@ -291,3 +292,16 @@ uint32_t getApbFrequency() {
   rtc_clk_cpu_freq_get_config(&conf);
   return calculateApb(&conf);
 }
+
+bool setAutomaticLightSleep(bool enabled)
+{
+    uint32_t cpuFreq = getCpuFrequencyMhz();
+
+    esp_pm_config_t pm_config = {
+        .max_freq_mhz = cpuFreq,
+        .min_freq_mhz = cpuFreq,
+        .light_sleep_enable = enabled,
+    };
+
+    return esp_pm_configure(&pm_config) == ESP_OK;
+}

cores/esp32/esp32-hal-cpu.h

@@ -44,6 +44,15 @@ uint32_t getCpuFrequencyMhz();   // In MHz
 uint32_t getXtalFrequencyMhz();  // In MHz
 uint32_t getApbFrequency();      // In Hz
 
+/**
+ * @brief Set automatic light sleep state. CPU will go into light sleep if no ongoing activity (active task, peripheral activity etc.)
+ * @param enabled true to enable automatic lightSleep
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
+ */
+bool setAutomaticLightSleep(bool enabled);
+
 #ifdef __cplusplus
 }
 #endif

libraries/ESP32/examples/PowerSave/CpuLightSleep/CpuLightSleep.ino

@@ -0,0 +1,45 @@
+/*
+Cpu automatic LightSleep
+=====================================
+This code displays how to use automatic light sleep
+and demonstrates a difference between busywait and
+sleep-aware wait using delay().
+Another examples of a 'sleep-friendly' blocking might be
+FreeRTOS mutexes/semaphores, queues.
+
+This code is under Public Domain License.
+
+Hardware Connections (optional)
+======================
+Use an ammeter/scope connected in series with a CPU/DevKit board to measure power consumption
+
+Author:
+Taras Shcherban <[email protected]>
+*/
+
+#include "Arduino.h"
+
+void setup()
+{
+    Serial.begin(115200);
+    while (!Serial)
+        ; // wait for serial port to connect
+
+    // CPU will automatically go into light sleep if no ongoing activity (active task, peripheral activity etc.)
+    setAutomaticLightSleep(true);
+}
+
+void loop()
+{
+    Serial.printf("Time since boot: %ld ms; going to block for a 5 seconds...\n", millis());
+
+    // Serial output is being suspended during sleeping, so without a Flush call logs
+    // will be printed to the terminal with a delay depending on how much CPU spends in a sleep state
+    Serial.flush();
+
+    // This is a sleep-aware waiting using delay(). Blocking in this manner
+    // allows CPU to go into light sleep mode until there is some task to do.
+    // if you remove that delay completely - CPU will have to call loop() function constantly,
+    // so no power saving will be available
+    delay(5000);
+}

libraries/ESP32/examples/PowerSave/GpioInterrupts/GpioInterrupts.ino

@@ -0,0 +1,85 @@
+/*
+Gpio Interrupts with sleep mode
+=====================================
+This code displays how to use automatic light sleep with a GPIO interrupts.
+
+With a light sleep mode the only available interrupts are ONLOW_WE and ONHIGH_WE.
+RISING/FALLING/CHANGE/ONLOW/ONHIGH would be not fired.
+Keep in mind that the interrupt ONLOW_WE/ONLOW would be fired repetitively as long as
+the input is held in a LOW state, so a single button press by a fraction of second can
+easily trigger your interrupt handler a few hundreds times.
+The same is valid for ONHIGH_WE/ONHIGH and HIGH level.
+To catch every button press only once - we are going to change the interrupt level
+(from ONHIGH_WE to ONLOW_WE and vice versa).
+Since ONHIGH_WE interrupt handler is detached right on the first execution - it can be
+also treated as a RISING interrupt handler.
+The same way ONLOW_WE can be treated as a FALLING interrupt handler.
+If CHANGE interrupt is needed - just put your logic in both ONHIGH_WE and ONLOW_WE handlers.
+
+This code is under Public Domain License.
+
+Hardware Connections
+======================
+A button from IO10 to ground (or a jumper wire to mimic that button).
+Optionally - an ammeter/scope connected in series with a CPU/DevKit board to measure power consumption.
+
+Author:
+Taras Shcherban <[email protected]>
+*/
+
+#include "Arduino.h"
+#include <atomic>
+
+std::atomic_int interruptsCounter = 0;
+
+#define BTN_INPUT 10
+
+void lowIsrHandler();
+
+void IRAM_ATTR highIsrHandler()
+{
+    // button was released - attach button press interrupt back
+    attachInterrupt(BTN_INPUT, lowIsrHandler, ONLOW_WE);
+}
+
+void IRAM_ATTR lowIsrHandler()
+{
+    // button is pressed - count it
+    interruptsCounter++;
+
+    // attach interrupt to catch an event of button releasing
+    // implicitly detaches previous interrupt and stops this function from being called
+    // while the input is held in a LOW state
+    attachInterrupt(BTN_INPUT, highIsrHandler, ONHIGH_WE);
+}
+
+void setup()
+{
+    Serial.begin(115200);
+    while (!Serial)
+        ; // wait for serial port to connect
+
+    // CPU will automatically go into light sleep if no ongoing activity (active task, peripheral activity etc.)
+    setAutomaticLightSleep(true);
+
+    pinMode(BTN_INPUT, INPUT_PULLUP);
+    attachInterrupt(BTN_INPUT, lowIsrHandler, ONLOW_WE);
+
+    // this function is required for GPIO to be able to wakeup CPU from a lightSleep mode
+    esp_sleep_enable_gpio_wakeup();
+}
+
+void loop()
+{
+    Serial.printf("Button press count: %d\n", (int)interruptsCounter);
+
+    // Serial output is being suspended during sleeping, so without a Flush call logs
+    // will be printed to the terminal with a delay depending on how much CPU spends in a sleep state
+    Serial.flush();
+
+    // This is a sleep-aware waiting using delay(). Blocking in this manner
+    // allows CPU to go into light sleep mode until there is some task to do.
+    // if you remove that delay completely - CPU will have to call loop() function constantly,
+    // so no power saving will be available
+    delay(5000);
+}

libraries/ESP32/examples/PowerSave/WiFiModemSleep/WiFiModemSleep.ino

@@ -0,0 +1,95 @@
+/*
+WiFi automatic LightSleep
+=====================================
+This code displays how to use automatic light sleep with an active WiFi connection
+and tune WiFi modem sleep modes
+
+This code is under Public Domain License.
+
+Hardware Connections (optional)
+======================
+Use an ammeter/scope connected in series with a CPU/DevKit board to measure power consumption
+
+Author:
+Taras Shcherban <[email protected]>
+*/
+
+#include "Arduino.h"
+
+#include <WiFi.h>
+#include <HTTPClient.h>
+
+const char *wifi_ssid = "";
+const char *wifi_password = "";
+
+void doHttpRequest();
+
+void setup()
+{
+    Serial.begin(115200);
+    while (!Serial)
+        ; // wait for serial port to connect
+
+    // CPU will automatically go into light sleep if no ongoing activity (active task, peripheral activity etc.)
+    setAutomaticLightSleep(true);
+
+    WiFi.begin(wifi_ssid, wifi_password);
+
+    // Additionally to automatic CPU sleep a modem can also be setup for a power saving.
+    // If a WiFi is active - selected modem sleep mode will determine how much CPU will be sleeping.
+    // There are two functions available:setSleep(mode) and setSleep(mode, listenInterval)
+    // mode - supports one of three values:
+    //     * WIFI_PS_NONE - No power save
+    //     * WIFI_PS_MIN_MODEM - Minimum modem power saving. In this mode, station wakes up to receive beacon every DTIM period
+    //     * WIFI_PS_MAX_MODEM - Maximum modem power saving. In this mode, interval to receive beacons is determined by the listenInterval parameter
+    // listenInterval - effective only with a WIFI_PS_MAX_MODEM mode. determines how often will modem (and consequently CPU) wakeup to catch WiFi beacon packets.
+    //     The larger the interval - the less power needed for WiFi connection support. However that comes at a cost of increased networking latency, i.e.
+    //     If your device responds to some external requests (web-server, ping etc.) - larger listenInterval means device takes more to respond.
+    //     Reasonable range is 2..9, going larger would not benefit too much in terms of power consumption. Too large value might result in WiFi connection drop.
+    //     listenInterval is measured in DTIM intervals, which is determined by your access point (typically ~100ms).
+    WiFi.setSleep(WIFI_PS_MAX_MODEM, 4);
+}
+
+void loop()
+{
+    doHttpRequest();
+
+    // Serial output is being suspended during sleeping, so without a Flush call logs
+    // will be printed to the terminal with a delay depending on how much CPU spends in a sleep state
+    Serial.flush();
+
+    // This is a sleep-aware waiting using delay(). Blocking in this manner
+    // allows CPU to go into light sleep mode until there is some task to do.
+    // if you remove that delay completely - CPU will have to call loop() function constantly,
+    // so no power saving will be available
+    delay(5000);
+}
+
+// simulate some job - make an HTTP GET request
+void doHttpRequest()
+{
+    if (!WiFi.isConnected())
+        return;
+
+    HTTPClient http;
+
+    Serial.print("[HTTP] request...\n");
+    http.begin("http://example.com/index.html");
+
+    int httpCode = http.GET();
+    if (httpCode > 0)
+    {
+        Serial.printf("[HTTP] GET... code: %d\n", httpCode);
+
+        if (httpCode == HTTP_CODE_OK)
+        {
+            Serial.printf("[HTTP] GET... payload size: %d\n", http.getSize());
+        }
+    }
+    else
+    {
+        Serial.printf("[HTTP] GET... failed, error: %s\n", http.errorToString(httpCode).c_str());
+    }
+
+    http.end();
+}

libraries/WiFi/src/WiFiGeneric.cpp

@@ -621,6 +621,27 @@ bool WiFiGenericClass::setSleep(wifi_ps_type_t sleepType) {
   return false;
 }
 
+bool WiFiGenericClass::setSleep(wifi_ps_type_t sleepType, uint16_t listenInterval)
+{
+    if (!setSleep(sleepType))
+        return false;
+
+    wifi_config_t current_conf;
+    if(esp_wifi_get_config((wifi_interface_t)ESP_IF_WIFI_STA, &current_conf) != ESP_OK){
+        log_e("setSleep(wifi_ps_type_t sleepType, uint16_t listenInterval) failed: get current config failed!");
+        return false;
+    }
+
+    current_conf.sta.listen_interval = listenInterval;
+
+    if(esp_wifi_set_config((wifi_interface_t)ESP_IF_WIFI_STA, &current_conf) != ESP_OK){
+        log_e("setSleep(wifi_ps_type_t sleepType, uint16_t listenInterval) failed: set wifi config failed!");
+        return false;
+    }
+
+    return true;
+}
+
 /**
  * get modem sleep enabled
  * @return true if modem sleep is enabled

libraries/WiFi/src/WiFiGeneric.h

@@ -103,6 +103,16 @@ class WiFiGenericClass {
   bool setSleep(wifi_ps_type_t sleepType);
   wifi_ps_type_t getSleep();
 
+  /**
+  * @brief Set modem sleep state
+  * @param sleepType Modem sleep type, one of WIFI_PS_NONE, WIFI_PS_MIN_MODEM, WIFI_PS_MAX_MODEM
+  * @param listenInterval Listen interval for ESP32 station to receive beacon when WIFI_PS_MAX_MODEM is set. Units: AP beacon intervals. Defaults to 3 if set to 0.
+  * @return
+  *      - true on success
+  *      - false on internal error when parameters combination is not valid
+  */
+  bool setSleep(wifi_ps_type_t sleepType, uint16_t listenInterval);
+
   bool setTxPower(wifi_power_t power);
   wifi_power_t getTxPower();