README

An asynchronous PHP library for serial port communication built on ReactPHP.

Introduction

Zeran SerialPort is a modern PHP library that provides asynchronous serial port communication using ReactPHP's event loop. It supports various baud rates, parity settings, and platform-specific configurations for both Linux and Windows systems.

This library is ideal for applications that need to communicate with hardware devices through serial ports, such as:

IoT devices
Microcontrollers (Arduino, ESP32, etc.)
Industrial equipment
Legacy hardware with serial interfaces
Embedded systems

Requirements

PHP 8.1 or higher (uses PHP enums)
ReactPHP event loop
PSR-3 compatible logger (optional)
Appropriate permissions to access serial port devices

Installation

You can install the package via composer:

composer require zeran/serial-port

Basic Usage

Here's a simple example of how to use the library:

<?php

use React\EventLoop\Loop;
use Zeran\SerialPort\AsyncSerialPort;
use Zeran\SerialPort\SerialPortConfiguration;
use Zeran\SerialPort\Enum\BaudRateEnum;
use Zeran\SerialPort\Enum\EventEnum;

// Create event loop
$loop = Loop::get();

// Configure serial port
$config = new SerialPortConfiguration(
    device: '/dev/ttyUSB0',  // Change to your device path
    platform: PHP_OS,
    baud: BaudRateEnum::BAUD_115200
);

// Optional: Configure additional parameters
$config->dataBits = \Zeran\SerialPort\Enum\BitsEnum::DATA_BITS_8;
$config->stopBits = \Zeran\SerialPort\Enum\BitsEnum::STOP_BITS_1;
$config->parity = \Zeran\SerialPort\Enum\ParityEnum::PARITY_NONE;
$config->xon = false;
$config->octs = false;
$config->rts = false;
$config->dtr = false;
$config->chunkSize = 256;

// Create serial port with event handler
$serialPort = new AsyncSerialPort($config, $loop, function (EventEnum $event, $data) {
    switch ($event) {
        case EventEnum::DATA->value:
            echo "Received data: " . bin2hex($data) . PHP_EOL;
            break;
        case EventEnum::ERROR->value:
            echo "Error: " . $data->getMessage() . PHP_EOL;
            break;
        case EventEnum::CLOSE->value:
            echo "Port closed" . PHP_EOL;
            break;
        case EventEnum::WRITE->value:
            echo "Data written successfully" . PHP_EOL;
            break;
    }
});

try {
    // Open the serial port
    $serialPort->open();
    
    // Write data to the port
    $serialPort->write("AT\r\n");
    
    // Run the event loop
    $loop->run();
} catch (\Zeran\SerialPort\Exception\SerialPortException $e) {
    echo "Serial port error: " . $e->getMessage() . PHP_EOL;
}

Configuration

The SerialPortConfiguration class allows you to configure various aspects of the serial port:

Required Parameters

device: Path to the serial port device (e.g., /dev/ttyUSB0 on Linux or COM1 on Windows)
platform: Operating system platform (usually you can use PHP_OS)
baud: Baud rate (defaults to 115200)

Optional Parameters

parity: Parity mode (PARITY_NONE, PARITY_EVEN, PARITY_ODD, PARITY_MARK, or PARITY_SPACE)
stopBits: Number of stop bits (STOP_BITS_1 or STOP_BITS_2)
dataBits: Number of data bits (DATA_BITS_8 or DATA_BITS_9)
xon: Enable/disable software flow control
octs: Enable/disable hardware flow control
rts: Enable/disable RTS (Request to Send) signal
dtr: Enable/disable DTR (Data Terminal Ready) signal
chunkSize: Size of read chunks in bytes

Supported Baud Rates

The library supports the following baud rates through the BaudRateEnum:

9600
14400
19200
38400
56000
57600
115200
128000
230400
256000

Example:

use Zeran\SerialPort\Enum\BaudRateEnum;

$config = new SerialPortConfiguration(
    device: '/dev/ttyUSB0',
    platform: PHP_OS,
    baud: BaudRateEnum::BAUD_9600
);

Events

The library provides event-based communication through a callback function. The following events are available:

EventEnum::DATA: Received data from the serial port
EventEnum::ERROR: An error occurred
EventEnum::OPEN: Port has been opened
EventEnum::CLOSE: Port has been closed
EventEnum::WRITE: Data has been written to the port

API Reference

AsyncSerialPort

Main class for serial port communication.

Methods

__construct(SerialPortConfiguration $configuration, LoopInterface $loop, callable $callback = null): Create a new serial port instance
open(): Open the serial port
close(): Close the serial port
write(string $message): Write data to the serial port
isOpened(): Check if the serial port is open

SerialPortConfiguration

Class for configuring the serial port parameters.

Properties

device: Device path
platform: Operating system platform
baud: Baud rate (from BaudRateEnum)
parity: Parity mode (from ParityEnum)
stopBits: Number of stop bits (from BitsEnum)
dataBits: Number of data bits (from BitsEnum)
xon: Software flow control
octs: Hardware flow control
rts: RTS signal
dtr: DTR signal
chunkSize: Read chunk size

Advanced Usage

Using with PSR-3 Logger

The library supports PSR-3 logging through the LoggerAwareTrait:

use Psr\Log\LoggerInterface;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// Create a logger
$logger = new Logger('serial_port');
$logger->pushHandler(new StreamHandler('path/to/your.log', Logger::DEBUG));

// Pass it to the serial port
$serialPort = new AsyncSerialPort($config, $loop, $callback);
$serialPort->setLogger($logger);

Platform-Specific Considerations

Linux

On Linux, you may need to add your user to the dialout group to access serial ports without root privileges:

sudo usermod -a -G dialout $USER

You'll need to log out and log back in for the changes to take effect.

Windows

On Windows, you need to use COM port names (e.g., COM1, COM2, etc.) for the device path.

Troubleshooting

Common Issues

Permission denied: Ensure your user has permission to access the serial port.
Device not found: Verify the device path is correct. Use ls /dev/tty* on Linux or Device Manager on Windows.
Invalid configuration: Check that your baud rate, parity, and other settings match your device requirements.

Debugging

Enable debugging by setting a logger:

$logger = new Logger('serial_port');
$logger->pushHandler(new StreamHandler('php://stdout', Logger::DEBUG));
$serialPort->setLogger($logger);

License

The MIT License (MIT). Please see License File for more information.

zeran / async-serial-port

Maintainers

Details