Lager CLI

A powerful command-line interface for controlling embedded hardware, test equipment, and development boards through Lager Data box devices.

Features

Hardware Control

Power Management: Control power supplies, battery simulators, solar simulators, and electronic loads
I/O Operations: ADC/DAC, GPIO, thermocouple sensors
Test Instruments: Oscilloscopes, logic analyzers, multimeters, signal generators

Embedded Development

Debugging: ARM Cortex-M debugging with J-Link, CMSIS-DAP, ST-Link support
Firmware Flashing: Flash firmware via debug probes
Serial Communication: UART terminal with test framework integration
Robotics: Robot arm control for automated testing

Wireless & Connectivity

Bluetooth LE: Scan, connect, and interact with BLE devices
USB: Programmable USB hub control
Webcam: Video streaming from box devices

Installation

Install the Lager CLI using pip:

pip install lager-cli

Or upgrade to the latest version:

pip install -U lager-cli

Quick Start

Configure your box:
```
lager defaults set box <your-box-id>
```
Test connectivity:
```
lager hello
```
List available instruments:
```
lager instruments
```

Control a power supply:

lager supply <net> voltage 3.3 --box <box-id>

Core Commands

Power Supply Control

# Set voltage and enable output
lager supply <net> voltage 3.3 --yes

# Set current limit
lager supply <net> current 0.5

# Check power state
lager supply <net> state

ADC/DAC Operations

# Read ADC voltage
lager adc <net>

# Set DAC output
lager dac <net> 1.8

Embedded Debugging

# Connect to debug probe
lager debug <net> connect --box <box>

# Flash firmware (auto-connects if needed)
lager debug <net> flash --hex firmware.hex --box <box>

# Reset and halt target
lager debug <net> reset --halt --box <box>

# Stream RTT logs
lager debug <net> rtt --box <box>

# Read memory
lager debug <net> memrd 0x08000000 256 --box <box>

Oscilloscope & Logic Analyzer

# Measure frequency on scope channel
lager scope <net> measure freq

# Configure edge trigger
lager logic <net> trigger edge --slope rising --level 1.8

Battery & Solar Simulation

# Set battery state of charge
lager battery <net> soc 80

# Configure solar irradiance
lager solar <net> irradiance 1000

Serial Communication

# Connect to UART
lager uart --baudrate 115200

# Interactive mode with test runner
lager uart -i --test-runner unity

# Show the tty path for a UART net
lager uart <net> serial-port

# Create a UART net for an adapter without a USB serial number (store /dev path directly)
lager nets add <net> uart /dev/ttyUSB0 <label> --box <box>
# Warning: tty names can change after reboot; prefer device-serial mode when available

Bluetooth LE

# Scan for BLE devices
lager ble scan --timeout 5.0

# Connect to device
lager ble connect <address>

Configuration

Box Setup

The CLI connects to boxes via:

Direct IP: Using Tailscale or VPN IP addresses

Create a .lager file in your project directory:

{
  "boxes": {
    "my-box": "box-abc123",
    "local-box": "<BOX_IP>"
  }
}

Direct IP Access

For direct IP connections, ensure SSH key authentication is configured:

# Configure SSH key for a box
ssh-copy-id lagerdata@<box-ip>

# Then connect via the CLI
lager ssh --box <box-ip>

Environment Variables

LAGER_BOX: Default box ID or IP address
LAGER_DEBUG: Enable debug output
LAGER_COMMAND_DATA: Command data (used internally)

Net Management

Lager uses "nets" to represent physical test points or signals on your PCB:

# List all configured nets
lager nets

# Create a new power supply net
lager nets add VDD_3V3 supply 1 USB0::0x1AB1::0x0E11::DP8C0000001

# Auto-discover and create all nets
lager nets add-all

# Interactive TUI for net management
lager nets tui

Advanced Features

Remote Python Execution

# Run a Python script on the box
lager python my_script.py --box <box-id>

# Run with port forwarding
lager python --port 5000:5000/tcp server.py

Development Environment

# Create a development environment
lager devenv create --image python:3.10

# Open interactive terminal
lager devenv terminal

Package Management

# Add a package to the box's declarative config
lager box-config pip add numpy

# Apply the change (restarts the lager container, runs pip install)
lager box-config apply

Supported Hardware

Debug Probes

SEGGER J-Link
ARM CMSIS-DAP
ST-Link v2/v3
Xilinx XDS110

Power Supplies

Rigol DP800 series
Keysight E36200/E36300 series
Keithley 2200/2280 series

Battery Simulators

Keithley 2281S

Solar Simulators

EA PSI/EL series (two-quadrant)

Oscilloscopes

Rigol MSO5000 series

I/O Hardware

LabJack T7 (ADC/DAC/GPIO)
MCC USB-202 (ADC/DAC/GPIO)

USB Hubs

Acroname USBHub3+
YKUSH

Robotics

Rotrics Dexarm

Temperature

Phidget Thermocouples

Target Microcontrollers

Supports debugging and flashing for:

STM32 (F0/F1/F2/F3/F4/F7/G0/G4/H7/L0/L1/L4/WB/WL series)
Nordic nRF52/nRF91
Atmel/Microchip SAM D/E/4S/70
Texas Instruments CC32xx
NXP i.MX RT, LPC54xx/55xx
Silicon Labs EFM32
Microchip PIC32MM

Authentication & Access

