Open-source examples: attaching your own hardware with the Scripted* counterparts, and testing it from Python #20

Requested 2026-09-20. pippy is the public repo, so this is where a customer with a Pico and their sensor setup learns how to wire it and test it — the private sim-fixtures tree has 97 overlay.repl-frag files and a 78-line tests/SCRIPTED-COUNTERPARTS.md, none of which a customer can see.

What lands here

examples/counterparts/ — one directory per counterpart type, each with the smallest firmware that talks to it, the overlay fragment, the Python peer, and a pytest that runs it through simantic.Sim and asserts on the UART. Runnable with pip install simantic + sim login, nothing cloned but this repo.

Plus the Pico + FE910C04 demo itself (source + prebuilt ELF; the 31 KB of custom source is main.c, the FE910C04 driver, prj.conf, board overlay, repl-frag, peer script). That one stays as the "here is a whole system" example; the table above is the "here is one thing at a time" ladder up to it.

Each example's README answers, in order

1. sim models --show <MCU> — find the peripheral you are attaching to. (simantic-cli issue; until it lands, the README states the names.)
2. The fragment: name: Type @ <peripheral> and the -> lines — what each means, using gpio0: 10 -> modem@0 as the worked line.
3. The Python side: which callbacks the counterpart class calls and what it hands you.
4. The pytest: Sim(...), step, assert. A negative control that fails when the fragment is removed, so the reader sees the test is real.

Rules

• Prebuilt ELF committed next to the source. Nobody should need west to run an example; they need it only to change one.
• Every example runs green in this repo's CI against the released sim, with a test-account token — the customer path, not a workspace path. If it is red, the docs are wrong.
• Stock Zephyr or pico-sdk, pinned. No private trees.
• Copy the sim-fixtures examples in; do not link to them.

Related

• simantic-cli: sim models --show.
• homepage#114 targets/onboarding docs; homepage: address map.
• simantic demo ble-pair: zero-signup two-node BLE scenario (stock ESP-IDF, real air frames) #17 (ble-pair demo) — same shape, same repo.