Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/esp32-i2c-hal

bm-hal MIT

ESP32 implementation of the neutral I2C HAL (bm_i2c_hal.h) over esp_driver_i2c, with CORE1 buses and pollers on esp32-executor.

platform: ESP32

The ESP32 side of ext-i2c: it implements the neutral I2C HAL (bm_i2c_hal.h, shipped by ext-i2c) over the ESP-IDF I2C master driver, and runs Bus::CORE1 buses and background samplers on esp32-executor. It adds no PHP API of its own.

Property Value
Type bm-hal
Platform esp32 (extra.baremetal.platform)
Provides php-baremetal/i2c-hal
Requires php-baremetal/esp32-executor
ESP-IDF components (idf-requires) esp_driver_i2c

Install

You do not require it. ext-i2c requires the virtual php-baremetal/i2c-hal, and conductor adds this package when the project's SDK is on the esp32 platform ("sdk": "esp32@^2.0"). Require the extension, or a driver:

bash
composer require php-baremetal/ext-i2c

The PHP API, limits and errors are documented in ext-i2c.

What it does on ESP32

  • Opening a bus. i2c_new_master_bus() on the requested port, or the first free one when the port is automatic, with a glitch filter of 7 clock cycles and the internal pull-ups on SDA and SCL. The bus is reset right after it opens.
  • Devices. Each device is added to its bus with 7-bit addressing and its own SCL clock.
  • Transactions. Every read, write and register access has a 1000 ms timeout. A transaction that ends in ESP_ERR_TIMEOUT or ESP_ERR_INVALID_STATE resets the bus and is retried once. A register write longer than 32 bytes allocates a temporary buffer.
  • Probe and scan. A probe waits 50 ms and is never retried. A scan probes each address in turn and gives up after 8 consecutive timeouts, resetting the bus, which ext-i2c reports as a stuck bus.
  • Ownership. A Bus::SYNC bus is used from the PHP task under a FreeRTOS mutex. A Bus::CORE1 bus is opened and used only on the executor task: calls from PHP are queued to it (waiting at most 1000 ms for a free queue slot) and run inline when already on that task, so its interrupt and all its traffic stay on one task. The executor is pinned to core 0.
  • Background sampling. poll() starts an executor poller that calls the driver's sample function at the requested rate; the sample function takes the bus lock (or runs inline on a CORE1 bus) itself. bm_i2c_hal_poll_pause() (i2c-hal 1.1) pauses and resumes it through executor_poll_pause().
  • Interrupt service. bm_i2c_hal_irq_start() (i2c-hal 1.2) configures the INT pin as an input with pull-up and a falling-edge interrupt through the events HAL (bm_hal_gpio_on_falling()), which installs the GPIO ISR service once. Each edge kicks an executor on-demand job (executor_irq_kick_from_isr(), IRAM-safe) that runs the driver's irq.service on the executor task, so the service may use the bus without a lock; kicks that arrive before it runs merge into one run, and its result is only logged. bm_i2c_hal_irq_after() and bm_i2c_hal_irq_pause() forward to executor_irq_after() and executor_irq_pause(). bm_i2c_hal_irq_stop() removes the pin's handler, then cancels the job (waiting out a running service). The package provides php-baremetal/i2c-hal 1.2.0 and needs php-baremetal/esp32-executor 1.1.1.
  • Errors. ext-i2c messages end with the esp_err_t name (ESP_ERR_TIMEOUT, ESP_ERR_NOT_FOUND, …) or with one of two php-baremetal texts: address already used by another driver on this bus and the port or a pin is already used by an I2C bus open with other pins.

It also provides bm_delay_ms(), the delay driver code uses during chip initialisation (vTaskDelay).

License

MIT.