Perfect Serial Browser API Documentation

• API Overview
• Authentication
• Port Management
• Connection Control
• Data Communication
• Logging Control
• Replay System
• WebSocket Protocol
• Error Handling
• Testing
• Integration Examples

API Overview

Perfect Serial Browser provides a REST API for programmatic access to serial port functionality. All endpoints return JSON responses and follow RESTful conventions.

Base URL

All API endpoints are relative to http://localhost:3000/api/.

Content Type

All requests should use Content-Type: application/json for POST and PUT requests.

Response Format

Responses are JSON with the following structure:

{
  "success": true|false,
  "data": {...},
  "error": "error message" // only present on errors
}

Authentication

Perfect Serial Browser API runs on localhost and does not currently require authentication. Future versions may include API key authentication for remote access.

Port Management

GET /ports

List all available serial ports on the system.

Response example:

{
  "success": true,
  "data": [
    {
      "path": "/dev/ttyUSB0",
      "type": "Unknown",
      "vid": 1027,
      "pid": 24577,
      "serial_number": "A50285BI",
      "manufacturer": "FTDI",
      "product": "FT232R USB UART"
    }
  ]
}

GET /ports/{port_path}

Get detailed information about a specific port.

Parameter	Type	Description
port_path	string	URL-encoded port path (e.g. %2Fdev%2FttyUSB0).

Connection Control

POST /ports/{port_path}/connect

Connect to a serial port with specified parameters.

Request body:

{
  "baud_rate": 9600,
  "data_bits": "Eight",
  "parity": "None",
  "stop_bits": "One",
  "flow_control": "None"
}

Parameter	Type	Options
baud_rate	integer	110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200, 128000, 256000
data_bits	string	"Five", "Six", "Seven", "Eight"
parity	string	"None", "Odd", "Even"
stop_bits	string	"One", "Two"
flow_control	string	"None", "Software", "Hardware"

POST /ports/{port_path}/disconnect

Disconnect from a serial port.

GET /ports/{port_path}/status

Get the current connection status of a port.

Data Communication

POST /ports/{port_path}/send

Send data to a connected serial port.

Request body:

{
  "data": "Hello World\r\n",
  "format": "text"
}

Parameter	Type	Description
data	string	Data to send. Format depends on the format field.
format	string	"text", "hex", or "binary".

GET /ports/{port_path}/receive

Get received data from a connected port.

Query parameters:

Parameter	Type	Description
since	string	ISO timestamp to get data since (optional).
limit	integer	Maximum number of messages to return (default: 100).

Logging Control

POST /ports/{port_path}/logging/start

Start logging for a specific port.

POST /ports/{port_path}/logging/stop

Stop logging for a specific port.

GET /logs

List available log files.

GET /logs/{log_id}

Download a specific log file.

Replay System

GET /replays

List available replay files.

POST /replays/{replay_id}/play

Start replay of a recorded session.

Request body:

{
  "speed": 1.0,
  "port_path": "/dev/ttyUSB0"
}

WebSocket Protocol

Perfect Serial Browser provides real-time data streaming via WebSocket connections at ws://localhost:3000/ws.

Connection

const ws = new WebSocket('ws://localhost:3000/ws');

Message Format

All WebSocket messages are JSON formatted:

{
  "type": "data|status|error",
  "port": "/dev/ttyUSB0",
  "timestamp": "2024-01-01T12:00:00Z",
  "payload": {...}
}

Error Handling

The API uses standard HTTP status codes and returns detailed error information in the response body.

Common Status Codes

Code	Description
200	Success.
400	Bad request. Invalid parameters.
404	Not found. Port or resource not found.
409	Conflict. Port already in use.
500	Internal server error.

Error Response Format

{
  "success": false,
  "error": "Port /dev/ttyUSB0 is already in use"
}

Testing

The API can be tested using curl, Postman, or any HTTP client.

Example With curl

# List ports
curl http://localhost:3000/api/ports

# Connect to a port
curl -X POST http://localhost:3000/api/ports/%2Fdev%2FttyUSB0/connect \
  -H "Content-Type: application/json" \
  -d '{"baud_rate": 9600, "data_bits": "Eight", "parity": "None", "stop_bits": "One"}'

# Send data
curl -X POST http://localhost:3000/api/ports/%2Fdev%2FttyUSB0/send \
  -H "Content-Type: application/json" \
  -d '{"data": "Hello World\r\n", "format": "text"}'

Integration Examples

Python

import requests
import json

# List available ports
response = requests.get('http://localhost:3000/api/ports')
ports = response.json()['data']

# Connect to first available port
if ports:
    port_path = ports[0]['path']
    encoded_path = requests.utils.quote(port_path, safe='')

    connect_data = {
        'baud_rate': 9600,
        'data_bits': 'Eight',
        'parity': 'None',
        'stop_bits': 'One'
    }

    response = requests.post(
        f'http://localhost:3000/api/ports/{encoded_path}/connect',
        json=connect_data
    )

    if response.json()['success']:
        print(f"Connected to {port_path}")

JavaScript

// Fetch available ports
fetch('http://localhost:3000/api/ports')
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log('Available ports:', data.data);
    }
  });

// WebSocket connection for real-time data
const ws = new WebSocket('ws://localhost:3000/ws');
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};