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

[ShahriarAhnaf]

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.

dir	counterpart	firmware does	the point
i2c-sensor/	I2C.ScriptedI2cSlave	reads a fake temperature register	the Pico + unknown-sensor case; the one most customers have
spi-flash/	SPI.ScriptedSpiSlave	JEDEC ID + read	pointer-carrying slave, not echo
uart-peer/	UART.ScriptedUartPeer	AT-style request/response	how the LTE demo's modem was built, at 1/10 the size
mmio-block/	Scripted.ScriptedPeripheral	reads a register, gets an IRQ	"hardware Renode doesn't ship", with ctx.irq and ctx.schedule_*
gpio-button/	Miscellaneous.Button + nets:	debounce	overlay: vs nets: — same-machine part vs between-machine pin

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.

[ShahriarAhnaf]

Siblings: simantic-dev/simantic-cli#223 (sim models --show, step zero in every README); simantic-dev/homepage#156 (address map); docs scope on simantic-dev/homepage#114.

[ShahriarAhnaf]

Scope note (2026-09-20): no KiCad importer anywhere. Add one example, kicad-to-scenario/, showing an agent authoring the overlay: / nets: from a KiCad project using analog-cli's parsed netlist + component packages' transactional facet (analog-cli issue, linked below) + sim models --show. The DAC53401 A0 strap → I2C address is the worked line.

[ShahriarAhnaf]

Transactional facet: simantic-dev/analog-cli#312.