dept-of-scrapyard-robotics/generic-buttons

Drive basic on/off GPIO buttons with PHP

dev-main 2026-07-12 21:07 UTC

Requires

• php: ^8.3
• bare-metal/actuation: ^0.5.0
• bare-metal/contracts: ^0.5.0
• scrapyard-io/nuts-and-bolts: ^0.5.0
• waveforms/digital: ^0.5.0

Suggests

• microscrap/scrapyard-posix-drivers: ^0.5.0 - for driving over DigitalPins with LineBias
• microscrap/scrapyard-usb-drivers: ^0.5.0 - for USB digital input carriers

MIT

• Angel Gonzalez

• framework
• GPIO
• buttons
• scrapyard-io

Published on Packagist.org on 2026-07-12 21:09 UTC

README

Basic on/off GPIO buttons with PHP

PHP package for simple digital buttons (momentary switches to GND or VCC). It sits on the ScrapyardIO GPIO stack and plugs into the BareMetal HumanInput components (BasicButton, DigitalButtonPad).

Compatible Digital Interfaces

Buttons are read from a digital input pin. Most switches to ground need an internal pull-up.

You can interface with them the following ways:

• A Linux single-board computer's exposed GPIO pins using the POSIX / libgpiod carrier (posix) with LineBias::PULL_UP
• An MPSSE-enabled USB-to-serial device such as an FT232H using the USB carrier (usb)

Dependencies

This package makes use of modules within:

• The ScrapyardIO Framework

For GPIO buttons you also need:

• POSI Extension v^0.4.0 or newer
• Microscrap POSIX Drivers (posix carrier)

Installing from Composer

composer require dept-of-scrapyard-robotics/generic-buttons

Basic Usage

Active-low button with pull-up (POSIX)

<?php

use GPIO\Common\GPIO;
use GPIO\Contracts\Digital\LineBias;
use BareMetal\Actuation\HumanInput\BasicButton;
use BareMetal\Actuation\HumanInput\DigitalButtonPad;
use DeptOfScrapyardRobotics\Actuators\GenericButtons\GenericButton;

$input = GPIO::digitalIn('posix')
    ->device(4)              // gpiochip4 on Raspberry Pi 5 (RP1)
    ->pin(17)
    ->name('btn-a')
    ->lineBias(LineBias::PULL_UP)
    ->create();

$ic = new GenericButton($input);                 // active-low by default
// $ic = new GenericButton($input, active_low: false);

$button = new BasicButton('A', $ic);
$pad = new DigitalButtonPad([$button]);

$pad->poll();

if ($pad->isPressed('A')) {
    // rising edge this frame
}

if ($pad->isHolding('A')) {
    // held past the default 500ms threshold
}

$input->close();

Multiple GPIO buttons on one pad

<?php

use BareMetal\Actuation\HumanInput\BasicButton;
use BareMetal\Actuation\HumanInput\DigitalButtonPad;
use DeptOfScrapyardRobotics\Actuators\GenericButtons\GenericButton;

$pad = new DigitalButtonPad([
    new BasicButton('A', new GenericButton($inputA)),
    new BasicButton('B', new GenericButton($inputB)),
]);

$pad->poll();

if ($pad->chord('A', 'B')) {
    // both down
}

Notes

• Configure LineBias on the DigitalInput factory — GenericButton does not set bias itself.
• Default polarity is active-low (line reads low when pressed), matching pull-up + switch-to-GND wiring.
• Wrap GenericButton in BasicButton for edge / hold semantics, then inject into DigitalButtonPad.