simantic 0.3.1__tar.gz → 0.4.0__tar.gz

{simantic-0.3.1 → simantic-0.4.0}/.github/workflows/ci.yml

@@ -25,8 +25,6 @@ on:
       - '.claude/**'
       - 'LICENSE'
   pull_request:
-    # `ready_for_review` is NOT a default activity type. Without it, flipping a
-    # draft to ready fires no event, so the macOS leg gated below never runs.
     types: [opened, synchronize, reopened, ready_for_review]
     paths-ignore:
       - 'docs/**'
@@ -40,20 +38,15 @@ concurrency:
 
 jobs:
   test:
-    runs-on: ${{ matrix.os }}
-    # The SDK is pure Python, so a macOS runner proves very little here that
-    # Linux does not — and it bills at $0.062/min against Linux's $0.006, with a
-    # 10x draw on the included-minutes allowance. Two of the six legs were
-    # macOS. It now joins on a push to main, on a v* tag (a release should be
-    # proven on all three), and on a pull request once marked ready for review.
-    # Windows is left unconditional: at 2x it is not what the bill is made of.
+    runs-on: ubuntu-latest
+    # macOS dropped from CI entirely (ci: drop macOS, single-OS fixtures,
+    # manual-only aux checks) — the SDK is pure Python, so a macOS runner
+    # proved very little here that Linux does not, at 10x Linux's billing
+    # rate. macOS is tested locally instead.
     timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
-        os: ${{ (github.event_name != 'pull_request' || github.event.pull_request.draft == false)
-          && fromJSON('["ubuntu-latest", "macos-latest"]')
-          || fromJSON('["ubuntu-latest"]') }}
         # 3.11 is the floor (tomllib landed there); 3.13 guards the top end.
         python: ["3.11", "3.13"]
     steps:

