feat: sequences v2, bridges, and sim-controller

Rework sequences (engine, seqplay, envelope, API, web UI), add bridge
support, add the host sim-controller and rig simulation tests, and
update docs, presets and project tooling config.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Sonnet 5.5 committed 2026-11-10 17:47:27 +13:00
1 parent d664026ee5
commit 2543673bd8
68 files changed
+5761 -460

No files matched your search

+45 -11
View File
@@ -34,7 +34,7 @@ Pages and static files are built into the firmware (gzipped, sent with `Content-
| Method | Path | Description |
|--------|------|-------------|
| GET | `/status` | IP, MAC, uptime, `free_heap`, `free_internal` (internal RAM), mic level, tempo and beat counts, ESP-NOW and link statistics |
| GET | `/status` | IP, `eth` (ip, mask, gw, up), `ap_ip`, `ap_clients` (`[{mac, ip}]` on the Wi-Fi access point), MAC, uptime, `free_heap`, `free_internal` (internal RAM), mic level, tempo and beat counts, ESP-NOW and link statistics |
| POST | `/reboot` | Replies `{"message":"rebooting"}`, then restarts after 0.5 s |
| GET | `/ota` | Running image: partition, version, build time, IDF version, sha |
| POST | `/ota` | Body: the raw firmware `.bin` (web UI included). Written to the idle slot, made the boot image, then the board reboots. A new image confirms itself after staying up a few seconds; one that crashes on start rolls back. `make ota HOST=<ip>` |
@@ -61,8 +61,9 @@ Keys with meaning on the controller (others are stored as they are):
| Key | Checked | Meaning |
|-----|---------|---------|
| `ap_enabled` | | Wi-Fi access point (open, SSID = hostname, `192.168.5.1`); default `true`; applies after a restart. Holding the D7 button at boot forces it on |
| `ap_enabled` | | Wi-Fi access point (open, SSID = hostname, `192.168.5.1`); default `true`; applies after a restart. Holding the D3 button at boot forces it on |
| `ap_password` | | AP password, 8-63 characters (WPA2); empty (default) is an open network; applies after a restart |
| `bridge` | string under 64 characters | `host:port` (UDP, default port 8766) of led-simulator: every ESP-NOW frame goes there as `dst_mac + packet` instead of over the radio, and frames from it (`src_mac + packet`) count as received. Empty or missing: the radio. Applies after a restart. The host build (`sim-controller/`) always uses a bridge (`LED_SIM_BRIDGE`, default `127.0.0.1:8766`) |
| `hostname` | | mDNS name (`<hostname>.local`, default `led-controller`); applies after a restart |
| `static_ips` | | List of `{ip, netmask?, gw, dns?}` tried in order when the Ethernet link comes up; the first whose gateway answers ARP is used, else DHCP, else `192.168.4.1/24` for a direct PC cable. Applies after a restart |
| `global_brightness` | integer 0–255 | Global factor of each driver's brightness (see Groups). Stored only: the UI pushes each driver its combined value |
@@ -97,7 +98,11 @@ A store with no profile gets one at boot, `default`, with the same seed, a start
## Presets — `/presets`
A preset has `name`, `pattern`, `colors` (`#RRGGBB`), `brightness`, `delay`, `n1`–`n8`, `profile_id`, and optionally `auto`, `palette_refs` (palette index per colour slot), `background` / `background_palette_ref`, `mode` (sent as `n6`) and `manual_beat_n`. New presets start with every field set and belong to the current profile.
A preset has `name`, `pattern`, `colors` (`#RRGGBB`), `brightness`, `delay`, `n1`–`n8`, `profile_id`, and optionally `auto`, `palette_refs` (palette index per colour slot), `background` / `background_palette_ref`, `mode` (sent as `n6`), `manual_beat_n`, `fade` (0–10000 ms: crossfade from what the strip showed when the preset is selected) and `beat_time` (`true`: the delay and timing parameters of patterns that support it count quarter beats, so the preset follows the tempo). New presets start with every field set and belong to the current profile.
**Animation patterns** (driver patterns, labels in `/patterns`). Each plays once with `auto: false` and holds its end state; with `auto: true` it repeats.
- One-shots: `hit` (flash with attack, hold and decay), `keyframes` (ramp through the colours with easing).
- Field patterns, which span the whole rig using each driver's place from `/devices/layout`: `sweep`, `ripple`, `spin`, `grow`, `field_wave`.
| Method | Path | Description |
|--------|------|-------------|
@@ -113,7 +118,7 @@ A preset has `name`, `pattern`, `colors` (`#RRGGBB`), `brightness`, `delay`, `n1
## Zones — `/zones`
A zone has `name`, `names` (driver names, the older way to target drivers), `group_ids` (groups it plays to), `presets` (rows of preset ids), `presets_flat`, `default_preset`, `preset_group_ids`, `sequence_ids`, `content_kind` (`presets` or `sequences`) and `brightness` (0–255, the zone slider).
A zone has `name`, `names` (driver names, the older way to target drivers), `group_ids` (groups it plays to), `presets` (rows of preset ids), `presets_flat`, `default_preset`, `preset_group_ids`, `sequence_ids`, `animation_ids` (animations shown as one-shot tiles), `content_kind` (`presets` or `sequences`) and `brightness` (0–255, the zone slider).
| Method | Path | Description |
|--------|------|-------------|
@@ -160,6 +165,7 @@ A device is `{id: MAC, name, type: "led", transport: "espnow" | "wifi", address,
| DELETE | `/devices/<id>` | Delete |
| GET | `/devices/status` | Per driver: `{"last_ack_ms_ago": ms or -1, "failed_messages": n}` from the acked link |
| POST | `/devices/ping` | Body `{"timeout_s": 0.5–30}` (default 3). Broadcasts a ping and collects replies: `{"ok", "ping_id", "timeout_s", "responses": {mac: {mac, name, rtt_ms}}, "registered": n}`. Drivers that answer are added or renamed |
| POST | `/devices/layout` | Body `{"placements": {mac: {x0, y0, x1, y1} \| null}, "center"?: {x, y}}`: where each bar sits, in any units with y up, and the rig's centre (kept in `settings.rig_center`; without one, the layout's bounding-box centre). `x0,y0` is LED 1, the data-in end; `null` removes a bar. Saved as the device's `placement`. Then every placed ESP-NOW driver gets `device_config.place`: its ends relative to the centre, scaled so the furthest end is 1 from it. Reply `{"updated", "sent", "failed"}`; 400 without `placements` |
| POST | `/devices/groups` | Send every ESP-NOW driver its groups and wait for the acks: `{"ok", "total", "sent", "failed"}` (503 when any failed, 400 with no ESP-NOW devices) |
| POST | `/devices/resolve-brightness` | Body `{"macs": [...], "zone_brightness"?}` → `{"values": {mac: brightness}}` |
| POST | `/devices/<id>/brightness` | Body `{"zone_brightness"?}`: send the combined brightness, saved on the driver. `{"message", "brightness"}` |
@@ -168,7 +174,22 @@ A device is `{id: MAC, name, type: "led", transport: "espnow" | "wifi", address,
## Sequences — `/sequences`
A sequence is `{name, profile_id, lanes: [[step, ...], ...], lanes_group_ids: [[group ids], ...], group_ids, loop (default true), advance_mode: "beats" | "time", steps, step_duration_ms, sequence_transition}`. A step is `{preset_id, beats (default 1), seconds (default 3, 0.1–3600), group_ids?}`. With `advance_mode` `beats` a step lasts `beats` beats; with `time` it lasts `seconds`.
A sequence is `{name, profile_id, kind?, targets?, lanes: [[step, ...], ...], lane_opts?, lanes_group_ids: [[group ids], ...], group_ids, loop (default true), advance_mode: "beats" | "time", steps, step_duration_ms, sequence_transition}`. Every field marked `?` is optional; a sequence without them plays as it always has.
- `kind`: `"sequence"` (default) or `"animation"`: a clip that is fired once over whatever runs (see Animations). Both are stored here.
- `targets`: the drivers the sequence plays to, in order (up to 32): `[{name, group_ids: [group ids], devices: [MACs]}]`. A target reaches every driver in its groups plus each listed driver (by its own group `d<mac>`, see Driver groups). Lanes and steps name targets by index.
- `lane_opts`: one object per lane (same index as `lanes`):
- `mode`: `"beats"` or `"time"`, overriding `advance_mode` for this lane, so beat lanes and time lanes run side by side.
- `offset`: beats (or seconds, time lanes) before the lane starts, on the first pass only. With a copy of a lane this gives a canon or ripple.
- `rate`: 0.25–4, speed multiplier. A 1-beat step at rate 2 lasts half a beat.
- `targets`: indexes into `targets` the lane plays to. Without them the lane's groups come from the older fields: `lanes_group_ids[lane]`, else `group_ids`, else (single lane) the step's `group_ids`, else the zone's groups.
- `chase`: `{order: "forward" | "reverse" | "bounce" | "random", width (default 1), others: "off" (default) | "hold"}`. Each step moves the lit position along the lane's targets (in the order listed in the lane's `targets`). The step's preset goes to `width` targets from there, and the rest go off or keep what they show.
- A step is `{preset_id, beats (default 1, from 0.25), seconds (default 3, 0.1–3600), targets?, others?, rest?, animation_id?, length?, group_ids?}`:
- `beats` / `seconds`: how long it lasts, by its lane's mode.
- `targets`: indexes of the lane's targets this step lights (default: all of the lane's, or the chase position).
- `others: "off"`: the lane's other targets go off for this step.
- `rest: true`: nothing lit; the lane's targets go off.
- `animation_id`: fire that animation instead of a preset. With `length: "animation"` the step lasts as long as the animation (at the current tempo).
| Method | Path | Description |
|--------|------|-------------|
@@ -178,7 +199,9 @@ A sequence is `{name, profile_id, lanes: [[step, ...], ...], lanes_group_ids: [[
| PUT | `/sequences/<id>` | Merge fields; stops it when it is playing |
| DELETE | `/sequences/<id>` | Delete; stops it when it is playing |
| POST | `/sequences/<id>/play` | Body `{"zone_id"}` (required). Reply `{"ok": true, "pending": bool, ...}`. 400 for a missing zone, a sequence without steps or one from another profile |
| POST | `/sequences/stop` | Stop playback and clear the presets on the zone's groups. `{"ok": true}` |
| POST | `/sequences/stop` | Stop playback (and any animation) and clear the presets on the zone's groups. `{"ok": true}` |
| POST | `/sequences/<id>/fire` | Play it once as an animation over whatever runs. Body `{"zone_id"?, "wait"?: "now" (default) \| "beat" \| "downbeat"}`; without `zone_id`, the playing sequence's zone. Reply `{"ok": true, "wait"}`. 404 for another profile's, 400 without a zone or steps |
| POST | `/sequences/overlay/stop` | End the animation now; its drivers go back (as when it ends). `{"ok": true}` |
| POST | `/sequences/sync-phase` | Body `{"mode": "step" | "pass"}`: `step` restarts the current step's beat count, `pass` restarts the sequence. Also makes this beat bar beat 1. 409 when nothing plays |
| GET | `/sequences/status` | Playback status (below) |
| GET | `/sequences/<id>/export` | Sequence bundle (the sequence and its presets) |
@@ -186,12 +209,19 @@ A sequence is `{name, profile_id, lanes: [[step, ...], ...], lanes_group_ids: [[
**Playback.** One sequence plays at a time, in one zone.
- **Start.** Each lane's first preset is uploaded to the lane's groups and selected, then the lane's other presets are uploaded, and every driver in the zone gets its combined brightness with the zone slider.
- **Advancing.** In `time` mode a lane moves on when its step's `seconds` are up, whatever the beat; the status then has `lane0_step_elapsed_ms` and `lane0_step_duration_ms` and `beat_readout` is empty. In `beats` mode, on each beat a lane counts towards its step's `beats`, then moves on: the next preset is uploaded (unless already there) and selected. A lane's groups are `lanes_group_ids[lane]`, else `group_ids`, else (single lane) the step's `group_ids`, else the zone's groups.
- **Advancing.** A time lane moves on when its step's `seconds` are up, whatever the beat. When lane 0 is a time lane, the status has `lane0_step_elapsed_ms` and `lane0_step_duration_ms` and `beat_readout` is empty. A beat lane counts quarter beats (the controller ticks between beats from the last beat interval) towards its step's `beats` ÷ `rate`, then moves on. Each step's preset is uploaded to all of the lane's targets (unless already there), then selected on the targets the step lights.
- **End.** Without `loop` the sequence ends after one pass. Its presets are cleared from the zone's groups, and the readout keeps `n/n`.
- **Switching.** Starting another sequence while one plays waits for the next beat. It waits for the next downbeat only when `sequence_switch_wait` is `downbeat` and the mic is timing. The current sequence holds meanwhile.
- **Animations.** `/sequences/<id>/fire` (or a step's `animation_id`) plays a sequence once in a second player over the running one. An animation loops only with `loop: true`.
- While it plays, the sequence keeps time, but its sends leave out the drivers the animation's lanes reach: groups are split into those drivers' own groups.
- When it ends (or `/sequences/overlay/stop`), those drivers get the sequence's current step again. With no sequence playing they get the zone's last played preset, else off.
- Firing another animation replaces the one playing. Drivers the new one doesn't reach go back.
- A sequence that ends while an animation plays clears the zone once the animation is over.
- **Beat source.** Beats come from the mic's beat detector while audio timing is on (`/api/audio/start`) and it has a tempo lock. Otherwise they come from a clock at `audio_simulated_bpm`, whose beats also go to the drivers. Beats closer than 0.3 s (200 BPM) are dropped.
Status: `{"active": false, "beat_readout": ""}` when idle, else `{active, advance_mode, sequence_id, zone_id, num_lanes, total_sequence_steps, lane0_current_step, lane0_lane_length, lane0_beat_in_step, lane0_beats_per_step, lane0_preset_id, lane0_preset_name, sequence_beat_at, sequence_beats_per_pass, sequence_loop_beat, beat_readout}`.
Status: `{"active": false, "beat_readout": "", overlay}` when idle, else `{active, advance_mode, sequence_id, zone_id, num_lanes, total_sequence_steps, lane0_current_step, lane0_lane_length, lane0_beat_in_step, lane0_beats_per_step, lane0_preset_id, lane0_preset_name, sequence_beat_at, sequence_beats_per_pass, sequence_loop_beat, beat_readout, lanes, overlay}`.
- `lanes`: one entry per playing lane, `{step (0-based), steps, mode, started, done, pos? (chase: the target index lit first), beat_in_step and beats_in_step (beat lanes) or elapsed_ms and duration_ms (time lanes)}`.
- `overlay`: `{active, pending, pending_id?}`, plus `{sequence_id, zone_id, drivers, progress (0–1), lanes}` while an animation plays.
## Audio — `/api/audio`
@@ -287,6 +317,9 @@ Pushes led-driver `.py` files to ESP-NOW drivers, one file per request; `tools/d
The UI, `/presets/push`, `/ws` and the controller itself send drivers **v1 messages**: JSON objects with `"v": "1"`. The controller does not send them as they are:
- **Binary envelope.** A message that only carries presets, a select, brightness, `save` and `groups` goes out as a compact binary envelope (`main/envelope.c`, mirrored by `test/binary_envelope.py`).
- Version 2 is the usual frame.
- A frame whose presets use `fade` or `beat_time` is version 3: each preset record is followed by `[ext_len][key, len, value]…`, with key 1 the fade ms (u16) and key 2 the beat timing (u8).
- Drivers skip keys they don't know. Drivers without v3 support ignore v3 frames, so they miss only presets that use the new fields.
- **JSON.** Any other message goes as JSON with short keys, split across several messages when it does not fit one ESP-NOW frame. A preset with a background colour (`bg`) is one of these: the envelope has no field for it.
- **Delivery.** Broadcasts are never acked (envelopes go out twice, JSON once); drivers that miss a state change notice from the state digest and ask to be brought up to date. Messages with `targets` are unicast to each MAC, acked and retried.
@@ -300,12 +333,12 @@ The UI, `/presets/push`, `/ws` and the controller itself send drivers **v1 messa
| `set_groups` | `sg` | With `groups`: replace the driver's group list |
| `save` | `sv` | Persist presets, brightness or config on the driver |
| `default` | `df` | Startup preset id |
| `device_config` | `dc` | `name`, `num_leds`, `color_order`, `startup_mode`, `max_brightness`, `reversed` |
| `device_config` | `dc` | `name`, `num_leds`, `color_order`, `startup_mode`, `max_brightness`, `reversed`, `place` ([x0, y0, x1, y1] in rig coordinates, see `/devices/layout`; `null` clears it), `usb_log` (per-beat USB log; on reboot). Drivers print nothing over USB unless their `debug` or `usb_log` setting is on: on the ESP32-C3, unread USB output blocks the driver |
| `clear_presets` | `cp` | Drop stored presets |
| `manifest` | `mf` | Pattern files to fetch (Wi-Fi drivers) |
| `b` | | Driver brightness 0–255 |
Preset fields: `p`/`pattern`, `c`/`colors` (`#RRGGBB`), `d`/`delay` (ms, default 100), `b`/`brightness` (0–255), `a`/`auto` (`true` runs freely, `false` steps once per beat), `bg`/`background`, `n1`–`n6` (pattern parameters; `n5` is reverse, `n6` the style mode). Other fields (`name`, `manual_beat_n`, …) are dropped on the way out.
Preset fields: `p`/`pattern`, `c`/`colors` (`#RRGGBB`), `d`/`delay` (ms, default 100), `b`/`brightness` (0–255), `a`/`auto` (`true` runs freely, `false` steps once per beat), `bg`/`background`, `n1`–`n6` (pattern parameters; `n5` is reverse, `n6` the style mode), `f`/`fade`, `tb`/`beat_time`. Other fields (`name`, `manual_beat_n`, …) are dropped on the way out.
Sending `select` again with the same preset is a beat for that preset. Selecting `off` resets the step, so the next select starts every driver at step 0 unless a step is given.
@@ -314,7 +347,8 @@ Sending `select` again with the same preset is a beat for that preset. Selecting
A driver keeps a list of group ids and applies a group command (or a message with `groups`) only when it holds one of them. The controller sends each ESP-NOW driver its list whenever groups, zones or devices change, when the driver boots, and when it asks to be brought up to date. A driver that has failed three messages in a row gets these updates at most every 30 s until it answers again. The list holds:
- every group (`group` collection) whose `devices` lists the driver's MAC, by group id;
- `z<zone id>` for every zone whose `names` lists the driver's name (zones from before groups).
- `z<zone id>` for every zone whose `names` lists the driver's name (zones from before groups);
- its own group `d<mac>` (12 lowercase hex digits), always first, so a sequence target can name a single driver. It doesn't change any other membership.
A zone plays to its `group_ids` and, when it names drivers, to `z<zone id>`. A message with `groups` that fits the envelope goes out as one group command per group.