The CLI authenticates to boxes via VPN access (Tailscale or similar). Access control is managed by your VPN permissions - if you have VPN access to a box, you can control it with the CLI.

Prerequisites

VPN Access: Connect to your organization's VPN (Tailscale, etc.)
SSH Keys: Configure SSH key authentication for direct box access:
```
ssh-copy-id lagerdata@<box-ip>
```
SSH to Box: Use the CLI to connect:
```
lager ssh --box <box-ip-or-name>
```

Verify Connectivity

# Test box connectivity
lager hello --box <box-id-or-ip>

# Check box status
lager boxes

Documentation

For detailed documentation, visit: https://docs.lagerdata.com

Command Help

Every command has built-in help:

lager --help                 # Show all commands
lager supply --help          # Show supply command options
lager debug --help           # Show debug command options

Examples

Automated Test Script

#!/bin/bash

BOX="my-box"

# Configure power supply
lager supply VDD voltage 3.3 --box $BOX --yes

# Flash firmware
lager debug DEBUG_SWD flash --hex build/firmware.hex --box $BOX

# Reset and start
lager debug DEBUG_SWD reset --box $BOX

# Monitor UART output
lager uart --baudrate 115200 --test-runner unity --box $BOX

# Read sensor values
voltage=$(lager adc SENSOR_OUT --box $BOX)
temp=$(lager thermocouple TEMP1 --box $BOX)

echo "Voltage: $voltage V"
echo "Temperature: $temp °C"

# Disable power
lager supply VDD disable --box $BOX

Interactive Python Control

# example_test.py - Run on box with: lager python example_test.py
from lager import Net, NetType

# Access hardware through net abstraction
supply_net = Net("VDD_3V3", NetType.SUPPLY)
adc_net = Net("VOUT", NetType.ADC)

# Set power supply voltage and enable
supply_net.set_voltage(3.3)
supply_net.enable()

import time
time.sleep(0.1)

# Measure voltage
voltage = adc_net.read()
print(f"Output voltage: {voltage:.3f} V")

# Disable supply
supply_net.disable()

Troubleshooting

Connection Issues

# Test box connectivity
lager hello --box <box-id>

# Check box status
lager hello --box <box-id>

Permission Errors

For Tailscale/direct IP connections, ensure SSH keys are configured:

# Set up SSH keys
ssh-copy-id lagerdata@<box-ip>

# Test SSH access
lager ssh --box <box-ip-or-name>

Debug Probe Not Found

Verify J-Link GDB Server is installed on the box:

# Download J-Link to /tmp/ on your local machine
# Visit: https://www.segger.com/downloads/jlink/
# Download: JLink_Linux_V794a_x86_64.tgz to /tmp/

# Deploy box (J-Link will be installed automatically)
lager install --ip <box-ip>

Authentication Issues

If you encounter connection issues:

Verify VPN connection: Ensure you're connected to the correct VPN
Check SSH keys: Verify SSH key authentication is configured
```
ssh-copy-id lagerdata@<box-ip>
```
Test SSH access: Try connecting to the box
```
lager ssh --box <box-ip-or-name>
```
Test connectivity: Use lager hello to verify the box is reachable
```
lager hello --box <box-ip-or-name>
```

Contributing

We welcome contributions! Please see CONTRIBUTING.md for more information.

Support

Documentation: https://docs.lagerdata.com
Issues: GitHub Issues

License

Apache License 2.0 - Copyright (c) Lager Data

Testing

Comprehensive test suites are available in the test/ directory:

# Hardware-dependent tests (require instruments)
./test/integration/power/supply.sh <BOX> <NET>
./test/integration/power/battery.sh <BOX> <NET>
./test/integration/debug/debug.sh <BOX> <NET> <HEXFILE> <ELFFILE>
./test/integration/io/labjack.sh <BOX> <NET>

See test/README.md for test format and how to write new tests.

Changelog

Recent Updates

Renamed test scripts for clarity (test_*_commands.sh → *.sh)
Unified box deployment script (setup_and_deploy_box.sh)
Added comprehensive test documentation (test/README.md)
Enhanced debug command with RTT streaming and memory operations
Improved error handling and validation across all commands

See full changelog in the releases.

Release files for lager-cli 0.49.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lager-cli 0.49.0
File	Size	Uploaded
lager_cli-0.49.0.tar.gz	586.9 kB	Sep 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for lager-cli 0.49.0
File	Interpreter	ABI	Platform	Reset
lager_cli-0.49.0-py3-none-any.whl 650.9 kB Sep 19, 2026	Python 3	none	any	Details

Total release size:1.2 MB

Release files / lager_cli-0.49.0.tar.gz

Download URL	lager_cli-0.49.0.tar.gz
Size	586.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`71fbec4de12805dafec8fa121d9d6374f81b848aa9964dfb5cbea4751fc922df`
BLAKE2b-256 checksum How to use checksums	`21125e488c12ee323a9e6478eb618c4ec3dfe77fb117d9b70099b3b0bf1a1013`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.13`

Release files / lager_cli-0.49.0-py3-none-any.whl

Download URL	lager_cli-0.49.0-py3-none-any.whl
Size	650.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f2e04c0b45e348b9a5f109258cc7a1df0d2670a4cc6e8ec55778594d040d7164`
BLAKE2b-256 checksum How to use checksums	`cac806e0fc41ea7d2bc46b2342a81758aedf53f1b9c766c977d27cb47dc584bc`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.13`