Your First Test

This guide walks you through a complete test workflow — from verifying connectivity to running an automated test, in Python or Rust. By the end, you’ll have used the CLI interactively and written your first Lager test script.

This tutorial assumes you have completed the Getting Started guide: the CLI is installed, your box is added, and your instruments are configured with nets.

Part 1: CLI Walkthrough

Let’s step through a typical test flow using individual CLI commands. This is useful for ad-hoc testing, debugging, and getting familiar with your setup.

Step 1: Verify your box is online

lager hello --box my-lager-box

Expected output:

my-lager-box says hello!

Step 2: Check connected instruments

lager instruments --box my-lager-box

This shows all instruments the box can see. Confirm your power supply, debug probe, and any other instruments appear.

Step 3: View your configured nets

lager nets --box my-lager-box

This shows the named nets you’ll use in subsequent commands. Note the net names — you’ll need them below.

Step 4: Set defaults to reduce typing

lager defaults add --box my-lager-box
lager defaults add --supply-net POWER
lager defaults add --debug-net DEBUG_NET

With defaults set, you can omit --box and net names from subsequent commands.

Step 5: Flash firmware

lager debug flash --hex firmware.hex

Expected output:

Flashing firmware.hex to target...
Flash complete. 32768 bytes written.

Step 6: Power on your device

# Set voltage with protection thresholds
lager supply voltage 3.3 --ovp 3.6 --ocp 0.5 --yes

# Enable the output
lager supply enable --yes

Step 7: Take a measurement

lager adc SENSOR_1

Expected output:

ADC 'SENSOR_1': 2.450000 V

Step 8: Power down

lager supply disable --yes

Always disable power supplies when you’re done testing.

Part 2: Your First Test Script

Now let’s convert the manual CLI steps into a repeatable test. The key advantage of a script is that it always cleans up after itself (disabling power) even if an error occurs. You can write it in Python (runs on the box via lager python) or in Rust (an ordinary cargo test in your firmware repo, using the lager-net crate). Both versions below do the same thing: flash, power on, measure, assert, clean up.

from lager import Net, NetType

def main():
    # Get our nets
    psu = Net.get('POWER', type=NetType.PowerSupply)
    debug = Net.get('DEBUG_NET', type=NetType.Debug)
    sensor = Net.get('SENSOR_1', type=NetType.ADC)

    try:
        # Flash firmware
        print("Flashing firmware...")
        debug.connect()
        debug.flash(['firmware.hex'])
        debug.reset()
        print("Flash complete.")

        # Power on the DUT
        print("Enabling power supply at 3.3V...")
        psu.set_voltage(3.3)
        psu.set_current(0.5)
        psu.enable()
        print("Power enabled.")

        # Take a measurement
        voltage = sensor.input()
        print(f"Sensor reading: {voltage:.4f} V")

        # Check the result
        if 2.0 <= voltage <= 3.0:
            print("PASS: Sensor voltage within expected range.")
        else:
            print(f"FAIL: Sensor voltage {voltage:.4f}V outside range [2.0, 3.0]")

    finally:
        # Always clean up, even if an error occurs
        print("Disabling power supply...")
        psu.disable()
        print("Done.")

if __name__ == '__main__':
    main()

use lager::LagerBox;

#[test]
fn sensor_reads_in_range_after_boot() -> lager::Result<()> {
    // Reads LAGER_BOX_HOST from the environment.
    let lager = LagerBox::from_env()?;
    let psu = lager.supply("POWER");
    let debug = lager.debug("DEBUG_NET");
    let sensor = lager.adc("SENSOR_1");

    // Flash firmware
    println!("Flashing firmware...");
    debug.connect()?;
    debug.flash("firmware.hex")?;
    debug.reset(false)?;
    println!("Flash complete.");

    // Power on the DUT
    println!("Enabling power supply at 3.3V...");
    psu.set_voltage(3.3)?;
    psu.set_current(0.5)?;
    psu.enable()?;
    println!("Power enabled.");

    // Take a measurement and check the result; disable power before
    // asserting so the DUT is never left energized by a failing test.
    let voltage = sensor.read()?;
    println!("Sensor reading: {voltage:.4} V");
    psu.disable()?;

    assert!(
        (2.0..=3.0).contains(&voltage),
        "sensor voltage {voltage:.4} V outside range [2.0, 3.0]"
    );
    Ok(())
}

Cleanup matters: the Python version uses try/finally to guarantee the power supply is disabled even if an error occurs, and the Rust version disables power before its assertion (any earlier ? error also ends the test with the supply’s state visible in the failure). This is important for protecting your hardware.

Part 3: Running It

Execute the Python script on your Lager Box:

lager python my_first_test.py --box my-lager-box

Or run the Rust test from your project (with lager = { package = "lager-net", version = "0.2" } in [dev-dependencies]):

LAGER_BOX_HOST=<box-ip> cargo test

Expected output (Python):

Flashing firmware...
Flash complete.
Enabling power supply at 3.3V...
Power enabled.
Sensor reading: 2.4500 V
PASS: Sensor voltage within expected range.
Disabling power supply...
Done.

If you need to send additional files along with your script (firmware binaries, config files), use --add-file:

lager python my_first_test.py --box my-lager-box --add-file firmware.hex

What’s Next

You’ve completed your first test with Lager. Here are some directions to explore:

CLI Reference — Full documentation for every CLI command
Python API — Complete Python SDK reference
Rust API — Write your HIL suite as cargo test integration tests
Troubleshooting — Solutions when things go wrong
Glossary — Definitions for technical terms used in the docs

For a more comprehensive automation example combining robot arm control, USB hub power cycling, debug probe flashing, and ADC measurement, see the demo script.

​Part 1: CLI Walkthrough

​Step 1: Verify your box is online

​Step 2: Check connected instruments

​Step 3: View your configured nets

​Step 4: Set defaults to reduce typing

​Step 5: Flash firmware

​Step 6: Power on your device

​Step 7: Take a measurement

​Step 8: Power down

​Part 2: Your First Test Script

​Part 3: Running It

​What’s Next

Part 1: CLI Walkthrough

Step 1: Verify your box is online

Step 2: Check connected instruments

Step 3: View your configured nets

Step 4: Set defaults to reduce typing

Step 5: Flash firmware

Step 6: Power on your device

Step 7: Take a measurement

Step 8: Power down

Part 2: Your First Test Script

Part 3: Running It

What’s Next