Hardware Test

Prefer the installed $embedded-debugger, $baud, and $ble integrations; otherwise use their own CLIs with structured output. Keep each component's native workflow format and evidence as the source of truth. Do not create a second untyped command runner in this plugin.

For saved instrument captures or assertion evidence, read offline instrument workflows. Use the explicitly selected environment's native lab/HIL/Trace commands. Inspect published pins by default; choose historical local builds only with explicit candidate mode. The standalone payload inspector is sufficient for this file-only domain; board discovery and native hardware doctor are unnecessary. Preserve failed/invalid evidence and distinguish recorded native recomputation from current import/view success. For saved AD3 or SDS804X voltage checks, then read analog waveform evidence. Use native waveform commands; retain the explicit source inventory, RMS definitions, measurement qualifications and complete verdict even in filtered views.

For saved SDL1020X-E measurements, read load evidence. Use native load checks, JUnit and self-contained views. Failed sources retain unscored partial readings and unknown cleanup; a passing or empty page never replaces the global verdict.

For saved PureThermal/Lepton ROI assertions, read thermal evidence. Use native thermal commands and the full ordered raw inventory. Keep invalid pixels, FFC/mask trend limits, failed-source cleanup and apparent surface-temperature qualifications visible; saved evidence work does not require camera access.

For simulation-only regressions, read optional simulation first. Inspect the explicitly selected payloads with simulation_runtime.py, then use sim-runner or HIL's native simulation CLI and the matching Trace evidence views. Skip hardware doctor/discovery/selection for this domain. Reuse development task consent without per-run hash confirmation. Stop on unsupported models or failed/indeterminate cases; never fall back to physical hardware automatically. Preserve passed_with_model_limits, its diagnostics and false coverage/security claims; Trace retains succeeded_with_model_limits. Simulation results remain distinct from physical-board acceptance. For GPIO/TIMER0, keep guest samples, paused model snapshots and host run windows distinct; inspect/query/report retain the recorded context and false physical timing claim. For ESP32-S3, select the independent Xtensa runtime and keep its unmeasured device clock/core declarations and qualified outcome in filtered evidence views. For experimental ESP-EMU WASM, read WASM simulation. Use the published default pin; choose recorded local builds only explicitly. Keep string UART provenance, opaque ROM/eFuse state, model-clock claims, restart requests and native failures visible; encoded UART strings are not verified original UART bytes. For GPIO/TIMER0 fault regressions, read model fault evidence. Use the published default for released fault components; select --candidate only for an explicitly chosen recorded local build. Keep the native nominal verdict, effect/null state, counter/IRQ raw spans and failure stop. Successful injection never makes a failed regression pass or allows a later case to run.

For TMP103 temperature conversion or sensor fault regressions, read sensor simulation. Select the published environment from that guide; preserve guest samples, raw model spans, fault effect/null state and the nominal verdict without adding per-run approval. For LM74 signed Q4, two-byte framing or SPI fault regressions, read SPI simulation. Use the published simulation selection, preserve raw words/model/slip spans and fail-stop behavior, and reuse the agreed task authorization without per-run confirmation. For watchdog reload, stopped feeding or guest reboot regressions, read watchdog simulation. Use native watchdog schemas and preserve reset/callback/model spans, unknowns and the failed nominal verdict even when a fault effect is observed; reuse the agreed task scope. For RTC0 compare, event clearing or stop/mask regressions, read RTC simulation. Keep counter/event/IRQ spans, native failures and unknown effects intact; reuse the agreed task authorization. For EGU task/event/interrupt regressions, read EGU simulation. Preserve raw PRE/POST and ISR spans, unknowns and the failed nominal verdict even when masking or misrouting is observed; reuse the agreed task authorization without per-case confirmation. For GPIOTE input-edge, polarity or masked-interrupt regressions, read GPIOTE simulation. Preserve pin-level ISR and model spans, failed nominal outcomes and unknowns; reuse the agreed task scope. For TIMER0-to-PPI-to-GPIOTE functional regressions, read PPI simulation. Preserve route/output snapshots, fault effects and native failure stops; reuse task consent without per-case approval.

If the project supplies .embedded/toolchain-lock.json, validate it with the installed toolkit's component_lock.py inspect, pass it to doctor, and use only its hash-bound component paths. Do not let environment overrides mask that lock. Otherwise honor a workstation lock selected by station_config.py; confirm the doctor report names project, workstation, or command_line as its lock source before treating component readiness as stable. Ambient PATH readiness is only a host diagnostic, not a stable test-station identity. When a different lock is proposed, run component_lock.py compare first and surface every changed path, version, and hash before selecting it. For a new test station, run component_install.py plan before any hardware discovery. The plan is offline and starts no component. Run its install mode only when the user requested host setup and every pinned platform artifact is available; it may download and write versioned host executables but must not be treated as hardware authorization. Compare its new lock before adopting it. For a fresh station, the authenticated Toolkit bootstrap may perform the same catalog-backed component installation and strict doctor in one explicit command. Require separate component and new-lock destinations, and do not interpret successful host setup as permission to enumerate or operate a board.

