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
+56
-67
@@ -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**.
|
||||
|
||||

|
||||
|
||||
*The active zone is highlighted. Extra management buttons appear only in Edit mode.*
|
||||

|
||||
|
||||
| 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.
|
||||
|
||||

|
||||
|
||||
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.
|
||||
|
||||

|
||||
|
||||
*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).
|
||||
|
||||

|
||||
|
||||
*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.
|
||||
|
||||

|
||||
|
||||
*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.
|
||||
|
||||

|
||||
|
||||
*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.
|
||||
Reference in new issue
Block a user