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.13", 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:
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.
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.
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.