I2C and sensors
Open an I2C bus on two pins, scan it, read chips, and let a driver sample a sensor in the background. Three drivers are packaged: an IMU, a magnetometer and a real-time clock.
ext-i2c is an I2C master. Baremetal\I2c\Bus
opens a bus on an SDA and an SCL pin, Baremetal\I2c\Device reads and writes one chip, and driver packages add
typed classes under Baremetal\I2c\Driver\.
A driver requires ext-i2c, so a driver alone is enough. ext-i2c also pulls in
ext-events, and the conductor adds the
esp32 HAL (esp32-i2c-hal).
Bus and scan
new Bus(int $sda, int $scl, int $port = -1, int $owner = Bus::SYNC) opens the bus. A second new Bus() with the
same pins returns the same bus, so libraries can each create their own object. Bus::scan() probes the
addresses 0x08 to 0x77 and returns the ones that answered, with the name of the driver mounted there.
The example 05-i2c-sensors/i2c-scan (board waveshare-esp32-s3-touch-lcd-1.85b, init-loop runtime, only
ext-i2c required):
Raw devices
Bus::device(int $address, int $hz = 100000): Device attaches a chip at a 7-bit address. A Device has
probe(), read(), write(), readReg() and writeReg(). Registers are binary strings: use ord() for one
byte and unpack() for more.
The drivers
| Package | Class | Default address | Clock | What it gives |
|---|---|---|---|---|
| imu-qmi8658 | Qmi8658 |
0x6B (0x6A when strapped) |
400 kHz | accel() in g, gyro() in degrees per second, temp() in degrees C |
| mag-mmc5603 | Mmc5603 |
0x30 |
400 kHz | mag() in microtesla, heading() in degrees (0 to 360, board flat, not calibrated), temp() |
| rtc-pcf85063 | Pcf85063 |
0x51 |
400 kHz | now() with year, month, day, hour, minute, second and valid; set() |
The constructor is new Qmi8658(Bus $bus, int $address = 0x6B, int $hz = 400000), and similarly for the others.
The constructor talks to the chip: it checks the identity and configures it, so it throws if nothing answers.
valid of the clock is false when it lost power: set the time only then, as in 05-i2c-sensors/rtc-pcf85063:
The other examples of the group use the same board: 05-i2c-sensors/mmc5603 and 05-i2c-sensors/compass (a
serial compass; the magnetometer is on SDA 7, SCL 8), and 05-i2c-sensors/rtc-clock.
Background sampling and events
A driver that has a sampler (Qmi8658 and Mmc5603) can read the chip on its own, without your code touching
the bus:
| Method | Meaning |
|---|---|
poll(int $hz, int $depth = 64, ?string $event = null) |
Start sampling at $hz into a ring of $depth samples (at most 256); the oldest are overwritten when it is full |
sample(): ?string |
The latest raw sample, or null |
drain(): array |
Every unread sample, oldest first, at most 256 per call |
decode(string $raw): array |
Turn a raw sample into numbers (accel and gyro for the IMU) |
With $event set to Baremetal\Sensor\Imu\SamplesReady::class, every stored sample also raises that event, which the
event-driven runtime delivers to your listener on the PHP task. The sampler itself runs on a separate executor
task. The example 05-i2c-sensors/imu-events requires ext-events, ext-i2c and imu-qmi8658:
If no event slot is free the event is dropped (and counted in Events::stats()), but the sample stays in the
ring, so a handler that calls drain() catches up. 05-i2c-sensors/imu-ws-stream sends the samples to a browser over a WebSocket.
Bus::SYNC and Bus::CORE1
The fourth argument of Bus says which task drives the wire. It is honoured only when the bus is first created.
| Owner | Who runs the transactions |
|---|---|
Bus::SYNC (default) |
The PHP task, under a lock per bus |
Bus::CORE1 |
The executor task: every call from PHP is queued to it and the PHP task waits |
The name describes the ownership mode, not the core: the executor task is pinned to core 0, and PHP runs on core 1.
Both behave the same from PHP. Pick CORE1 when the bus carries background samplers and you want your own
transactions serialised with them on one task. The example 05-i2c-sensors/i2c-core1 opens
new Bus(sda: 11, scl: 10, owner: Bus::CORE1), scans it and reads the IMU in loop().
With the power-save option on, new Bus(..., owner: Bus::CORE1) throws
Bus::CORE1 is not available with the power-save option; use Bus::SYNC. A sampler on a SYNC bus wakes
the chip once per period, so the board never sleeps longer than 1000 / $hz ms, and a running sampler keeps doing so:
stop it with the Poller that poll() returns, and start one only when you need it. See Power saving.
What the ESP32 does
| Behaviour | Detail |
|---|---|
| Opening a bus | On the requested port, or the first free one; internal pull-ups on SDA and SCL, glitch filter on, and the bus is reset right after it opens |
| Addressing | 7 bit only |
| Timeout | 1000 ms per transaction; a timeout or an invalid state resets the bus and retries once |
| Probe and scan | Each probe waits 50 ms; a scan stops after 8 consecutive timeouts and throws |
| Limits | 4 buses, 32 devices in all, 8 background samplers in the whole firmware, samples up to 64 bytes, 16 event source classes shared with ext-events |
| Rate | The sampling period is whole milliseconds, so rates above 1000 Hz run at 1000 Hz |
| Lifetime | Buses and devices stay open until the board restarts |
Common errors
| Message | Cause |
|---|---|
cannot open I2C bus (sda=.. scl=..): ... |
A pin or the port is used by another bus, no bus slot is free, or the port could not be opened |
I2C scan aborted, bus stuck (repeated timeouts on SDA=.. SCL=..): ... |
Missing pull-ups, swapped pins or a chip holding the line |
cannot init qmi8658 at 0x..: ESP_ERR_TIMEOUT |
No chip answers at that address (the driver name changes with the class) |
cannot init qmi8658 at 0x..: ESP_ERR_NOT_FOUND |
Something answered with the wrong identity |
address 0x.. on this bus is already used by another driver |
The address is held by a raw device or by another driver |
this device has no poller (driver has no poll block) |
poll() on a raw device or on Pcf85063 |
not polling; call poll() first |
sample() before poll() |
cannot start poller (too many, or out of memory) |
Eight samplers are already running |
The full API is on the ext-i2c package page; each driver package documents its own methods.