feat: browser simulator served by the controller, desktop build, browser bridge

- led-simulator: the rig runs the C++ led-driver as WebAssembly (sim-driver/),
  one single-threaded worker per bar, no cross-origin isolation needed. Rooms
  (one JSON per room) with an on-page editor, and a pattern gallery. The
  Python server, Pyodide boot and ring buffer are removed.
- sim-controller sim_rig.c: serves /sim/ from an embedded pack, the page's
  WebSocket and the rooms/flash API. The desktop build embeds it too.
- bridge.c: a "browser" bridge kind that carries ESP-NOW frames to the page;
  devices announced through it are marked sim.
- UI: Simulator in the Menu, split view with resize and pop-out, swipe
  between controller and rig on phones; SIM/REAL badges in Devices.
- Fades: preset pushes and Wi-Fi driver bodies always carry fade and
  beat_time, so "off" no longer inherits an earlier fade.
- Also the sequences-v2 work in progress: desktop port, bridge firmware,
  serial bridge, Wi-Fi drivers, sequence timeline, audio and API changes.
- led-driver: ESP-NOW link, beat sync, control messages, sim hooks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-11-16 19:32:46 +13:00
1 parent 698c1463c0
commit 581b751904
506 files changed
+42336 -3599

No files matched your search

+98 -102
View File
@@ -1,134 +1,130 @@
# led-simulator
A web app that simulates a whole LED rig behind a **Wi‑Fi bridge**.
A whole LED rig in the browser, served by **led-controller itself**. The host build of the controller
(`sim-controller`, and the desktop build) serves the rig at **`/sim/`**:
- 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`).
- Every LED bar is its own led-driver: the real **C++ firmware** (`led-driver/main`) built to **WebAssembly**
(`../sim-driver/`), one module worker per bar. The worker runs what the board's pattern task and ESP-NOW link task
run (`patterns_frame`, `espnow_link_poll`) from a timer, so there are no threads, no `SharedArrayBuffer`, and the
page works on any address. Only the hardware is replaced: NVS is kept by the controller, ESP-NOW goes
through the page, and the WS2812 strip is the canvas.
- The controller reaches the bars over **ESP-NOW**, through its **`browser` bridge**. The frames it would hand to a
USB or network bridge board go to the page over a WebSocket (`/sim/ws`), and the page delivers them to each bar by
MAC. Beats, sequences, groups and the reliable link all run as on hardware.
- **Rooms** say where the bars are. One room per JSON file, edited on the page. The bars' places go to the
controller's rig layout.
- **`/sim/gallery`** shows every pattern side by side, from the same C++ engine, with each preset field editable.
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.
One program and one port. There is no Python server and no UDP bridge.
## 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)
## Run
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`
make sim-web # builds the drivers (Emscripten in Docker), the controller for the host, and runs it
```
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.
Then open **http://localhost:8080/sim/** in Chrome, Edge or Firefox. The controller's own UI
is on http://localhost:8080/. Any address works, a phone on the LAN included (`http://<computer>:8080/sim/`): the
drivers need no cross-origin isolation.
### Headless
The bars register with the controller from their announces when they power on, and the page gives the controller
their places from the room. Only one tab runs the rig: opening it in a second tab powers the first one's bars off.
`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).
`make desktop` embeds the rig too (after `make sim-wasm`). There, add **`browser`** to the bridges, under
Settings > Network > Bridges or with the page's *Add the browser bridge* button. `make sim-web` starts the host build
with `LED_SIM_BRIDGE=browser`. With no bridge configured, `browser` is the default.
## Run
## Rooms
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):
The spatial config follows the stage maps of the qlcplus simulator: one file per room, a size in metres,
strip types in `definitions`, and `fixtures` keyed by id, each placed by position and heading.
```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/"
"name": "studio",
"units": "metres",
"width": 7.0,
"depth": 5.0,
"origin": "X=0 at the room centre, +X right; Y=0 at the front edge, +Y up the screen; headings clockwise from +Y",
"definitions": {
"bar-119": { "leds": 119, "pitch_m": 0.01667 }
},
"fixtures": {
"sim-01": { "label": "sim-01", "def": "bar-119", "mac": "02:51:4d:00:00:01", "x": -0.1, "y": 2.55, "direction": -90 }
}
}
```
- `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.
- A **fixture** is one bar, so one simulated driver. `x`, `y` (metres) is **pixel 0**, the data-in end. The bar
runs from there along **`direction`**: degrees clockwise from +Y, so `90` runs right and `-90` runs left. It is
`leds × pitch_m` long. `leds` on a fixture overrides its type's count (1–512).
- **`mac`** identifies the driver. Each bar's flash is kept per MAC, so a bar in two rooms (a copied room, say) is
the same bar with the same presets. New bars get a MAC no room uses yet.
- The first run makes the `default` room: 16 bars × 119 LEDs in 2 columns × 8 rows, pixel 0 at the centre line,
`sim-01` … `sim-16` = `02:51:4d:00:00:01` … `…:10`. The rig's bridge is `02:51:4d:00:00:00`.
## Simulated flash
Everything is kept in the controller's store folder (`LED_SIM_DB`; `sim-controller/data` for `make sim-web`):
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.
| | |
| --- | --- |
| `sim/rooms/<name>.json` | the rooms |
| `sim/flash/<mac>.json` | each bar's NVS store, `{namespace: {key: [type, value]}}` |
| `sim/sim.json` | the active room |
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.
On every boot a bar's `led.num_leds` is set from its room. The first boot also takes its hostname from the fixture's
label. Delete `sim/flash/` to factory-reset every bar.
On the page, pick the room in the header. **Edit room** changes it, and every change is saved and sent to the
controller's rig layout:
- Click the floor to add a bar. Drag a bar to move it, which snaps to 5 cm; hold Alt to move it freely.
- Drag the circle at its far end to turn it, which snaps to 15°; hold Shift to turn it freely. Delete removes the
selected bar.
- The side panel edits a bar's label, type, LED count, position and heading.
- **Size & strip types…** sets the room's size and adds or changes strip types.
- **New room…** makes an empty room or a copy of the current one. **Delete room** removes the room's file.
A bar whose LED count changes keeps running with the old count until it is power-cycled, as `num_leds` is read at
boot.
### API (on the controller)
| | |
| --- | --- |
| `GET /sim/api/config` | the active room, the room list and the bridge state |
| `GET /sim/api/flash/<mac>` | a bar's NVS store |
| `GET /sim/api/rooms` | `{current, rooms}` |
| `POST /sim/api/rooms` | `{name, width, depth, copy_from?}` makes a room |
| `GET`, `PUT`, `DELETE /sim/api/rooms/<name>` | one room: read it, replace it (validated), delete it (not the active one) |
| `POST /sim/api/room` | `{name}` switches the rig to that room |
| `GET /sim/api/next-mac` | a MAC no room uses |
| `WS /sim/ws` | the page's radio: binary `dst_mac + packet` down, `src_mac + packet` up; text `{"t":"flash"}` up |
## 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)
led-controller (host build) ──"browser" bridge──▶ WS /sim/ws ──▶ page ──postMessage──▶ driver worker × N
rel, beats, sequences ◀── src_mac+pkt ───── ◀── tx, px, flash ── (led_driver.wasm:
/sim/ page + rooms (sim_rig.c) sim_tick: link + patterns)
```
- `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).
| Where | What |
| --- | --- |
| `sim-controller/components/sim/sim_rig.c` | serves the page and the wasm from `www_dist/sim.pack`, the page's WebSocket, rooms and flash |
| `main/bridge.c` | the `browser` bridge kind next to UDP and serial |
| `tools/build_sim_web.sh` | packs `web/` and `web/wasm/` into `www_dist/sim.pack`. It is empty when the drivers are not built, so `make desktop` works without Emscripten. |
| `../sim-driver/` | the Emscripten build of the driver (`led_driver`) and the pattern engine for the gallery (`led_fx`) |
| `web/app.js` | the room canvas, editor, power control, packet routing by MAC, and placements for `POST /devices/layout` |
| `web/driver-worker.js` | loads `led_driver.mjs` and boots one bar |
| `web/gallery.js` | one `led_fx` instance per pattern, each stepped every 10 ms of its own clock |
## Notes
Not simulated: the drivers' Wi-Fi, their own web UI and HTTP API, DDP and USB. Bars do not hear each other's
ESP-NOW.
- `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.
## Headless (older)
`python3 led-simulator/bridge_sim.py` ran each bar as a CPython process with the MicroPython driver
(`led-driver/src`, now removed from led-driver) behind a UDP bridge, so it no longer has drivers to run. Its grid
comes from `layout` in `sim.json` (`layout.py`, `rig_seed.py`).