Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-i2c

bm-ext MIT

Baremetal\I2c\Bus + \Device and the device-driver framework. Drivers are packages registering into the i2c_drivers registry; the platform side is an i2c-hal package.

bus: i2c

ext-i2c · Reference

Errors and limits

Every exception ext-i2c throws, and the fixed sizes and timeouts behind them.

ext-i2c throws plain \Exception for runtime failures, \RuntimeException for a board block onboard() cannot use, and \ValueError for invalid arguments; it defines no exception classes of its own. Messages end with the HAL's error name where one applies (on ESP32 an esp_err_t name such as ESP_ERR_TIMEOUT, or one of the two php-baremetal names below).

Exceptions

Message Thrown by Cause
cannot open I2C bus (sda=.. scl=..): ... new Bus(), Bus::onboard() Pin or port conflict, no free bus slot, or the HAL could not open the port.
board '<id>' has no '<block>' block Bus::onboard() The board does not describe that block.
board '<id>' has a <block> of type '<type>', not 'i2c' Bus::onboard() The block is not an I2C bus.
board '<id>': <block>.sda is missing, board '<id>': <block>.scl is missing Bus::onboard() The block has no such pin.
Bus::CORE1 is not available with the power-save option; use Bus::SYNC new Bus(), Bus::onboard() Bus::CORE1 with the power-save option on.
address 0x.. on this bus is already used by another driver Bus::device(), new Device(), a driver constructor The address is held by a device of another kind (raw vs driver, or another driver).
cannot add I2C device 0x..: ... Bus::device(), new Device() No free device slot, or the HAL could not attach it.
cannot init <driver> at 0x..: ... a driver constructor The chip did not answer, or answered with the wrong identity (ESP_ERR_NOT_FOUND).
I2C scan aborted, bus stuck (repeated timeouts on SDA=.. SCL=..): ... Bus::scan() Eight consecutive probe timeouts.
I2C read failed: ..., I2C write failed: ... read(), write() The transfer failed after its retry.
I2C readReg 0x.. failed: ..., I2C writeReg 0x.. failed: ... readReg(), writeReg() The transfer failed after its retry.
this device has no poller (driver has no poll block) poll(), sample(), drain() Raw device, or a driver without a sampler.
not polling; call poll() first sample() No sampler started for this device.
cannot start poller (too many, or out of memory) poll() Eight samplers already running, or no memory for the ring.
poll(): $every must be between 1 and $depth poll() \ValueError: $every is below 1 or above the depth of the device's ring (the first poll()'s, at most 256).
Poller::setHz(): $hz must be greater than 0 Poller::setHz() \ValueError: the rate is 0 or negative.
Cannot directly construct Baremetal\I2c\Poller new Poller() \Error: a Poller only comes from Device::poll().
poll(): unknown event class '...' or too many sources poll() The class is not loaded or cannot be instantiated (abstract class, interface, trait, enum), or the event source table (32 entries) is full.
poll() is not available in the web-server runtime: event sources need the event-driven runtime poll() with an event Called in web-server (a request or the init script), where nothing delivers events. Poll without an event, or use event-driven.
Trying to clone an uncloneable object of class ... clone A copy would not own the bus or the device: keep one object for each.
I2c\Bus is not initialised, I2c\Device is not initialised any method The object was created without its constructor running (for example a subclass that skipped it).

\ValueError is thrown for $owner not Bus::SYNC/Bus::CORE1, for an $address outside 0x08 to 0x77 (must be a 7-bit address between 0x08 and 0x77), for a device $hz outside 1 to 1000000 (must be between 1 and 1000000 (Hz); a driver constructor takes 0 as its default clock), and for a $length or a sampler $hz that is not greater than 0. Driver methods throw their own \Exception messages (for example QMI8658 accel read failed).

The php-baremetal error names: 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.

A read that does not throw is not proof that the data is right. I2C has no checksum, and SDA held low looks like an acknowledge, so a transfer that starts or ends while a line is shorted or a contact bounces can complete with wrong bytes: on the board, an MMC5603 returned [90, 90, 90] from mag() the moment SDA was tied to GND. Once the bus is stuck, transfers throw. When a wrong value matters, check readings for range or repeat them.

Limits

Limit Value Source
Open buses 4 ext-i2c bus table
Devices (raw and driver, all buses) 32 ext-i2c device table
Scan range and accepted addresses 0x08 to 0x77 ext-i2c
Device clock 1 Hz to 1 MHz ext-i2c
Default device clock 100 kHz (drivers set their own, 400 kHz for the packaged ones) ext-i2c, driver descriptor
Transaction timeout 1000 ms, then a bus reset and one retry esp32-i2c-hal
Probe timeout 50 ms, no retry esp32-i2c-hal
Scan abort after 8 consecutive probe timeouts esp32-i2c-hal
Wait for the executor queue (CORE1) 1000 ms esp32-i2c-hal
Background samplers 8 in the whole firmware esp32-executor
Sample size up to 64 bytes esp32-executor
Ring depth 1 to 256 samples (default 64) esp32-executor
Samples returned by one drain() 256 ext-i2c
Event sources 32 entries, shared with every ext-events source; one class polled with both coalesce values takes two ext-events

Addresses are 7-bit; 10-bit addressing is not supported. Tables are never freed: buses and devices stay open until the board restarts.

Related