Metadata-Version: 2.4
Name: labwired
Version: 0.25.0
Classifier: Framework :: Pytest
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: pytest>=7 ; extra == 'test'
Provides-Extra: test
Summary: Run and test microcontroller firmware in a deterministic virtual-time simulator
Keywords: embedded,firmware,simulator,testing,pytest
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://labwired.com
Project-URL: Source, https://github.com/w1ne/labwired-core

# labwired (Python)

Run microcontroller firmware in the LabWired simulator and test it with pytest.
Time is virtual: execution advances only inside `run_for` and `expect`.

## Install

```sh
pip install labwired
```

Wheels are abi3: one wheel per platform covers CPython 3.9 and newer
(Linux x86_64/aarch64, macOS arm64/x86_64, Windows x64).

## Test firmware with pytest

The package installs a pytest plugin with a `sim` fixture:

```python
def test_boot_banner(sim):
    with sim("firmware.elf", chip="stm32f103") as s:
        s.expect(r"boot ok", timeout="10ms")
        s.send("ping\n")
        assert s.expect("pong", timeout="5ms").text == "pong"
```

Run it with `pytest`. Give `--labwired-chip <name>` to set a default chip for
every `sim(...)` call. On a failure, the report shows the UART transcript.

## API summary

- `Sim(elf, chip=... | system=..., uart=None)`: one ELF on one machine.
- `run_for(duration)`, `expect(pattern, timeout)`: advance virtual time.
- `read_uart()` returns text (invalid UTF-8 becomes U+FFFD).
  `read_uart_bytes()` returns the raw bytes.
- `send(text)`, `send_bytes(data)`, `read_u32`, `write_u32`, `read_memory`,
  `snapshot()`, `restore(snap)`, `set_input`, `set_pin`, `frames()`.
- `run_firmware(elf, chip=..., duration="1s", expect=...)`: one-shot helper.

