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

Bus

Baremetal\I2c\Bus is a handle onto one I2C master bus. Same pins, same bus: constructing it twice is safe and cheap.

Baremetal\I2c\Bus opens an I2C master on an SDA/SCL pin pair. The bus lives for the whole run: a second new Bus() with the same pins (and a matching or automatic port) returns the same underlying bus, so libraries can each construct their own Bus object without coordinating.

Constructor

new Bus(int $sda, int $scl, int $port = -1, int $owner = Bus::SYNC)

Public method.

Parameters

$sda int required

GPIO number of the data line.

$scl int required

GPIO number of the clock line.

$port int optional, default -1

Hardware I2C port. -1 lets the HAL pick the first free port.

$owner int optional, default Bus::SYNC

Who drives the wire: Bus::SYNC (the PHP task, under a per-bus lock) or Bus::CORE1 (the executor task). Honoured only when the bus is first created; later constructions with the same pins get the existing bus.

Throws \ValueError when $owner is neither constant, and \Exception when:

  • $owner is Bus::CORE1 and the project enables the power-save option;
  • a pin is already used by an open bus with other pins, or $port is taken by a bus on other pins;
  • all four bus slots are in use, or the HAL cannot open the port.

The bus is reset right after it opens, which frees a slave left holding SDA by an interrupted transfer.

onboard()

Bus::onboard(string $block = 'i2c', int $owner = Bus::SYNC): Bus

Public method. Returns Bus.

Opens the bus the board describes in its i2c block (sda and scl), the same as new Bus($sda, $scl, -1, $owner) with the pins read from the board. $block names another block of the same kind, and $owner is as in the constructor.

$bus = Bus::onboard();

Throws \RuntimeException board '<id>' has no '<block>' block when the board lacks the block, board '<id>' has a <block> of type '<type>', not 'i2c' when the block is not an I2C bus, and board '<id>': <block>.sda is missing (or .scl) when a pin is not set. Opening the bus throws what the constructor throws.

Constants

Constant Value Meaning
Bus::SYNC 0 The calling PHP task runs each transaction while holding the bus lock. Default.
Bus::CORE1 1 The executor task owns the wire; every transaction is handed to it and the caller waits.

See Bus ownership and power-save for when to pick CORE1.

device()

Bus::device(int $address, int $hz = 100000): Device

Public method. Returns Device.

Attaches the chip at 7-bit $address (0x08 to 0x77) with clock $hz (1 to 1000000) and returns a raw Device; values out of range throw \ValueError. Same as new Device($bus, $address, $hz).

Devices are kept per bus and address: asking again for an address returns the existing device (the new $hz is ignored). If a driver class already holds that address, it throws address 0x.. on this bus is already used by another driver, and the reverse holds too: a driver cannot be constructed on an address taken by a raw device.

scan()

Bus::scan(): array

Public method. Returns array.

Probes every address from 0x08 to 0x77 and returns the ones that answered, as [address => ['driver' => ?string]]. driver is the registry name of the driver mounted at that address ('qmi8658'), or null for a raw device or nothing constructed yet.

php scan
<?php
use Baremetal\I2c\Bus;

$bus = new Bus(sda: 11, scl: 10);

foreach ($bus->scan() as $address => $info) {
    printf("0x%02X %s\n", $address, $info['driver'] ?? '(no driver)');
}

Each probe waits at most 50 ms. After eight consecutive timeouts the sweep stops, resets the bus and throws I2C scan aborted, bus stuck (repeated timeouts on SDA=.. SCL=..): usually missing pull-ups or swapped pins. The sweep runs under the bus lock (SYNC) or on the executor (CORE1), like any transaction.

Related