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 Plugin snippets can be edited in the Playground, but native capabilities are executed locally with the Zolo CLI.
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
From import to result
- 01Import only what you use
- 02Copy the smallest example
- 03Run it with the Zolo CLI
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()) // falseCheck 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]) // 115200Feed 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"]) // 0Format 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)) // evenList 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)