Chapter 248: Power Management Framework in ESP-IDF

Chapter Objectives

By the end of this chapter, you will be able to:

• Understand the critical importance of power management in embedded systems.
• Describe the components and goals of the ESP-IDF Power Management Framework.
• Explain Dynamic Frequency Scaling (DFS) and Automatic Light Sleep.
• Correctly configure the power management framework using menuconfig.
• Use power management locks (esp_pm_lock...) to programmatically control system performance and power states.
• Implement DFS in a practical application and observe its effects.
• Recognize variant-specific differences in power management capabilities across the ESP32 family.

Introduction

A significant portion of modern IoT and embedded devices operate on battery power. For these products, from wearables to remote environmental sensors, battery life is not just a feature—it is often the most critical design constraint. An otherwise brilliant device is useless if its battery dies in a matter of hours. Achieving a multi-month or multi-year lifespan requires diligent and intelligent power management.

This is where the ESP-IDF‘s Power Management Framework becomes an essential tool. It provides a sophisticated, yet easy-to-use system for dynamically balancing performance and power consumption. By automatically reducing the CPU speed or putting the system into a light sleep state when idle, the framework can drastically reduce energy usage. This chapter will guide you through the theory and practice of using this framework to build power-efficient, long-lasting applications.

Theory

The core of power management lies in a fundamental trade-off: performance versus power. Running a processor faster allows it to complete tasks more quickly, but the energy cost rises significantly. The power consumed by a CMOS processor is approximately proportional to the equation P ≈ C × V² × f (Power ≈ Capacitance × Voltage² × Frequency). This means that doubling the CPU frequency (f) roughly doubles the power consumption, but the necessary increase in voltage (V) can cause the power draw to more than double. The ESP-IDF power management framework is designed to navigate this trade-off intelligently.

1. Framework Components: DFS and Light Sleep

The framework operates primarily through two automatic mechanisms:

• Dynamic Frequency Scaling (DFS): This feature allows the ESP-IDF to change the CPU’s clock frequency on the fly. When high performance is required, the CPU can be set to its maximum frequency (e.g., 240 MHz). When the system is idle or performing trivial tasks, the frequency can be scaled down to a minimum value (e.g., 40 MHz), significantly reducing power consumption.
• Automatic Light Sleep: Light Sleep is a low-power state where the CPUs are clock-gated, and most peripherals are turned off. However, the system’s RAM is retained, allowing for an extremely fast wakeup. The framework can automatically put the system into Light Sleep whenever the FreeRTOS idle task is scheduled to run on both cores (i.e., when no application tasks are ready to run).

2. Developer Control: Power Management Locks

While the framework is automatic, it needs input from the application to know when performance is required. This is accomplished using power management locks.

Think of locks as a voting system. The framework will always try to put the system into the lowest possible power state. However, any part of your application (or a driver, like the Wi-Fi driver) can “vote” against this by acquiring a lock. The system will only enter a lower power state when all locks of that type have been released.

A lock is represented by the handle esp_pm_lock_handle_t. There are three main types of locks you can create:

The lifecycle of using a lock is straightforward:

1. Create: esp_pm_lock_create() – Create a lock of a specific type and get a handle. This is typically done once during initialization.
2. Acquire: esp_pm_lock_acquire() – Acquire the lock before a critical section that needs high performance or must prevent sleep.
3. Release: esp_pm_lock_release() – Release the lock immediately after the critical section is complete.
4. Delete: esp_pm_lock_delete() – Destroy the lock handle when it’s no longer needed, usually during de-initialization.

By strategically acquiring and releasing these locks around performance-critical code paths, you give the framework the information it needs to save power at all other times.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': '"Open Sans", sans-serif'}}}%%
sequenceDiagram
    participant App as Application Code
    participant PM as Power Manager
    
    App->>PM: 1. esp_pm_lock_create()
    activate PM
    PM-->>App: Returns lock_handle
    deactivate PM

    Note over App, PM: Initialization Phase (Done once)

    loop Performance-Critical Section
        App->>PM: 2. esp_pm_lock_acquire(handle)
        activate PM
        PM->>PM: Vote for high power state<br>(e.g., raise CPU frequency)
        PM-->>App: Lock acquired
        deactivate PM

        App->>App: Perform intensive work...

        App->>PM: 3. esp_pm_lock_release(handle)
        activate PM
        PM->>PM: Remove vote for high power state<br>(System can now scale down)
        PM-->>App: Lock released
        deactivate PM
    end
    
    Note over App, PM: De-initialization Phase (Done once)

    App->>PM: 4. esp_pm_lock_delete(handle)
    activate PM
    PM-->>App: Lock destroyed
    deactivate PM

