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>
22 KiB
LED Controller API
This document covers:
- HTTP and WebSocket exposed by the Raspberry Pi app (
src/main.py) — profiles, zones, presets, transport send, pattern OTA helpers, and related resources. - 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:
{
"preset_ids": ["1", "2"],
"save": true,
"default": "1",
"destination_mac": "aabbccddeeff"
}
preset_ids(orids): non-empty list of preset ids to include.save: if true, the outgoing message includes"save": trueso 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(orto): 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 tocolors. 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:
{"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
{
"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). Optionalnamefield 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) msn2: Hold msn3: Decay (fade out) msd: Off time between pulses ms
Transition
d: Transition duration ms
Chase
n1: LEDs with first colourn2: LEDs with second colourn3: Movement on even steps (may be negative)n4: Movement on odd steps (may be negative)
Circle
n1: Head speed (LEDs/s)n2: Max lengthn3: Tail speed (LEDs/s)n4: Min length
Select messages
{
"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
selectagain with the same preset name acts as a beat (advances manual patterns / restarts generators per driver logic). - Choosing
offresets step as a sync point; then selecting a pattern aligns step 0 across devices unless a step is passed explicitly.
Example (compact preset map)
{
"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)
- Reject if
v != "1". - Apply optional top-level
b(global brightness). - For each entry in
presets, normalize colours and upsert preset by id. - If this device’s
nameappears inselect, run selection (optional step). - If
defaultis set, store startup preset id. - If
saveis 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 top/c/dfor the driver. - For a copy of the older long-key reference, see
led-driver/docs/API.mdin this repo (conceptually the same behavior; wire format prefers short keys).