Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-events

bm-ext MIT

Event bus: events, listeners, timer, pin and button sources. Core, every firmware requires it.

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:

json composer.json, extra.baremetal
{
  "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-loop with loop-interval 0 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-i2c refuses Bus::CORE1 while 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