ext-events · PHP API
Power hold and power-save
With the power-save option the chip light-sleeps by itself whenever every task waits. power_hold() and power_release() keep it awake for a stretch; without power-save they do nothing.
The power-save option
power-save is an SDK option, off by default. Turn it on in the project composer.json:
{
"runtime": "event-driven",
"options": { "power-save": "on" }
}
The firmware then enables automatic light sleep at boot: whenever every task is waiting (the event-driven
runtime waiting for the next event, or init-loop between two loop() calls with a loop-interval), the
chip drops into light sleep, keeps its RAM, and wakes on the next timer, interrupt or network activity. No
sleep call is needed in PHP.
init-loopwithloop-interval0 never sleeps: the PHP task never waits.- While a USB host is connected to the USB-JTAG console, the chip does not light-sleep. Power the board from an external 5 V supply without the data cable to see it sleep.
ext-i2crefusesBus::CORE1while power-save is on.
power_hold()
power_hold(): void
Returns void.
Forbids light sleep until the matching power_release(). Calls nest: each power_hold() needs its own
power_release(). Use it around work that must not be slowed or interrupted by sleep, such as a tight timing
loop.
power_release()
power_release(): void
Returns void.
Undoes one power_hold(). Extra calls are ignored.
Holds end with the event
A hold taken while an event is delivered belongs to the outermost delivery: the reactor event, or, outside
one, the outermost Events::dispatch() or Events::now() call. When that delivery ends, the holds still
standing are released, so a forgotten power_release() cannot keep the chip awake for good, and a hold never
spans two events. A hold taken inside a nested now() or a dispatched event stays until the outer event ends.
A fatal error in a listener releases every hold before the program stops. In the
event-driven runtime a hold taken by the top-level script is released after the first event. Under
init-loop a hold taken by loop() outside any delivery lasts until power_release().
power_release() undoes the most recent hold still standing.
Without power-save (or on a build where power management could not start) both functions do nothing, so the same script runs either way.
What wakes the chip
| Source | Wakes the chip |
|---|---|
every($ms, ...) |
Every $ms. Pick the longest period that works. |
watch_gpio() |
Only on an edge. |
watch_button() |
Every 10 ms while the button sampler runs; button_sampling(false) stops it. |
ext-i2c background samplers |
While any sampler is running. |
Related
- Sleep between events Recipe
- Sources PHP API
- esp32-events-hal HAL