- 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>
131 lines
7.0 KiB
Markdown
131 lines
7.0 KiB
Markdown
# led-simulator
|
||
|
||
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/`**:
|
||
|
||
- 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.
|
||
|
||
One program and one port. There is no Python server and no UDP bridge.
|
||
|
||
## Run
|
||
|
||
From the repository root:
|
||
|
||
```bash
|
||
make sim-web # builds the drivers (Emscripten in Docker), the controller for the host, and runs 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.
|
||
|
||
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.
|
||
|
||
`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.
|
||
|
||
## Rooms
|
||
|
||
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
|
||
{
|
||
"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 }
|
||
}
|
||
}
|
||
```
|
||
|
||
- 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`.
|
||
|
||
Everything is kept in the controller's store folder (`LED_SIM_DB`; `sim-controller/data` for `make sim-web`):
|
||
|
||
| | |
|
||
| --- | --- |
|
||
| `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 |
|
||
|
||
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 (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)
|
||
```
|
||
|
||
| 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 |
|
||
|
||
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.
|
||
|
||
## 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`).
|