UART

Connect to UART serial ports on Lager Boxes for serial communication with devices.

Syntax

lager uart [NETNAME] [OPTIONS]

Arguments

Argument	Description
`NETNAME`	UART net name (optional if default is set)

Options

Option	Description
`--box BOX`	Lager Box name or IP address
`--baudrate RATE`	Baudrate (e.g., 9600, 115200)
`--bytesize SIZE`	Data bits (5, 6, 7, 8)
`--parity MODE`	Parity: none, even, odd, mark, space
`--stopbits BITS`	Stop bits (1, 1.5, 2)
`--xonxoff` / `--no-xonxoff`	Software flow control
`--rtscts` / `--no-rtscts`	Hardware flow control (RTS/CTS)
`--dsrdtr` / `--no-dsrdtr`	Hardware flow control (DSR/DTR)
`-i` / `--interactive`	Enable input mode for typing
`--opost` / `--no-opost`	Convert \n to \r\n on output
`--line-ending MODE`	Line ending: lf, crlf, cr (default: lf)
`--sessions`	List the UART sessions that hold a net, then exit
`--force`	Take over the net if another session holds it

Usage

Read-Only Mode (Default)

# Monitor serial output
lager uart SERIAL1 --box my-lager-box

# With specific baudrate
lager uart SERIAL1 --baudrate 115200

Interactive Mode

# Type commands and see responses
lager uart SERIAL1 --interactive

# With specific settings
lager uart SERIAL1 -i --baudrate 9600 --parity none

Get Serial Port Info

# Show device path for a UART net
lager uart SERIAL1 serial-port

A Net Held By Another Session

A UART device takes one reader at a time, so a second session on the same net is refused:

Error: UART net 'SERIAL1' is already in use by another session
To take over the net: lager uart SERIAL1 --force --box my-lager-box

Two nets can name the same device. In that case the error names the device path and the net that holds it: UART device /dev/ttyUSB0 is already in use by net 'SERIAL2'. The take-over command names that net too. Ask the box who holds what:

lager uart --sessions --box my-lager-box

Net       Device Path     Client      Reader
==============================================
SERIAL1   /dev/ttyUSB0    connected   running

Column	Value	Meaning
`Client`	`connected`	The holder’s connection to the box is open
`Client`	`gone`	The holder’s client left
`Client`	`unknown`	The box cannot tell
`Reader`	`running`	The session reads the device
`Reader`	`stopped`	The session no longer reads the device
`Reader`	`starting`	The session has no read loop yet

How long a holder keeps the net:

A holder whose client reads gone releases the net within about 0.1 seconds. If the adapter re-enumerates at that time, the release can take up to 60 seconds.
A holder whose computer went to sleep, or lost its network, still reads connected for about 85 seconds.
A holder whose reader reads stopped does not block you. The next lager uart on the net reclaims it.

A holder that reads connected can belong to somebody, so check before you take it:

lager uart SERIAL1 --force --box my-lager-box

--force releases every session that holds the net, and then connects. If it releases a session, it prints Released the session that held 'SERIAL1'. If nothing held the net, it prints nothing. The session that you displaced stops receiving data and prints Error: UART net 'SERIAL1' was taken over by another client. --force acts only on the net that you name. If the error names a device path, another net on the same device holds it. Take over the net that the error names. An older box does not name that net, so use --sessions to find it. --sessions prints one of these messages instead of a table:

No UART sessions are active on this box. No session holds a net.
This box does not report UART sessions; update it with lager update. The box is older than 0.46.0. Run lager update. On such a box, --force prints a warning that the box is too old to support it.

--force cannot clear this error: UART device /dev/ttyUSB0 is already in use (locked by another session or the lager uart CLI). Another process holds the port, for example a lager python script that opened the UART net. Stop that process first.

--force takes the box lock, as every lager uart command that connects does. If another user holds the box lock, it fails with Error: Box 'my-lager-box' is locked by <holder>. --sessions does not take the box lock, so it works while another user holds it.

If the box does not start the session within 15 seconds, the command prints Error: the box did not start the UART session within 15s and exits 1.

Serial Configuration

Baudrate

Common baudrates:

9600 (default for many devices)
19200
38400
57600
115200 (common for embedded development)
230400
460800
921600

Data Format

Setting	Options	Default
Bytesize	5, 6, 7, 8	8
Parity	none, even, odd, mark, space	none
Stopbits	1, 1.5, 2	1