Practical Examples

Let’s build an application that demonstrates DFS in action. We’ll create a task that demands high CPU performance, and we’ll watch the CPU frequency scale up and down accordingly.

1. Configure the Power Management Framework

1. Open the Project Configuration menu (>ESP-IDF: SDK Configuration editor (menuconfig)).
2. Navigate to Power Management —>.
3. Check the box for [*] Enable Power Management.
4. Check the box for [*] Enable Dynamic Frequency Scaling (DFS).
5. Set the Maximum CPU frequency (MHz). For an ESP32-S3, 240 MHz is a good choice.
6. Set the Minimum CPU frequency (MHz). Choose a lower value, like 80 MHz or 40 MHz.
7. Save the configuration and exit.

2. Application Code

Modify your main/main.c file with the following code. This program will create a lock, then start a task that periodically acquires the lock to simulate a heavy workload.

#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_pm.h"
#include "esp_clk.h" // Deprecated in later versions, but esp_clk_cpu_freq() is useful for demo. For IDF 5.x, esp_clk_get_cpu_freq_mhz() is preferred.

static const char *TAG = "PM_EXAMPLE";

// Handle for the CPU frequency lock
esp_pm_lock_handle_t cpu_freq_lock;

// This task simulates a periodic, high-performance workload.
void high_performance_task(void *param)
{
    while (1) {
        ESP_LOGI(TAG, "Starting high-performance workload...");

        // 1. Acquire the lock to boost CPU frequency
        esp_pm_lock_acquire(cpu_freq_lock);
        ESP_LOGI(TAG, "CPU_FREQ_MAX lock acquired. Current CPU frequency: %d MHz", esp_clk_cpu_freq() / 1000000);
        
        // 2. Simulate a heavy workload (e.g., calculations, data processing)
        // We use a busy-wait loop for demonstration.
        uint32_t start_time = xTaskGetTickCount();
        while((xTaskGetTickCount() - start_time) < pdMS_TO_TICKS(2000)) {
            // Spinning here to represent work
        }

        // 3. Release the lock to allow frequency to scale down
        esp_pm_lock_release(cpu_freq_lock);
        ESP_LOGI(TAG, "CPU_FREQ_MAX lock released.");
        
        // The frequency will drop after the lock is released. We delay to observe it.
        vTaskDelay(pdMS_TO_TICKS(100)); // Short delay to allow scheduler to run and DFS to act
        ESP_LOGI(TAG, "Workload finished. Current CPU frequency: %d MHz", esp_clk_cpu_freq() / 1000000);

        // Wait for the next cycle
        vTaskDelay(pdMS_TO_TICKS(5000));
    }
}

void app_main(void)
{
    // Configure the power management based on menuconfig settings.
    // The following settings are for demonstration and may vary based on your menuconfig.
    esp_pm_config_t pm_config = {
        .max_freq_mhz = 240, // Match your menuconfig setting
        .min_freq_mhz = 80,  // Match your menuconfig setting
        .light_sleep_enable = true
    };
    ESP_ERROR_CHECK(esp_pm_configure(&pm_config));
    ESP_LOGI(TAG, "Power management configured.");

    // Create the lock for max CPU frequency.
    ESP_ERROR_CHECK(esp_pm_lock_create(ESP_PM_CPU_FREQ_MAX, 0, "cpu_freq_lock", &cpu_freq_lock));

    ESP_LOGI(TAG, "Initial CPU frequency: %d MHz", esp_clk_cpu_freq() / 1000000);
    ESP_LOGI(TAG, "Starting high-performance task in 3 seconds...");

    vTaskDelay(pdMS_TO_TICKS(3000));

    xTaskCreate(high_performance_task, "high_perf_task", 4096, NULL, 5, NULL);
}

Note: The esp_clk_cpu_freq() function used here for demonstration is part of an older API. In newer ESP-IDF versions, the preferred function is esp_clk_get_cpu_freq_mhz(). Both achieve the same goal of reporting the current CPU speed.

3. Build, Flash, and Monitor

1. Build: Click the Build button.
2. Flash: Connect your board and click the Flash button.
3. Monitor: Open the serial monitor.

