The ESP32 side of ext-events: the event queue, the periodic timers, the
GPIO interrupts and the light-sleep lock that every(), watch_gpio(), watch_button() and
power_hold() run on. It implements bm_events_hal.h from ext-events.
| Key | Value |
|---|---|
| Type | bm-hal |
| Platform | esp32 (extra.baremetal.platform) |
| Provides | php-baremetal/events-hal 1.5.0 (1.4.0 in esp32-events-hal 1.1.0, 1.1.0 in esp32-events-hal 1.0.2, 1.0.0 before) |
| ESP-IDF components | esp_timer, esp_driver_gpio, esp_pm, phpbm (the SDK host component) |
Install
Projects do not require it. A project requires php-baremetal/ext-events (or a package that needs it, such
as ext-i2c or ext-web), and conductor adds php-baremetal/esp32-events-hal because the project's SDK
("sdk": "esp32@^2.0") has the platform esp32:
composer require php-baremetal/ext-events
Behaviour on ESP32
| ext-events feature | ESP-IDF mechanism |
|---|---|
| Event queue | A FreeRTOS queue. Posting never waits for sources; ISRs post with the ISR variant and yield if a higher-priority task woke. |
every(), the button sampler |
Periodic esp_timer timers. Their callbacks run on the esp_timer task (core 0) and only post to the queue. |
watch_gpio() |
The pin is configured as input with the internal pull-up and a falling-edge interrupt; the GPIO ISR service is installed on first use. |
watch_gpio(), watch_gpios() (GpioWatch::stop()) |
bm_hal_gpio_off(): gpio_intr_disable() and gpio_isr_handler_remove(); the pin stays an input. |
watch_button() |
The pin is configured as input with a pull-up (pull-down when activeLow is false), interrupts off; the sampler reads its level. |
power_hold() / power_release() |
An esp_pm lock of type ESP_PM_NO_LIGHT_SLEEP named php_hold. Creating it fails when power management is off, and the two functions then do nothing. |
| power-save state | Read from the SDK host (phpbm_power_save()): true when the power-save option is on and power management started at boot. |
| Request-scoped runtime | Read from the SDK host (phpbm_runtime_request_scoped(), SDK 2.0.0): true in web-server. |
| Clock | esp_system_get_time(), microseconds since boot: the clock of CLOCK_MONOTONIC and of PHP's hrtime(). |
Own tasks (bm_hal_task_start()) |
xTaskCreatePinnedToCore(): priority is the PHP task's plus the requested offset, limited to 1..configMAX_PRIORITIES - 1; BM_HAL_CORE_ANY is tskNO_AFFINITY. The wrapper calls fn(arg) and then vTaskDelete(NULL). |
Memory by kind (bm_hal_alloc(), bm_hal_free()) |
heap_caps_malloc(): BM_HAL_MEM_INTERNAL asks for MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT; BM_HAL_MEM_EXTERNAL asks for MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT and falls back to internal RAM on a board without PSRAM (or with it full); BM_HAL_MEM_EXTERNAL_ONLY asks for the same PSRAM and returns NULL instead of falling back. bm_hal_free() is heap_caps_free(). |
Event pool lock (bm_hal_lock_*) |
A portMUX spinlock in internal RAM, taken with portENTER_CRITICAL_SAFE(), so tasks on both cores and ISRs can use it. |
AI usage
The policy for AI-assisted work on this package is in AI_USAGE.md, next to this README.
License
MIT.