iot_button + Auto Light Sleep: Baseline Current Never Returns to Idle After Button Activity (ESP32-S3) (AEGHB-1318)

[michaelboeding]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

General issue report

iot_button + Auto Light Sleep: Baseline Current Never Returns to Idle After Button Activity (ESP32-S3)

Overview

When using Dynamic Frequency Scaling (DFS) with automatic light sleep enabled, pressing a button managed by the iot_button component causes the baseline current draw to increase and never return to the original low-power level.

This happens after one or more button interactions (especially multiple/rapid clicks). Once it occurs, the system appears to stop entering automatic light sleep until reboot.

I've attached a current trace screenshot showing:

• Initial low baseline (auto light sleep active)
• Several button presses (single/double)
• A step change to a higher baseline current that never recovers

---

Environment

• Chip: ESP32-S3
• Framework: ESP-IDF (ESP32-S3 target)
• iot_button version: v3.5.0
• Power Management:
  • esp_pm_configure() with:
    • DFS enabled
    • light_sleep_enable = true
• Button Library: iot_button component
  • enable_power_save = true in configuration
• Transports tested:
  • Wi-Fi enabled
  • BLE enabled
    ➜ Issue reproduces in both cases, so it doesn't appear Wi-Fi–specific.

(If useful: I can provide exact ESP-IDF version and commit hash I'm currently using.)

---

Power Management Configuration

esp_pm_config_t pm_config = {
    .max_freq_mhz = 240,
    .min_freq_mhz = 40,
    .light_sleep_enable = true,
};

ESP_ERROR_CHECK(esp_pm_configure(&pm_config));

Button initialization (simplified):

button_config_t cfg = {
    .type = BUTTON_TYPE_GPIO,
    .gpio_button_config = {
        .gpio_num = BUTTON_GPIO,
        .active_level = 0,
    },
    .enable_power_save = true, // Also tested with false
};

button_handle_t btn = iot_button_create(&cfg);

// single click / double click handlers registered as normal...

---

Steps to Reproduce

1. Configure DFS + auto light sleep via esp_pm_configure() as above.
2. Initialize iot_button with enable_power_save = true (also happens with false).
3. Let the device run idle until:
   • Current settles at low baseline (auto light sleep clearly active).
4. Perform:
   • A few single clicks ➜ LED updates, current returns to baseline.
   • Then double-click or several rapid clicks in a row.
5. Observe:
   • Current climbs to a higher "active" baseline and
   • Never returns to the original low-power level, even after the button is idle for a long period, no tasks running, etc.

This reproduces consistently on my hardware.

---

Expected Behavior

• After button activity finishes and the button enters the idle state, the iot_button timer should stop, GPIO wakeup should be re-enabled, and:
  • ESP-IDF auto light sleep should resume as before.
  • Baseline current should drop back to the original light-sleep level.

---

Actual Behavior

• After some sequences of button presses (often double/multiple rapid clicks):
  • Baseline current jumps to a higher, non-sleep state.
  • The device never returns to the original light-sleep baseline.
  • This persists indefinitely (until reset), even though:
    • No button presses are happening
    • Button is logically idle
    • There is no obvious high-activity task in my app code.

It looks like the system is stuck in a non-light-sleep state as far as the PM subsystem is concerned.

---

What I've Tried / Ruled Out

Change / Test	Result
Disabled all LED/status logic inside singleClick()	❌ Baseline still gets stuck high
Disabled multi-click (e.g., 15-click handler)	❌ No change
Added explicit double-click handler (to consume event)	❌ No change
Added a race-condition flag (s_entering_power_save)	❌ No change
Added GPIO level checks in ISR to filter spurious edges	❌ No change
Disabled enable_power_save in iot_button	❌ Problem still occurs

So far this does not appear to be caused by my application callbacks (LEDs, app logic, etc.). Even with minimal handlers, the behavior is the same.

---

Relevant Code Path (Button Timer Lifecycle)

From the iot_button side (simplified view of the logic):

// On GPIO interrupt (button edge):
static void button_isr_handler(void *arg) {
    // ...
    // Start periodic timer to poll button state
    if (!g_is_timer_running) {
        esp_timer_start_periodic(g_button_timer_handle, 5 * 1000); // 5 ms
        g_is_timer_running = true;
    }
}

// In the timer callback:
static void button_timer_callback(void *arg) {
    // Poll button state, detect click, etc.

    if (button_state == BUTTON_NONE_PRESS) {
        // Stop timer when idle
        esp_timer_stop(g_button_timer_handle);
        g_is_timer_running = false;

        // Re-enable GPIO interrupt and wakeup
        button_gpio_intr_control(button_handle, true);
        button_gpio_enable_gpio_wakeup(button_handle, true);
    }
}

In my testing, logs confirm that:

• esp_timer_stop() is called when the button becomes idle.
• g_is_timer_running is set to false.
• GPIO wakeup is re-enabled.

Despite this, auto light sleep appears not to re-engage after certain press sequences.

---

Hypothesis

My working theory is that there is a subtle interaction between esp_timer (used by iot_button) and ESP-IDF's automatic light sleep / DFS logic:

1. iot_button uses a periodic esp_timer (5 ms) to poll button state.
2. Automatic light sleep requires:
   • No active timers / pending work that would prevent tickless idle and light sleep.
3. In some sequence of presses (especially double/multiple), it seems that:
   • Either a timer, wake-up source, or PM lock is left in a state that prevents idle detection, or
   • Some internal subsystem (GPIO, timer, etc.) keeps the chip from returning to light sleep, even though esp_timer_stop() has been called.

Since the issue persists even when enable_power_save is disabled in iot_button, I suspect this may relate to:

• How iot_button manages esp_timer + GPIO wakeup together, or
• How those interact with tickless idle / PM locks on ESP32-S3 in auto light sleep mode.

---

Tickless Idle + Auto Light Sleep Settings

For reference, I’m using:

• CONFIG_PM_ENABLE=y
• CONFIG_PM_DFS_INIT_AUTO=y
• CONFIG_PM_RTOS_IDLE_OPT=y
• CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP=y
• CONFIG_FREERTOS_USE_TICKLESS_IDLE=y
• CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP=3
• CONFIG_GPIO_BUTTON_SUPPORT_POWER_SAVE=y
• CONFIG_BUTTON_PERIOD_TIME_MS=5
• CONFIG_BUTTON_DEBOUNCE_TICKS=2

Additional Observation:
Once the system enters the bad state (baseline current stuck high), further button presses do not restore light sleep. The button still wakes the CPU and my click callbacks run, but after each subsequent press the device never returns to the original light-sleep baseline — it stays at the elevated “active” baseline indefinitely, even with long idle periods.

[michaelboeding]

Solution Found: Fixed Button Timer + Light Sleep Integration

I tracked down the high idle current + "button breaks light sleep after double-click" issue to how iot_button was handling its scan timer and power-save integration.

Summary of the Fix

I made two main changes to main/components/button/iot_button.c:

1. Idle detection in button_cb() now uses the internal state + debounced GPIO level instead of relying on event == BUTTON_NONE_PRESS.
2. A per-button PM lock was added around the scan timer, so the CPU can't slip into light sleep while actively polling, and the lock is released as soon as the scan timer stops.

Together, these ensure:

• The scan timer actually stops after multi-click/double-click sequences
• GPIO wakeup is re-enabled properly
• Auto light sleep can resume and baseline current returns to the expected low value

---

Root Cause

Previously, the logic that decided whether to enter power save was tied to the last event emitted by the button state machine:

• It waited for event == BUTTON_NONE_PRESS to consider the button "idle" and stop the scan timer
• During certain rapid multi-click or double-click transitions, the state machine returned to idle and the GPIO was released, but no BUTTON_NONE_PRESS event was emitted in the right window
• As a result, the scan timer never stopped, and the power-save path that re-enables GPIO wakeup and allows light sleep never ran

So after one of these sequences, I ended up in a state where:

• The periodic scan timer kept running indefinitely
• GPIO-based wakeup remained disabled
• Auto light sleep stayed blocked and idle current stayed high until reboot

---

Changes I Made

1. Robust Idle Detection in button_cb()

Instead of keying off BUTTON_NONE_PRESS, I now compute "true idle" directly from the button's internal state:

bool btn_idle =
    (target->enable_power_save &&
     target->debounce_cnt == 0 &&
     target->state == 0 &&
     target->button_level != target->active_level);

if (!btn_idle) {
    enter_power_save_flag = false;
}

This means I only consider the button idle when:

• Power save is enabled for this button
• The debounce counter has fully settled (debounce_cnt == 0)
• The internal state machine is back at idle (state == 0)
• The GPIO is at the released level (button_level != active_level)

This is much more reliable for double-click/repeat-click patterns because it doesn't depend on a specific event value; it looks at the actual state and pin level.

2. Safe Stop + PM Lock Release When Entering Power Save

When enter_power_save_flag is set, I now:

• Stop the scan timer only if it's actually running
• Release the PM lock in sync with that:

if (g_is_timer_running) {
    esp_timer_stop(g_button_timer_handle);
    g_is_timer_running = false;

    if (s_btn_sleep_lock && s_btn_sleep_lock_held) {
        esp_pm_lock_release(s_btn_sleep_lock);
        s_btn_sleep_lock_held = false;
    }

    ESP_LOGI(TAG, "Button timer stopped - entering power save");
}

// Then re-enable GPIO wakeup for this button
button_power_save_enable(target);

I also marked g_is_timer_running as volatile to avoid stale reads between ISR and task context.

3. PM Lock Acquired When Scan Timer Starts (ISR)

In button_power_save_isr_handler(), when a GPIO wake triggers, I:

• Disable GPIO wake for that button
• Start the periodic scan timer only if it's not already running
• Acquire a PM lock so the CPU can't enter light sleep while scanning:

if (!g_is_timer_running) {
    if (esp_timer_start_periodic(g_button_timer_handle, TICKS_INTERVAL * 1000U) == ESP_OK) {
        g_is_timer_running = true;

        if (s_btn_sleep_lock && !s_btn_sleep_lock_held) {
            esp_pm_lock_acquire(s_btn_sleep_lock);
            s_btn_sleep_lock_held = true;
        }
    }
}

This keeps the core awake for the duration of the scan. Once the timer stops, the PM lock is released and the system is free to enter light sleep again.

4. PM Lock Created When Button Timer is Created

When creating the shared g_button_timer_handle in button_create_com(), I also create the PM lock:

if (g_button_timer_handle == NULL) {
    const esp_timer_create_args_t button_timer = {
        .callback = button_cb,
        .arg = NULL,
        .dispatch_method = ESP_TIMER_TASK,
        .name = "button_scan"
    };

    esp_timer_create(&button_timer, &g_button_timer_handle);

    if (s_btn_sleep_lock == NULL) {
        esp_pm_lock_create(ESP_PM_NO_LIGHT_SLEEP, 0, "btn_scan", &s_btn_sleep_lock);
    }
}

The lock type is ESP_PM_NO_LIGHT_SLEEP, so it only blocks light sleep while the scan is active.

---

Why This Fixes the Issue

• The idle condition now matches the real state of the button (state machine idle + debounced release), so the scan timer always stops once the button is truly idle, even after complex multi-click sequences
• When the scan timer stops, I:
  • Release the PM lock
  • Re-enable GPIO wake
• This restores the expected power-save behavior:
  • No stray scan timers running forever
  • GPIO wake is active again
  • Auto light sleep works normally
  • Baseline idle current returns to the low value expected for tickless + light sleep

---

Key Takeaways for Future Reference

If this needs to be reapplied or referenced:

1. The btn_idle condition in button_cb() that checks actual state
2. The PM lock acquire/release around esp_timer_start_periodic / esp_timer_stop
3. The volatile qualifier on g_is_timer_running
4. Creating the ESP_PM_NO_LIGHT_SLEEP lock alongside the button scan timer

Environment where I tested the fix:

• ESP-IDF v5.3.2
• iot_button v3.5.0
• ESP32-S3
• DFS + automatic light sleep enabled

[lijunru-hub]

Thank you very much for the thorough testing and detailed report. I’ve run into this issue before, and it appears to be related to some aspects of the DFS mechanism. From what I can tell, the key to resolving it is your second point—adding explicit PM lock management. Relying solely on the power-management behavior inside esp_timer seems to cause problems (though this still needs to be confirmed).

[michaelboeding]

That makes sense - although wouldn't on the next press it should revert back to the low power state? When I get it into this state it's impossible to get it back to the lower baseline current. That makes me think something is stuck or corrupted at the iot_button level?