You should see output that clearly shows the CPU frequency changing:

I (314) PM_EXAMPLE: Power management configured.
I (314) PM_EXAMPLE: Initial CPU frequency: 80 MHz
I (324) PM_EXAMPLE: Starting high-performance task in 3 seconds...
I (3324) PM_EXAMPLE: Starting high-performance workload...
I (3324) PM_EXAMPLE: CPU_FREQ_MAX lock acquired. Current CPU frequency: 240 MHz
I (5334) PM_EXAMPLE: CPU_FREQ_MAX lock released.
I (5434) PM_EXAMPLE: Workload finished. Current CPU frequency: 80 MHz
I (10434) PM_EXAMPLE: Starting high-performance workload...
I (10434) PM_EXAMPLE: CPU_FREQ_MAX lock acquired. Current CPU frequency: 240 MHz
...

To see the real impact, you would connect a power profiling tool (like a Joulescope, Power Profiler Kit II, or INA219) to your board’s power input and observe the current draw spike when the lock is acquired and drop when it is released.

Variant Notes

While the power management API is consistent across the ESP32 family, the underlying capabilities and power characteristics vary.

• ESP32: Has a mature power management system with DFS support (typically 80, 160, 240 MHz steps) and Light Sleep.
• ESP32-S2 & S3: Offer more granular control over clock frequencies and generally have lower power consumption in active modes compared to the original ESP32. Their Light Sleep power consumption is also very low.
• ESP32-C3 (RISC-V): Designed with low power in mind. Its DFS range is typically smaller (e.g., 80 MHz to 160 MHz), but its baseline power consumption is significantly lower.
• ESP32-C6 & H2 (RISC-V): These variants add an 802.15.4 radio (for Thread/Zigbee) to the mix. The power management framework also coordinates with this radio’s sleep states. Their ultra-low-power RISC-V core allows for very efficient operation at lower frequencies.
• PSRAM Impact: If your board uses external PSRAM, the power consumption in all modes, especially Light Sleep, will be higher due to the need to keep the PSRAM refreshed. This is an important hardware trade-off to consider.

Common Mistakes & Troubleshooting Tips

Exercises

1. Measure the Impact: If you have a power measurement tool, connect it to your board. Run the example code and record the average current during the “workload” phase (lock acquired) and the “idle” phase (lock released). Quantify the power savings.
2. Preventing Light Sleep: Create a new power lock of type ESP_PM_NO_LIGHT_SLEEP. Write a task that acquires this lock for 10 seconds, then releases it for 10 seconds, in a loop. While you cannot easily see “Light Sleep” in the serial log, if you are measuring power, you will see the baseline idle current increase during the 10 seconds the lock is held.
3. Wi-Fi and Power: Write a simple application that connects to your Wi-Fi network and does nothing else. Using a power profiler, observe the current consumption. It will be significantly higher than a non-connected device because the Wi-Fi driver is actively managing locks to maintain the connection.
4. Button-Activated Boost: Modify the main example to be event-driven. The device should stay at the minimum frequency. When a GPIO button is pressed, the high-performance task should wake up, acquire the CPU lock, perform its work, release the lock, and go back to sleep. This is a much more realistic power-saving pattern.

Summary

• Power efficiency is a cornerstone of battery-powered embedded systems.
• The ESP-IDF Power Management Framework automates power savings through Dynamic Frequency Scaling (DFS) and Automatic Light Sleep.
• Developers guide the framework by using power management locks (esp_pm_lock_handle_t).
• Acquiring an ESP_PM_CPU_FREQ_MAX lock boosts performance, while an ESP_PM_NO_LIGHT_SLEEP lock ensures system availability.
• The key to effective power management is to hold locks for the shortest possible duration, allowing the system to return to a low-power state as quickly as possible.
• Always remember to release every lock you acquire to prevent the system from getting stuck in a high-power state.

Further Reading

• ESP-IDF Power Management Documentation: https://docs.espressif.com/projects/esp-idf/en/v5.2.1/api-reference/system/power_management.html
• ESP-IDF Clock API Reference (esp_clk.h): https://docs.espressif.com/projects/esp-idf/en/v5.2.1/api-reference/system/esp_clk.html
• Application Note: How to Optimize Wi-Fi Power Consumption: https://www.espressif.com/en/support/documents/technical-documents?keys=power+consumption (Search for relevant power consumption app notes)