simantic-0.4.0/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.5
+Name: simantic
+Version: 0.4.0
+Summary: Python SDK and pytest plugin for the Simantic circuit and firmware simulators
+Project-URL: Homepage, https://simantic.dev
+Project-URL: Source, https://github.com/simantic-dev/pippy
+Project-URL: Issues, https://github.com/simantic-dev/pippy/issues
+Author: Simantic
+License-Expression: MIT
+License-File: LICENSE
+Keywords: circuit,eda,firmware,kicad,pytest,simulation,spice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.11
+Requires-Dist: pythonnet>=3.0.5
+Requires-Dist: pyyaml>=6
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://simantic.dev/simantic_logo_4_full.png" alt="Simantic" width="340">
+</p>
+
+<h3 align="center">Test your firmware without a board.</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/simantic/"><img src="https://img.shields.io/pypi/v/simantic.svg" alt="PyPI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/simantic.svg" alt="Python versions">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT licence">
+</p>
+
+Nothing to plug in, nothing to flash. Simantic boots your real ELF on a
+simulated microcontroller and hands you the whole machine from Python. Watch it
+print, press a button, read a variable straight out of RAM.
+
+```bash
+pip install simantic
+```
+
+```python
+from simantic import Sim
+
+with Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2") as sim:
+    sim.expect("ready")
+    sim.inject_gpio("gpioc", 13, True)      # press the user button
+    sim.expect("button pressed")
+    assert sim.read_u32("press_count") == 1
+```
+
+That is a whole test. No probe, no breakpoint, no waiting on hardware.
+
+Three things you get that a bench cannot give you:
+
+* **See inside.** Read any variable, register, or RTOS thread while the
+  firmware runs, without halting it.
+* **Poke it.** Press buttons, send CAN frames, feed the radio, all from your
+  script.
+* **Repeat exactly.** Time moves only when you ask, so a run comes out the same
+  every time, on your laptop and in CI.
+
+The simulator lives inside your Python process, so there is no server to start
+and no port to talk to.
+
+> **Alpha, version 0.4.x.** We are still moving things around, so the API can
+> change without a deprecation period. Pin an exact version
+> (`simantic==0.4.0`) if you depend on it, and please hold off on production
+> pipelines for now. Tell us what breaks.
+
+## Setup
+
+`pip install` is the whole setup. The first `Sim(...)` downloads the engine it
+needs into `~/.simantic/` and checks it against the published checksum. The
+wheel on PyPI holds only Python code; the simulators are never inside it.
+
+Sign in once if you want to name MCUs by part number:
+
+```bash
+simantic auth
+```
+
+That opens a browser tab, much like `gh auth login`, and saves a token to
+`~/.sim_id`. In CI, pipe one in instead: `echo $TOKEN | simantic auth`.
+
+Already have the `sim` binary? Put it on PATH or point `$SIMANTIC_SIM` at it.
+`simantic status` shows what resolved.
+
+## Pick your engine
+
+The same script runs on either engine. You choose per simulation:
+
+```python
+Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2")                  # Renode engine, the default
+Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2", backend="rust")  # our Rust engine
+```
+
+The Rust engine is a small extension module, runs one machine, and is
+considerably faster. Anything it cannot do yet, such as multi machine scenarios
+or CAN and radio injection, raises `simantic.NotSupported` and names the gap
+instead of quietly doing nothing. What each engine covers is listed in
+[the engine table](https://github.com/simantic-dev/pippy/blob/main/docs/session-api.md#what-each-engine-supports).
+
+## ESP32 images
+
+The ESP32-C3, C6 and P4 boot the way silicon does: Espressif's mask ROM runs
+first, then your bootloader, then your app. `sim --elf` therefore takes one ELF
+that carries the ROM and your whole flash image. Build it from the files your
+ESP-IDF or PlatformIO build already produced:
+
+```bash
+simantic esp-image --chip esp32c3 \
+    --part 0x0:bootloader.bin --part 0x8000:partitions.bin --part 0x10000:firmware.bin \
+    --flash-size 16MB -o image.elf
+sim --elf image.elf ...
+```
+
+Already have a merged image from `esptool.py merge_bin`? Pass `--flash merged.bin`
+instead of the parts. The same thing from Python is
+`simantic.esp_image.build_image("esp32c3", flash, out="image.elf")`.
+
+The mask ROM is Espressif's and is not bundled. On first use it is downloaded
+from Espressif's own repositories, pinned by commit and SHA-256, and cached in
+`~/.simantic/esp-rom`: the raw C3 and C6 dumps from
+[espressif/qemu](https://github.com/espressif/qemu/tree/master/pc-bios), and
+the P4 ROM from the [esp-rom-elfs](https://github.com/espressif/esp-rom-elfs)
+release ESP-IDF installs. Offline, or with your own copy, pass `--rom`.
+`simantic esp-rom --chip esp32c3` downloads it ahead of time and prints where it
+went.
+
+## Testing with pytest
+
+Take the `sim` fixture and write ordinary tests:
+
+```python
+def test_timer_irq_fires(sim):
+    s = sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2")
+    s.expect("fired=1", timeout=8)
+    assert s.read_u32("fired") == 1
+```
+
+The engine starts once per worker rather than once per test, and every machine
+is closed for you. When a test fails, its UART transcript is attached to the
+report, because that is usually the evidence you want.
+
+### Test what went over the wire
+
+Firmware that prints "sensor OK" is reporting its own bookkeeping. The bus
+tells you what happened. Put a scripted device on the other end of each bus
+(a `parts` entry per device, each backed by a few dozen lines of Python), wire
+the media in a scenario, and assert on `frames()`:
+
+```python
+SCENARIO = {
+    "machines": {"dut": {
+        "mcu": "STM32H753IITX", "elf": "fc.elf",
+        "parts": [
+            {"name": "imu0",    "type": "spi-device",  "bus": "spi1", "cs": "PC4", "script": "icm42688.py"},
+            {"name": "baro",    "type": "i2c-device",  "bus": "i2c2", "address": 0x63, "script": "icp20100.py"},
+            {"name": "gpspeer", "type": "uart-device", "baud": 230400, "script": "gps.py"},
+            {"name": "canpeer", "type": "can-node",    "script": "dronecan.py"},
+        ],
+    }},
+    "media": [
+        {"type": "uart", "connect": ["dut.usart6", "dut.gpspeer"]},
+        {"type": "can",  "connect": ["dut.fdcan1", "dut.canpeer"]},
+    ],
+}
+
+def test_imu_configured_then_streams(sim):
+    s = sim(scenario=SCENARIO, machine="dut", uart="usart1")
+    s.run_for(3.0)                                            # virtual seconds
+    imu = [f for f in s.frames() if f["label"] == "imu0"]     # one dict per chip-select window
+    cfg = next(f for f in imu if f["data"][0] == 0x4F)        # GYRO_CONFIG0 write
+    assert cfg["data"][1] & 0x0F == 0x06                      # ODR the driver programmed
+    assert cfg["miso"][0] == 0x00                             # what the slave answered
+    bursts = [f for f in imu if f["t"] > cfg["t"] and len(f["data"]) > 16]
+    assert len(bursts) > 100                                  # FIFO reads after configuration
+```
+
+Every record carries its virtual-time stamp, so a rate is a subtraction between
+consecutive frames and an ordering is a comparison. The scenario dict is the
+same shape as `sim --scenario`'s YAML, and because the test owns it, the
+negative control is the same test with a peer removed from `media`. Changing
+what a device does (a NACK for 50 ms, a stale frame, a node that stops
+answering at t = 5 s) is an edit to the peer script, on the virtual clock. The
+`sim` guide covers every output and the peer API:
+https://simantic.com/docs
+
+`--sim-backend=renode|rust|both` chooses the engine. With `both`, each test runs
+on each and the engine name appears in the test id. Anything an engine cannot do
+is reported as a skip with the reason, so one suite can target both and stay
+honest about what each covers.
+
+`test.yaml` manifests follow the same option. On `rust` a manifest, including a
+multi machine one with `media:`, runs to its timeout in one call and its UART
+output is checked afterwards; `expect_frames` checks are skipped there for now.
+`simantic.run_firmware(..., backend="rust")` does the same for a single ELF.
+
+One tip worth real time: on the Renode engine, every hand off between Python and
+the simulation costs a few hundred microseconds. Reading is free, pausing and
+resuming is not. Prefer `expect()`, which crosses once, over a loop that polls
+every millisecond. On the Rust engine, polling is essentially free.
+
+If you keep `test.yaml` fixture manifests, installing the package also turns
+each one into its own pytest item, so you get `-k` filtering, `--junitxml`, and
+xdist for free. A manifest is the fire-and-forget form of a test: name the
+machine(s) with their `parts`, the `media` that wire UART and CAN peers to
+the firmware's controllers, how long to run, and what must and must not
+appear:
+
+```yaml
+machines:
+  dut:
+    mcu: STM32H753ZI
+    elf: fc.elf
+    parts:
+      - { name: gpspeer, type: uart-device, baud: 230400, script: gps.py }
+media:
+  - { type: uart, connect: [dut.usart6, dut.gpspeer] }
+timeout: 12
+expect:               ["GPS fix: 3"]
+expect_absent:        ["RESULT: FAIL"]
+expect_frames:        ["SPI Rx cs=0 len=2 mosi=4F 06"]   # same line shape as `sim --frames`
+expect_frames_absent: ["CAN Dropped"]
+```
+
+Single-machine manifests (`mcu:` at the top level) are the one-machine case.
+Models resolve through your account; no checkout of ours is needed. A model can
+require a minimum engine version; if yours is older, the failure names the
+version and the fix (`simantic install engine --force`).
+
+Three more keys cover fixtures that need files or peers on the host side:
+`sparse_files` creates blank files of a given size before the run (a blank SD
+card, say), `networkServices` adds scripted network peers, and `{TEST_DIR}` and
+`{WORK_DIR}` in a board file expand to the manifest's directory and a per-test
+scratch directory. A manifest whose `sim_args` asks for a `sim`
+command-line flag with no equivalent here is skipped, with the flag named.
+
+A run also has a wall-clock budget: 30 s of host time by default, 100 s with
+`wireless: true`, or whatever `wall:` says. Going over it fails the test with
+the virtual time reached. Slow simulation is a firmware busy-wait or a model
+gap, and the report tells you which to go find rather than waiting it out.
+
+For a single run with no assertions in the middle, there is `run_firmware(...)`:
+
+```python
+run = simantic.run_firmware("build/zephyr.elf", mcu="STM32F401RE",
+                            expect=["RESULT: PASS"])
+assert run.passed, run.failure_report()
+```
+
+## Telemetry
+
+Only when you are signed in, we report two things:
+
+* **Test counts.** At the end of a pytest run, how many simulator tests passed,
+  failed and were skipped. One request per run.
+* **Which calls you use.** The names of the SDK calls and `simantic` commands
+  you run, such as `sdk.run_firmware` or `cli.install`, and how often. They are
+  counted in `~/.simantic/usage.jsonl` and uploaded at most hourly.
+
+Each report also carries the version of this package, your Python version,
+operating system and CPU architecture. Reports go out when a pytest run or a
+`simantic` command finishes, never while a simulation is running, and a failed
+or slow request is dropped silently.
+
+We do not send file paths, project names, test names, call arguments, firmware,
+or simulation output. Those are yours. Turn it off whenever you like:
+
+```bash
+export SIMANTIC_TELEMETRY=0     # or DO_NOT_TRACK=1
+```
+
+## Questions
+
+We would genuinely like to hear how this goes for you, especially if something
+is confusing or broken. Write to **founder@simantic.dev**, or open an issue.
+
+## License
+
+MIT. The simulators it drives are separate software under their own terms.

{simantic-0.3.1 → simantic-0.4.0}/PUBLISHING.md

@@ -1,8 +1,8 @@
 # Publishing `simantic` to PyPI
 
-First-time setup, then the per-release loop. Steps marked **[you]** need a
+One-time setup (done; kept for reference), then the per-release loop. Steps marked **[you]** need a
 human with the accounts; everything else is automated in
-`.github/workflows/python.yml`.
+`.github/workflows/ci.yml`.
 
 ## One-time setup
 
@@ -18,18 +18,15 @@ the first upload so a mistake is not permanent.
 
 ### 2. Claim the name **[you]**
 
-`simantic` was unregistered as of this writing. Names are first-come and a
-published version number can never be reused or overwritten — only yanked —
-so publish `0.1.0` to TestPyPI first, confirm it looks right, and only then
-push the real tag. Claiming early is cheap insurance against someone else
-taking it.
+Done: `simantic` is ours on PyPI. A published version number can never be
+reused or overwritten — only yanked — so check the version before pushing a
+tag.
 
 ### 3. Configure Trusted Publishing **[you]**
 
 This replaces API tokens with short-lived OIDC credentials, so there is no
 long-lived secret in the repo. On PyPI, go to your account's **Publishing**
-page and add a *pending* publisher (pending = the project does not exist
-yet, which is the case before the first upload):
+page and add a publisher:
 
 | Field | Value |
 |---|---|
@@ -69,8 +66,8 @@ uv run --with simantic --index https://test.pypi.org/simple/ \
 3. Tag and push:
 
 ```bash
-git tag v0.1.0
-git push origin v0.1.0
+git tag v0.4.0
+git push origin v0.4.0
 ```
 
 The workflow tests on Linux/macOS/Windows across 3.11 and 3.13, builds the
@@ -79,9 +76,9 @@ sdist and wheel, runs `twine check`, and uploads via trusted publishing.
 ## Versioning
 
 Semantic versioning on the SDK's own surface, which is independent of the
-`analog-cli` version it drives. The coupling that matters is the report
-schema: `simantic` speaks `analog-cli.test-report/1` and refuses anything
-else, so a schema revision in the CLI is a major bump here.
+engine version it drives: the package is 0.4.x while the engine is 0.6.x, and
+the two are not meant to match. The engine a model needs is declared by the
+model (`min_sim_version`), not by this package's version.
 
 Stay on `0.x` until the API has survived real use. Pre-1.0 signals that
 breaking changes can still happen, which is honest for a first release.

simantic-0.4.0/README.md

@@ -0,0 +1,261 @@
+<p align="center">
+  <img src="https://simantic.dev/simantic_logo_4_full.png" alt="Simantic" width="340">
+</p>
+
+<h3 align="center">Test your firmware without a board.</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/simantic/"><img src="https://img.shields.io/pypi/v/simantic.svg" alt="PyPI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/simantic.svg" alt="Python versions">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT licence">
+</p>
+
+Nothing to plug in, nothing to flash. Simantic boots your real ELF on a
+simulated microcontroller and hands you the whole machine from Python. Watch it
+print, press a button, read a variable straight out of RAM.
+
+```bash
+pip install simantic
+```
+
+```python
+from simantic import Sim
+
+with Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2") as sim:
+    sim.expect("ready")
+    sim.inject_gpio("gpioc", 13, True)      # press the user button
+    sim.expect("button pressed")
+    assert sim.read_u32("press_count") == 1
+```
+
+That is a whole test. No probe, no breakpoint, no waiting on hardware.
+
+Three things you get that a bench cannot give you:
+
+* **See inside.** Read any variable, register, or RTOS thread while the
+  firmware runs, without halting it.
+* **Poke it.** Press buttons, send CAN frames, feed the radio, all from your
+  script.
+* **Repeat exactly.** Time moves only when you ask, so a run comes out the same
+  every time, on your laptop and in CI.
+
+The simulator lives inside your Python process, so there is no server to start
+and no port to talk to.
+
+> **Alpha, version 0.4.x.** We are still moving things around, so the API can
+> change without a deprecation period. Pin an exact version
+> (`simantic==0.4.0`) if you depend on it, and please hold off on production
+> pipelines for now. Tell us what breaks.
+
+## Setup
+
+`pip install` is the whole setup. The first `Sim(...)` downloads the engine it
+needs into `~/.simantic/` and checks it against the published checksum. The
+wheel on PyPI holds only Python code; the simulators are never inside it.
+
+Sign in once if you want to name MCUs by part number:
+
+```bash
+simantic auth
+```
+
+That opens a browser tab, much like `gh auth login`, and saves a token to
+`~/.sim_id`. In CI, pipe one in instead: `echo $TOKEN | simantic auth`.
+
+Already have the `sim` binary? Put it on PATH or point `$SIMANTIC_SIM` at it.
+`simantic status` shows what resolved.
+
+## Pick your engine
+
+The same script runs on either engine. You choose per simulation:
+
+```python
+Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2")                  # Renode engine, the default
+Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2", backend="rust")  # our Rust engine
+```
+
+The Rust engine is a small extension module, runs one machine, and is
+considerably faster. Anything it cannot do yet, such as multi machine scenarios
+or CAN and radio injection, raises `simantic.NotSupported` and names the gap
+instead of quietly doing nothing. What each engine covers is listed in
+[the engine table](https://github.com/simantic-dev/pippy/blob/main/docs/session-api.md#what-each-engine-supports).
+
+## ESP32 images
+
+The ESP32-C3, C6 and P4 boot the way silicon does: Espressif's mask ROM runs
+first, then your bootloader, then your app. `sim --elf` therefore takes one ELF
+that carries the ROM and your whole flash image. Build it from the files your
+ESP-IDF or PlatformIO build already produced:
+
+```bash
+simantic esp-image --chip esp32c3 \
+    --part 0x0:bootloader.bin --part 0x8000:partitions.bin --part 0x10000:firmware.bin \
+    --flash-size 16MB -o image.elf
+sim --elf image.elf ...
+```
+
+Already have a merged image from `esptool.py merge_bin`? Pass `--flash merged.bin`
+instead of the parts. The same thing from Python is
+`simantic.esp_image.build_image("esp32c3", flash, out="image.elf")`.
+
+The mask ROM is Espressif's and is not bundled. On first use it is downloaded
+from Espressif's own repositories, pinned by commit and SHA-256, and cached in
+`~/.simantic/esp-rom`: the raw C3 and C6 dumps from
+[espressif/qemu](https://github.com/espressif/qemu/tree/master/pc-bios), and
+the P4 ROM from the [esp-rom-elfs](https://github.com/espressif/esp-rom-elfs)
+release ESP-IDF installs. Offline, or with your own copy, pass `--rom`.
+`simantic esp-rom --chip esp32c3` downloads it ahead of time and prints where it
+went.
+
+## Testing with pytest
+
+Take the `sim` fixture and write ordinary tests:
+
+```python
+def test_timer_irq_fires(sim):
+    s = sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2")
+    s.expect("fired=1", timeout=8)
+    assert s.read_u32("fired") == 1
+```
+
+The engine starts once per worker rather than once per test, and every machine
+is closed for you. When a test fails, its UART transcript is attached to the
+report, because that is usually the evidence you want.
+
+### Test what went over the wire
+
+Firmware that prints "sensor OK" is reporting its own bookkeeping. The bus
+tells you what happened. Put a scripted device on the other end of each bus
+(a `parts` entry per device, each backed by a few dozen lines of Python), wire
+the media in a scenario, and assert on `frames()`:
+
+```python
+SCENARIO = {
+    "machines": {"dut": {
+        "mcu": "STM32H753IITX", "elf": "fc.elf",
+        "parts": [
+            {"name": "imu0",    "type": "spi-device",  "bus": "spi1", "cs": "PC4", "script": "icm42688.py"},
+            {"name": "baro",    "type": "i2c-device",  "bus": "i2c2", "address": 0x63, "script": "icp20100.py"},
+            {"name": "gpspeer", "type": "uart-device", "baud": 230400, "script": "gps.py"},
+            {"name": "canpeer", "type": "can-node",    "script": "dronecan.py"},
+        ],
+    }},
+    "media": [
+        {"type": "uart", "connect": ["dut.usart6", "dut.gpspeer"]},
+        {"type": "can",  "connect": ["dut.fdcan1", "dut.canpeer"]},
+    ],
+}
+
+def test_imu_configured_then_streams(sim):
+    s = sim(scenario=SCENARIO, machine="dut", uart="usart1")
+    s.run_for(3.0)                                            # virtual seconds
+    imu = [f for f in s.frames() if f["label"] == "imu0"]     # one dict per chip-select window
+    cfg = next(f for f in imu if f["data"][0] == 0x4F)        # GYRO_CONFIG0 write
+    assert cfg["data"][1] & 0x0F == 0x06                      # ODR the driver programmed
+    assert cfg["miso"][0] == 0x00                             # what the slave answered
+    bursts = [f for f in imu if f["t"] > cfg["t"] and len(f["data"]) > 16]
+    assert len(bursts) > 100                                  # FIFO reads after configuration
+```
+
+Every record carries its virtual-time stamp, so a rate is a subtraction between
+consecutive frames and an ordering is a comparison. The scenario dict is the
+same shape as `sim --scenario`'s YAML, and because the test owns it, the
+negative control is the same test with a peer removed from `media`. Changing
+what a device does (a NACK for 50 ms, a stale frame, a node that stops
+answering at t = 5 s) is an edit to the peer script, on the virtual clock. The
+`sim` guide covers every output and the peer API:
+https://simantic.com/docs
+
+`--sim-backend=renode|rust|both` chooses the engine. With `both`, each test runs
+on each and the engine name appears in the test id. Anything an engine cannot do
+is reported as a skip with the reason, so one suite can target both and stay
+honest about what each covers.
+
+`test.yaml` manifests follow the same option. On `rust` a manifest, including a
+multi machine one with `media:`, runs to its timeout in one call and its UART
+output is checked afterwards; `expect_frames` checks are skipped there for now.
+`simantic.run_firmware(..., backend="rust")` does the same for a single ELF.
+
+One tip worth real time: on the Renode engine, every hand off between Python and
+the simulation costs a few hundred microseconds. Reading is free, pausing and
+resuming is not. Prefer `expect()`, which crosses once, over a loop that polls
+every millisecond. On the Rust engine, polling is essentially free.
+
+If you keep `test.yaml` fixture manifests, installing the package also turns
+each one into its own pytest item, so you get `-k` filtering, `--junitxml`, and
+xdist for free. A manifest is the fire-and-forget form of a test: name the
+machine(s) with their `parts`, the `media` that wire UART and CAN peers to
+the firmware's controllers, how long to run, and what must and must not
+appear:
+
+```yaml
+machines:
+  dut:
+    mcu: STM32H753ZI
+    elf: fc.elf
+    parts:
+      - { name: gpspeer, type: uart-device, baud: 230400, script: gps.py }
+media:
+  - { type: uart, connect: [dut.usart6, dut.gpspeer] }
+timeout: 12
+expect:               ["GPS fix: 3"]
+expect_absent:        ["RESULT: FAIL"]
+expect_frames:        ["SPI Rx cs=0 len=2 mosi=4F 06"]   # same line shape as `sim --frames`
+expect_frames_absent: ["CAN Dropped"]
+```
+
+Single-machine manifests (`mcu:` at the top level) are the one-machine case.
+Models resolve through your account; no checkout of ours is needed. A model can
+require a minimum engine version; if yours is older, the failure names the
+version and the fix (`simantic install engine --force`).
+
+Three more keys cover fixtures that need files or peers on the host side:
+`sparse_files` creates blank files of a given size before the run (a blank SD
+card, say), `networkServices` adds scripted network peers, and `{TEST_DIR}` and
+`{WORK_DIR}` in a board file expand to the manifest's directory and a per-test
+scratch directory. A manifest whose `sim_args` asks for a `sim`
+command-line flag with no equivalent here is skipped, with the flag named.
+
+A run also has a wall-clock budget: 30 s of host time by default, 100 s with
+`wireless: true`, or whatever `wall:` says. Going over it fails the test with
+the virtual time reached. Slow simulation is a firmware busy-wait or a model
+gap, and the report tells you which to go find rather than waiting it out.
+
+For a single run with no assertions in the middle, there is `run_firmware(...)`:
+
+```python
+run = simantic.run_firmware("build/zephyr.elf", mcu="STM32F401RE",
+                            expect=["RESULT: PASS"])
+assert run.passed, run.failure_report()
+```
+
+## Telemetry
+
+Only when you are signed in, we report two things:
+
+* **Test counts.** At the end of a pytest run, how many simulator tests passed,
+  failed and were skipped. One request per run.
+* **Which calls you use.** The names of the SDK calls and `simantic` commands
+  you run, such as `sdk.run_firmware` or `cli.install`, and how often. They are
+  counted in `~/.simantic/usage.jsonl` and uploaded at most hourly.
+
+Each report also carries the version of this package, your Python version,
+operating system and CPU architecture. Reports go out when a pytest run or a
+`simantic` command finishes, never while a simulation is running, and a failed
+or slow request is dropped silently.
+
+We do not send file paths, project names, test names, call arguments, firmware,
+or simulation output. Those are yours. Turn it off whenever you like:
+
+```bash
+export SIMANTIC_TELEMETRY=0     # or DO_NOT_TRACK=1
+```
+
+## Questions
+
+We would genuinely like to hear how this goes for you, especially if something
+is confusing or broken. Write to **founder@simantic.dev**, or open an issue.
+
+## License
+
+MIT. The simulators it drives are separate software under their own terms.