ext-i2c · PHP API
Device
Baremetal\I2c\Device is one chip on a bus: raw reads and writes, register access, and the background sampler that driver classes use.
A Device addresses one 7-bit address on a Bus. Get one from Bus::device() or construct it. Every
driver class (Baremetal\I2c\Driver\Qmi8658, …) extends Device, so the raw methods below also work on a
driver object, next to its typed methods.
The object is a handle into a table that lives for the whole run: dropping it never touches the hardware, and asking for the same address again returns the same device.
Constructor
new Device(Bus $bus, int $address, int $hz = 100000)
Public method.
Parameters
-
$busBusrequired The bus the chip is wired to.
-
$addressintrequired 7-bit address, e.g.
0x51, from0x08to0x77; anything else throws\ValueError(the other values are reserved by the I2C specification).-
$hzintoptional, default100000 SCL clock for this device, 1 to 1000000; anything else throws
\ValueError. Ignored when the device already exists.
Throws \Exception when a driver already holds the address, when all 32 device slots are in use, or when the
HAL cannot attach the device.
Methods
Device::probe(): bool
Public method. Returns bool.
true when the chip acknowledges its address (50 ms timeout). Never throws for a missing chip.
Device::read(int $length): string
Public method. Returns string.
Reads $length bytes from the chip. \ValueError when $length is not greater than 0.
Device::write(string $data): void
Public method. Returns void.
Writes the bytes of $data in one transaction.
Device::readReg(int $reg, int $length = 1): string
Public method. Returns string.
Writes the register address $reg, then reads $length bytes (a combined write-read). Returns a binary
string: use ord() for one byte, unpack() for more. \ValueError when $length is not greater than 0.
Device::writeReg(int $reg, string|int $value): void
Public method. Returns void.
Writes to register $reg. An int writes one byte (the low 8 bits); a string writes all its bytes after the
register address.
Device::poll(int $hz, int $depth = 64, ?string $event = null, bool $coalesce = true, int $every = 1): Baremetal\I2c\Poller
Public method. Returns Baremetal\I2c\Poller.
Device::sample(): ?string
Public method. Returns ?string.
Device::drain(): array
Public method. Returns array.
Background sampling, available on driver classes whose driver declares a sampler. A raw Device throws
this device has no poller (driver has no poll block). See
Background sampling and events.
Errors
A failed transfer throws \Exception with the operation and the HAL's error name (an esp_err_t name on
ESP32), for example I2C readReg 0x00 failed: ESP_ERR_TIMEOUT. A transaction that times out (or
finds the bus in an invalid state) has already been retried once after a bus reset. Full list in
Errors and limits.
Example
<?php
use Baremetal\I2c\Bus;
$rtc = (new Bus(sda: 11, scl: 10))->device(0x51);
if (!$rtc->probe()) {
exit("no chip at 0x51\n");
}
$raw = $rtc->readReg(0x04, 3); // seconds, minutes, hours (BCD)
[, $s, $m, $h] = unpack('C3', $raw);
$bcd = fn (int $v): int => ($v >> 4) * 10 + ($v & 0x0F);
printf("%02d:%02d:%02d\n", $bcd($h & 0x3F), $bcd($m & 0x7F), $bcd($s & 0x7F));
Related
- Bus PHP API
- Background sampling and events PHP API
- Read and write registers Recipe