> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lagerdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust SDK Overview

> Write your entire hardware-in-the-loop test suite in Rust and run it with cargo test

The Lager Rust crate gives embedded developers first-class access to Lager
nets. A hardware-in-the-loop (HIL) test suite can live next to your firmware
and run with `cargo test`. No Python is required.

The crate is a pure HTTP/JSON client of the Lager Box API. It covers:

* power supplies, battery simulators, e-loads and solar simulators
* GPIO, ADC, DAC, thermocouples, bench multimeters, watt meters and energy analyzers
* SPI, I2C, USB hub ports, robot arms, webcams and routers
* oscilloscopes and YubiHSM 2 HSMs
* nets that a custom driver on the box runs
* streaming UART
* the box-level capabilities: its own BLE adapter, WiFi interface, and BluFi
  ESP32 provisioning

Debug-probe nets (flash / erase / reset / memory reads / RTT) talk to the
box's debug service.

> [!NOTE]
>
> The package publishes on crates.io as
> [**`lager-net`**](https://crates.io/crates/lager-net), because the bare
> `lager` name is taken by an unrelated crate. The library target is still
> named `lager`, so your code reads `use lager::LagerBox;`. Full API reference
> lives on [docs.rs/lager-net](https://docs.rs/lager-net).

## Quickstart

Add the crate to your firmware project's dev-dependencies:

```toml theme={null}
# Cargo.toml
[dev-dependencies]
lager = { package = "lager-net", version = "0.12" }
```

The crate requires Rust **1.75** or newer and builds on edition 2021.

Write a test:

```rust theme={null}
// 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()
}
```

Run it:

```sh theme={null}
LAGER_BOX_HOST=192.168.1.42 cargo test
```

`LagerBox::connect("hostname-or-ip")` also works, with an optional
`host:port` or full URL.

## Features

| Feature | Default | What you get |
| - | - | - |
| `blocking` | yes | `LagerBox` on [`ureq`](https://crates.io/crates/ureq) — tiny dependency tree, no tokio |
| `async` | no | `AsyncLagerBox` on [`reqwest`](https://crates.io/crates/reqwest)/tokio; same methods, `.await`ed |
| `uart` | no | `Uart` streaming sessions over the box's Socket.IO `/uart` namespace; `AsyncUart` when `async` is on too |
| `rtt` | no | RTT log streaming over the box's Socket.IO namespace, for reading `defmt` output from a running target; `AsyncRttSession` when `async` is on too |
| `scope-trace` | no | Scope waveform samples: `Scope::capture()` and `Scope::stream()` |
| `admin` | no | Box setup through `admin()`: saved nets, metadata, instruments, the bench manifest, drivers, binaries, file download, custom devices and diagnostics. `AsyncAdmin` when `async` is on too |

Both clients execute the exact same request builders and response parsers,
so the two transports cannot drift apart.

```toml theme={null}
lager = { package = "lager-net", version = "0.12", features = ["async"] }
```

## Errors

Everything returns `lager::Result<T>` with a single `Error` enum:

| Variant | Meaning |
| - | - |
| `Connection` | Box unreachable (network/Tailscale/box offline) |
| `Timeout` | The box stalled past the (already widened) budget |
| `Box { status, message }` | The box refused or the hardware failed |
| `FlashFailed`, `ProbeBusy`, `SafetyRefused` | A debug-probe operation failed in a way the crate names |
| `DfuFailed` | Box-side `dfu-util` exited non-zero |
| `UnsupportedByBox` | The box image predates this endpoint; update the box |
| `AuthRequired` | The box's gateway wants a bearer token and none is available |
| `NotSupportedByBox` | Kept for compatibility; no net type returns it |
| `UartInUse` | Another session holds the UART net or its serial device |
| `Decode` | The box's response did not parse into the expected shape |
| `Config` | A client-side configuration problem, such as a bad host string or a missing environment variable |
| `Stream` | A streaming session reported an error, for example the device disappeared |

## Requirements

* A Lager Box with software new enough to serve `POST /net/command` —
  check `lager.status()?.capabilities.net_command`, or run
  `lager update`. Newer calls need newer box software, and each page names the
  version. An older box returns `Error::UnsupportedByBox`.
* Rust 1.75+.

> [!NOTE]
>
> Logic-analyzer nets are not on the box HTTP API yet. The work list is in the crate's
> [`MISSING_ENDPOINTS.md`](https://github.com/lagerdata/lager-rs/blob/main/MISSING_ENDPOINTS.md).

## Reference

### Getting started

* [Client and Box](https://docs.lagerdata.com/source/reference/rust/client.md) — constructing `LagerBox`, discovery, box locks, safety limits
* [Net Types](https://docs.lagerdata.com/source/reference/rust/net-types.md) — the index of every handle
* [Errors](https://docs.lagerdata.com/source/reference/rust/errors.md) — every `Error` variant and when it fires

### Firmware and debug

* [Debug Probes](https://docs.lagerdata.com/source/reference/rust/debug.md) — flash, erase, reset, read memory
* [RTT](https://docs.lagerdata.com/source/reference/rust/rtt.md) — firmware logs, and driving an RTT console
* [USB DFU](https://docs.lagerdata.com/source/reference/rust/dfu.md) — flashing without a debug probe

### Power and simulation

* [Power Supply](https://docs.lagerdata.com/source/reference/rust/supply.md)
* [Battery Simulation](https://docs.lagerdata.com/source/reference/rust/battery.md)
* [Solar Simulation](https://docs.lagerdata.com/source/reference/rust/solar.md)
* [Electronic Load](https://docs.lagerdata.com/source/reference/rust/eload.md)
* [Watt Meter](https://docs.lagerdata.com/source/reference/rust/watt.md)
* [Energy Analyzer](https://docs.lagerdata.com/source/reference/rust/energy.md)

### Measurement

* [Oscilloscope](https://docs.lagerdata.com/source/reference/rust/scope.md)
* [ADC](https://docs.lagerdata.com/source/reference/rust/adc.md)
* [Thermocouple](https://docs.lagerdata.com/source/reference/rust/thermocouple.md)
* [DMM](https://docs.lagerdata.com/source/reference/rust/dmm.md)

### I/O and communication

* [GPIO](https://docs.lagerdata.com/source/reference/rust/gpio.md)
* [DAC](https://docs.lagerdata.com/source/reference/rust/dac.md)
* [I2C](https://docs.lagerdata.com/source/reference/rust/i2c.md)
* [SPI](https://docs.lagerdata.com/source/reference/rust/spi.md)
* [USB Hub Ports](https://docs.lagerdata.com/source/reference/rust/usb.md)
* [UART](https://docs.lagerdata.com/source/reference/rust/uart.md)
* [BLE](https://docs.lagerdata.com/source/reference/rust/ble.md)
* [WiFi](https://docs.lagerdata.com/source/reference/rust/wifi.md)
* [BluFi](https://docs.lagerdata.com/source/reference/rust/blufi.md)
* [Router](https://docs.lagerdata.com/source/reference/rust/router.md)

### Utilities

* [Robot Arm](https://docs.lagerdata.com/source/reference/rust/arm.md)
* [Webcam](https://docs.lagerdata.com/source/reference/rust/webcam.md)

### Security

* [HSM](https://docs.lagerdata.com/source/reference/rust/hsm.md) — YubiHSM 2 keys and signing

### Box setup

* [Box Setup (admin)](https://docs.lagerdata.com/source/reference/rust/admin.md) — nets, drivers, files and diagnostics, behind the `admin` feature

### Guides

* [Testing with cargo test](https://docs.lagerdata.com/source/reference/rust/testing.md) — structuring a suite, parallelism, CI
* [Authentication](https://docs.lagerdata.com/source/reference/rust/auth.md) — boxes behind an authenticating gateway
* [Async Client](https://docs.lagerdata.com/source/reference/rust/async.md) — `AsyncLagerBox`, and where it differs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.