LabWired Core

LabWired Core runs embedded firmware in a deterministic simulated hardware lab.

It loads real firmware ELFs and executes them against modeled chips, boards, peripherals, buses, sensors, displays, and protocol devices. The goal is not to replace every hardware test. The goal is to move the fast, repeatable part of firmware bring-up and regression testing into a local and CI-friendly simulator.

What You Can Do

Use case	Where to start	What LabWired provides
Run firmware without a board	labwired run	ELF loading, system manifests, UART/GPIO output, traces, snapshots
Gate firmware behavior in CI	labwired test	YAML test scripts, assertions, exit codes, artifacts, JUnit output
Debug firmware without hardware	Debugging, GDB	GDB RSP and VS Code DAP support for breakpoints and register inspection
Model board-level I/O	examples/demo-blinky	External I2C/SPI-style device attachment, board I/O mapping, deterministic checks
Validate simulator behavior against hardware	examples/nucleo-h563zi	Hardware and simulator traces, UART logs, reproducible validation reports
Add or audit chip support	Board onboarding, coverage	Chip/system YAML, target support rubric, smoke coverage, catalog metadata

Supported targets are intentionally uneven. ARM Cortex-M and RISC-V have the deepest CI coverage today; selected ESP32/Xtensa paths exist for specific examples. Check the per-board docs before assuming a peripheral is modeled: docs/boards.

Quick Start

Install the CLI

Pinned release:

curl -fsSL https://labwired.com/install.sh | LABWIRED_VERSION=v0.18.0 sh
labwired --version

Prefer to inspect the installer first:

curl -fsSL https://labwired.com/install.sh -o install.sh
# review install.sh, then:
LABWIRED_VERSION=v0.18.0 sh install.sh

Supported host environments:

• Linux
• macOS
• Windows via WSL2

Install options:

• LABWIRED_VERSION=v0.18.0 pins a release. Omit it to install the latest published version.
• LABWIRED_FROM_SOURCE=1 forces a source build.
• LABWIRED_INSTALL_DIR=~/.local/bin changes the install directory.

Run the CI smoke example from a source checkout

The bundled smoke script expects the fixture firmware to exist in target/. From the repository root:

rustup target add thumbv6m-none-eabi
cargo build -p firmware-ci-fixture --release --target thumbv6m-none-eabi
cargo run -q -p labwired-cli -- test \
  --script examples/ci/uart-ok.yaml \
  --output-dir /tmp/labwired-readme-smoke \
  --no-uart-stdout

That script runs the fixture firmware against configs/systems/ci-fixture-uart1.yaml and asserts that UART output contains OK.

Build the simulator from source

rustup target add thumbv6m-none-eabi thumbv7m-none-eabi riscv32i-unknown-none-elf
cargo build --release -p labwired-cli
./target/release/labwired --version

Examples

Start with examples that have a clear system manifest, firmware path, and smoke test:

• CI UART smoke: minimal labwired test scripts for deterministic pass/fail behavior.
• Blinky + TMP102: STM32F103 firmware talking to a virtual TMP102 sensor over I2C.
• NUCLEO-H563ZI: same demo story on the simulator and a physical STM32H563ZI Nucleo board, with committed validation artifacts.
• NUCLEO-L476RG: survival and validation traces for an STM32 Nucleo target.
• Seeed XIAO nRF52840 Sense: nRF52840 board coverage with UART/GPIO/SPI smoke paths.
• UDS on STM32F103 and UDS on STM32H563: CAN/UDS-oriented firmware examples.
• IO-Link DIDO: IO-Link device-oriented system wiring and smoke test.

For the broader list, see docs/demos.md. Treat each example's README and validation file as the source of truth for what is actually modeled.

Validation Model

LabWired distinguishes between three levels of confidence:

• Modeled: a chip, peripheral, bus, or external device has simulator logic behind it and can execute firmware behavior.
• Smoke-tested: a repository test or example script exercises that model and checks observable output.
• Hardware-compared: captured hardware behavior is compared with simulator behavior for a documented scope.

The H563 example is the best place to inspect hardware-comparison artifacts:

• examples/nucleo-h563zi/golden-reference/determinism_report_h563.json
• examples/nucleo-h563zi/VALIDATION.md
• docs/golden_reference.md

Those reports are evidence for the scope they describe. They are not a blanket claim that every instruction, peripheral, or timing path matches hardware.

Repository Scope

This repository owns the core simulator and its validation assets:

• CPU, bus, memory, peripheral, and external device execution.
• Chip and system descriptors in configs/chips and configs/systems.
• CLI, test runner, debug adapters, and snapshot/trace tooling.
• Hardware-target validation metadata consumed by catalog and app surfaces.

Application UI, hosted playground behavior, and product-specific surfaces live outside this core package.

CI and Release Signals

The main merge gate is .github/workflows/core-ci.yml: formatting, linting, build, and integration tests.

Additional workflows publish narrower signals:

• core-board-ci.yml: board/example smoke coverage.
• core-coverage.yml: coverage checks.
• core-unsupported-audit.yml: unsupported instruction audits.
• core-nightly.yml: broader scheduled validation.
• core-validate-hw-targets.yml: onboarding target sweep and catalog metadata.

For release mechanics, see RELEASE_PROCESS.md and RELEASE_READINESS_CHECKLIST.md.

Documentation

• Docs index
• Architecture overview
• Engine architecture
• CLI reference
• CI test runner
• Configuration reference
• Board onboarding playbook
• Target support rubric
• Debugging
• PlatformIO integration
• Agents manual

Contributing

Use CONTRIBUTING.md for repository workflow and docs/agents.md for AI-agent-specific guidance. For security issues, see SECURITY.md.

License

MIT. See LICENSE.