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:
jimmyandClaude Opus 5.5 committed 2026-11-03 20:42:03 +13:00
1 parent bfeeb958df
commit b2cd242390
5 files changed
+335 -429

No files matched your search

+56 -67
View File
@@ -1,8 +1,8 @@
# LED controller — user guide
This page describes the **main web UI** served from the Raspberry Pi app: profiles, **zones**, presets, colour palettes, and sending commands to LED devices. Traffic may go over the **serial → ESP-NOW bridge** or **Wi-Fi** (TCP to drivers on the LAN), depending on each device’s transport.
This page describes the web UI served by the controller (an ESP32-S3 on Ethernet). It covers profiles, zones, presets, device groups, sequences and audio. The controller reaches the LED drivers over ESP-NOW itself, so there is no bridge to set up.
For HTTP routes and the wire format the driver expects, see **[API.md](API.md)**. For running the app locally, see the project **README**.
For HTTP routes and the driver message format, see **[API.md](API.md)**. For building and flashing, see the project **README**.
Figures below are **schematic** (layout and ideas), not pixel-perfect screenshots.
@@ -10,120 +10,109 @@ Figures below are **schematic** (layout and ideas), not pixel-perfect screenshot
## Run mode and Edit mode
The header has a mode toggle (desktop and mobile menu). The **label on the button is the mode you switch to** when you press it.
The header has a mode toggle (desktop and mobile menu). The **label on the button is the mode you switch to**.
![Schematic: zone buttons on the left; Profiles, Zones, Presets, Patterns, and the mode toggle on the right (example shows Edit mode with “Run mode” on the button).](images/help/header-toolbar.svg)
*The active zone is highlighted. Extra management buttons appear only in Edit mode.*
![Schematic: zone buttons on the left; management buttons and the mode toggle on the right.](images/help/header-toolbar.svg)
| Mode | Purpose |
|------|--------|
| **Run mode** | Day-to-day control: choose a zone, tap presets, apply profiles. Management buttons are hidden. |
| **Edit mode** | Full setup: zones, presets, patterns, outputs, sequences, colour palette, **Send Presets**, profile create/clone/delete, preset reordering, and per-tile **Edit** on the strip. |
| **Edit mode** | Full setup: devices, groups, zones, presets, sequences, outputs, patterns, colour palette and settings, plus per-tile **Edit** on the strip. |
**Profiles** is available in both modes: in Run mode you can only **apply** a profile; in Edit mode you can also **create**, **clone**, and **delete** profiles.
On narrow screens, **Menu** reaches the same actions as the desktop header.
---
## Zones
- **Select a zone**: click its button in the top bar. The main area shows that zone’s preset strip and controls.
- **Edit mode — open zone settings**: **right-click** a zone button to change its name, **device IDs** (comma-separated), and which presets appear on the zone. Device identifiers are matched to each device’s **name** when the app builds `select` messages for the driver.
- **Zones modal** (Edit mode): create new zones from the header **Zones** button. New zones need a name and device ID list (defaults to `1` if you leave a simple placeholder).
- **Brightness slider** (header, and in the mobile menu): adjusts the **global** brightness (0–255) sent to devices (`b` in the driver message), with a short debounce so small drags do not flood the link. The level is stored on the server (`global_brightness`) and re-sent to Wi-Fi drivers when they reconnect; the slider position is also remembered in your browser.
- **Search**: the Devices, Zones and Presets lists have a search box that hides non-matching rows as you type. It clears when you reopen the list or press **Esc**.
- **Select a zone**: click its button in the top bar. The main area shows the zone's preset strip.
- **Zones** (Edit mode): create and manage zones. A zone lists **device groups**, presets and sequences; presets and sequences can share a zone. **Right-click** a zone button for its settings.
- A zone plays to its device groups. Zones made before groups list drivers by **name** instead, and still work.
- **Brightness slider**: sets the brightness for the current zone. Each driver gets one value: global × its groups × the device × the zone.
- **Search**: the Devices, Zones and Presets lists have a search box that hides rows that do not match as you type.
![Schematic: zone title, brightness slider, and a row of preset tiles; Edit mode adds an Edit control and drag handles.](images/help/tab-preset-strip.svg)
Click the coloured part of a preset tile to select that preset on every driver in the zone. In Edit mode, drag tiles to reorder them, and use **Edit** and **Remove** on each tile.
---
## Presets on the zone strip
## Presets
- **Run and Edit mode**: click the **main part** of a preset tile to **select** that preset on all devices assigned to the current zone (same logical action as a `select` in the driver API).
- **Edit mode only**:
- **Edit** beside a tile opens the preset editor for that preset, scoped to the current zone (so you can **Remove from zone** without deleting the preset from the profile).
- **Drag and drop** tiles to reorder them; order is saved for that zone.
![Schematic: zone title, brightness slider, and a row of preset tiles; Edit mode adds an Edit control and drag handles for reordering.](images/help/tab-preset-strip.svg)
*The slider controls global brightness for the zone’s devices. Click the coloured area of a tile to select that preset.*
The **Presets** header button (Edit mode) opens a **profile-wide** list: **Add** new presets, **Edit**, **Send** (push definition over the transport), and **Delete** (removes the preset from the profile entirely).
---
## Preset editor
- **Pattern**: chosen from the dropdown; optional **n1–n8** fields depend on the pattern (see **Pattern-specific parameters** in [API.md](API.md)).
- **Colours**: choosing a value in the colour picker **adds** a swatch when the picker closes. Swatches can be **reordered** by dragging. Changing a swatch with the picker **clears** palette linkage for that slot.
- **From Palette**: inserts a colour **linked** to the current profile’s palette. Linked slots show a **P** badge; if you change that palette entry later, presets using it update.
- **Brightness (0–255)** and **Delay (ms)**: stored on the preset and sent with the compact preset payload.
- **Try**: sends the current form values to devices on the **current zone**, then selects that preset — **without** `save` on the device (good for auditioning).
- **Default**: updates the zone’s **default preset** and sends a **default** hint for those devices; it does not force the same live selection behaviour as clicking a tile.
- **Save & Send**: writes the preset to the server, then pushes definitions with **save** so devices may persist them. It does **not** auto-select the preset on devices (use the strip or **Try** if you want that).
- **Remove from zone** (when you opened the editor from a zone): removes the preset from **this zone’s list only**; the preset remains in the profile for other zones.
The **Presets** button (Edit mode) opens the profile's presets: **Add**, **Edit**, **Send**, **Delete**, plus **Import** and **Export** (a preset as a JSON file).
![Schematic: preset editor with name, pattern, colour swatches (one with a P badge for palette-linked), and action buttons.](images/help/preset-editor.svg)
*Try previews without persisting on the device; **Save & Send** stores the preset and pushes definitions with save.*
The preset editor:
- **Pattern** and its **n1–n8** parameters, colours, background, brightness and delay.
- **Manual** presets step once per beat instead of running freely.
- **From Palette** inserts a colour linked to the profile's palette (badge **P**). It follows the palette when the palette changes.
- **Try** previews on the current zone without saving on the drivers.
- **Save** stores the preset on the controller; **Send** pushes it to the drivers with save.
- **Remove from zone** (when opened from a zone) removes it from that zone only.
---
## Profiles
- **Apply**: sets the **current profile** in your session. Zones and presets you see are scoped to that profile.
- **Edit mode — Create**: new profiles always get a populated **default** zone. Optionally tick **DJ zone** to also create a `dj` zone (device name `dj`) with starter DJ-oriented presets.
- **Clone** / **Delete**: available in Edit mode from the profile list.
- **Apply** makes a profile current. Zones, presets and sequences you see belong to it.
- **Create** (Edit mode) gives a new profile a palette and a **default** zone with starter presets. Optionally tick **DJ zone** for a starter `dj` zone.
- **Clone** copies a profile with its own zones, presets and palette. **Delete** removes it with its presets and sequences.
- **Export** saves a profile with its zones, presets, sequences and palette as a JSON file. **Import** loads one as a new profile and applies it.
---
## Outputs (Edit mode)
## Devices and groups
Besides the ESP32 drivers, the Pi can render patterns itself and stream pixels to network or DMX fixtures. **Outputs** lists these fixtures; each has a **name**, a **protocol** (DDP, Art-Net, sACN/E1.31 or USB-DMX), its address (host/port, universe or serial port), pixel count and offset, colour order, brightness and frame rate. Use **Test** on an output to flash red, green, blue and white, then black.
To drive an output from a zone, add the output's **name** to the zone's device list (the same list used for ESP32 device names). Clicking a preset tile then renders it on the Pi for those outputs and still sends `select` to any ESP32 drivers in the zone.
- **Devices** (Edit mode) lists the LED drivers by MAC. Drivers appear by themselves when they boot or answer a ping; you can also add them by hand.
- **Ping drivers** checks which drivers answer (green dot with the round-trip time) and adds new ones.
- **Identify** blinks a driver red for two seconds.
- **Update groups** sends every driver its group membership.
- **Edit** a device for its name, brightness and driver settings (LED count, colour order, power-on pattern).
- **Groups** (Edit mode): put drivers in a group, set the group's brightness and driver defaults once, then attach the group to zones and sequence lanes.
- Groups are shared by every profile unless you tick **this profile only**.
- **Identify devices in group** blinks all members together.
---
## Sequences (Edit mode)
## Sequences
**Sequences** are timed chains of presets that play on one zone. Each step is a preset plus a duration (0.5–600 s); steps switch with hard cuts. Choose whether the sequence **loops** (and how many passes, 0 = forever), then **Play** or **Stop** it. Picking a preset by hand on that zone stops its sequence. Running sequences resume after the app restarts, and a **scene** can start every sequence it lists.
**Sequences** (Edit mode) are shows of presets in one or more **lanes**. Each lane plays to its own device group.
- **Steps.** A step is a preset and a number of beats. When a step's beats have passed, the lane moves to its next step. A sequence loops unless you turn looping off.
- **Playing.** Attach a sequence to a zone in the zone editor, then play it from the zone. One sequence plays at a time. Stopping a sequence clears its presets from the zone's drivers.
- **Switching.** Starting another sequence waits for the next beat, or the next downbeat when the header toggle says **Downbeat** and the microphone is timing.
- **Syncing.** Press **S** (or the BPM button) on a downbeat to line the sequence up with the music.
---
## Send Presets (Edit mode)
## Audio
**Send Presets** walks **every zone** in the **current profile**, collects each zone’s preset IDs, and calls **`POST /presets/send`** per zone (including each zone’s **default** preset when set). Use this to bulk-push definitions to hardware after editing, without clicking **Send** on every preset individually.
- The controller listens through its microphone and detects the tempo and the bar.
- While **Audio** is started, the microphone's beats time sequences and go to the drivers, so manual presets step on the music.
- While it is stopped, a clock at the **simulated BPM** does both instead.
- **Reset detector** forgets a stuck tempo. The **/audio** page has a full readout, a tap for beat 1 and a live listen.
---
## Patterns
## Patterns, outputs and palette
The **Patterns** dialog (Edit mode) lists pattern names and typical **delay** ranges from the pattern definitions. Choosing a pattern still happens inside the preset editor.
**Wi-Fi drivers** can install new pattern modules over HTTP: the REST API exposes **`/patterns/ota/*`**, **`POST /patterns/<name>/send`**, **`POST /patterns/upload`**, and **`POST /patterns/driver`** (see [API.md](API.md)). ESP-NOW devices follow the bridge/serial path you configure for preset traffic.
---
## Colour palette
**Colour Palette** (Edit mode) edits the **current profile’s** palette swatches. Those colours are reused by **From Palette** in the preset editor and stay in sync while the **P** link remains.
- **Patterns** (Edit mode) lists the patterns and their typical delays. **Send** pushes a pattern file to the drivers over ESP-NOW; they reset to load it. **Create pattern** uploads your own pattern file.
- **Outputs** (Edit mode) lists network pixel fixtures (DDP, Art-Net, sACN). **Test** flashes red, green, blue and white, then black. Zones do not drive outputs on this controller.
- **Colour Palette** (Edit mode) edits the current profile's swatches. Preset colours linked with **From Palette** update with it.
![Schematic: palette modal with a row of swatches for the current profile.](images/help/colour-palette.svg)
*Add or change swatches here; linked preset colours update automatically.*
---
## Mobile layout
## Settings
On narrow screens, use **Menu** to reach the same actions as the desktop header (Profiles, Zones, Presets, Outputs, Sequences, Help, mode toggle, brightness, etc.).
**Settings** (Edit mode) holds the controller's name, the ESP-NOW channel (for reference: the controller's channel is set at build time), its mDNS **hostname** and the **static IPs** it tries on the Ethernet link (DHCP when none answers). Network changes apply after a restart. Drivers are configured over USB with `led-cli` on a computer.
![Schematic: narrow layout with Menu and the same header actions in a dropdown.](images/help/mobile-menu.svg)
*Preset tiles behave the same once a zone is selected.*
---
## Further reading
- **[API.md](API.md)** — REST routes, session scoping, WebSocket `/ws`, and LED driver JSON (`presets`, `select`, `save`, `default`, pattern keys, pattern **manifest**).
- **README** — `pipenv run run`, port 80 setup, and high-level behaviour.
- **[API.md](API.md)**: HTTP routes, the WebSocket `/ws`, and the driver message format.
- **README**: building, flashing and updating the controller and drivers.