Events and timers
Typed events, listeners, timers and pin watchers with ext-events. The event-driven runtime delivers them; under init-loop only Events::now() and Events::dispatch() do.
ext-events lets a script react instead of running top to bottom. An event is an object of a class you declare
as a subclass of Baremetal\Event. Listeners are callables registered per event class. Sources raise events
below PHP: a periodic timer, a falling edge on a pin, gestures on a push button. Other extensions raise events
into the same queue: ext-i2c sensor samples, and ext-web HTTP requests and
WebSocket frames.
Install
The conductor adds the ESP32 HAL (esp32-events-hal) for you: never require it. The event-driven runtime
requires ext-events, so the build fails without it. ext-i2c and ext-web bring it in as well.
The main functions
| Name | Meaning |
|---|---|
Baremetal\Event |
Base class of every event. $device holds the object that raised it, or null. |
Events::listen(string $event, callable $listener) |
Register a listener for one exact class. Returning false stops the later listeners of that event. |
Events::now(Event $event) |
Deliver at once, on the caller's stack. |
Events::dispatch(Event $event): bool |
Deliver breadth-first: events dispatched by listeners run after the current batch. false when no event slot is free or beyond 16 levels. |
Events::stats(): array |
Event slots in use, per-class counters (queued, delivered, dropped, coalesced) and cascade depths since boot. |
every(int|float $ms, string $event, bool $coalesce = true): Baremetal\Timer |
Raise $event every $ms milliseconds, from 0.1 ms, rounded to the microsecond: every(1000 / 60, Frame::class) is 60 per second. A tick waits at most once. |
watch_gpio(int $pin, string $event, bool $coalesce = false): Baremetal\GpioWatch |
Raise $event on each falling edge of $pin, with a 200 ms debounce. |
watch_button(int $pin, array $on, array $opts = []): Baremetal\Button |
Raise events for button gestures: pressed, released, held, click, repeat, double. |
button_sampling(bool $on) |
Pause or resume the button sampler. |
power_hold(), power_release() |
Forbid or allow automatic light sleep. |
The full signatures, options and exceptions are in the ext-events package.
A timer and a button
07-event-driven/event-driven-hello is the example of the event-driven
page. 07-event-driven/gpio-interrupt toggles an LED from the BOOT button (GPIO 0 on the
Waveshare ESP32-S3-Zero):
The script runs once, registers the listener and the source, and returns. From then on the runtime delivers
each press. $on keeps its value between events, because the script stays resident.
Which runtime delivers what
| Runtime | Timers, pin and button events | Events::now() and dispatch() |
Listener table |
|---|---|---|---|
event-driven |
Delivered by the runtime, one at a time on the PHP task | Work | Frozen when the entry script returns |
init-loop |
Never delivered: the sources run, and after each loop() the runtime gives their slots back |
Work | Never frozen |
web-server |
Refused: the source functions throw | Work, inside the request | One per request, dropped when it ends |
Under init-loop, every() and watch_gpio() start without error, and their events are never delivered. Use
the event-driven runtime for them. In web-server (ext-events 1.0.2 and later)
every(), watch_gpio(), watch_button() and button_sampling() throw, in a request and in the init
script, because nothing reads the queue; listeners registered during a request last until that request ends.
In event-driven, Events::listen() throws Events::listen() must be called in setup(); the listener table is frozen afterwards once the entry script has returned, also from inside a listener. Register every listener in
the entry script.
Behaviour on the board
- Event slots. Every event from outside the PHP task (timers, pin edges, buttons, sensor samples, HTTP
requests, WebSocket frames) and every event waiting in a
dispatch()cascade takes a slot allocated at boot: 64 small slots by default, set with the ext-events optionsevents-small,events-mediumandevents-large. A timer or pin event that finds no free slot is dropped and counted, and the first drop of its class prints a warning; an HTTP request is answered 503.Events::stats()andphpinfo()show the counters. - Timers.
every()starts anesp_timer; its callback runs on theesp_timertask (core 0) and only posts to the queue. The period goes down to 0.1 ms, but each event costs a PHP call of tens of microseconds: a timer faster than its listener coalesces its ticks (one waits at a time), or withcoalesce: falseruns out of slots and drops them.every(),watch_gpio()andwatch_button()return a handle:stop()pauses the timer, pin watch or button watch andstart()resumes it (a dropped handle leaves it running;button_sampling()pauses all buttons). - Pins.
watch_gpio()makes the pin an input with the internal pull-up and catches the falling edge by interrupt. Wire the button between the pin and GND. The 200 ms debounce is per event class, so two pins that share a class share it. - Buttons.
watch_button()samples every 10 ms, so timings have a 10 ms resolution; at most four buttons. Preferwatch_gpio()where gestures are not needed. - Delivery. Events arrive in order and their listeners never run at the same time. A long listener delays
every event behind it, HTTP requests included. Keep listeners short and split long work into steps driven by
every(). - Matching. A listener matches the exact class: a listener on a parent class receives nothing from its subclasses. Events raised by a source are created without calling their constructor.
- Limits. Sources can use at most 32 distinct event classes in the whole firmware, shared with the sample events of ext-i2c.
Power: power_hold() and power_release()
With the power-save option on, the chip light-sleeps whenever every task waits, and the event-driven runtime
waits on the queue between events. Nothing in PHP is needed for that. power_hold() forbids light sleep until
the matching power_release(); calls nest. Use it around work that must not be slowed by sleep, such as a
tight timing loop.
- In
event-driven, a hold still standing when the listeners of an event return is released: a hold never spans two events. Underinit-loopa hold lasts untilpower_release(). - Without
power-saveboth functions do nothing, so the same script runs either way. - What wakes the chip: an
every()timer wakes it each period,watch_gpio()only on an edge,watch_button()every 10 ms while the sampler runs. See Power saving.
Common errors
| Message | Cause |
|---|---|
Events::listen() must be called in setup(); the listener table is frozen afterwards |
A listener registered after the entry script returned. |
every(): unknown class '...' or too many sources |
The event class does not exist, or 32 source classes are already in use. The same message exists for watch_gpio() and watch_button(). |
every(): cannot start the timer |
The timer could not be created or started. |
watch_button(): too many buttons |
Four buttons are already watched. |
phpbm: cannot create the event queue |
The runtime could not create the queue; the program ends. |
An uncaught exception in a listener follows the on-error option: see event-driven.