@eryx/serial Module

Serial port I/O module backed by OS serial APIs.

Supports full-duplex communication over RS-232, USB CDC, and similar serial interfaces. Reads are asynchronous and yield the calling coroutine without blocking the event loop.

local serial = require("@eryx/serial")

local port = serial.open("COM3", { baudRate = 115200 })
port:write("hello\r\n")
local response = port:read(64, 1000) -- up to 64 bytes, 1 s timeout
port:close()

Summary

Classes

SerialPort
inWaiting: number
outWaiting: number
SerialPort:read(size: number?) → string
SerialPort:flush(direction: ("input" | "output" | "both")?) → ()
SerialPort:setDTR(value: boolean) → ()
SerialPort:setRTS(value: boolean) → ()
SerialPort:getSignals() → Signals

Functions

serial.open(port: string, options: PortOptions?) → SerialPort
serial.list() → { PortInfo }

API Reference

Classes

SerialPort

An open serial port.

Properties

inWaiting: number

Number of bytes currently in the OS receive buffer (available to read).

outWaiting: number

Number of bytes currently in the OS transmit buffer (not yet sent).

SerialPort:read

⚠ Yields

Read bytes from the port.

  • :read() — non-blocking; returns all bytes currently in the OS receive buffer, or "" if none are available.
  • :read(n) — blocks until between 1 and n bytes arrive.
  • :read(n, timeout) — blocks up to timeout milliseconds; returns nil if no bytes arrived before the timeout. Pass 0 for an instant non-blocking check.
  • :read(nil, timeout) — waits up to timeout ms for any data, then drains the receive buffer (up to 64 KB); returns nil on timeout.

Throws on device errors (e.g. disconnection).

SerialPort:read(size: number?) → string

Parameters

size: number?

maximum bytes to read; omit to drain the buffer non-blocking

SerialPort:read(size: number?, timeout: number) → string?

Parameters

size: number?

maximum bytes to read; omit to drain the buffer non-blocking

timeout: number

timeout in milliseconds; 0 = non-blocking

SerialPort:flush

Discard buffered data in the OS receive or transmit queue.

SerialPort:flush(direction: ("input" | "output" | "both")?) → ()

Parameters

direction: ("input" | "output" | "both")?

defaults to "both"

SerialPort:setDTR

Set the DTR (Data Terminal Ready) output line.

SerialPort:setDTR(value: boolean) → ()

Parameters

value: boolean

boolean

SerialPort:setRTS

Set the RTS (Request To Send) output line.

SerialPort:setRTS(value: boolean) → ()

Parameters

value: boolean

boolean

SerialPort:getSignals

Read the state of the modem-control input lines (CTS, DSR, DCD, RI).

SerialPort:getSignals() → Signals

Functions

serial.open

Open a serial port.

local port = serial.open("/dev/ttyUSB0", { baudRate = 9600, parity = "even" })
serial.open(port: string, options: PortOptions?) → SerialPort

Parameters

port: string

device name, e.g. "COM3" or "/dev/ttyUSB0"

options: PortOptions?

port configuration; all fields are optional

serial.list

Enumerate available serial ports on the system.

Returns a list of PortInfo tables. USB-to-serial adapters typically populate the extra fields (vid, pid, manufacturer, etc.); built-in UARTs usually only have name.

for _, info in serial.list() do
    print(info.name, info.description)
end
serial.list() → { PortInfo }

Types

PortOptions

Options passed to serial.open.

type PortOptions = { baudRate: number?, dataBits: number?, stopBits: number?, parity: ("none" | "odd" | "even")? }
baudRate: number?

Baud rate in bits per second. Common values: 9600, 19200, 38400, 57600, 115200, 230400. Defaults to 9600.

dataBits: number?

Number of data bits per character: 5, 6, 7, or 8. Defaults to 8.

stopBits: number?

Number of stop bits: 1 or 2. Defaults to 1.

parity: ("none" | "odd" | "even")?

Parity mode. Defaults to "none".

PortInfo

Information about a serial port returned by serial.list. Fields beyond name are present only when the OS can supply them (typically USB-to-serial adapters; native UARTs usually only have name).

type PortInfo = { name: string, description: string?, hwid: string?, vid: number?, pid: number?, manufacturer: string?, serialNumber: string? }
name: string

Device path, e.g. "COM3" on Windows or "/dev/ttyUSB0" on Linux.

description: string?

Human-readable product description, e.g. "USB Serial Port (COM3)".

hwid: string?

Raw hardware ID string. On Windows this is the SetupAPI hardware ID; on Linux it is a "USB VID:PID=xxxx:yyyy" style string.

vid: number?

USB vendor ID as an integer.

pid: number?

USB product ID as an integer.

manufacturer: string?

USB manufacturer string reported by the device.

serialNumber: string?

USB serial number reported by the device.

Signals

State of the modem-control input lines on a serial port.

type Signals = { cts: boolean, dsr: boolean, dcd: boolean, ri: boolean }
cts: boolean

Clear To Send.

dsr: boolean

Data Set Ready.

dcd: boolean

Data Carrier Detect.

ri: boolean

Ring Indicator.