php-baremetal/php-esp32-sdk

SDK First-party

The esp32 SDK: boards, the PHP build recipe, runtimes, storages and the ESP-IDF toolchain for ESP32-P4 and ESP32-S3. phpbm downloads and drives it.

SDK · Reference

Power saving

The power-save option lets the board enter light sleep by itself whenever every task waits. What it changes, what keeps the board awake, and what to do when a sleeping board stops answering.

power-save is an SDK option: off (the default) or on.

json composer.json, extra.baremetal
{
  "sdk": "esp32@^2.0",
  "board": "waveshare-esp32-s3-zero",
  "runtime": "event-driven",
  "storage": "embedded",
  "options": { "power-save": "on" }
}

What the option does

With on, the build adds the sdkconfig fragment host/sdkconfig/power-save and defines PHPBM_OPTION_POWER_SAVE_ON. The fragment enables:

Setting Meaning
CONFIG_PM_ENABLE ESP-IDF power management.
CONFIG_FREERTOS_USE_TICKLESS_IDLE Light sleep from the idle task.
CONFIG_PM_SLP_IRAM_OPT Sleep entry and exit code in IRAM.
CONFIG_PM_RTOS_IDLE_OPT FreeRTOS idle code in IRAM.
CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION No automatic light sleep while a USB host is connected to the USB-Serial-JTAG port.

At boot app_main configures the power manager for automatic light sleep: the CPU clock runs between the crystal frequency and the default maximum frequency, and the console prints phpbm: power save on (light sleep, <min>-<max> MHz). If the manager cannot be configured it prints phpbm: warning: power save could not be configured, light sleep stays off, and the program runs without sleep.

The board then sleeps whenever every task is waiting: the event-driven runtime waiting for the next event, or init-loop between two loop() calls when loop-interval is above 0. RAM, PSRAM and PHP state survive, and the board wakes on a timer, an interrupt or network activity. Nothing changes in PHP: no call is needed.

What keeps the board awake

Cause Detail
init-loop with loop-interval 0 loop() never waits, so the board never sleeps.
A USB data cable on the USB-Serial-JTAG console The firmware sets CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION on purpose, otherwise the console port goes silent. To measure real sleep, power the board from 5 V without the data cable. The boards with this console are freenove-esp32-s3-wroom-lite-n16r8, freenove-esp32-s3-wroom-lite-n16r16, waveshare-esp32-s3-eth, waveshare-esp32-s3-touch-lcd-1.85b, waveshare-esp32-s3-zero and waveshare-esp32-s3-zero-n8r8.
The W5500 network (waveshare-esp32-s3-eth) The firmware forbids light sleep for as long as the W5500 runs, and prints w5500: power save: no light sleep while the W5500 runs. The W5500 signals a packet with an edge that cannot wake the chip, so a sleeping board answered pings in about 200 ms and HTTP requests in up to 1 s. Only the clock still scales. Light sleep would save little on this board anyway: the W5500 and its PHY draw most of the current (measured from 5 V: 127 mA with the USB data cable, 111 mA with light sleep, 122 mA with only the clock scaling).
power_hold() Forbids light sleep until the matching power_release(); the calls nest. In event-driven a hold still standing when an event's listeners return is released.
Periodic work An every() timer wakes the board each period; a button watch wakes it every 10 ms while it runs; an ext-i2c sampler wakes it once per sampling period for as long as it runs (esp32-executor 1.0.2 and later; earlier versions woke it every millisecond).

power_hold() and power_release() belong to ext-events, not to ext-sys. Without power-save they do nothing, so the same script runs either way.

Warning Not with Bus::CORE1

With power-save on, ext-i2c refuses a bus opened with Bus::CORE1. Use Bus::SYNC. A sampler on a SYNC bus wakes the chip once per period, so the board never sleeps longer than that period. See the ext-i2c page on ownership and power-save.

Explicit sleeps

The ext-sys package has three calls that work with or without the option. They are described in the ext-sys package.

Call What it does
sys_light_sleep($ms, $wakePin, $wakeLow) Sleeps in place for $ms or until a pin reaches its level, then returns timer, gpio or other, or none when the chip did not sleep. It runs on the executor task, which is blocked for the whole sleep: NVS writes and Bus::CORE1 buses wait.
sys_deep_sleep($ms, $wakePin, $wakeLow) Ends the program and puts the chip in deep sleep; waking is a full boot. The wake pin must be an RTC IO on ESP32-S3 or an LP IO on ESP32-P4.
sys_wake_cause() What ended the deep sleep this boot came from: timer, gpio, other, or none.

Explicit light sleep suspends the flash cache, so the PHP task, whose stack is in PSRAM, never calls it directly: see Writing native packages. sys_restart() and sys_deep_sleep() stop the whole program, even when a web-server request calls them.

The USB-JTAG console and sleep

On a board with the USB-Serial-JTAG console, the console port goes silent while the chip sleeps; it is also what drops out during sys_light_sleep(). That is why the firmware sets CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION: with a USB host connected the board does not light-sleep by itself, so the console stays up, at the price of no automatic sleep while the cable is plugged in.

When a board stops answering

If a board with a sleeping or crashing program no longer shows a serial port, or phpbm flash cannot reach it, put the chip in download mode by hand:

  1. Hold the BOOT button.
  2. Press and release RESET, then release BOOT.
  3. Run phpbm flash again. If phpbm does not find the board, pass the port with --port.

A firmware built without power-save replaces the sleeping one, and the board answers again.

Not yet measured

The sleep current of the firmware has not been measured. A build with power-save and the explicit sleep calls runs on the ESP32-S3; on the ESP32-P4 it builds but has not been run. Wake-up from a pin has not been exercised with a real edge.

Last updated 2026-11-15 · v2.0.x Edit on GitHub Report issue