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 · 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

$bus Bus required

The bus the chip is wired to.

$address int required

7-bit address, e.g. 0x51, from 0x08 to 0x77; anything else throws \ValueError (the other values are reserved by the I2C specification).

$hz int optional, default 100000

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 raw register access
<?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