Files
led-controller/led-simulator/README.md
T
jimmyandClaude Opus 5.5 698c1463c0 chore: move led-simulator in from its submodule
Merges led-simulator (sim-bridge, 4d8aeb5) under led-simulator/ with its history,
in place of the submodule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 15:08:49 +13:00

135 lines
6.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# led-simulator
A web app that simulates a whole LED rig behind a **Wi‑Fi bridge**.
- To **led-controller** it *is* a `bridge-wifi`: a WebSocket on **`/ws`** with the same downlink
rules (binary wire packets are broadcast; v1 JSON envelopes `{"v":"1","dv":{mac: body}}` are
split per MAC) and the same uplink framing (`0x00 + peer MAC + ESP-NOW packet`).
- In the **browser**, every strip is its own led-driver: a web worker running the real
**`led-driver/src/main.py`** and **`led-driver/src/patterns/`** in [Pyodide](https://pyodide.org),
as [led-editor](https://git.technical.kiwi/technicalkiwi/led-editor) runs MicroPython. Only the
hardware modules are stubbed (`stubs/`: `machine`, `neopixel`, `network`, `espnow`, `utime`,
`urandom`, `ubinascii`).
Strips **register like hardware**: each driver sends its JSON hello once when it powers on, and
the bridge forwards it to the controllers connected at that moment. A strip that booted while no
controller was connected is not registered until you power-cycle it.
## Default rig
16 strips × 119 LEDs in **2 columns × 8 rows**. Each strip runs along its row and **starts in the
middle**: pixel 0 is next to the centre line, so left-column strips run right-to-left and
right-column strips run left-to-right.
| Strip | Name | MAC |
| --- | --- | --- |
| 1 … 16 | `sim-01` … `sim-16` | `02:51:4d:00:00:01` … `02:51:4d:00:00:10` |
| bridge | `bridge-sim` | `02:51:4d:00:00:00` |
Strip 1 is row 1 left, strip 2 row 1 right, and so on (`layout.order`).
## With the simulated controller (no hardware at all)
From the repository root:
```bash
make sim-web # this page at http://localhost:8765/ + led-controller built for the host at :8080
make sim # the same with headless drivers (bridge_sim.py), for tests
make test-sim # API and rig tests (groups, field patterns, sequences) against `make sim`
```
The controller reaches the strips over the **UDP bridge** on port **8766**: each datagram is
`dst_mac(6) + packet` down and `src_mac(6) + packet` up, exactly the frames it would send over ESP-NOW.
A board can use it too: set `"bridge": "<this computer>:8766"` in its settings and restart it.
### Headless
`python3 led-simulator/bridge_sim.py [--udp-port 8766] [--port 8765]` runs every strip as its own
CPython process (`sim_driver.py`, `stubs/_simlink_proc.py`) with no browser. `GET /api/pixels` on its
port returns each strip's place and current RGB frame (`rgb`, hex, pixel 0 first).
## Run
From the repository root (Python 3.10+, no extra packages; Microdot comes from `led-driver/lib`):
```bash
python3 led-simulator/server.py # --port 8765 --host 0.0.0.0 --debug
```
1. Open **http://localhost:8765/** in Chrome, Edge or Firefox **on the same computer**.
Drivers need `SharedArrayBuffer`, which browsers only allow on a cross-origin isolated page in
a secure context: `localhost` or HTTPS, not a plain `http://192.168.…` address.
2. In led-controller add a bridge: transport **`ip`**, address **`127.0.0.1`** (controller on
this computer) or this computer's LAN address, port **`8765`**.
3. Power the strips on (or power-cycle them) once the controller is connected, so their hellos
reach it.
The first boot downloads Pyodide (~10 MB) from the CDN; after that the browser caches it.
Strips boot four at a time (`drivers.boot_concurrency`).
Only one tab runs the rig: opening the page in a second tab powers the first one's strips off.
## Page
- **Power on all / Power cycle all / Power off all**, and *Power on when opened*.
- Click a strip for its details: state, MAC, packets received and sent, power on / reset / off,
and its serial output (what the board would print over USB).
- The dot at each strip's start end shows its state: grey off, amber booting, green running,
red stopped (see its serial log for the traceback).
## Configuration
`workspace/sim.json` overrides `sim.default.json` (keep only the keys you change):
```json
{
"bridge": { "name": "bridge-sim", "host": "0.0.0.0", "ws_port": 8765, "wifi_channel": 5, "debug": false },
"layout": { "rows": 8, "columns": 2, "leds_per_strip": 119, "order": "row", "start": "center" },
"drivers": { "name": "sim-{n:02d}", "fps": 30, "loop_sleep_ms": 2, "boot_concurrency": 4 },
"pyodide_url": "https://cdn.jsdelivr.net/pyodide/v0.26.4/full/"
}
```
- `layout.order`: `row` (1 = row 1 left, 2 = row 1 right, …) or `column` (1–8 down the left
column, 9–16 down the right).
- `layout.start`: `center` (pixel 0 next to the middle), `left`, or `right`.
- `drivers.name`: format for new strips; `{n}`, `{row}`, `{col}`, `{side}` (`left`/`right`).
A name the controller sets is kept.
- `drivers.fps`: how often each strip sends its pixels to the page.
- `drivers.loop_sleep_ms`: sleep per driver main-loop pass (in the `WDT.feed()` stub) so 16
drivers do not pin the CPU.
- `pyodide_url`: point at a local copy of Pyodide (full distribution folder, trailing `/`) to run
offline.
## Simulated flash
Each strip keeps `settings.json` and `presets.json` in **`workspace/drivers/NN/`** on the server:
created from **`settings.default.json`** on first boot, then saved whenever the driver writes
them. `num_leds` always follows the layout. Delete `workspace/drivers/` to factory-reset every
strip.
Driver code and **patterns are always the current `led-driver/src`**, loaded fresh on every
boot. Patterns the controller pushes by OTA live only until that strip powers off.
## How it fits together
```
led-controller ──ws /ws──▶ server.py (bridge rules) ──ws /sim──▶ page ──SharedArrayBuffer──▶ worker × 16
◀── 0x00+mac+pkt ── ◀── mac+pkt ── ◀──── postMessage ──── (Pyodide, main.py)
```
- `server.py` – HTTP + both WebSockets, bridge downlink rules, flash files.
- `web/app.js` – rig canvas, power control, packet routing by MAC.
- `web/driver-worker.js` – loads Pyodide, writes the strip's flash, runs `web/driver_boot.py`.
- `web/ring.js` – the SharedArrayBuffer queue that delivers packets to a driver while `main.py`
runs (it never yields to the JavaScript event loop).
- `stubs/_simlink.py` – the driver side of that link (radio, pixels, flash, sleeps).
## Notes
- `machine.reset()` in a driver reboots that strip.
- The ping reply that led-driver sends from a thread runs from the main loop after the same
50–500 ms delay (Pyodide has no threads).
- Strips do not hear each other's ESP-NOW broadcasts; the bridge forwards driver transmissions to
the controller only.