UART

Stream a serial port from a cargo test

Open a streaming session against a serial port on the box and drive your DUT’s console from a test.

Enabling the feature

UART sessions ride on Socket.IO, so they are behind a cargo feature:

[dev-dependencies]
lager = { package = "lager-net", version = "0.9", features = ["uart"] }

The uart feature implies blocking. For AsyncUart, enable uart and async together. AsyncLagerBox::uart() and uart_with() open it, and its methods match Uart, with read, wait_for, write and stop awaited.

Handle

use lager::LagerBox;

let lager = LagerBox::from_env()?;
let mut uart = lager.uart("uart1")?;

uart() and uart_with() are the only handle constructors that return a Result. Every other net handle is inert until you call a method. They connect the session and start streaming immediately, so they can fail right here.

To open with different serial settings for this session, pass a UartConfig:

use lager::{Parity, UartConfig};

let mut uart = lager.uart_with("uart1", &UartConfig {
    baudrate: Some(921_600),
    parity: Some(Parity::None),
    ..Default::default()
})?;

Fields left None keep the net’s saved settings, and the saved net is never changed.

Methods

Method	Description
netname()	The net this session streams
device_path()	The device path on the box, e.g. /dev/ttyUSB0
baudrate()	The baud rate the port was opened at
last_status()	Most recent session status notification
read()	Bytes arriving within a timeout; may be empty
try_read()	Bytes already buffered, without waiting
wait_for()	Accumulate until a needle appears
write()	Write raw bytes to the device
write_str()	Write a string to the device
stop()	Stop cleanly, closing the port on the box

Types

UartConfig

pub struct UartConfig {
    pub baudrate: Option<u32>,
    pub bytesize: Option<u8>,
    pub parity: Option<Parity>,      // None, Even, Odd, Mark, Space
    pub stopbits: Option<StopBits>,  // One, OnePointFive, Two
    pub xonxoff: Option<bool>,
    pub rtscts: Option<bool>,
    pub dsrdtr: Option<bool>,
    pub opost: Option<bool>,
}

UartSession

lager.uart_sessions() returns one UartSession for each session holding a net. It has netname, device_path, sid, heartbeat_age_seconds, client_connected and reader_alive.

Method Reference

read(timeout: Duration) -> Result<Vec<u8>>

Bytes arriving within timeout. The call can return an empty vector.

read() waits out the full timeout when the device is idle. Use try_read() in a poll loop, or every iteration costs the whole timeout.

try_read() -> Result<Vec<u8>>

Bytes already received, without waiting.

wait_for(needle: &[u8], timeout: Duration) -> Result<Vec<u8>>

Accumulate until needle appears.

Returns: everything up to and including the needle; the remainder stays buffered. An empty needle returns immediately; a miss is Error::Timeout.

write(data: &[u8]) -> Result<()> and write_str(s: &str) -> Result<()>

Write to the device.

last_status() -> Option<&str>

The most recent session status notification, updated during reads. While a USB serial adapter re-enumerates — because a hub port was cycled, or the DUT was reflashed — this reads "reconnecting" and then "reconnected". Checking it distinguishes “the DUT is quiet” from “the adapter went away”.

stop() -> Result<()>

Stop cleanly and close the port on the box. Consumes the session. Dropping it also stops the session, but stop() surfaces errors.

LagerBox::uart_sessions() -> Result<Vec<UartSession>>

List the sessions holding a net, with liveness detail. Requires box software 0.46.0 or later. An older box gives Error::UnsupportedByBox.

LagerBox::release_uart_session(name: &str) -> Result<Vec<String>>

Force-release the session holding a net. Requires box software 0.46.0 or later.

Examples

Wait for a boot banner, then drive the console

use lager::LagerBox;
use std::time::Duration;

let lager = LagerBox::from_env()?;
let supply = lager.supply("supply1");
let mut uart = lager.uart("uart1")?;

supply.set_voltage(3.3)?;
supply.enable()?;

uart.wait_for(b"boot complete", Duration::from_secs(10))?;
uart.write_str("status\r\n")?;
let reply = uart.wait_for(b"OK", Duration::from_secs(2))?;
println!("{}", String::from_utf8_lossy(&reply));

uart.stop()?;
supply.disable()?;

Survive a reflash without losing the session

use std::time::Duration;

dbg.flash_bin("target/app.bin", 0x0)?;   // the adapter may re-enumerate

// The session reconnects on its own; watch the status while it does.
let banner = uart.wait_for(b"ready", Duration::from_secs(30))?;
println!("status during reflash: {:?}", uart.last_status());
assert!(String::from_utf8_lossy(&banner).contains("ready"));

Free a net held by a leaked session

use lager::Error;

match lager.uart("uart1") {
    Err(Error::UartInUse { held_by: Some(net), .. }) => {
        lager.release_uart_session(&net)?;
    }
    other => { other?; }
}

Supported Hardware

Adapter	Notes
SiLabs CP210x
FTDI FT232R / FT232H / FT2232H / FT4232H	On multi-channel parts, all four channels can serve UART
Prolific USB serial
ESP32 JTAG/serial

Notes

• The box owns the port exclusively, and only one session per net or device is allowed. A second opener gets Error::UartInUse. That includes a session your own previous test leaked — call stop(). held_by names the net to release (box 0.49.0 or later). When two nets share one device, that is the other net.
• The connect confirmation timeout is 15 seconds; failing it is Error::Timeout.
• Bytes are raw. There is no line discipline, no echo handling and no encoding conversion; wait_for works on bytes.
• Sessions carry the gateway bearer token on the Socket.IO handshake, so a gated box needs no extra setup.
• On FTDI multi-channel parts, UART works on all four channels, unlike the MPSSE protocols (debug, spi, i2c) which are limited to channels A and B. On a single-channel FT232H, claiming UART makes the MPSSE roles unavailable and vice versa.