Red-Serial

A cross-platform serial port communication library for Red, inspired by PySerial.

Features

• Cross-platform: Linux support (Windows coming in Phase 2)
• Dual API: High-level Red API and low-level Red/System API
• Full serial port control: Baudrate, data bits, parity, stop bits, flow control
• Control lines: DTR, RTS, CTS, DSR, CD, RI
• Timeouts: Configurable read/write timeouts
• Buffer management: Flush input/output, check available bytes

Project Structure

Red-Serial/
├── Red-Serial.red                # High-level Red API (user-facing)
├── system/
│   ├── serial-core.reds          # Common definitions
│   ├── serial-api.reds           # Public Red/System API
│   └── platforms/
│       └── serial-linux.reds     # Linux/POSIX driver
├── examples/
│   ├── example-red.red           # High-level Red example
│   ├── basic.reds                # Red/System example
│   └── esp32-adc-lines.reds      # ESP32 ADC reader
├── tests/
│   └── test-no-hardware.reds     # Unit tests (no hardware needed)
├── tools/
│   └── build.red                 # Build script
└── docs/
    └── STYLE-GUIDE.md            # Code style guide

Quick Start (Red - Recommended)

Red []

#include %Red-Serial.red

;-- Open serial port: 115200 baud, 8N1, 5 second timeout
port: open-serial/config/timeout "/dev/ttyUSB0" 115200 8 0 1 0 5000

if port [
    ;-- Read lines
    line: read-line-serial port
    print line
    
    ;-- Write data
    write-serial port "Hello World!"
    
    ;-- Read raw data
    data: read-serial port 100
    
    ;-- Close
    close-serial port
]

Quick Start (Red/System - Low-level)

Red/System []

#include %system/serial-api.reds

port: serial-new

if SERIAL_OK = serial-open port "/dev/ttyUSB0" [
    serial-configure port 115200 8 PARITY_NONE STOPBITS_1 FLOW_NONE
    
    serial-write-string port "AT^M^J"
    
    buffer: allocate 256
    bytes: serial-read port buffer 255
    
    serial-close port
    free buffer
]

serial-free port

API Reference

High-Level API (Red)

Port Management

Function	Description
open-serial device	Open port with defaults (9600 8N1)
open-serial/config device baud bits par stop flow	Open with full config
open-serial/timeout device ms	Open with custom timeout
close-serial port	Close port

Data Transfer

Function	Description
write-serial port data	Write string, binary, or byte
read-serial port size	Read up to size bytes
read-line-serial port	Read until newline
available-serial port	Bytes available to read

Buffer Control

Function	Description
flush-serial port	Flush both buffers
flush-serial/input port	Flush input buffer
flush-serial/output port	Flush output buffer
drain-serial port	Wait for transmission complete

Control Lines

Function	Description
set-dtr port state	Set DTR line
set-rts port state	Set RTS line
get-cts port	Get CTS state
get-dsr port	Get DSR state
get-cd port	Get Carrier Detect
get-ri port	Get Ring Indicator

Low-Level API (Red/System)

Function	Description
serial-new	Create port instance
serial-free port	Free port instance
serial-open port device	Open port
serial-close port	Close port
serial-configure port baud bits par stop flow	Configure port
serial-read port buffer size	Read bytes
serial-write port buffer size	Write bytes
serial-read-byte port	Read single byte
serial-write-byte port byte	Write single byte
serial-available port	Bytes available
serial-flush port input? output?	Flush buffers
serial-set-dtr port state	Set DTR line
serial-set-rts port state	Set RTS line
serial-get-cts port	Get CTS state
serial-get-dsr port	Get DSR state
serial-get-cd port	Get Carrier Detect
serial-get-ri port	Get Ring Indicator

Constants

Parity

parity-none  (0)    PARITY_NONE
parity-odd   (1)    PARITY_ODD
parity-even  (2)    PARITY_EVEN
parity-mark  (3)    PARITY_MARK
parity-space (4)    PARITY_SPACE

Stop Bits

stopbits-1   (1)    STOPBITS_1
stopbits-1.5 (15)   STOPBITS_1_5
stopbits-2   (2)    STOPBITS_2

Flow Control

flow-none    (0)    FLOW_NONE
flow-xonxoff (1)    FLOW_XONXOFF
flow-rtscts  (2)    FLOW_RTSCTS
flow-dsrdtr  (3)    FLOW_DSRDTR

Error Codes (Red/System)

SERIAL_OK              (0)   - Success
SERIAL_ERROR_OPEN      (-1)  - Failed to open port
SERIAL_ERROR_CLOSE     (-2)  - Failed to close port
SERIAL_ERROR_CONFIG    (-3)  - Failed to configure port
SERIAL_ERROR_READ      (-4)  - Read error
SERIAL_ERROR_WRITE     (-5)  - Write error
SERIAL_ERROR_TIMEOUT   (-6)  - Timeout
SERIAL_ERROR_INVALID   (-7)  - Invalid parameter
SERIAL_ERROR_BUSY      (-8)  - Port is busy
SERIAL_ERROR_NOPORT    (-9)  - Port not found
SERIAL_ERROR_PERM      (-10) - Permission denied

Building

Compile High-Level Example (Red)

./redc -c examples/example-red.red
sudo ./example-red

Compile Low-Level Example (Red/System)

./redc -c examples/basic.reds
sudo ./basic

Run Tests

./redc -c tests/test-no-hardware.reds
./test-no-hardware

Linux Permissions

Add your user to the dialout group:

sudo usermod -a -G dialout $USER

Then log out and back in. Or use sudo to run examples.

Roadmap

Phase	Status	Description
Phase 1	✅ Done	Linux driver + Red/System API + Red API
Phase 2	Planned	serial:// port scheme for Red
Phase 3	Planned	Windows support
Phase 4	Planned	macOS support
Phase 5	Planned	Propose to Red official

Author

ANLACO - Creator and maintainer

License

BSD-3-Clause License - See LICENSE for details.

Copyright (c) 2026 ANLACO. All rights reserved.

Requirements

• Red Compiler: Version 0.6.6 or compatible
  • Download from red-lang.org/download
  • Tested with Red 0.6.6 (January 2026)
• Platform: Linux (Windows support planned)

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow the Style Guide
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Acknowledgments

• Inspired by PySerial
• Built with Red Language