Define the test contract

For project setup without hardware access, use the component's host-only embedded-debugger runtime init and runtime inspect commands. Read runtime-contract.md when creating a project's serial/reset acceptance contract. Keep this native format as the source of truth; do not add a toolkit execution wrapper or copy another board's identity.

Before hardware access, record:

• exact board, probe, target, serial, and BLE selection rules;
• firmware artifact hashes and expected memory layout;
• preconditions, allowed mutations, physical hazards, and abort conditions;
• positive and negative assertions with bounded deadlines;
• cleanup and recovery policy for every stage.

When the station has multiple boards or a test spans interfaces, use optional board-registry only on saved discovery evidence; read offline board identity resolution. Require a unique result for every transport in the test contract. Resolution narrows the board selection but does not authorize flash, reset, serial transmit, BLE write, or debug control.

For a multi-stage test, read hardware test contracts and use the host-only test_contract.py compile, inspect, and evaluate commands. Reference component-native workflows and firmware by path and SHA-256; never put shell commands, argv, executable paths, confirmation digests, or authorization claims in the contract or run manifest. Treat input drift, missing evidence, or an incomplete effect declaration as a stopping state. The compiled contract orders and constrains native workflows but cannot execute them or bypass their own gates. After separately gated component operations, bind the unchanged native JSON evidence in a non-authorizing run manifest and evaluate assertions and cleanup offline.

For CI reporting, Toolkit 0.23.0+ adds test_contract.py junit <contract> --run <run> --output <new.xml> --json; read the test-contract guide's JUnit section. It reevaluates the hash-bound saved evidence and exports assertions, input/stage checks and cleanup as distinct CI cases without rerunning hardware. Preserve nonzero exit status and upload XML on failure; missing or unevaluable evidence is an error, never a skip. Keep native JSON for details truncated in XML.

Friendly names and discovery order are not exact selection rules. Make retries explicit per stage; default state-changing operations to zero retries.

Execute in gates

The following gates apply to hardware tests. Saved instrument evaluation uses the file-only workflow above; it needs no board discovery or hardware doctor.

1. Run the host-only toolkit doctor. When discovery belongs to a repeatable test, declare baud.list, blea.doctor, or embedded-debugger.probes-list as the first contract stage and assert the exact native identity fields. BLEA doctor performs a short scan; none of these discovery stages may open a serial port, connect, attach, or control a target.
2. Verify preconditions and acquire exclusive ownership of the relevant ports, probes, adapters, and board. Do not run competing transports concurrently when reset lines, boot modes, or target state can interact.
3. Plan and confirm flashing through $embedded-debugger; preserve the exact result and cleanup evidence. For repeated firmware builds, read bounded flash sessions. A native session can reuse one user-approved scope for bounded code-Flash builds only while its executor remains alive. Do not turn a test contract into authorization or auto-forward per-build digests through the old CLI path. For continuous build/flash/observe loops or shared-board ownership, read optional HIL Runner. Use its native managed owner with the inspected runtime and qualified debugger, including the additional per-build runtime reset in the agreed scope. Reuse valid task authorization; do not add a confirmation before each build or require HIL for a single flash.
4. Wait for a bounded ready assertion through zero-transmit serial observation, RTT when supported by the debugger, or read-only BLE evidence. For RTT, read bounded RTT workflows. Use the native CLI, declare read-cursor consumption and attach effects, and preserve both summary and raw JSONL. Offline integrity checks do not replace a project's complete READY/build/heartbeat assertions or prove final core state. Use the RTT guide's offline inspect/preview/extract commands for saved logs; bind the derived payload hash and evaluate the full bytes for readiness, not a bounded or truncated preview.
5. Perform only the declared interactions. Serial transmissions, BLE writes, pairing changes, reset control lines, and debug target control retain their component gates. For blea.pair or blea.unpair, require an exact observed identifier and BLEA's native pairing guard. An authorization already granted for the agreed device and bounded task remains valid; do not interrupt each stage to ask for the same authorization again. Never place a pairing PIN in a Toolkit contract, evidence file, process argument, or report, and never retry an indeterminate pairing change.
6. Evaluate hash-bound structured evidence with test_contract.py evaluate, not console appearance. A missing pointer, mismatched digest, or unverified cleanup state is a failure, never an implicit pass.
7. Close the exact sessions and report target, process, port, and adapter cleanup.

For offline review across saved serial/RTT evidence, use optional Embedded Trace timelines. Retain native evidence and full runtime assertions: a successful import or bounded READY query does not replace per-build native acceptance or Toolkit contract evaluation. This analysis adds no hardware action or per-flash confirmation.

Stop at the first indeterminate state-changing result. Preserve all evidence and require an explicit recovery decision instead of retrying or switching devices.