docs: describe the v2 controller's API, UI and tests
API.md now documents what the firmware serves: groups, combined brightness, beat-driven sequences, import/export, /api/audio, patterns over ESP-NOW, outputs, /ws, driver OTA, and how API calls become driver messages and group commands. The user guide follows the current UI; the in-app audio help describes the microphone instead of input devices. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
bfeeb958df
commit
b2cd242390
5 files changed
+335
-429
No files matched your search
+266
-351
@@ -1,417 +1,332 @@
|
||||
# LED Controller API
|
||||
|
||||
This document covers:
|
||||
The controller is an ESP32-S3 on Ethernet (W5500). It serves the web UI and a JSON API on port 80, detects beats from its I2S microphone and talks to the LED drivers over ESP-NOW. This document covers:
|
||||
|
||||
1. **HTTP and WebSocket** exposed by the Raspberry Pi app (`src/main.py`) — profiles, zones, presets, transport send, pattern OTA helpers, and related resources.
|
||||
2. **LED driver JSON** — the compact **v1** message format. It is sent over the **serial → ESP-NOW bridge** to ESP32 peers and as **single JSON text messages** over the **outbound WebSocket** to **Wi-Fi** drivers (same logical fields).
|
||||
1. The HTTP and WebSocket API, by resource.
|
||||
2. How the controller turns API calls into driver messages, and the message format.
|
||||
|
||||
Default HTTP listen address: `0.0.0.0`. Port defaults to **80**; override with the **`PORT`** environment variable (see `pipenv run run`).
|
||||
Request and response bodies are JSON (`Content-Type: application/json`) unless noted. Errors come back as `{"error": "..."}` with a 4xx or 5xx status.
|
||||
|
||||
**Serial:** UART path and baud come from settings (defaults include `serial_port` such as `/dev/ttyS0` and `serial_baudrate`). **Wi-Fi drivers:** **UDP** on port **8766** is the **discovery** channel: each driver’s JSON hello (**`device_name`**, **MAC**, optional **`type`**) **creates or updates** that device in **`db/device.json`** (keyed by MAC); the Pi echoes the datagram. After a valid hello with **`v`:** **`"1"`**, the Pi also opens an **outbound WebSocket** to that IP (**`wifi_driver_ws_port`**, default **80**; **`wifi_driver_ws_path`**, default **`/ws`**) for v1 commands; presets are not pushed automatically on connect (use **Send Presets** / profile apply). The Pi may send periodic UDP **hello** nudges to known Wi‑Fi device IPs when the WebSocket is down (**`wifi_driver_hello_interval_s`** in settings).
|
||||
## Data and scoping
|
||||
|
||||
All JSON APIs use `Content-Type: application/json` for bodies and responses unless noted.
|
||||
- **Storage.** Each resource is a collection (`device`, `zone`, `preset`, `profile`, `palette`, `pattern`, `sequence`, `scene`, `group`, `output`, `settings`), stored as one JSON object of id → record on the flash filesystem. New records get the next numeric id (highest + 1), as a string. Devices are keyed by MAC (12 lowercase hex digits, no colons) and patterns by name.
|
||||
- **Current profile.** `settings.current_profile_id`, set by `POST /profiles/<id>/apply`. When it is unset or names a missing profile, the first profile is current. It is global (the same for every browser).
|
||||
- **Profile scoping.** Presets and sequences belong to a profile (`profile_id`). The list routes return only the current profile's records, and the single-record routes answer 404 for another profile's. Groups with a `profile_id` are visible only while that profile is current; groups without one are shared.
|
||||
- **Current zone.** A `current_zone` cookie, set by `POST /zones/<id>/set-current`. Without it, the current profile's first zone.
|
||||
- **Migration.** At boot, groups, zones and sequences written by older versions get the fields described below.
|
||||
|
||||
---
|
||||
|
||||
## UI behavior notes
|
||||
|
||||
The main UI has two modes controlled by the mode toggle:
|
||||
|
||||
- **Run mode**: optimized for operation (zone/preset selection and profile apply).
|
||||
- **Edit mode**: shows editing/management controls (zones, presets, patterns, colour palette, send presets, profile management actions, **Devices** registry for LED driver names/MACs, and related tools).
|
||||
|
||||
Profiles are available in both modes, but behavior differs:
|
||||
|
||||
- **Run mode**: profile **apply** only.
|
||||
- **Edit mode**: profile **create/clone/delete/apply**.
|
||||
|
||||
`POST /presets/send` is wired to the **Send Presets** UI action, which is exposed in Edit mode.
|
||||
|
||||
---
|
||||
|
||||
## Session and scoping
|
||||
|
||||
Several routes use **`@with_session`**: the server stores a **current profile** in the session (cookie). Endpoints that scope data to “the current profile” (notably **`/presets`**) only return or mutate presets whose `profile_id` matches that session value.
|
||||
|
||||
Profiles are selected with **`POST /profiles/<id>/apply`**, which sets `current_profile` in the session.
|
||||
|
||||
---
|
||||
|
||||
## Static pages and assets
|
||||
## Pages and static files
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/` | Main UI (`templates/index.html`) |
|
||||
| GET | `/settings/page` | Standalone settings page (`templates/settings.html`) |
|
||||
| GET | `/favicon.ico` | Empty response (204) |
|
||||
| GET | `/static/<path>` | Static files under `src/static/` |
|
||||
| GET | `/` | Main UI |
|
||||
| GET | `/settings/page` | Standalone settings page |
|
||||
| GET | `/audio` | Live audio and beat page (level, tempo, bar position, tap) |
|
||||
| GET | `/static/<path>` | UI scripts and styles |
|
||||
| GET | `/favicon.ico` | 204 |
|
||||
|
||||
---
|
||||
Pages and static files are built into the firmware (gzipped, sent with `Content-Encoding: gzip`). They carry `Cache-Control: no-cache` and an `ETag` of the firmware build, so a browser revalidates each load (304 until the next update).
|
||||
|
||||
## WebSocket: `/ws`
|
||||
|
||||
Connect to **`ws://<host>:<port>/ws`**.
|
||||
|
||||
- Send **JSON**: the object is forwarded through the **serial sender** (6-byte MAC prefix + payload to the ESP-NOW bridge). Optional key **`to`**: 12-character hex MAC address; if present it is removed from the object and the payload is sent to that peer; otherwise the default destination from settings is used.
|
||||
- Send **non-JSON text**: forwarded as raw bytes with the default address.
|
||||
- On send failure, the server may reply with `{"error": "Send failed"}`.
|
||||
|
||||
Wi-Fi devices are not targeted by `/ws` directly; use **`POST /presets/send`**, device routes, or **`POST /patterns/<name>/send`** as appropriate.
|
||||
|
||||
---
|
||||
|
||||
## HTTP API by resource
|
||||
|
||||
Below, `<id>` values are string identifiers used by the JSON stores (numeric strings in practice).
|
||||
|
||||
### Driver app update over ESP-NOW — `/drivers/ota` (v2 controller)
|
||||
|
||||
Pushes led-driver `.py` files to ESP-NOW drivers, one file per request. `tools/driver_ota.py` (or `make ota-drivers`) runs a whole session. The wire format is described in `led-driver/src/espnow_ota.py`. Only one request runs at a time; a second one gets `409`.
|
||||
## Controller
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| POST | `/drivers/ota/file?mac=<macs>&sess=<n>&path=<p>&sha=<64 hex>` | Body: the raw file (0 to 65536 bytes). `mac` is a comma-separated list of 12-hex MACs, or `all` for every ESP-NOW device. `sess` is 1–65535 and is shared by all files of one update. `path` is the device path: a root file, `patterns/…` or `lib/…`. Drivers that already have a file with that sha256 skip it. With one target the chunks go by acked unicast. With several, the file is broadcast once, then each driver is asked for its missing chunks and repaired. The file is staged as `<path>.new` until commit. Reply: `{"<mac>":{"result":"same"\|"written"\|"error","code":"…","repaired":n}}`. Error codes come from the driver (`badhash`, `badpath`, `ioerr`, `toobig`, `incomplete`, `nosess`) or the link (`no reply to begin`, `link lost`, …). |
|
||||
| POST | `/drivers/ota/commit?mac=<macs>&sess=<n>` | Each driver moves its staged files into place, updates `file_hashes.json` and resets if anything changed. Reply: `{"<mac>":{"result":"ok"\|"error"}}`. |
|
||||
| POST | `/drivers/ota/abort?mac=<macs>&sess=<n>` | Each driver deletes its staged files. |
|
||||
| GET | `/status` | IP, 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>` |
|
||||
| GET | `/db/<collection>` | Export a whole collection |
|
||||
| PUT | `/db/<collection>` | Replace a whole collection. Body: the object of id → record. Reply: `{"records": n}` |
|
||||
|
||||
### Settings — `/settings`
|
||||
**Bench tests** (see `docs/BENCH_TEST.md`):
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/settings` | Full settings object (from `settings.json` / `Settings` model). |
|
||||
| PUT | `/settings/settings` | Merge keys into settings and save. Returns `{"message": "Settings updated successfully"}`. |
|
||||
| POST | `/reboot` | v2 controller: restart the board. Replies `{"message":"rebooting"}` first, then reboots after 0.5 s. Network settings (`hostname`, `static_ips`) apply on the next boot. |
|
||||
| GET | `/settings/wifi/ap` | Saved Wi‑Fi AP fields: `saved_ssid`, `saved_password`, `saved_channel`, `active` (Pi: `active` is always false). |
|
||||
| POST | `/settings/wifi/ap` | Body: `ssid` (required), `password`, `channel` (1–11). Persists AP-related settings. |
|
||||
| GET | `/settings/page` | Serves `templates/settings.html`. |
|
||||
| GET, POST | `/test/loss` | Simulated ESP-NOW loss. Body `{"percent": 0–100, "beats": bool}` (whether beat frames are dropped too). Reply: the current setting |
|
||||
| POST | `/test/beats` | Body `{"bpm": 30–300, "count": n}` (0 = until stopped): synthetic beats to the drivers, with delivery and latency measured from their echoes. The mic's beats are muted meanwhile |
|
||||
| GET | `/test/beats` | Results so far |
|
||||
| POST | `/test/beats/stop` | Stop the generator |
|
||||
|
||||
### Devices — `/devices`
|
||||
|
||||
Registry in `db/device.json`: storage key **`<id>`** (string, e.g. `"1"`) maps to an object that always includes:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **`id`** | Same as the storage key (stable handle for URLs). |
|
||||
| **`name`** | Shown in the UI and used in `select` keys. |
|
||||
| **`type`** | `led` (only value today; extensible). |
|
||||
| **`transport`** | `espnow` or `wifi`. |
|
||||
| **`address`** | For **`espnow`**: optional 12-character lowercase hex MAC. For **`wifi`**: optional IP or hostname string. |
|
||||
| **`default_pattern`**, **`zones`** | Optional. Legacy **`tabs`** may still appear in old files and is migrated away on load. |
|
||||
|
||||
Existing records without `type` / `transport` / `id` are backfilled on load (`led`, `espnow`, and `id` = key).
|
||||
## Settings — `/settings`
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/devices` | Map of device id → device object. |
|
||||
| GET | `/devices/<id>` | One device, 404 if missing. |
|
||||
| POST | `/devices` | Create. Body: **`name`** (required), **`type`** (default `led`), **`transport`** (default `espnow`), optional **`address`**, **`default_pattern`**, **`zones`**. Returns `{ "<id>": { ... } }`, 201. |
|
||||
| PUT | `/devices/<id>` | Partial update. **`name`** cannot be cleared. **`id`** in the body is ignored. **`type`** / **`transport`** validated; **`address`** normalised for the resulting transport. |
|
||||
| DELETE | `/devices/<id>` | Remove device. |
|
||||
| GET | `/settings` | The settings object |
|
||||
| PUT | `/settings` or `/settings/settings` | Merge keys into the settings. Reply: `{"message": "Settings updated successfully"}` |
|
||||
|
||||
### Profiles — `/profiles`
|
||||
Keys with meaning on the controller (others are stored as they are):
|
||||
|
||||
| Key | Checked | Meaning |
|
||||
|-----|---------|---------|
|
||||
| `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. 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 |
|
||||
| `wifi_channel` | integer 1–11 | Stored for reference. The controller's ESP-NOW channel is set at build time (`make menuconfig`) |
|
||||
| `audio_simulated_bpm` | clamped to 60–200 | Tempo of the beat clock (default 120) |
|
||||
| `sequence_switch_wait` | `beat` or `downbeat` | When a newly started sequence takes over from the playing one |
|
||||
| `audio_beat_phase_ms` | integer 0–500 | Stored for the UI |
|
||||
| `audio_input_volume` | integer 0–200 | Stored for the UI |
|
||||
| `current_profile_id` | | Set by profile apply and import |
|
||||
| `audio_timing` | | Set by `/api/audio/start` and `/stop` |
|
||||
|
||||
Defaults filled at boot: `wifi_channel` (the build's ESP-NOW channel) and `global_brightness` (255).
|
||||
|
||||
## Profiles — `/profiles`
|
||||
|
||||
A profile is `{name, type: "zones", zones: [zone ids], scenes, palette_id}`.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/profiles` | `{"profiles": {...}, "current_profile_id": "<id>"}`. Ensures a default current profile when possible. |
|
||||
| GET | `/profiles/current` | `{"id": "...", "profile": {...}}` |
|
||||
| GET | `/profiles/<id>` | Single profile. If `<id>` is `current`, same as `/profiles/current`. |
|
||||
| POST | `/profiles` | Create profile. Body may include `name` and other fields. Optional `seed_dj_zone` (request-only) seeds a DJ zone + presets. New profiles always get a populated `default` zone. Returns `{ "<id>": { ... } }` with status 201. |
|
||||
| POST | `/profiles/<id>/apply` | Sets session current profile to `<id>`. |
|
||||
| POST | `/profiles/<id>/clone` | Clone profile (zones, palettes, presets). Body may include `name`. |
|
||||
| PUT | `/profiles/current` | Update the current profile (from session). |
|
||||
| PUT | `/profiles/<id>` | Update profile by id. |
|
||||
| DELETE | `/profiles/<id>` | Delete profile. |
|
||||
| GET | `/profiles` | `{"profiles": {...}, "current_profile_id": "<id>"}` |
|
||||
| GET | `/profiles/current` | `{"id": "<id>", "profile": {...}}`; 404 when there are no profiles |
|
||||
| GET | `/profiles/<id>` | One profile (`current` works as an id) |
|
||||
| POST | `/profiles` | Create. Body: `name` and any other fields; optional `seed_dj_zone`. Reply `{"<id>": profile}`, 201. See below |
|
||||
| PUT | `/profiles/<id>`, `/profiles/current` | Merge fields |
|
||||
| POST | `/profiles/<id>/apply` | Make it current. Reply `{"message": "Profile applied", "id": "<id>"}` |
|
||||
| POST | `/profiles/<id>/clone` | Copy with its own palette, zones and presets (preset references in the zones point at the copies). Body: optional `name`. 201 |
|
||||
| DELETE | `/profiles/<id>` | Delete it with its presets and sequences, and its zones and palette unless another profile lists them |
|
||||
| GET | `/profiles/<id>/export` | Profile bundle (see Import and export) |
|
||||
| POST | `/profiles/import` | Body: `{"bundle": {...}, "name"?, "apply"? (default true)}` or the bundle itself. Reply `{"<id>": profile, "id": "<id>"}`, 201 |
|
||||
|
||||
### Presets — `/presets`
|
||||
A new profile gets an empty palette, eight presets (`on`, `off`, `rainbow` (`colour_cycle`), `Colour Cycle`, `transition`, `flicker`, `flame`, `twinkle`) and a zone `default` that lists them and names driver `1`. With `seed_dj_zone` it also gets three `DJ …` presets in a zone `dj` naming driver `dj`.
|
||||
|
||||
Scoped to **current profile** in session (see above).
|
||||
## 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.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/presets` | Map of preset id → preset object for the current profile only. |
|
||||
| GET | `/presets/<id>` | One preset, 404 if missing or wrong profile. |
|
||||
| POST | `/presets` | Create preset; server assigns id and sets `profile_id`. Body fields stored on the preset. Returns `{ "<id>": { ... } }`, 201. |
|
||||
| PUT | `/presets/<id>` | Update preset (must belong to current profile). |
|
||||
| DELETE | `/presets/<id>` | Delete preset. |
|
||||
| POST | `/presets/send` | Push presets to the LED driver over the configured transport (see below). |
|
||||
| GET | `/presets` | The current profile's presets |
|
||||
| GET | `/presets/<id>` | One preset (404 for another profile's) |
|
||||
| POST | `/presets` | Create in the current profile. Reply `{"<id>": preset}`, 201 |
|
||||
| PUT | `/presets/<id>` | Merge fields |
|
||||
| DELETE | `/presets/<id>` | Delete |
|
||||
| POST | `/presets/push` | Send driver messages. Body: `{"sequence": [message, ...]}` or `{"payload": message}`, optional `targets` (MACs: acked unicast to each). Without targets, broadcast. Reply `{"message": "Delivered"}`. See Driver messages |
|
||||
| POST | `/presets/send` | Send stored presets. Body: `preset_ids` (or `ids`), `save` (default true), `default` (startup preset id), `targets` or `destination_mac`. Reply `{"message": "Presets sent", "presets_sent": n}` |
|
||||
| GET | `/presets/<id>/export` | Preset bundle |
|
||||
| POST | `/presets/import` | Body: a preset bundle (or `{"bundle": ...}`). New id in the current profile, 201 |
|
||||
|
||||
**`POST /presets/send` body:**
|
||||
## Zones — `/zones`
|
||||
|
||||
```json
|
||||
{
|
||||
"preset_ids": ["1", "2"],
|
||||
"save": true,
|
||||
"default": "1",
|
||||
"destination_mac": "aabbccddeeff"
|
||||
}
|
||||
```
|
||||
|
||||
- **`preset_ids`** (or **`ids`**): non-empty list of preset ids to include.
|
||||
- **`save`**: if true, the outgoing message includes `"save": true` so the driver may persist presets (default true).
|
||||
- **`default`**: optional preset id string; forwarded as top-level `"default"` in the driver message (startup selection on device).
|
||||
- **`destination_mac`** (or **`to`**): optional 12-character hex MAC for unicast; omitted uses the transport default (e.g. broadcast).
|
||||
|
||||
Response on success includes `presets_sent`, `messages_sent` (chunking splits payloads so each JSON string stays ≤ 240 bytes).
|
||||
|
||||
Stored preset records can include:
|
||||
|
||||
- `colors`: resolved hex colours for editor/display.
|
||||
- `palette_refs`: optional array of palette indexes parallel to `colors`. If a slot contains an integer index, the colour is linked to the current profile palette at that index.
|
||||
|
||||
### 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).
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/zones` | `zones` (map of zone id → zone object), `zone_order`, `current_zone_id`, `profile_id` for the session-backed profile. |
|
||||
| GET | `/zones/current` | Current zone from cookie/session. |
|
||||
| POST | `/zones` | Create zone; optional JSON `name`, `names`, `presets`; can append to current profile’s zone list. |
|
||||
| GET | `/zones/<id>` | Zone JSON. |
|
||||
| PUT | `/zones/<id>` | Update zone. |
|
||||
| DELETE | `/zones/<id>` | Delete zone; can delete `current` to remove the active zone; updates profile zone list. |
|
||||
| POST | `/zones/<id>/set-current` | Sets `current_zone` cookie. |
|
||||
| POST | `/zones/<id>/clone` | Clone zone into current profile. |
|
||||
| POST | `/zones/<id>/play` | Body **`{"preset_id": "16", "drivers": true}`**. Runs the preset on every target in the zone through the Pi engine: pixel **outputs** are rendered on the Pi, ESP32 drivers get the preset + `select` (skipped when **`drivers`** is `false`; the UI sends to drivers itself and passes `false`). Stops any sequence on the zone. Returns the zone's player status. |
|
||||
| POST | `/zones/<id>/stop` | Stops the zone's sequence and Pi rendering (pixel outputs go black). ESP32 drivers keep their current preset. |
|
||||
| GET | `/zones/engine/status` | Engine state: `zones` (per-zone player: preset, pattern, error, per-output frame/packet/error counters) and `sequences`. |
|
||||
| GET | `/zones` | `{"zones": {...all zones}, "zone_order": [current profile's zone ids], "current_zone_id", "profile_id"}` |
|
||||
| GET | `/zones/current` | `{"zone": {...}, "zone_id": "<id>"}`, or 404 `{"error", "zone": null, "zone_id": null}` |
|
||||
| GET | `/zones/<id>` | One zone |
|
||||
| POST | `/zones` | Create (body: `name` required, `names` or `ids`, `group_ids`, `presets`, `content_kind`, ...). Added to the current profile's zone list. 201 |
|
||||
| PUT | `/zones/<id>` | Merge fields |
|
||||
| DELETE | `/zones/<id>` | Delete (`current` works as an id) and remove it from every profile. Clears the cookie if it was current |
|
||||
| POST | `/zones/<id>/set-current` | Set the `current_zone` cookie |
|
||||
| POST | `/zones/<id>/clone` | Copy into the current profile. Body: optional `name` (default `<name> Copy`). 201 |
|
||||
| GET | `/zones/<id>/content-fragment` | With `HX-Request`: the zone's tab content (HTML); otherwise the main page |
|
||||
| POST | `/zones/<id>/play` | Body `{"preset_id", "drivers"?}`: upload the preset to the zone's groups and select it (`drivers: false` skips sending). 404 for an unknown zone or preset |
|
||||
| POST | `/zones/<id>/stop` | Select `off` on the zone's groups. `{"stopped": bool}` |
|
||||
| GET | `/zones/engine/status` | Sequence playback status (as `/sequences/status`) |
|
||||
|
||||
### Palettes — `/palettes`
|
||||
## Groups — `/groups`
|
||||
|
||||
A group lists drivers by MAC (`devices`) and carries `output_brightness` (0–255), driver defaults (`wifi_driver_display_name`, `wifi_driver_num_leds`, `wifi_color_order`, `wifi_startup_mode`) and pattern fields. MACs are normalised to 12 lowercase hex digits. A driver's group membership is every group listing its MAC (see Driver groups), sent to it whenever groups, zones or devices change.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/palettes` | Map of id → colour list. |
|
||||
| GET | `/groups` | Groups visible in the current profile |
|
||||
| GET | `/groups/<id>` | One group (404 when scoped to another profile) |
|
||||
| POST | `/groups` | Create with defaults; `profile_scoped: true` ties it to the current profile, `profile_id` may only name the current profile or be null. Reply: the group, 201 |
|
||||
| PUT | `/groups/<id>` | Merge fields |
|
||||
| DELETE | `/groups/<id>` | Delete |
|
||||
| POST | `/groups/<id>/brightness` | Each member gets its combined brightness, saved on the driver. `{"message", "sent", "errors": [{mac, error}]}` |
|
||||
| POST | `/groups/<id>/driver-config` | Each member gets `device_config` from the group's driver defaults (body fields override for this send). 400 when none is set |
|
||||
| POST | `/groups/<id>/identify` | All members blink red together for 2 s, then go off. 400 when the group has no devices |
|
||||
|
||||
**Combined brightness** for a driver: `round(255 × global/255 × g₁/255 × … × device/255 [× zone/255])`, with one factor per group listing it (`output_brightness`), the device's `output_brightness` and, when given, the zone slider.
|
||||
|
||||
## Devices — `/devices`
|
||||
|
||||
A device is `{id: MAC, name, type: "led", transport: "espnow" | "wifi", address, default_pattern, zones, output_brightness?}`. ESP-NOW drivers register themselves when they boot (announce) and when they answer a ping. For ESP-NOW devices `address` is the MAC. The controller has no Wi-Fi driver transport: Wi-Fi records are kept, but nothing is sent to them.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/devices` | All devices, each with `connected` (`null` for ESP-NOW, `false` for Wi-Fi) |
|
||||
| GET | `/devices/<id>` | One device (the id may be written with colons) |
|
||||
| POST | `/devices` | Create. `name` required; `mac` (or, for ESP-NOW, a MAC in `address`); `transport` `espnow` (default) or `wifi`. Reply `{"<mac>": device}`, 201; 409 for a MAC already registered |
|
||||
| PUT | `/devices/<id>` | Merge fields. `name` cannot be blank, the MAC cannot change, `output_brightness` 0–255. Changing `max_brightness`, `num_leds`, `color_order`, `startup_mode` or `reversed` also sends them to the driver as `device_config` |
|
||||
| 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/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"}` |
|
||||
| POST | `/devices/<id>/driver-config` | Body: any of `name`, `num_leds` (1–2048), `color_order`, `startup_mode` (`default`, `last`, `off`) |
|
||||
| POST | `/devices/<id>/identify` | Red 10 Hz blink for 2 s, then off |
|
||||
|
||||
## Sequences — `/sequences`
|
||||
|
||||
A sequence is `{name, profile_id, lanes: [[step, ...], ...], lanes_group_ids: [[group ids], ...], group_ids, loop (default true), advance_mode: "beats", steps, step_duration_ms, sequence_transition}`. A step is `{preset_id, beats (default 1), group_ids?}`.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/sequences` | The current profile's sequences |
|
||||
| GET | `/sequences/<id>` | One sequence |
|
||||
| POST | `/sequences` | Create in the current profile. A non-empty `steps` without lanes becomes lane 0. Reply `{"<id>": sequence}`, 201 |
|
||||
| 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/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) |
|
||||
| POST | `/sequences/import` | Body: a sequence bundle. The presets are copied into the current profile and the steps point at the copies. 201 |
|
||||
|
||||
**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.** 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.
|
||||
- **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.
|
||||
- **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}`.
|
||||
|
||||
## Audio — `/api/audio`
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/api/audio/status` | `{"status": {...}}`, see below |
|
||||
| GET | `/api/audio/events` | Server-sent events, `data: {"type": "status" | "beat", "status": {...}}`: a status event first, one on every detected beat, and a status heartbeat every 0.5 s |
|
||||
| POST | `/api/audio/start` | Mic beats time sequences and go to the drivers. Saved. `{"ok": true, "status"}` |
|
||||
| POST | `/api/audio/stop` | The beat clock times sequences instead; the mic's beats stop going to the drivers. Saved |
|
||||
| POST | `/api/audio/reset` | Forget the tempo and bar position and track again (409 while stopped) |
|
||||
| POST | `/api/audio/anchor-bar` | Make the last beat bar beat 1 (409 while stopped) |
|
||||
| GET | `/api/audio/devices` | The single input: `{"devices": [{"id": "i2s", "name", "display_name", "is_default": true}], "diagnostics": {}}` |
|
||||
| PUT | `/api/audio/device` | Body `{"device_select"}`: stored only (there is one microphone) |
|
||||
|
||||
Status fields: `running` (audio timing on), `bpm` (locked tempo, `null` without a lock, the clock's tempo while stopped), `bpm_simulated`, `beat_seq`, `bar_beat`, `beats_per_bar`, `is_downbeat`, `bar_phase_readout`, `phase_confidence`, `input_level`, `last_beat_ts`, `sequence` (playback status), `sequence_pending`, `beat_readout`, `sequence_switch_wait` (in effect) and `sequence_switch_wait_saved`, `audio_simulated_bpm`, `simulated_beat_tick`, `audio_run`, `beat_phase_ms`, `input_volume`.
|
||||
|
||||
The `/audio` page uses its own routes:
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/audio.wav` | Live microphone audio (16 kHz mono WAV stream; one listener at a time) |
|
||||
| GET | `/beats` | Server-sent events: `beat` (`bpm`, `n`, `bar`, `meter`, `sure`, `us`), `onset`, and `tempo` every second |
|
||||
| POST | `/tap` | The user tapped bar beat 1 now |
|
||||
| GET | `/time` | Board clock (`{"us": ...}`) for the page to line its clock up with |
|
||||
|
||||
## Patterns — `/patterns`
|
||||
|
||||
Pattern metadata is the `pattern` collection, keyed by name. Pattern sources are the led-driver `src/patterns/*.py` files built into the firmware, plus uploads (stored on the controller, and they take precedence). `on` and `off` are built into the driver and have no file.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/patterns`, `/patterns/definitions` | Metadata, plus `{}` for every pattern file without metadata |
|
||||
| GET | `/patterns/<name>` | Metadata record |
|
||||
| POST | `/patterns` | Body `{name, data: {...}, ...}`: `data` and the other keys become the record under `name`. Reply: the record, 201 |
|
||||
| PUT, DELETE | `/patterns/<name>` | Merge, delete (the file stays) |
|
||||
| GET | `/patterns/ota/manifest` | `{"files": [{"name": "x.py", "url": "http://<Host>/patterns/ota/file/x.py"}]}` |
|
||||
| GET | `/patterns/ota/file/<name>.py` | The source (`text/plain`); 400 for `on`/`off`, 404 when missing |
|
||||
| POST | `/patterns/upload` | Body `{name, code, overwrite?}`: store a source. 409 when it exists and `overwrite` is false. 201 |
|
||||
| POST | `/patterns/driver` | Body `{name, code, overwrite?, min_delay?, max_delay?, max_colors?, n1?..n8?}`: store the source and its metadata (`n1`–`n8` are parameter labels). The name must be an identifier. 201 |
|
||||
| POST | `/patterns/<name>/send` | Push the source over ESP-NOW to one driver (`{"device_id"}`) or every ESP-NOW driver, as `patterns/<name>.py`; drivers that wrote it reset to load it. `{"message", "pattern", "device_ids", "sent_count", "results"}`; 503 when none took it |
|
||||
| POST | `/devices/<id>/patterns/push` | 400: use `/patterns/<name>/send` |
|
||||
|
||||
## Palettes — `/palettes`
|
||||
|
||||
A palette is a list of colours.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/palettes` | `{id: [colours]}` |
|
||||
| GET | `/palettes/<id>` | `{"colors": [...], "id": "<id>"}` |
|
||||
| POST | `/palettes` | Body may include `colors`. Returns palette object with `id`, 201. |
|
||||
| PUT | `/palettes/<id>` | Update colours (`name` ignored). |
|
||||
| DELETE | `/palettes/<id>` | Delete palette. |
|
||||
| POST | `/palettes` | Body `{"colors"}`. Reply `{"id", "colors"}`, 201 |
|
||||
| PUT | `/palettes/<id>` | Body `{"colors"}`: replaces the list |
|
||||
| DELETE | `/palettes/<id>` | Delete |
|
||||
|
||||
### Groups — `/groups`
|
||||
## Scenes — `/scenes`
|
||||
|
||||
Plain records: GET (list, one), POST (201), PUT (merge), DELETE. Scenes do not play.
|
||||
|
||||
## Outputs — `/outputs`
|
||||
|
||||
Network pixel fixtures. An output is `{id, name, protocol: "ddp" | "artnet" | "sacn" | "dmx_serial", host, port, universe, channel, serial_port, dmx_mode, pixel_count, pixel_offset, color_order, reverse, brightness, fps, enabled}` with defaults filled in. The checks:
|
||||
- `ddp` needs a `host`. `dmx_serial` needs a `serial_port`, and its pixels must fit one DMX universe.
|
||||
- Number ranges: `port` 1–65535, `universe` 0–32767 (sACN 1–63999), `channel` 1–512, `brightness` 0–255, `fps` 1–120.
|
||||
- `color_order` is one of `rgb rbg grb gbr brg bgr`.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/groups` | All groups. |
|
||||
| GET | `/groups/<id>` | One group. |
|
||||
| POST | `/groups` | Create; optional `name` and fields. |
|
||||
| PUT | `/groups/<id>` | Update. |
|
||||
| DELETE | `/groups/<id>` | Delete. |
|
||||
| GET | `/outputs`, `/outputs/<id>` | List, one |
|
||||
| POST | `/outputs` | Create (400 with the failed check). Reply: the output, 201 |
|
||||
| PUT | `/outputs/<id>` | Merge and check again |
|
||||
| DELETE | `/outputs/<id>` | Delete |
|
||||
| POST | `/outputs/<id>/test` | Body `{"step_s": 0.1–5}` (default 1): solid red, green, blue and white for `step_s` each at `fps`, then black. `{"message", "status": {name, protocol, kind, pixel_count, frames, packets, bytes, errors, last_error}}`. 503 for `dmx_serial` (no USB-DMX adapter on this board) |
|
||||
|
||||
### Scenes — `/scenes`
|
||||
Zones do not render to outputs: only the test pattern is sent.
|
||||
|
||||
## WebSocket — `/ws`
|
||||
|
||||
On connect the controller sends `{"type": "device_tcp_snapshot", "connected_ips": []}` (there are no Wi-Fi driver sessions). Each text frame is a driver message (JSON object), sent as `/presets/push` would send it: an optional `to` (MAC) addresses one driver, otherwise it is broadcast. A frame that is not a JSON object, or a failed send, gets `{"error": ...}` back. A plain GET gets 426.
|
||||
|
||||
## Driver app update — `/drivers/ota`
|
||||
|
||||
Pushes led-driver `.py` files to ESP-NOW drivers, one file per request; `tools/driver_ota.py` (`make ota-drivers`) runs a whole session. The wire format is in `led-driver/src/espnow_ota.py`. One request runs at a time; another gets 409.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/scenes` | All scenes. |
|
||||
| GET | `/scenes/<id>` | One scene. |
|
||||
| POST | `/scenes` | Create (body JSON stored on scene). |
|
||||
| PUT | `/scenes/<id>` | Update. |
|
||||
| DELETE | `/scenes/<id>` | Delete. |
|
||||
|
||||
### Scene playback
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| POST | `/scenes/<id>/play` | Starts every sequence listed in the scene's `sequences`. Returns `started` ids and per-sequence `errors`. |
|
||||
| POST | `/scenes/<id>/stop` | Stops the scene's sequences. |
|
||||
|
||||
### Sequences — `/sequences`
|
||||
|
||||
Timed preset chains for one zone, run by the Pi engine (hard cuts). Stored in **`db/sequence.json`**:
|
||||
|
||||
```json
|
||||
{"name": "Showcase", "zone_id": "2", "loop": true, "repeat_count": 0,
|
||||
"steps": [{"preset_id": "16", "duration_s": 8}, {"preset_id": "17", "duration_s": 8}],
|
||||
"active": false}
|
||||
```
|
||||
|
||||
`duration_s` is clamped to 0.5–600 (default 5). `repeat_count` counts passes when `loop` is true (0 = forever). `active` is maintained by the engine; active sequences resume after a restart. Legacy records (`group_name`, `presets`, `sequence_duration` in ms) are migrated on load.
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/sequences` | All sequences. |
|
||||
| GET | `/sequences/status` | Runtime state per sequence: `zone_id`, `step_index`, `preset_id`, `pass`, `next_at`, `running`, optional `error`. |
|
||||
| GET | `/sequences/<id>` | One sequence. |
|
||||
| POST | `/sequences` | Create (body as above). 400 on invalid steps. |
|
||||
| PUT | `/sequences/<id>` | Update (merged, then re-validated). |
|
||||
| DELETE | `/sequences/<id>` | Stop if running, then delete. |
|
||||
| POST | `/sequences/<id>/play` | Start on its zone; replaces a sequence already running there. 400 without `zone_id`/steps. |
|
||||
| POST | `/sequences/<id>/stop` | Stop; the zone keeps its current preset. |
|
||||
|
||||
Picking a preset manually on a zone (`/zones/<id>/play`) stops that zone's sequence.
|
||||
|
||||
### Outputs — `/outputs`
|
||||
|
||||
Pixel outputs the Pi renders frames for, stored in **`db/output.json`**. A zone drives an output when the output's **`name`** appears in the zone's `names` (the same list that holds ESP32 device names).
|
||||
|
||||
| Field | Notes |
|
||||
|-------|-------|
|
||||
| `name` | Matched against zone `names`. |
|
||||
| `protocol` | `ddp` (UDP 4048), `artnet` (ArtDMX, UDP 6454), `sacn` (E1.31, UDP 5568), `dmx_serial` (USB-DMX). |
|
||||
| `host`, `port` | Network outputs. `ddp` needs a host; Art-Net without host broadcasts; sACN without host uses multicast `239.255.<hi>.<lo>`. Blank port = protocol default. |
|
||||
| `universe` | Art-Net/sACN start universe (sACN 1–63999). 170 RGB pixels per universe; consecutive universes are used for longer strips. |
|
||||
| `serial_port`, `dmx_mode`, `channel` | USB-DMX: `enttec_pro` (Enttec DMX USB Pro) or `open_dmx` (FTDI); start channel 1–512; one universe max. |
|
||||
| `pixel_count`, `pixel_offset` | Pixels this output takes from the zone frame, starting at `pixel_offset`. Outputs at offset 0 mirror the frame start. |
|
||||
| `color_order`, `reverse`, `brightness`, `fps`, `enabled` | Per-output wiring order, direction, 0–255 brightness (× global brightness), frame-rate cap (default 40). |
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/outputs` | All outputs. |
|
||||
| GET | `/outputs/<id>` | One output. |
|
||||
| POST | `/outputs` | Create; 400 with `error` on validation failure. |
|
||||
| PUT | `/outputs/<id>` | Update. |
|
||||
| DELETE | `/outputs/<id>` | Delete. |
|
||||
| POST | `/outputs/<id>/test` | Sends red, green, blue, white (optional body `step_s`, default 1 s each) then black. Returns per-output counters. |
|
||||
|
||||
### Patterns — `/patterns`
|
||||
|
||||
Pattern metadata lives in **`db/pattern.json`**; driver source files live under **`led-driver/src/patterns/`**. Several routes expose a **runtime map** (metadata merged with on-disk `.py` names so new files appear in menus).
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/patterns` | Runtime pattern map (object keyed by pattern id). |
|
||||
| GET | `/patterns/definitions` | Same runtime map (intended for UI “definitions” clients). |
|
||||
| GET | `/patterns/ota/manifest` | JSON `{"files":[{"name":"blink.py","url":"http://<Host>/patterns/ota/file/blink.py"},...]}` for OTA pulls. Requires **`Host`** header. |
|
||||
| GET | `/patterns/ota/file/<name>` | Raw **`.py`** source for one driver pattern (`name` must be a safe filename, e.g. `rainbow.py`). |
|
||||
| POST | `/patterns/<name>/send` | Push a **manifest** JSON line to **Wi-Fi** devices so they pull one pattern file over HTTP. Body may include **`device_id`** to target one device; otherwise all Wi-Fi devices with an **`address`** are tried. **`<name>`** may be with or without `.py`. |
|
||||
| POST | `/patterns/upload` | Body JSON: **`name`**, **`code`**, optional **`overwrite`** (default true). Writes **`led-driver/src/patterns/<name>.py`**. |
|
||||
| POST | `/patterns/driver` | Body JSON: **`name`** (identifier), **`code`**, optional metadata (`min_delay`, `max_delay`, `max_colors`, `n1`…`n8`, **`overwrite`**). Creates/updates both the **`.py`** file and **`db/pattern.json`** via the Pattern model. |
|
||||
| GET | `/patterns/<id>` | One pattern record from the Pattern model (metadata only). |
|
||||
| POST | `/patterns` | Create (`name`, optional `data`). |
|
||||
| PUT | `/patterns/<id>` | Update. |
|
||||
| DELETE | `/patterns/<id>` | Delete. |
|
||||
|
||||
**Devices — pattern OTA push**
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| POST | `/devices/<id>/patterns/push` | Wi-Fi only. Asks the driver at **`address`** to pull pattern files from this server. Optional body **`manifest`**: either a **URL string** pointing at a manifest JSON document, or a **manifest object** (same shape as in driver messages). If omitted, a default manifest is built from the request **`Host`** header. |
|
||||
| POST | `/drivers/ota/file?mac=<macs>&sess=<n>&path=<p>&sha=<64 hex>` | Body: the raw file (up to 65536 bytes). `mac` is a comma-separated list of MACs, or `all` for every ESP-NOW device. `sess` (1–65535) is shared by every file of one update. `path` is the driver path: a root file, `patterns/…` or `lib/…`. Drivers that already have that sha256 skip it. One target gets acked unicast. Several get one broadcast, then each is asked for its missing chunks and repaired. The file is staged until commit. Reply: `{"<mac>": {"result": "same" | "written" | "error", "code"?, "repaired": n}}` |
|
||||
| POST | `/drivers/ota/commit?mac=<macs>&sess=<n>` | Drivers move their staged files into place, update `file_hashes.json` and reset if anything changed |
|
||||
| POST | `/drivers/ota/abort?mac=<macs>&sess=<n>` | Drivers delete their staged files |
|
||||
|
||||
---
|
||||
|
||||
## LED driver message format (transport / ESP-NOW / Wi-Fi)
|
||||
## Driver messages
|
||||
|
||||
Messages are JSON objects. The Pi **`build_message()`** helper (`src/util/espnow_message.py`) produces the same shape sent over serial and forwarded by the ESP32 bridge, and the same logical object can be sent as a **single JSON text message** to a Wi-Fi driver over the **WebSocket**.
|
||||
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`).
|
||||
- **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.
|
||||
|
||||
### Top-level fields
|
||||
### Fields
|
||||
|
||||
| Long key | Short | Meaning |
|
||||
|----------|-------|---------|
|
||||
| `presets` | `p` | Map of preset id → preset |
|
||||
| `select` | `s` | `["preset_id"]` or `["preset_id", step]` for every driver addressed; or a map of driver name → that list |
|
||||
| `groups` | `g` | Only drivers in one of these groups apply the message |
|
||||
| `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` |
|
||||
| `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.
|
||||
|
||||
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.
|
||||
|
||||
### Driver groups
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
### Example
|
||||
|
||||
```json
|
||||
{
|
||||
"v": "1",
|
||||
"presets": { },
|
||||
"select": { },
|
||||
"save": true,
|
||||
"default": "preset_id",
|
||||
"b": 255
|
||||
}
|
||||
```
|
||||
|
||||
- **`v`** (required): Must be `"1"` or the driver ignores the message.
|
||||
- **`presets`**: Map of **preset id** (string) → preset object (see below). Optional **`name`** field on each value is accepted for display; the driver keys presets by map key.
|
||||
- **`select`**: Map of **device name** (as in device settings) → `[ "preset_id" ]` or `[ "preset_id", step ]`.
|
||||
- **`save`**: If present (e.g. true), the driver may persist presets to flash after applying.
|
||||
- **`default`**: Preset id string to use as startup default on the device.
|
||||
- **`b`**: Optional **global** brightness 0–255 (driver applies this in addition to per-preset brightness).
|
||||
|
||||
### Preset object (wire / driver keys)
|
||||
|
||||
On the wire, presets use **short keys** (saves space in the ≤240-byte chunks):
|
||||
|
||||
| Key | Meaning | Notes |
|
||||
|-----|---------|--------|
|
||||
| `p` | Pattern id | `off`, `on`, `blink`, `rainbow`, `pulse`, `transition`, `chase`, `circle` |
|
||||
| `c` | Colours | Array of `"#RRGGBB"` hex strings; converted to RGB on device |
|
||||
| `d` | Delay ms | Default 100 |
|
||||
| `b` | Preset brightness | 0–255; combined with global `b` on the device |
|
||||
| `a` | Auto | `true`: run continuously; `false`: one step/cycle per “beat” |
|
||||
| `n1`–`n6` | Pattern parameters | See below |
|
||||
|
||||
The HTTP app’s **`POST /presets/send`** path builds this from stored presets via **`build_preset_dict()`** (long names like `pattern` / `colors` in the DB are translated to `p` / `c` / …).
|
||||
|
||||
### Pattern-specific parameters (`n1`–`n6`)
|
||||
|
||||
#### Rainbow
|
||||
- **`n1`**: Step increment on the colour wheel per update (default 1).
|
||||
|
||||
#### Pulse
|
||||
- **`n1`**: Attack (fade in) ms
|
||||
- **`n2`**: Hold ms
|
||||
- **`n3`**: Decay (fade out) ms
|
||||
- **`d`**: Off time between pulses ms
|
||||
|
||||
#### Transition
|
||||
- **`d`**: Transition duration ms
|
||||
|
||||
#### Chase
|
||||
- **`n1`**: LEDs with first colour
|
||||
- **`n2`**: LEDs with second colour
|
||||
- **`n3`**: Movement on even steps (may be negative)
|
||||
- **`n4`**: Movement on odd steps (may be negative)
|
||||
|
||||
#### Circle
|
||||
- **`n1`**: Head speed (LEDs/s)
|
||||
- **`n2`**: Max length
|
||||
- **`n3`**: Tail speed (LEDs/s)
|
||||
- **`n4`**: Min length
|
||||
|
||||
### Select messages
|
||||
|
||||
```json
|
||||
{
|
||||
"select": {
|
||||
"device_name": ["preset_id"],
|
||||
"other_device": ["preset_id", 10]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- One element: select preset; step behavior follows driver rules (reset on `off`, etc.).
|
||||
- Two elements: explicit **step** for sync.
|
||||
|
||||
### Beat and sync behavior
|
||||
|
||||
- Sending **`select`** again with the **same** preset name acts as a **beat** (advances manual patterns / restarts generators per driver logic).
|
||||
- Choosing **`off`** resets step as a sync point; then selecting a pattern aligns step 0 across devices unless a step is passed explicitly.
|
||||
|
||||
### Example (compact preset map)
|
||||
|
||||
```json
|
||||
{
|
||||
"v": "1",
|
||||
"save": true,
|
||||
"presets": {
|
||||
"1": {
|
||||
"name": "Red blink",
|
||||
"p": "blink",
|
||||
"c": ["#FF0000"],
|
||||
"d": 200,
|
||||
"b": 255,
|
||||
"a": true,
|
||||
"n1": 0, "n2": 0, "n3": 0, "n4": 0, "n5": 0, "n6": 0
|
||||
}
|
||||
"12": {"pattern": "chase", "colors": ["#ff0000", "#0000ff"], "delay": 80, "brightness": 255, "auto": true, "n1": 4, "n2": 4}
|
||||
},
|
||||
"select": {
|
||||
"living-room": ["1"]
|
||||
}
|
||||
"select": ["12"],
|
||||
"groups": ["3"],
|
||||
"save": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Processing summary (driver)
|
||||
|
||||
1. Reject if `v != "1"`.
|
||||
2. Apply optional top-level **`b`** (global brightness).
|
||||
3. For each entry in **`presets`**, normalize colours and upsert preset by id.
|
||||
4. If this device’s **`name`** appears in **`select`**, run selection (optional step).
|
||||
5. If **`default`** is set, store startup preset id.
|
||||
6. If **`save`** is set, persist presets.
|
||||
|
||||
---
|
||||
|
||||
## Error handling (HTTP)
|
||||
|
||||
Controllers typically return JSON with an **`error`** string and 4xx/5xx status codes. Invalid JSON bodies often yield `{"error": "Invalid JSON"}`.
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Human-readable preset fields** (`pattern`, `colors`, `delay`, …) are fine in the **web app / database**; the **send path** converts them to **`p` / `c` / `d`** for the driver.
|
||||
- For a copy of the older long-key reference, see **`led-driver/docs/API.md`** in this repo (conceptually the same behavior; wire format prefers short keys).
|
||||
Pattern parameters are documented in the led-driver repository.
|
||||
Reference in new issue
Block a user