UART

对 Box 上的某个串口打开一个流式会话，并从测试中驱动被测设备的控制台。

启用该 feature

UART 会话基于 Socket.IO，因此它位于一个 cargo feature 之后：

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

uart feature 隐含启用 blocking。要使用 AsyncUart，请同时启用 uart 和 async。AsyncLagerBox::uart() 和 uart_with() 会打开它，它的方法与 Uart 相同，其中 read、wait_for、write 和 stop 需要 .await。

句柄

use lager::LagerBox;

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

uart() 和 uart_with() 是仅有的返回 Result 的句柄构造方法。其他每个 Net 句柄在您调用方法之前都是静止的，而它们会连接会话并立即开始流式传输，因此在这一步就可能失败。

要让本次会话使用不同的串口设置，请传入一个 UartConfig：

use lager::{Parity, UartConfig};

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

保留为 None 的字段沿用 Net 保存的设置，保存的 Net 本身不会被修改。

方法

方法	说明
`netname()`	该会话所流式接收的 Net
`device_path()`	Box 上的设备路径，例如 `/dev/ttyUSB0`
`baudrate()`	打开该端口时使用的波特率
`last_status()`	最近一次会话状态通知
`read()`	在超时时间内到达的字节；可能为空
`try_read()`	已经缓冲的字节，不等待
`wait_for()`	一直累积，直到出现指定的标记
`write()`	向设备写入原始字节
`write_str()`	向设备写入一个字符串
`stop()`	干净地停止，并关闭 Box 上的该端口

类型

`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() 为每个占用 Net 的会话返回一个 UartSession，包含 netname、device_path、sid、heartbeat_age_seconds、client_connected 和 reader_alive。

方法参考

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

在 timeout 时间内到达的字节。该调用可能返回空 vector。

设备空闲时，read() 会把整个超时时间等满。在轮询循环里请用 try_read()，否则每一轮迭代都要花掉整个超时时长。

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

已经收到的字节，不等待。

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

一直累积，直到出现 needle。 返回： 直到该标记为止、并且包含该标记的全部内容；剩余部分继续留在缓冲区里。空标记会立即返回；没找到则是 Error::Timeout。

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

向设备写入。

`last_status() -> Option<&str>`

最近一次会话状态通知，在读取过程中更新。当一个 USB 串口适配器正在重新枚举时 —— 因为某个集线器端口被断电重启，或者被测设备被重新烧录 —— 它读到的是 "reconnecting"，然后是 "reconnected"。检查它可以区分”被测设备很安静”和”适配器不见了”。

`stop() -> Result<()>`

干净地停止，并关闭 Box 上的该端口。它会消耗掉该会话。把会话 drop 掉同样会停止它，但 stop() 会把错误暴露出来。

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

列出占用 Net 的会话，并附带存活状态的详细信息。需要 Box 软件 0.46.0 或更高版本。较旧的 Box 会返回 Error::UnsupportedByBox。

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

强制释放占用某个 Net 的会话。需要 Box 软件 0.46.0 或更高版本。

示例

等待启动横幅，然后驱动控制台

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()?;

在重新烧录过程中保住会话

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"));

释放被泄漏会话占用的 Net

use lager::Error;

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

受支持的硬件

适配器	备注
SiLabs CP210x
FTDI FT232R / FT232H / FT2232H / FT4232H	在多通道芯片上，四个通道都能承载 UART
Prolific USB 串口
ESP32 JTAG/串口

说明

Box 独占该端口，并且每个 Net 或设备只允许一个会话。 第二个打开者会得到 Error::UartInUse。这也包括您自己上一个测试泄漏下来的会话 —— 请调用 stop()。held_by 指明要释放的 Net（Box 0.49.0 或更高版本）。当两个 Net 共用一台设备时，它指的是另一个 Net。
连接确认的超时是 15 秒；超过它是 Error::Timeout。
字节是原始的。没有行规程、不处理回显、也不做编码转换；wait_for 是按字节工作的。
会话会在 Socket.IO 握手时带上网关 bearer 令牌，因此受网关保护的 Box 无需额外配置。
在 FTDI 多通道芯片上，UART 四个通道都能用，这与只限于通道 A 和 B 的 MPSSE 协议（debug、spi、i2c）不同。在单通道的 FT232H 上，占用 UART 会让 MPSSE 类角色不可用，反之亦然。

入门

开发

电源与仿真

测量

I/O 与通信

实用工具

安全

Box 设置

指南

启用该 feature

句柄

方法

类型

`UartConfig`

`UartSession`

方法参考

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

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

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

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

`last_status() -> Option<&str>`

`stop() -> Result<()>`

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

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

示例

等待启动横幅，然后驱动控制台

在重新烧录过程中保住会话

释放被泄漏会话占用的 Net

受支持的硬件

说明

启用该 feature

句柄

方法

类型

UartConfig

UartSession

方法参考

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

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

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

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

last_status() -> Option<&str>

stop() -> Result<()>

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

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

示例

等待启动横幅，然后驱动控制台

在重新烧录过程中保住会话

释放被泄漏会话占用的 Net

受支持的硬件

说明

`UartConfig`

`UartSession`

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

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

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

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

`last_status() -> Option<&str>`

`stop() -> Result<()>`

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

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