serial
stableSerial port communication primitives: open ports with baud rate configuration, read/write data, and utility functions for port names and common settings.
use plugin serial::{SerialPort.new, close, is_open, …} Functions (16)
- SerialPort.new Open a serial port by name and baud rate
- close Close the port
- is_open Check if the port is open
- write Write bytes or a string to the port
- read Read up to N bytes from the port
- set_baud_rate Change the baud rate
- set_data_bits Set data bits (5, 6, 7, or 8)
- set_stop_bits Set stop bits (1 or 2)
- set_parity Set parity mode
- set_timeout Set read timeout in milliseconds
- get_config Return all current port settings
- common_baud_rates List standard baud rates
- parse_port_config Parse a config string into a table
- format_port_name Format a port name from an index
- parity_name Convert a parity code to its name
- list_common_ports List common system port names
Overview
serial models serial-port communication through a stateful SerialPort
handle. Opening a port with SerialPort.new registers a handle that carries
its own configuration (baud rate, data bits, stop bits, parity, and read
timeout) and an internal transmit/receive buffer, so you call methods on that
handle to write, read, and reconfigure the port for its lifetime. Alongside the
handle there is a small set of free utility functions for enumerating standard
baud rates, building platform-correct port names, and translating parity codes
— useful for presenting choices in a UI or normalizing configuration before a
port is opened.
The mental model is: build or pick a port name (format_port_name,
list_common_ports), open it with SerialPort.new, drive it with the instance
methods (write, read, the set_* configurators), inspect it with
get_config, and close it when done.
Common patterns
Open a port, send a command, and close it:
use plugin serial::{SerialPort}
let port = SerialPort.new("COM3", 9600)
if port.is_open() {
let n = port.write("AT\r\n")
print("sent {n} bytes")
}
port.close()
Configure a port after opening it, then read back the effective settings:
use plugin serial::{SerialPort}
let port = SerialPort.new("/dev/ttyUSB0", 9600)
port.set_baud_rate(115200)
port.set_data_bits(8)
port.set_parity("even")
port.set_timeout(500)
let cfg = port.get_config()
print("{cfg["baud_rate"]} baud, {cfg["data_bits"]} data bits, parity {cfg["parity"]}")
port.close()
Discover available ports and a valid baud rate before opening anything:
use plugin serial::{list_common_ports, common_baud_rates, SerialPort}
let ports = list_common_ports()
let rates = common_baud_rates()
let port = SerialPort.new(ports[1], rates[5])
print(port.get_config()["port_name"])
port.close()
Open a serial port by name and baud rate
Opens a serial port with the given name and baud rate. Default settings are 8 data bits, 1 stop bit, no parity, 1000 ms timeout.
use plugin serial::{SerialPort}
let port = SerialPort.new("COM3", 9600)
print(port.is_open()) // true
port.write("AT\r\n")
port.close()
Close the port
Marks the port as closed. Further reads and writes will fail.
use plugin serial::{SerialPort}
let port = SerialPort.new("COM3", 115200)
port.close()
print(port.is_open()) // false
Check if the port is open
Returns true if the port is open and ready for I/O. Use it to guard reads and
writes, which error on a closed port.
use plugin serial::{SerialPort}
let port = SerialPort.new("COM4", 9600)
if port.is_open() {
port.write("PING\n")
}
port.close()
Write bytes or a string to the port
Writes a string or bytes to the port's transmit buffer. Returns the number of bytes written. Errors if the port is closed.
use plugin serial::{SerialPort}
let port = SerialPort.new("/dev/ttyUSB0", 9600)
let n = port.write("HELLO\n")
print("sent {n} bytes")
port.close()
Read up to N bytes from the port
Reads up to max_bytes from the receive buffer (returned as a bytes value). Returns the available bytes (may be fewer than requested). Returns empty bytes if the buffer is empty. Errors if the port is closed.
use plugin serial::{SerialPort}
let port = SerialPort.new("/dev/ttyACM0", 9600)
let data = port.read(64)
print("received {data.len()} bytes")
port.close()
Because read drains only what is available, it is safe to poll in a loop and
break when nothing more arrives:
use plugin serial::{SerialPort}
let port = SerialPort.new("/dev/ttyUSB0", 115200)
let chunk = port.read(256)
while chunk.len() > 0 {
print("got {chunk.len()} bytes")
chunk = port.read(256)
}
port.close()
Change the baud rate
Changes the baud rate of the port. Common values: 9600, 19200, 57600, 115200.
use plugin serial::{SerialPort}
let port = SerialPort.new("COM1", 9600)
port.set_baud_rate(115200)
let cfg = port.get_config()
print(cfg["baud_rate"]) // 115200
port.close()
Set data bits (5, 6, 7, or 8)
Sets the number of data bits per frame. Must be 5, 6, 7, or 8.
use plugin serial::{SerialPort}
let port = SerialPort.new("COM1", 9600)
port.set_data_bits(8)
port.close()
Set stop bits (1 or 2)
Sets the number of stop bits. Must be 1 or 2.
use plugin serial::{SerialPort}
let port = SerialPort.new("COM1", 9600)
port.set_stop_bits(2)
port.close()
Set parity mode
Sets the parity mode. Accepted values: "none", "odd", "even", "mark", "space".
use plugin serial::{SerialPort}
let port = SerialPort.new("COM2", 9600)
port.set_parity("even")
let cfg = port.get_config()
print(cfg["parity"]) // even
port.close()
Set read timeout in milliseconds
Sets the read timeout in milliseconds.
use plugin serial::{SerialPort}
let port = SerialPort.new("COM2", 9600)
port.set_timeout(500)
port.close()
Return all current port settings
Returns the full current configuration as a table with fields: port_name, baud_rate, data_bits, stop_bits, parity, timeout_ms, open.
use plugin serial::{SerialPort}
let port = SerialPort.new("COM3", 115200)
let cfg = port.get_config()
print(cfg["baud_rate"]) // 115200
print(cfg["data_bits"]) // 8
print(cfg["parity"]) // none
print(cfg["timeout_ms"]) // 1000
port.close()
List standard baud rates
Returns a 1-indexed table of standard baud rates (300 through 921600).
use plugin serial::{common_baud_rates}
let rates = common_baud_rates()
print(rates[1]) // 300
print(rates[5]) // 9600
print(rates[12]) // 115200
Feed a rate straight into SerialPort.new to open at a known-good speed:
use plugin serial::{common_baud_rates, SerialPort}
let rates = common_baud_rates()
let port = SerialPort.new("COM3", rates[13]) // 230400
print(port.get_config()["baud_rate"])
port.close()
Parse a config string into a table
Parses serial port parameters into a structured table including a human-readable config_string (e.g. "9600-8N1").
use plugin serial::{parse_port_config}
let cfg = parse_port_config(9600, 8, "none", 1)
print(cfg["config_string"]) // 9600-8N1
print(cfg["parity_name"]) // none
print(cfg["parity"]) // 0
Format a port name from an index
Formats a port name from an integer index. Returns "COMn" on Windows and "/dev/ttyUSBn" on other platforms.
use plugin serial::{format_port_name}
print(format_port_name(3)) // COM3 (on Windows)
// /dev/ttyUSB3 (on Linux)
Convert a parity code to its name
Converts a numeric parity code (0–4) to its name string: "none", "odd", "even", "mark", "space".
use plugin serial::{parity_name}
print(parity_name(0)) // none
print(parity_name(1)) // odd
print(parity_name(2)) // even
List common system port names
Returns a 1-indexed table of common port name strings for the current platform. On Windows: COM1–COM16. On Linux: /dev/ttyUSB0–7, /dev/ttyACM0–7, /dev/ttyS0–3.
use plugin serial::{list_common_ports}
let ports = list_common_ports()
print(ports[1]) // COM1 (Windows) or /dev/ttyUSB0 (Linux)