Flow Control

Type	Options	Description
Software	`--xonxoff`	XON/XOFF characters
Hardware	`--rtscts`	RTS/CTS pins
Hardware	`--dsrdtr`	DSR/DTR pins

Flow control types cannot be combined.

Line Endings

Mode	Sequence	Use Case
`lf`	\n	Unix/Linux
`crlf`	\r\n	Windows
`cr`	\r	Legacy systems

Use --opost to automatically convert line endings on output.

Supported USB Serial Adapters

The following USB-to-serial adapters are automatically detected and supported:

Adapter	VID:PID	Description
Prolific USB-Serial	067b:23a3	Common USB-Serial adapter
Silicon Labs CP210x	10c4:ea60	Popular embedded dev boards
FTDI FT232R	0403:6001	Single-channel USB-Serial
FTDI FT232H	0403:6014	Single-channel, multi-protocol
FTDI FT2232H	0403:6010	Dual-channel, multi-protocol
FTDI FT4232H	0403:6011	Quad-channel USB-Serial
ESP32 USB JTAG/Serial	303a:1001	Built-in ESP32-S3/C3 USB

These adapters are automatically recognized by lager instruments and can be configured as UART nets.

Device Path Support

UART nets can reference devices two ways: USB Serial Number (preferred):

Net configured with USB serial number
Automatically resolves to correct /dev/ttyUSBx

Direct Device Path (fallback): if the adapter has no serial number, save a net on its device path. The last argument is a label of your choice. Then connect to the net by name. lager uart does not accept a device path in place of a net name.

lager nets add CONSOLE uart /dev/ttyUSB0 console-adapter --box my-lager-box
lager uart CONSOLE --baudrate 115200 --box my-lager-box

Examples

# Basic serial monitor
lager uart DEBUG_UART --box my-lager-box

# Interactive shell with common embedded settings
lager uart CONSOLE -i --baudrate 115200

# Legacy device with specific format
lager uart LEGACY --baudrate 9600 --bytesize 7 --parity even --stopbits 2

# With software flow control
lager uart MODEM --xonxoff

# Windows-style line endings
lager uart TERMINAL --line-ending crlf --opost

WebSocket Connection

The UART command uses WebSocket for communication:

Provides real-time bidirectional data
Supports both read-only and interactive modes
If the USB adapter re-enumerates, the box reopens it for up to 60 seconds and the session continues. The CLI prints [UART device disconnected - reconnecting...] while it waits.
The CLI does not reconnect to the box. If the connection to the box drops, the session ends. Run the command again.

Troubleshooting

Device Not Found

# List available instruments to find UART devices
lager instruments --box my-lager-box

# Check if USB serial adapter is connected
ssh lagerdata@my-lager-box 'ls -la /dev/ttyUSB*'

Permission Denied

# Ensure udev rules are installed
lager update --box my-lager-box --yes

No Output

Check baudrate matches device
Verify TX/RX connections
Try interactive mode to test input
Check flow control settings

Notes

Interactive mode requires a TTY terminal
USB serial numbers are truncated for display
Default net can be set with lager defaults add --uart-net
The box reopens an adapter that re-enumerates, for up to 60 seconds

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Arguments

Options

Usage

Read-Only Mode (Default)

Interactive Mode

Get Serial Port Info

A Net Held By Another Session

Serial Configuration

Baudrate

Data Format

Flow Control

Line Endings

Supported USB Serial Adapters

Device Path Support

Examples

WebSocket Connection

Troubleshooting

Device Not Found

Permission Denied

No Output

Notes

See Also

​Syntax

​Arguments

​Options

​Usage

​Read-Only Mode (Default)

​Interactive Mode

​Get Serial Port Info

​A Net Held By Another Session

​Serial Configuration

​Baudrate

​Data Format

​Flow Control

​Line Endings

​Supported USB Serial Adapters

​Device Path Support

​Examples

​WebSocket Connection

​Troubleshooting

​Device Not Found

​Permission Denied

​No Output

​Notes

​See Also

Syntax

Arguments

Options

Usage

Read-Only Mode (Default)

Interactive Mode

Get Serial Port Info

A Net Held By Another Session

Serial Configuration

Baudrate

Data Format

Flow Control

Line Endings

Supported USB Serial Adapters

Device Path Support

Examples

WebSocket Connection

Troubleshooting

Device Not Found

Permission Denied

No Output

Notes

See Also