sim86 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,416 @@
1
+ Metadata-Version: 2.5
2
+ Name: sim86
3
+ Version: 0.1.0
4
+ Summary: DEMO/FEEDBACK PREVIEW, not for production (contact t@simulator86.com). Run firmware on simulated boards in the Simulator86 cloud: CLI, pytest plugin, fault injection.
5
+ Project-URL: Homepage, https://sim86.com
6
+ Project-URL: Documentation, https://docs.sim86.com
7
+ Author: Simulator86
8
+ License: Proprietary
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Framework :: Pytest
11
+ Classifier: Topic :: Software Development :: Embedded Systems
12
+ Classifier: Topic :: Software Development :: Testing
13
+ Requires-Python: >=3.9
14
+ Requires-Dist: certifi
15
+ Requires-Dist: pytest>=8
16
+ Requires-Dist: websockets>=13
17
+ Provides-Extra: dev
18
+ Requires-Dist: pytest>=8; extra == 'dev'
19
+ Provides-Extra: test
20
+ Requires-Dist: pytest-xdist>=3; extra == 'test'
21
+ Requires-Dist: pytest>=8; extra == 'test'
22
+ Description-Content-Type: text/markdown
23
+
24
+ # sim86
25
+
26
+ > **Demo and feedback preview.** sim86 is shared so you can try Simulator86
27
+ > and tell us what you think. It is **not designed for production use**: no
28
+ > stability, compatibility or availability guarantees, and commands may
29
+ > change. For more information, contact **Tariq** at
30
+ > [t@simulator86.com](mailto:t@simulator86.com).
31
+
32
+ Run your firmware on simulated boards in the Simulator86 cloud, test it with
33
+ pytest, and break the hardware on purpose to see what your firmware does.
34
+
35
+ - **One JSON file per board**: parts, wires, firmware per chip ([how to build one](docs/circuits.md)).
36
+ - **`sim86 run`**: run it and stream what every chip prints.
37
+ - **pytest plugin**: each test gets a live run of your board.
38
+ - **Fault injection**: short, open or bridge wires, or force waveforms onto a net, at an exact
39
+ edge or nanosecond.
40
+ - **Deterministic**: the same seed and firmware give the same run, cycle for cycle.
41
+
42
+ Your tests run wherever you run pytest (your laptop, your CI). Only the
43
+ simulation runs in the cloud. Stops and faults happen inside the simulator on
44
+ the exact cycle, so network latency never changes what the firmware sees.
45
+
46
+ ## Install
47
+
48
+ **One file, nothing else needed** (Linux, Windows, macOS): download
49
+ `sim86-<os>-<arch>` from the releases page, make it executable, and run it.
50
+ It includes everything, test runner too.
51
+
52
+ **Or with Python:** `pip install "sim86[test]"` (the CLI plus pytest and
53
+ pytest-xdist).
54
+
55
+ ```
56
+ sim86 login # or: export SIM86_API_KEY=sim86_live_…
57
+ ```
58
+
59
+ Create an API key at **app.sim86.com → Cloud → API keys**.
60
+
61
+ ## Quick start
62
+
63
+ ```
64
+ sim86 init # starter board.json + tests/test_board.py (+ editor schema)
65
+ sim86 info board.json # what the board is: parts, firmware, nets, what tests can do
66
+ sim86 check board.json # catches wrong pins, types, settings, firmware formats
67
+ sim86 run board.json # run it, stream serial output
68
+ ```
69
+
70
+ ```
71
+ ▸ starting my-board on the Simulator86 cloud (3 parts, 1 chip, up to 10s simulated)…
72
+ ▸ run 0193f2c4-…
73
+ ▸ https://app.sim86.com/cloud/0193f2c4-…
74
+ [ 0.412 ms] mcu:uart0 ESP-ROM:esp32c3-api1-20210207
75
+ [ 812.035 ms] mcu:uart0 ready
76
+ ```
77
+
78
+ Useful flags:
79
+
80
+ | Flag | |
81
+ |---|---|
82
+ | `--expect "ready"` | exit 0 as soon as the text is printed, 1 if it never is (good for shell CI) |
83
+ | `--duration 20s` | simulated time to run |
84
+ | `--firmware motor=out/m.elf` | swap one chip's image |
85
+ | `--scenario faults.json` | run with a fault plan ([below](#planned-faults-scenarios)) |
86
+ | `--seed 42` | reproduce a run exactly |
87
+ | `--no-open` | don't open the live page (it opens by default at a terminal) |
88
+ | `--json` | one JSON object per output line, for scripts and agents |
89
+
90
+ ## Drive a running board from the shell
91
+
92
+ For agents and quick experiments: start a board, then act on it one command
93
+ at a time. Every command prints one JSON object and exits non-zero on
94
+ failure. `last` is the run you started most recently.
95
+
96
+ ```
97
+ sim86 start board.json {"run": "01a1…", "url": "…/live/01a1…"}
98
+ sim86 events last & everything that happens, one JSON line each
99
+ sim86 wait last "thermostat ready" --since-start
100
+ sim86 input last temp temperature=72 set what a sensor senses
101
+ sim86 wait last "ALARM" --ms 3000 run until printed (simulated ms)
102
+ sim86 state last alarm {"state": {"intensity": 100}}
103
+ sim86 press last mute --hold 300ms buttons
104
+ sim86 until last --edge temp.SCL --falling --nth 3 pause on the exact edge
105
+ sim86 fault last short temp.SDA gnd {"fault": 0}
106
+ sim86 wait last "sensor error" --ms 500
107
+ sim86 fault last clear clears what you applied
108
+ sim86 read last mcu GPIO.IN chip registers
109
+ sim86 measure last temp.SCL --over 200ms edges and volts on a net
110
+ sim86 stop last
111
+ ```
112
+
113
+ `wait` reads output in order: it looks at what was printed after your last
114
+ action (or the last line it matched), so nothing printed between two
115
+ commands is missed. `--since-start` searches everything.
116
+
117
+ **Step mode (`sim86 start board.json --step`)**: the board only moves inside
118
+ `wait`, `advance` and `until`, and stays paused between commands. Timing is
119
+ then exact however slow you (or your agent) are: a short applied for
120
+ `advance last 20ms` lasts exactly 20 ms. Without `--step` the board runs in
121
+ real time between commands, like real hardware on a bench. In step mode,
122
+ `wait` moves in 50 ms slices and stops within one slice of the match.
123
+
124
+ A session runs up to 10 minutes of simulated time by default (`--duration`);
125
+ the board file's `limits` only apply to `sim86 run` and tests.
126
+
127
+ Sensors behave like real parts: a temperature set with `input` reaches the
128
+ firmware gradually (thermal lag), and a sensor's first reading after
129
+ power-up can be 0 until its first conversion finishes.
130
+
131
+ `sim86 events` prints history first, then live events until the run ends:
132
+ `serial` (firmware output), `action` (what a program did to the run),
133
+ `note`, `plan` (scheduled faults), `paused`/`running`, `state` (with
134
+ `--state`: LEDs, sensors, displays), `ended`. Filter with `--type`, `--part`,
135
+ `--grep`; stop with `--until-text` or `--wall SECONDS`.
136
+
137
+ Also: `status`, `pause`, `resume`, `advance last 5ms`, `until last --at 2s`,
138
+ `event last PART ACTION`, `write last mcu REG VALUE`, `inside last PART`,
139
+ `note last "…"`.
140
+
141
+ ## Test it with pytest
142
+
143
+ ```
144
+ sim86 test -v # runs your tests/ — works with the single-file download
145
+ sim86 test -n 4 -k sda # any pytest option: parallel, select, --junitxml=results.xml
146
+ ```
147
+
148
+ `sim86 test` is pytest with the sim86 plugin loaded; the downloadable
149
+ executable carries pytest and pytest-xdist inside, so no Python is needed.
150
+ With a pip install, plain `pytest` works too (the plugin registers itself).
151
+ Your test files can import `pytest` and `sim86`, plus anything else when you
152
+ run them from your own Python environment.
153
+
154
+ Point it at your board in `pytest.ini`:
155
+
156
+ ```ini
157
+ [pytest]
158
+ sim86_board = board.json
159
+ ```
160
+
161
+ Each test that takes `board` gets its own fresh run of that file. The run
162
+ stops when the test ends.
163
+
164
+ ```python
165
+ def test_boots(board):
166
+ board["mcu"].serial.wait_for("ready", ms=2000)
167
+ ```
168
+
169
+ `wait_for` runs the board until the text appears, for at most that much
170
+ **simulated** time. If it times out, the board is left paused exactly at the
171
+ deadline and the test fails, showing the last lines printed.
172
+
173
+ When a test fails, the report includes the run link, the faults still
174
+ applied and the last 40 lines every chip printed:
175
+
176
+ ```
177
+ ---------------------------- sim86 ----------------------------
178
+ run: https://app.sim86.com/cloud/0193f2c4-…
179
+ faults still applied: short sensor.SDA to gnd
180
+ last output:
181
+ [ 1203.551 ms] mcu:uart0 i2c timeout, retrying
182
+ ```
183
+
184
+ ### What a test can do
185
+
186
+ ```python
187
+ board["mcu"].serial.wait_for("text", ms=500) # run until printed (simulated time)
188
+ board["mcu"].serial.lines # everything it printed: .t (ms) .source .line
189
+ board.serial.text # the whole board's output
190
+
191
+ board.until(edge="sensor.SCL", kind="falling", nth=3) # pause on the exact edge (counted from now)
192
+ board.until(at="250ms") # pause at a simulated time
193
+ board.advance("5ms") # run exactly 5 ms more, then pause
194
+ board.resume() # keep running
195
+ board.time_ms # current simulated time
196
+
197
+ board["mcu"].read("I2C0.SR") # chip register, exact while paused
198
+ board["mcu"].read("I2C0.SR")["BUS_BUSY"] # one bit field
199
+ board["mcu"].read("cpu.pc", "mem[0x3fc80000:16]")
200
+ board["mcu"].write("GPIO.OUT", 0)
201
+
202
+ board["btn"].press(hold="200ms") # buttons
203
+ board["sensor"].set_input("temperature", 85) # what a sensor senses
204
+ board["imu"].set_input("acceleration", [0, 0, 9.8])
205
+ board["sensor"].internals() # a part's registers, state, recent writes
206
+ ```
207
+
208
+ Register names are the vendor's own (from its SVD). Search them with
209
+ `sim86 registers XiaoESP32C3 "i2c0 sr"`.
210
+
211
+ ### Volts, edges and part state
212
+
213
+ ```python
214
+ board["alarm"].state # what a part shows: {"intensity": 100}, currents, …
215
+ m = board.measure("temp.SDA", over="5ms") # a net over the last 5 ms of simulated time
216
+ m.min, m.max, m.mean, m.last # volts (analog nets: the solver's exact values)
217
+ len(m.rising), m.rising[0].rise_ns # edges; 10–90 % rise time and delay on analog nets
218
+ board.volts("r1.2") # a net's voltage right now
219
+ board.watch("temp.SDA", "temp.SCL") # start recording nets before something happens
220
+ ```
221
+
222
+ A net is named by any pin on it. Volts and rise times come from the analog
223
+ layer: nets with resistors, capacitors, supplies and so on. A purely digital
224
+ net reports its edges and the rail volts each edge drove to.
225
+
226
+ In the board file, part values can be written like on a schematic:
227
+ `"ohms": "4k7"`, `"farads": "100n"`, `"volts": "3V3"`.
228
+
229
+ ### Radio (Wi-Fi, BLE)
230
+
231
+ ```python
232
+ board.radio.loss("mcu", "ap", 120) # out of range (40 ≈ same desk, 90 far)
233
+ board.radio.jam(channel=6, dbm=20) # interferer on Wi-Fi channel 6 (22 MHz wide)
234
+ board.radio.jam(channel=6, dbm=30, mhz=90) # the whole 2.4 GHz band
235
+ board.radio.restore() # as the board file set it up
236
+ ```
237
+
238
+ See `examples/wifi` and `examples/ble`.
239
+
240
+ ### Choosing the board per test
241
+
242
+ ```python
243
+ import pytest
244
+
245
+ @pytest.mark.board("boards/two-node.json", duration="20s", seed=7)
246
+ def test_two_nodes(board): ...
247
+
248
+ @pytest.mark.board(firmware={"motor": "out/motor-debug.elf"})
249
+ def test_debug_build(board): ...
250
+ ```
251
+
252
+ ### Watch tests live
253
+
254
+ ```
255
+ sim86 test --open -k sda
256
+ ```
257
+
258
+ Each test's run opens in the browser: the board live, a banner with the
259
+ test's name and result, and an **Activity** feed of every step the test takes
260
+ (paused on an edge, shorted a wire, set an input), stamped with simulated
261
+ time. Any program driving a run shows up the same way. Label your own steps
262
+ with `board.note("heating to 80 °C")`. `--sim86-linger 10` keeps each run
263
+ going for 10 s after its test.
264
+
265
+ `sim86 run` opens the same live page by default when you run it in a
266
+ terminal. Pass `--no-open` to skip it; it never opens under CI or `--json`.
267
+
268
+ ## Fault injection
269
+
270
+ Pause on the exact moment, break something, then watch how the firmware
271
+ recovers:
272
+
273
+ ```python
274
+ def test_sensor_survives_a_shorted_sda(board):
275
+ mcu = board["mcu"]
276
+ mcu.serial.wait_for("ready", ms=2000)
277
+
278
+ board.until(edge="sensor.SCL", kind="falling", nth=3) # mid-transaction
279
+ fault = board.short("sensor.SDA", "gnd") # SDA stuck low
280
+ board.advance("5ms")
281
+ board.clear(fault)
282
+
283
+ mcu.serial.wait_for("sensor ok", ms=1000) # it must recover
284
+ ```
285
+
286
+ | Fault | |
287
+ |---|---|
288
+ | `board.short(pin, "gnd" \| "vcc")` | tie a net to a rail (stuck line) |
289
+ | `board.open(a, b)` | break the wire between two pins |
290
+ | `board.bridge(a, b)` | join two nets, like a solder bridge |
291
+ | `board.drive(pin, [[0, 0], [2000, 1]], repeat="4us")` | force a waveform onto a net: `[time_ns, level]` steps |
292
+ | `board.clear(fault)` / `board.clear()` | remove one fault / all of them |
293
+
294
+ Faults apply at the board's current simulated time. While it is paused,
295
+ that's the exact instant it paused at.
296
+
297
+ ### Sweeps
298
+
299
+ A sweep is plain pytest. Each case is its own cloud run, so they
300
+ parallelise (`pip install pytest-xdist`, then `pytest -n 8`):
301
+
302
+ ```python
303
+ import pytest
304
+
305
+ @pytest.mark.parametrize("pin", ["sensor.SDA", "sensor.SCL"])
306
+ @pytest.mark.parametrize("to", ["gnd", "vcc"])
307
+ @pytest.mark.parametrize("nth", [1, 9, 40])
308
+ def test_stuck_bus(board, pin, to, nth):
309
+ board["mcu"].serial.wait_for("ready", ms=2000)
310
+ board.until(edge="sensor.SCL", kind="falling", nth=nth)
311
+ fault = board.short(pin, to)
312
+ board.advance("20ms")
313
+ board.clear(fault)
314
+ board["mcu"].serial.wait_for("sensor ok", ms=2000)
315
+ ```
316
+
317
+ ### Planned faults (scenarios)
318
+
319
+ For long runs, describe the faults up front. The simulator then runs the
320
+ whole plan by itself, at full speed:
321
+
322
+ ```json
323
+ {
324
+ "name": "flaky bus, then overheat",
325
+ "events": [
326
+ { "on": { "wire": "sensor.SCL", "edge": "falling", "count": 30 },
327
+ "bridge": { "wires": ["sensor.SDA", "mcu.GND"], "duration": "5ms" } },
328
+ { "at": "2s", "env": { "part": "sensor", "input": "temperature", "from": 25, "to": 85, "over": "5s" } },
329
+ { "at": "8s", "env": { "part": "btn", "action": "pressed", "hold": "200ms", "release": "released" } }
330
+ ]
331
+ }
332
+ ```
333
+
334
+ ```
335
+ sim86 run board.json --scenario scenarios/flaky.json
336
+ ```
337
+ ```python
338
+ @pytest.mark.board(scenario="scenarios/flaky.json", duration="15s")
339
+ def test_overheat_alarm(board):
340
+ board["mcu"].serial.wait_for("ALARM", ms=10_000)
341
+ ```
342
+
343
+ `on` edges count from the start of the run. Times are `"250us"`, `"5ms"`,
344
+ `"2s"`.
345
+
346
+ ## CI
347
+
348
+ ```yaml
349
+ # .github/workflows/firmware.yml
350
+ jobs:
351
+ sim:
352
+ runs-on: ubuntu-latest
353
+ steps:
354
+ - uses: actions/checkout@v4
355
+ - run: ./build.sh # your firmware build
356
+ - uses: actions/setup-python@v5
357
+ with: { python-version: "3.12" }
358
+ - run: pip install "sim86[test]"
359
+ - run: sim86 test -n 8 --junitxml=results.xml
360
+ env:
361
+ SIM86_API_KEY: ${{ secrets.SIM86_API_KEY }}
362
+ ```
363
+
364
+ Every test result carries its run link (`sim86_run` in the JUnit
365
+ properties).
366
+
367
+ ## Other commands
368
+
369
+ ```
370
+ sim86 parts [word] [--kind sensor] search the part catalog
371
+ sim86 parts --show MCP9808 pins, I2C address, settings, sensor inputs
372
+ sim86 registers <chip> [words] search a chip's registers and fields
373
+ sim86 runs your recent runs
374
+ sim86 logs <run> a run's output
375
+ sim86 open <run> the run's page in the browser
376
+ sim86 stop <run> stop a run
377
+ ```
378
+
379
+ ## Feedback (people and agents)
380
+
381
+ Found something the simulator gets wrong, or something missing? Send it
382
+ straight to the team:
383
+
384
+ ```
385
+ sim86 feedback --kind wrong_simulation \
386
+ --summary "BMP280 returns 0x00 for chip id after a soft reset" \
387
+ --steps "write 0xB6 to 0xE0, read 0xD0" --expected "0x58" --actual "0x00" \
388
+ --board board.json --run 0193f2c4-…
389
+ ```
390
+
391
+ Agents can pipe a JSON report:
392
+
393
+ ```
394
+ echo '{"kind":"bug","summary":"…","goal":"…","steps":"…","expected":"…","actual":"…",
395
+ "reproducible":"always","impact":"blocked","target":{"chip":"ESP32-C3","part":"BMP280"}}' \
396
+ | sim86 feedback --json -
397
+ ```
398
+
399
+ `kind` is one of `bug`, `wrong_simulation`, `missing`, `confusing`, `idea`. It's for problems with
400
+ Simulator86 itself, not with your firmware.
401
+
402
+ ## Python API
403
+
404
+ The fixture is a thin layer over the API, which also works outside pytest:
405
+
406
+ ```python
407
+ from sim86 import load_board, Run
408
+
409
+ board = load_board("board.json")
410
+ with Run.start(board, duration="10s") as run: # stops the run on exit
411
+ run["mcu"].serial.wait_for("ready", ms=2000)
412
+ print(run.url)
413
+ ```
414
+
415
+ The only setting is your key: `SIM86_API_KEY`, or `sim86 login`, which saves
416
+ it to `~/.config/sim86/config.json`.
@@ -0,0 +1,12 @@
1
+ sim86/__init__.py,sha256=gu13wZMuFyvh1-J2GkHUViVqIAG2TtIJHxpUyGuI5Jc,1082
2
+ sim86/api.py,sha256=m5QottXA9G_CH-Ee_VVYk4oGlOzjGC2S2Bw5oWao8eE,15799
3
+ sim86/board.py,sha256=WdLy8vC7ikOqw_37H89XFbcMUMgX1JQKKRLesR3NzIU,19440
4
+ sim86/cli.py,sha256=BZKOv3PfiuOS3eLlSAOPUkKaiPEGsuMabv8WKOq6PwE,31009
5
+ sim86/pytest_plugin.py,sha256=7eeAplw19xuhbctiXZaiEfdWb8fJjO4zgTQd7D-WuEw,5896
6
+ sim86/run.py,sha256=cinGwkT03WK15i92h79CIZDUHXy2NVKCpC9hd8VI4Uc,39984
7
+ sim86/session.py,sha256=t2YGUezvNXJPU8R70vTp_ckxNyY_9j8WyOkCJxb3FbE,23209
8
+ sim86/_build.py,sha256=OtjNehCeBBscJIf-iyyELKH847jymCs8Gby-wOqmmtY,20
9
+ sim86-0.1.0.dist-info/METADATA,sha256=jxWt6s3znMeqdYsAH45R0pFdbdT85aJoj0Cuin7A1lE,15845
10
+ sim86-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
11
+ sim86-0.1.0.dist-info/entry_points.txt,sha256=1M9wtJoelCA4yPXI8Vs2g0kvEqY8dzZ1VFRXy225Zgo,81
12
+ sim86-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,5 @@
1
+ [console_scripts]
2
+ sim86 = sim86.cli:main
3
+
4
+ [pytest11]
5
+ sim86 = sim86.pytest_plugin