Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/esp32-events-hal

bm-hal MIT

ESP32 events HAL for ext-events: queue, timers, GPIO interrupts, sleep lock.

platform: ESP32

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:

bash
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.