lr-lumentest-sdk

Step-authoring SDK for LumenRadio LumenTest test sequences.

This package is for an embedded developer writing or updating test steps and sequences for a LumenTest production station, who wants a .venv and an editor with working imports, type hints and autocomplete for the step API — without checking out or installing the station itself. It ships the exact same lumentest_station source files the station runs, so a step written and tested against this package behaves identically when the station loads it.

Installation

pip install lr-lumentest-sdk

This package and lumentest-station both provide the lumentest_station import name and must never be installed into the same environment. A station developer already has the real package — install lr-lumentest-sdk only in a separate .venv dedicated to authoring steps and sequences.

Public API

from lumentest_station import (
    step_options,      # decorator: attaches step metadata (type, timeout, limits section)
    sequence_options,  # decorator: attaches sequence metadata (name, serial handling)
    run_tool,          # run an external tool as a supervised subprocess
    StepFailed,        # raise to fail the step; optionally carrying the ToolResult that failed
    ToolResult,        # what run_tool() returns: exit_code, stdout, stderr, timed_out
    Measurement,       # a single limits-checked measurement to report
    step_main,         # run this step standalone from the command line
)

Running a single step

A step module can run itself directly, with no separate harness:

from lumentest_station import step_options, step_main


@step_options("PROGRAMMING", display_name="Flash Firmware")
def flash_firmware(test):
    ...


if __name__ == "__main__":
    raise SystemExit(step_main(flash_firmware))

python my_step.py --limits limits.toml --manifest artifact-manifest.json

For a step file with no __main__ guard, use the lumentest-step console script instead:

lumentest-step validate my_step.py
lumentest-step run my_step.py --limits limits.toml --manifest artifact-manifest.json --env NRF_TOOLS=/opt/nrf --results-dir ./results

validate is a static check only — it never imports the file, so it needs no hardware and no environment. It enforces the two rules the station's loader enforces: exactly one @step_options-decorated top-level function, and no direct subprocess use (steps call run_tool instead). run performs the same check, then imports and executes the step.

Options for run, and for step_main under a __main__ guard:

The exit status is 0 when the step passed, 1 when it failed (an explicit StepFailed, or an out-of-limit measurement), and 2 on an error — an unexpected exception, a timeout, or a file the loader rejects.

A station does far more than run one step: it uploads to QRM, validates serial numbers, curates the PATH a tool is resolved against, and runs a whole sequence in order. None of that is reproduced here. A green standalone run says the step's own logic holds, not that the sequence will pass on a station.

Full authoring guide

For the complete authoring reference — sequence structure, limits files, manifests, the step SDK's allowed third-party imports, and the full lumentest-step command reference — see doc/step-sdk.md in the LumenTest repository.