LabWired Core

Run your firmware on a virtual instance of a real chip, from your terminal, your CI, or your AI coding agent. No board on your desk.

Recorded from docs/assets/demo.tape against a real binary. You can re-run it. The second half breaks an assertion on purpose, so you can see the gate fail.

What is LabWired Core?

LabWired Core loads a firmware ELF and executes it against modeled silicon: CPU, buses, peripherals, sensors, displays, and protocol devices. You get UART output, GPIO and bus traces, register state, and a pass/fail exit code.

Runs are deterministic. The same ELF and the same board manifest give the same trace on every machine. That is what makes a simulator run usable as a CI gate.

Supported cores:

• ARM Cortex-M0+, Cortex-M3, Cortex-M4, Cortex-M7, Cortex-M33
• RISC-V
• Xtensa LX6 and LX7 (selected ESP32 paths)

This repository is the engine behind labwired.com. The hosted browser Playground and the hosted MCP connector run the same models. To look before installing anything, open a lab: SSD1306 hello, U575 Star Catcher, BME280 weather, or IO-Link DI/DO.

Why use LabWired Core?

Testing firmware on real boards is slow. You wait for hardware, you flash it, and when something breaks you get a dark LED and no trace. Do that for every board in a product line and a hardware CI bench stops being worth the upkeep.

LabWired runs the same binary you would flash. You assert on what the firmware made the hardware do.

Two things separate it from a CPU emulator.

The board is modeled, not only the chip. Sensors, displays, and bus devices live in the system manifest. You can assert on I2C traffic, SPI framing, or what a panel was told to draw.

We publish where the model is thin. Every capability sits in a named tier. Anywhere the simulator short-circuits real hardware, we write it down in the Fidelity Ledger. You cannot gate on a simulator you cannot audit.

Quickstart

Clone the repository, install the CLI, run a firmware. No cross-toolchain needed.

git clone https://github.com/w1ne/labwired-core && cd labwired-core
curl -fsSL https://labwired.com/install.sh | LABWIRED_VERSION=v0.25.0 sh
labwired test --script examples/nrf54l15-dk/io-smoke.yaml

nRF54L15 boot OK
core=cortex-m33 rram=1524K ram=256K
uarte20@0x500C6000 gpio2@0x50050400
regs from MDK/SVD, not nRF52
PASS  4/4 checks · io-smoke · 200000 steps · 0.04s

That is a committed bare-metal ELF booting on an nRF54L15-DK profile in under a second. Nothing is compiled on your machine.

The four checks are the three UART lines plus the stop reason.

The firmware prints those lines from string literals. The text proves nothing by itself. What it proves is that the bytes arrived. To send them, the firmware had to boot from RRAM at 0x0, set up RAM at 0x20000000, and drive UARTE20 over EasyDMA. Get the UARTE base wrong in the chip model and you get no output at all.

GPIO is checked at the pin, not in the banner, by firmware_survival::test_nrf54l15_lights_dk_led0. The example README says why both tests are needed.

The verdict goes to stderr. The exit code is the gate: 0 passes, anything else fails. UART output and --json stay on stdout, so pipes keep working.

Installation

The install script covers Linux, macOS, and Windows via WSL2.

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

To read the installer before running it:

curl -fsSL https://labwired.com/install.sh -o install.sh   # review it, then:
sh install.sh

Windows

There is a native Windows build — labwired.exe and labwired-dap.exe — but no install script for it; the archive is unpacked by hand. PowerShell 5.1 and later have tar built in.

$v = "v0.25.0"
Invoke-WebRequest "https://github.com/w1ne/labwired-core/releases/download/$v/labwired-$v-windows-x86_64.tar.gz" -OutFile labwired.tar.gz
mkdir $env:LOCALAPPDATA\LabWired -Force
tar -xzf labwired.tar.gz -C $env:LOCALAPPDATA\LabWired
$env:PATH += ";$env:LOCALAPPDATA\LabWired"
labwired --version

The VS Code extension does this for you on Windows — it downloads the same archive on first use. WSL2 also works and takes the Linux instructions above.

Or build it yourself:

cargo build --release -p labwired-cli

Running LabWired

From your terminal

labwired run  --chip configs/chips/<chip>.yaml --firmware path/to/firmware.elf
labwired test --script  path/to/test.yaml --junit report.xml

run is interactive: UART, GPIO, traces, snapshots.

test is the gate. It writes result.json, uart.log, and JUnit, and returns an exit code. Assertions cover UART content, memory and register values, stop reasons, and step and wall-time limits.

See the CLI reference and the test runner reference.

From Python

Use labwired.Sim to run an ELF, wait for UART output, and write pytest checks:

from labwired import Sim

with Sim("tests/fixtures/uart-ok-thumbv7m.elf",
         chip="ci-fixture-cortex-m3-uart1", uart="uart1") as sim:
    sim.expect("OK", timeout="1ms")

The SDK runs the Rust engine in your Python process. Start with the Python SDK quickstart for source installation and a runnable pytest test. This SDK is not yet published to PyPI.

In CI

The same YAML scripts are the merge gate, with no HIL bench to maintain:

- run: labwired test --script examples/ci/uart-ok.yaml --junit report.xml

See CI integration and labwired.com/ci.

From an AI coding agent (MCP)

LabWired speaks MCP. An agent can assemble a board, run firmware, and read the result back. You never touch the toolchain.

claude mcp add labwired --transport http https://api.labwired.com/mcp
codex   mcp add labwired --url https://api.labwired.com/mcp

Your client opens a browser to sign in on first use. Other MCP clients take the standard block:

{ "mcpServers": { "labwired": { "type": "http", "url": "https://api.labwired.com/mcp" } } }

Then ask for what you want:

"Connect LabWired over MCP. Load a virtual STM32 LED + UART board, run the firmware, check the UART output, and give me the Playground URL."

Agents working inside this repository should read docs/agents.md.

How a board is described

A board is data, not code.

A chip descriptor in configs/chips declares memory geometry, cores, and peripheral bases. A system manifest in configs/systems wires up pins, buses, and the devices on them. Firmware writes to modeled registers. The modeled hardware drives the firmware back.

To add a board you write those two files and an example. You do not patch the engine. See the board onboarding playbook and the configuration reference.

What we validate

Every capability sits in one of three tiers, and