Rust SDK 概述

Lager Rust crate 让嵌入式开发者以一等公民的方式访问 Lager Net。一整套硬件在环（HIL）测试可以和您的固件放在一起，用 cargo test 运行，完全不需要 Python。这个 crate 是 Lager Box API 的纯 HTTP/JSON 客户端。它覆盖：

电源、电池仿真器、电子负载和太阳能仿真器
GPIO、ADC、DAC、热电偶、台式万用表、功率计和能量分析仪
SPI、I2C、USB 集线器端口、机械臂、摄像头和路由器
示波器和 YubiHSM 2 HSM
由 Box 上的自定义驱动运行的 Net
流式 UART
Box 级别的能力：Box 自带的 BLE 适配器、WiFi 接口，以及 BluFi ESP32 配网

调试探针 Net（烧录 / 擦除 / 复位 / 内存读取 / RTT）与 Box 的调试服务通信。

该包在 crates.io 上以 lager-net 名义发布，因为 lager 这个名字已被一个无关的 crate 占用。库目标的名称仍然是 lager，所以您的代码写的是 use lager::LagerBox;。完整的 API 参考在 docs.rs/lager-net。

快速上手

把这个 crate 加到您固件工程的 dev-dependencies 中：

# Cargo.toml
[dev-dependencies]
lager = { package = "lager-net", version = "0.13" }

该 crate 需要 Rust 1.75 或更高版本，基于 2021 edition 构建。写一个测试：

// tests/boot.rs
use lager::{LagerBox, Level};

#[test]
fn dut_boots_at_3v3() -> lager::Result<()> {
    let lager = LagerBox::from_env()?; // reads LAGER_BOX_HOST
    let supply = lager.supply("supply1");
    let boot_ok = lager.gpio("boot_ok");

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

    // Hardware-timed wait on the box; returns elapsed seconds.
    let t = boot_ok.wait_for_level(Level::High, 5.0)?;
    println!("booted in {t:.3}s");

    supply.disable()
}

运行它：

LAGER_BOX_HOST=192.168.1.42 cargo test

LagerBox::connect("hostname-or-ip") 同样可用，也接受 host:port 或完整 URL。

Feature

Feature	默认启用	您会得到什么
`blocking`	是	基于 `ureq` 的 `LagerBox` —— 依赖树极小，不需要 tokio
`async`	否	基于 `reqwest`/tokio 的 `AsyncLagerBox`；方法相同，加 `.await`
`uart`	否	通过 Box 的 Socket.IO `/uart` 命名空间进行 `Uart` 流式会话；同时启用 `async` 时还有 `AsyncUart`
`rtt`	否	通过 Box 的 Socket.IO 命名空间进行 RTT 日志流式传输，用于读取运行中目标的 `defmt` 输出；同时启用 `async` 时还有 `AsyncRttSession`
`scope-trace`	否	示波器波形样本：`Scope::capture()` 和 `Scope::stream()`
`admin`	否	通过 `admin()` 设置 Box：已保存的 Net、元数据、仪器、实验台清单、驱动、二进制文件、文件下载、自定义设备和诊断。同时启用 `async` 时为 `AsyncAdmin`

两种客户端执行的是完全相同的请求构造器和响应解析器，因此这两条传输路径不会各自跑偏。

lager = { package = "lager-net", version = "0.13", features = ["async"] }

错误

所有调用都返回 lager::Result<T>，配套单一的 Error 枚举：

变体	含义
`Connection`	联系不上 Box（网络/Tailscale 问题，或 Box 离线）
`Timeout`	Box 卡住，超过了（已经放宽的）时间预算
`Box { status, message }`	Box 拒绝了请求，或者硬件出错
`FlashFailed`, `ProbeBusy`, `SafetyRefused`	某个调试探针操作以该 crate 有专门命名的方式失败
`DfuFailed`	Box 端的 `dfu-util` 以非零状态退出
`UnsupportedByBox`	Box 镜像早于该端点；请更新 Box
`AuthRequired`	Box 的网关需要 bearer 令牌，而当前没有可用的令牌
`NotSupportedByBox`	为兼容性而保留；没有任何 Net 类型会返回它
`UartInUse`	另一个会话占用了该 UART Net 或其串行设备
`Decode`	Box 的响应无法解析为预期的结构
`Config`	客户端配置问题，例如主机字符串有误或缺少环境变量
`Stream`	串流会话报告了错误，例如设备消失

要求

一台软件足够新、能提供 POST /net/command 的 Lager Box —— 请检查 lager.status()?.capabilities.net_command，或者运行 lager update。较新的调用需要较新的 Box 软件，每个页面都会写明所需版本。较旧的 Box 会返回 Error::UnsupportedByBox。
Rust 1.75 或更高版本。

逻辑分析仪 Net 还没有进入 Box HTTP API。待办清单记录在该 crate 的 MISSING_ENDPOINTS.md 中。

参考

入门

客户端与 Box —— 构造 LagerBox、发现、Box 锁、安全限值
Net 类型 —— 全部句柄的索引
错误 —— 每一个 Error 变体及其触发时机

固件与调试

调试探针 —— 烧录、擦除、复位、读取内存
RTT —— 固件日志，以及驱动 RTT 控制台
USB DFU —— 不用调试探针进行烧录

电源与仿真

测量

I/O 与通信

实用工具

安全

HSM —— YubiHSM 2 密钥与签名

Box 设置

Box 设置（admin） —— Net、驱动、文件和诊断，位于 admin 功能之后

指南

用 cargo test 做测试 —— 组织测试套件、并行度、CI
认证 —— 位于认证网关之后的 Box
异步客户端 —— AsyncLagerBox，以及它与阻塞客户端的差异