gregorj/serial-port

PHP interfaces and classes for serial port communication.

v2.0.0 2026-04-22 10:43 UTC

Requires

• php: ^8.1
• ext-curl: *
• ext-sockets: *
• gregorj/to-string: ^1.0
• psr/container: ^2.0

Requires (Dev)

• ext-pcntl: *
• ext-posix: *
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5
• squizlabs/php_codesniffer: ^4.0

MIT

• Gregor J.

README

PHP classes to connect to serial devices using streams or HTTP(S) gateways.

This library separates the command model from the transport:

• Command defines command payload, terminators, timeout, and response mapping
• Communication executes the command (StreamCommunication or HttpCommunication)
• transport is provided by either Stream (for sockets) or HttpTransport (for gateways)

Usage

You can either:

1. bridge a serial device to TCP (for example with pySerial tcp_serial_redirect) and use TcpStream
2. call an HTTP(S) serial gateway and use HttpCommunication

TCP stream communication

<?php

use GregorJ\SerialPort\Commands\BasicStringCommand;
use GregorJ\SerialPort\StreamCommunication;
use GregorJ\SerialPort\TcpStream;

$stream = new TcpStream('127.0.0.1', 5000);
$communication = new StreamCommunication($stream);

$command = new BasicStringCommand('HELLO', "\n", "\n");
$response = $command->invoke($communication);

echo $response?->get('response');

HTTP gateway communication

<?php

use GregorJ\SerialPort\Commands\BasicStringCommand;
use GregorJ\SerialPort\CurlTransport;
use GregorJ\SerialPort\HttpCommunication;

$communication = new HttpCommunication(
	new CurlTransport(),
	'https://example.com/query',
	'ttyUSB0',
	HttpCommunication::DEVICE_TYPE_WIRED
);

$command = new BasicStringCommand('HELLO', "\n", "\n");
$response = $command->invoke($communication);

echo $response?->get('response');

HttpCommunication::setTimeout() configures the serial-device response timeout and sends it to the gateway as deviceTimeoutMs. HTTP transport timeouts (connect and request) are configured separately in CurlTransport.

For the expected HTTP JSON contract and fields, see src/Http/JsonSerialGatewayContract.php.