README

dept-of-scrapyard-robotics/gpio — GPIO module for the ScrapyardIO Framework.

Provides an object-oriented PHP interface to Linux GPIO character devices (/dev/gpiochip*) via the ext-gpio PHP extension. Supports configuring lines as inputs or outputs, setting line bias, and listening for rising/falling edge events.

Requirements

PHP ^8.3
ext-gpio 0.1.0 (Zephir extension — see DeptOfScrapyardRobotics/GPIO for build & install instructions)
dept-of-scrapyard-robotics/fd 0.3.0
Linux with GPIO char device support (/dev/gpiochip0 or similar)

Installation

composer require dept-of-scrapyard-robotics/gpio

Quick Start

Output — driving a pin high or low

use ScrapyardIO\GPIO\GPIO;
use ScrapyardIO\GPIO\Exceptions\GPIOException;

try {
    $gpio = (new GPIO())->usePin(6)->asOutput('my-app');
    $gpio->high(); // drive pin 6 high
    $gpio->low();  // drive pin 6 low
} catch (GPIOException $e) {
    echo $e->getMessage();
}

Input — reading a button with edge events

use ScrapyardIO\GPIO\GPIO;
use ScrapyardIO\GPIO\Enums\GPIOLineEvent;
use ScrapyardIO\GPIO\Exceptions\GPIOException;

try {
    $gpio = (new GPIO())->usePin(18)
        ->asInput('my-app')
        ->hasEvent(GPIOLineEvent::EDGE_FALLING)
        ->hasEvent(GPIOLineEvent::EDGE_RISING)
        ->build();

    fwrite(STDOUT, "Trigger your button.\n\n");
    var_dump($gpio->listen());
} catch (GPIOException $e) {
    echo $e->getMessage();
}

API Reference

`GPIO`

The entry point. Opens a GPIO chip device node.

new GPIO(string $chip = '/dev/gpiochip0')

Method	Returns	Description
`usePin(int $pin)`	`GPIOConnectionBuilder`	Begin configuring a line by pin number
`useLine(int $pin)`	`GPIOConnectionBuilder`	Alias for `usePin()`
`chipInfo()`	`array`	Returns chip metadata from the kernel

Throws GPIOException if the requested line is already in use or unavailable.

`GPIOConnectionBuilder`

Fluent builder returned by GPIO::usePin(). Configure the line before finalizing it.

Method	Returns	Description
`asInput(string $consumer, int $eventBufferSize = 64)`	`static`	Configure as an input; must call `build()` to finalize
`asOutput(string $consumer = 'scrapyard-io')`	`GPIOOutput`	Configure and open as an output immediately
`hasEvent(GPIOLineEvent $edge)`	`static`	Subscribe to a rising or falling edge event (input only)
`addBias(GPIOLineBias $bias)`	`static`	Set pull-up, pull-down, or disabled bias (input only)
`build()`	`GPIOInput\|GPIOOutput`	Finalize the configuration and open the line

`GPIOInput`

Returned by ->asInput(...)->build().

Method	Returns	Description
`read()`	`int`	Raw line value (`0` or `1`)
`isHigh()`	`bool`	`true` if line is high
`isLow()`	`bool`	`true` if line is low
`listen()`	`?array`	Block until the next edge event; returns event data
`getEvents()`	`array`	Drain buffered events (non-blocking mode) as `GPIOEvent[]`
`nonblocking()`	`static`	Switch the line FD to non-blocking I/O

`GPIOOutput`

Returned by ->asOutput(...) or ->build() when configured as output.

Method	Returns	Description
`high()`	`void`	Drive the line high
`low()`	`void`	Drive the line low

Enums

`GPIOLineBias`

Controls the electrical bias applied to an input line.

Case	Linux Flag	Description
`NONE`	—	No bias (default)
`PULL_UP`	`GPIO_V2_LINE_FLAG_BIAS_PULL_UP`	Internal pull-up resistor
`PULL_DOWN`	`GPIO_V2_LINE_FLAG_BIAS_PULL_DOWN`	Internal pull-down resistor
`DISABLED`	`GPIO_V2_LINE_FLAG_BIAS_DISABLED`	Bias explicitly disabled

`GPIOLineEvent`

Edge types for event subscriptions on inputs.

Case	Linux Flag	Description
`EDGE_RISING`	`GPIO_V2_LINE_FLAG_EDGE_RISING`	Triggered on low → high transition
`EDGE_FALLING`	`GPIO_V2_LINE_FLAG_EDGE_FALLING`	Triggered on high → low transition

Exceptions

All exceptions are of type ScrapyardIO\GPIO\Exceptions\GPIOException.

Factory method	Thrown when
`gpioChipNotAvailable(int $chip)`	The chip device cannot be opened
`gpioPinLineNotAvailable(int $line, int $chip)`	The requested line is already consumed or does not exist
`missingGpioChipLine()`	The line file descriptor could not be obtained
`missingGpioChip()`	The chip file descriptor is missing

Examples

See the examples/ directory:

gpio-button-example.php — reading a button via edge events on pin 18
gpio-fan-example.php — driving an output (fan/trigger) on pin 6

scrapyard-io / gpio

Maintainers

Package info

Statistics

Security