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
-
$sdaintrequired GPIO number of the data line.
-
$sclintrequired GPIO number of the clock line.
-
$portintoptional, default-1 Hardware I2C port.
-1lets the HAL pick the first free port.-
$ownerintoptional, defaultBus::SYNC Who drives the wire:
Bus::SYNC(the PHP task, under a per-bus lock) orBus::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:
$ownerisBus::CORE1and the project enables thepower-saveoption;- a pin is already used by an open bus with other pins, or
$portis 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
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
- Device PHP API
- Bus ownership and power-save Reference
- Scan the bus Recipe