tools/driver_ota.py (make ota-drivers) pushes the driver's .py files through the controller, one file per POST /drivers/ota/file. Drivers skip files they already have, and the rest are committed together. - one target: acked unicast, two chunks in flight - several targets: each file is broadcast once, then each driver is asked for its missing chunks and repaired by unicast - rel: rel_send_seq, rel_wait and rel_send_wait, plus a callback for the drivers' 0x26 status replies - commands are retried, because status replies are not acked - broadcast chunks are paced 50 ms apart: faster broadcast left C3 drivers unable to receive until reset - bench results in docs/BENCH_TEST.md, endpoints in docs/API.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
418 lines
22 KiB
Markdown
418 lines
22 KiB
Markdown
# LED Controller API
|
||
|
||
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).
|
||
|
||
Default HTTP listen address: `0.0.0.0`. Port defaults to **80**; override with the **`PORT`** environment variable (see `pipenv run run`).
|
||
|
||
**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).
|
||
|
||
All JSON APIs use `Content-Type: application/json` for bodies and responses unless noted.
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
| 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/` |
|
||
|
||
---
|
||
|
||
## 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`.
|
||
|
||
| 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. |
|
||
|
||
### Settings — `/settings`
|
||
|
||
| 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`. |
|
||
|
||
### 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).
|
||
|
||
| 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. |
|
||
|
||
### Profiles — `/profiles`
|
||
|
||
| 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. |
|
||
|
||
### Presets — `/presets`
|
||
|
||
Scoped to **current profile** in session (see above).
|
||
|
||
| 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). |
|
||
|
||
**`POST /presets/send` body:**
|
||
|
||
```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`
|
||
|
||
| 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`. |
|
||
|
||
### Palettes — `/palettes`
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| GET | `/palettes` | Map of id → colour list. |
|
||
| 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. |
|
||
|
||
### Groups — `/groups`
|
||
|
||
| 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. |
|
||
|
||
### Scenes — `/scenes`
|
||
|
||
| 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. |
|
||
|
||
---
|
||
|
||
## LED driver message format (transport / ESP-NOW / Wi-Fi)
|
||
|
||
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**.
|
||
|
||
### Top-level fields
|
||
|
||
```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
|
||
}
|
||
},
|
||
"select": {
|
||
"living-room": ["1"]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 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).
|