PHPackages                             flat3/revpi - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. flat3/revpi

ActiveLibrary[Utility & Helpers](/categories/utility)

flat3/revpi
===========

Control package for the Revolution Pi

v1.0.6(10mo ago)21MITPHPPHP ^8.2

Since Jun 23Pushed 10mo agoCompare

[ Source](https://github.com/flat3/revpi)[ Packagist](https://packagist.org/packages/flat3/revpi)[ Docs](https://github.com/flat3/revpi)[ RSS](/packages/flat3-revpi/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (16)Versions (8)Used By (0)

RevolutionPi
============

[](#revolutionpi)

This package provides a comprehensive abstraction for interacting with Revolution Pi hardware (and virtualized devices) within a PHP application. It enables process image access, IO control, LED control, serial port management, and more, with a convenient and flexible API.

The package has specific support for Laravel, and Laravel Zero. It can also be used with plain PHP, although some functionality such as the auto-generation commands will not be available.

The package works with the built-in PHP 8.2 on the Debian Bookworm image shipped in the RevolutionPi. No extra extensions or configuration changes are required.

Features
--------

[](#features)

- **ProcessImage**: Full read/write access to PiControl variables.
- **Trait-based interface**: Add Revolution Pi capabilities to your own app classes via the `RevolutionPi` trait.
- **LED support**: Control and read RevPi device LEDs (color, position).
- **Serial communications**: Robust non-blocking serial port abstraction for baud rate, parity, stop/data bits, flags
- **Monitor/Observer**: Register IO monitor callbacks for change detection.
- **Magic method & attribute support**: Easy, expressive access to IO variables, matching your PiCtory configuration.
- **Remote (WebSocket/RPC) and Virtual device support**.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Simplified interface](#simplified-interface)
    - [Accessing IO variables](#accessing-io-variables)
    - [Monitoring IO variables](#monitoring-io-variables)
    - [Process image](#process-image-low-level)
    - [LED control](#led-control)
    - [Serial port access](#serial-port-access)
- [Remote interface](#remote-interface)
- [Low-level interface](#low-level-interface)
    - [Hardware devices (PiControl, Terminal)](#hardware-devices-picontrol-terminal)
    - [ProcessImage interface](#processimage-interface)
    - [SerialPort interface](#serialport-interface)
    - [Monitoring with custom monitors](#monitoring-with-custom-monitors)
- [Deployment](#deployment)
- [Example: Polling and running the event loop](#example-polling-and-running-the-event-loop)
- [CLI Commands](#cli-commands)
- [License](#license)

---

Installation
------------

[](#installation)

**Require with Composer**

```
composer require flat3/revpi

```

Out of the box `revpi` pulls in only the required packages.

**To include the PHP class generator**

```
composer require --dev nette/php-generator

```

**To include websocket support**

```
composer require amphp/websocket-server amphp/websocket-client

```

---

Quick start
-----------

[](#quick-start)

`flat3/revpi` makes heavy use of the Laravel service container. All concrete implementations can be resolved from interfaces. Code should either be run *on* the RevolutionPi device, or via an IDE that can run code remotely like PhpStorm.

Note that Laravel Zero does not use package auto-discovery. You will need to add this package's service provider to your `config/app.php`.

```
  use Flat3\RevPi\Interfaces\Module;
  use Flat3\RevPi\Led\LedColour;
  use Flat3\RevPi\Led\LedPosition;

  $pi = app(Module::class); // Resolved from the interface to the correct module type

  $pi->led(LedPosition::A1)->set(LedColour::Red);
  print_r($pi->led(LedPosition::A1)->get());
```

---

Simplified Interface
--------------------

[](#simplified-interface)

It's recommended to generate a device-specific class from your exported PiCtory JSON. This provides IDE auto-completion for all IO variables as strongly typed methods and documented properties.

1. **Export your configuration from the PiCtory web interface as a project file**
    (e.g. `pictory.rsc`)
2. **Generate the PHP class**

```
  php artisan revpi:generate pictory.rsc MyPi
```

This creates `app/MyPi.php`.

3. **Use your class**

```
  use Flat3\RevPi\Interfaces\Module;
  use Flat3\RevPi\Interfaces\SerialPort;
  use Flat3\RevPi\Led\LedColour;
  use Flat3\RevPi\Led\LedPosition;
  use Flat3\RevPi\Monitors\DigitalMonitor;
  use Flat3\RevPi\SerialPort\BaudRate;
  use Flat3\RevPi\SerialPort\LocalFlag;
  use Illuminate\Console\Command;
  use Revolt\EventLoop;

  $pi = new \App\MyPi;

  // Create an instance of the serial port that loops the input back to the output
  $port = $pi->serialPort();
  $port->setSpeed(BaudRate::B576000);
  $port->clearFlag(LocalFlag::CanonicalInput);
  $port->onReadable(function (SerialPort $port) {
      $port->write($port->read(1024));
  });

  // Monitor the core temperature, writing updated values to the serial port
  $pi->Core_Temperature()->monitor(new DigitalMonitor, function ($value) use ($port) {
      $port->write($value."\n");
  });

  // Start polling
  $pi->module()->resume();

  // Start the event loop
  EventLoop::run();
```

### Accessing IO Variables

[](#accessing-io-variables)

Assuming your PiCtory-exported class has an input named `input1` and an output named `output1`:

```
$pi = new \App\MyPi;

// Read input (as property)
$level = $pi->input1; // int|bool

// Or as a method (returns InputIO object)
$input = $pi->input1();
$currentValue = $input->get();

// Read output
$currentStatus = $pi->output1;

// Set output (as property)
$pi->output1 = true;

// Or as a method (returns OutputIO object)
$pi->output1()->set(1);

// Reset output to its default value
$pi->output1()->reset();
```

### Monitoring IO Variables

[](#monitoring-io-variables)

The monitor will cause the callback to be called whenever the monitored value changes.

```
use Flat3\RevPi\Monitors\DigitalMonitor;

$pi = new \App\MyPi;

$pi->input1()->monitor(new DigitalMonitor, function($newValue) {
    // React to input1 changes
    logger("input1 changed: $newValue");
});
```

#### Monitor::debounce

[](#monitordebounce)

Configures the monitor to fire **only after changes stop** for the given interval (in milliseconds).

```
$pi->input1()->monitor((new DigitalMonitor)->debounce(200), function($value) {
    // Handle change after quiet period
});
```

#### Monitor::throttle

[](#monitorthrottle)

Configures the monitor to fire **at most once per interval** (in milliseconds).

```
$pi->input1()->monitor((new DigitalMonitor)->throttle(200), function($value) {
    // Handle change no more than every 200ms
});
```

### Process Image (Low-Level)

[](#process-image-low-level)

Get the raw process image interface for advanced access:

```
$image = $pi->processImage();

$value = $image->readVariable('input1');
$image->writeVariable('output1', 1);
$dump = $image->dumpImage(); // Raw string of process image data
$info = $image->getDeviceInfo(); // Information about the base module
$infoList = $image->getDeviceInfoList(); // Information about all expansion modules
```

### LED Control

[](#led-control)

```
use Flat3\RevPi\Led\LedColour;
use Flat3\RevPi\Led\LedPosition;

// Set LED A1 to green
$pi->led(LedPosition::A1)->set(LedColour::Green);

// Get current LED color (as enum)
$current = $pi->led(LedPosition::A1)->get(); // LedColour instance

// Turn an LED off
$pi->led(LedPosition::A1)->off();
```

### Serial Port Access

[](#serial-port-access)

```
use Flat3\RevPi\SerialPort\BaudRate;

// Open default serial port
$port = $pi->serialPort();

// Or specify device path:
$port = $pi->serialPort('/dev/ttyRS485-1');

// Configure the port:
$port->setSpeed(BaudRate::B9600);
$port->setParity(Parity::Even);
$port->setDataBits(DataBits::CS8);

// Write and read
$port->write("Hello, RevPi!");
$response = $port->read(128); // up to 128 bytes

// Register event handler for readable data
$port->onReadable(function (SerialPort $port) {
    echo "Serial received: " . $port->read(1024) . "\n";
});

// Flush or break
$port->flush(QueueSelector::Both);
$port->break();
```

---

Remote interface
----------------

[](#remote-interface)

You can communicate with a *remote* RevPi device via a WebSocket by calling the `remote` method on the client before using the module.

```
use Flat3\RevPi\RevolutionPi;

$pi = new \App\MyPi;

// Adding the remote call creates a connection to a device
$pi->remote('ws://10.1.2.3:12873');

// From now, other methods act remotely:
$pi->output1 = 1;
$status = $pi->input2;
$pi->led(LedPosition::A1)->set(LedColour::Cyan);
```

The remote device should listen for incoming connections, use `php artisan revpi:listen` to start the server on the device.

Remote devices support the same features that local devices do, including reading and writing to the process image, using the serial ports and setting up change monitors.

Out of the box the package does not provide for authentication or encryption. These can be added by creating a more complex websocket handshake object and passing it to the `remote` method. On the server-side, the basic `revpi:listen`code can be modified to support encryption and authentication.

---

Low-level interface
-------------------

[](#low-level-interface)

### Hardware Devices (PiControl, Terminal)

[](#hardware-devices-picontrol-terminal)

You can inject or instantiate the underlying devices (see `Flat3\RevPi\Interfaces\Hardware\*`) for advanced operations, e.g. binary FFI device IO, custom IOCTLs, etc.

```
$picontrol = app(\Flat3\RevPi\Interfaces\Hardware\PiControl::class);
$terminal = app(\Flat3\RevPi\Interfaces\Hardware\Terminal::class);
```

### ProcessImage Interface

[](#processimage-interface)

Everything required for direct process image manipulation:

```
$image = app(\Flat3\RevPi\Interfaces\ProcessImage::class);

$value = $image->readVariable('SomeName');
$image->writeVariable('OtherVar', 123);
```

### SerialPort Interface

[](#serialport-interface)

Inject or use via the module interface.

```
$port = app(\Flat3\RevPi\Interfaces\SerialPort::class); // Usually you want $pi->serialPort(...)
```

### Monitoring with Custom Monitors

[](#monitoring-with-custom-monitors)

If you want to create a custom monitor:

```
use Flat3\RevPi\Monitors\Monitor;

class MyMonitor extends Monitor {
    public function evaluate(int|bool $next): bool {
        // Implement custom transition/action logic here
        // e.g. if crossing a threshold
        // Return true if the monitor has detected sufficient change
    }
}

// Register:
$pi->module()->monitor('input1', new MyMonitor, function($newValue) {
    // Callback logic
});
```

---

Deployment
----------

[](#deployment)

The package has been specifically designed to work with [Laravel Zero](https://laravel-zero.com). Using the [standalone application](https://laravel-zero.com/docs/build-a-standalone-application)feature will convert your RevolutionPi project into a single executable file that can be started automatically when the base module boots up.

---

Example: Polling and running the event loop
-------------------------------------------

[](#example-polling-and-running-the-event-loop)

Typically you'll want to run your polling/event loop. The package provides an artisan command (see below) or call from code:

```
use Revolt\EventLoop;

$pi = new \App\MyPi;

$pi->repeat(1, function($pi) {
    // This is called every second
    logger("Current value is: " . $pi->input1);
});

EventLoop::run();
```

Or as a CLI command:

```
php artisan revpi:run
```

---

CLI Commands
------------

[](#cli-commands)

This package includes artisan commands (`php artisan revpi`):

- `revpi:generate  [class]`
    Generate a typed PHP class for your device from your pictory export.
- `revpi:run`
    Run your polling/event loop (call `resume()` and enter main loop).
- `revpi:led:get `
    Display current color of the chosen LED.
- `revpi:led:set  `
    Set a given LED (positions: a1–a5; colors: off, red, green, orange, blue, magenta, cyan, white).
- `revpi:info`
    List available device(s) and their info/status.
- `revpi:dump `
    Dump the current process image binary to a file.
- `revpi:listen [--address=0.0.0.0] [--port=12873]`
    Run the JSON-RPC/WS server for remote connections.

---

License
-------

[](#license)

[MIT](LICENSE)
Flat3/RevPi, 2025.

---

Further Reading
---------------

[](#further-reading)

- [Revolution Pi Documentation](https://revolutionpi.com/)
- [PiCtory Configuration Tool](https://revolutionpi.com/tutorials/pictory/)
- [Laravel Documentation](https://laravel.com/docs/)
- [Amp](https://amphp.org/)
- [FFI Manual (PHP)](https://www.php.net/manual/en/book.ffi.php)

---

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance53

Moderate activity, may be stable

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

7

Last Release

324d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/67b55562fe987d2fcbb682d82a5cf0c92375abc6adf8be8a658da3ca31def862?d=identicon)[chrislloyd403](/maintainers/chrislloyd403)

---

Top Contributors

[![27pchrisl](https://avatars.githubusercontent.com/u/6286310?v=4)](https://github.com/27pchrisl "27pchrisl (60 commits)")

---

Tags

raspberrypirevolutionpilaravelrevolutionpirevpikunbus

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/flat3-revpi/health.svg)

```
[![Health](https://phpackages.com/badges/flat3-revpi/health.svg)](https://phpackages.com/packages/flat3-revpi)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[laravel-zero/framework

The Laravel Zero Framework.

3371.4M369](/packages/laravel-zero-framework)[psalm/plugin-laravel

Psalm plugin for Laravel

3274.9M308](/packages/psalm-plugin-laravel)[tightenco/jigsaw

Simple static sites with Laravel's Blade.

2.2k438.5k29](/packages/tightenco-jigsaw)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)