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>
119 lines
6.7 KiB
Markdown
119 lines
6.7 KiB
Markdown
# LED controller — user guide
|
||
|
||
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 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.
|
||
|
||
---
|
||
|
||
## 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**.
|
||
|
||

|
||
|
||
| Mode | Purpose |
|
||
|------|--------|
|
||
| **Run mode** | Day-to-day control: choose a zone, tap presets, apply profiles. Management buttons are hidden. |
|
||
| **Edit mode** | Full setup: devices, groups, zones, presets, sequences, outputs, patterns, colour palette and settings, plus per-tile **Edit** on the strip. |
|
||
|
||
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 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
|
||
|
||
The **Presets** button (Edit mode) opens the profile's presets: **Add**, **Edit**, **Send**, **Delete**, plus **Import** and **Export** (a preset as a JSON file).
|
||
|
||

|
||
|
||
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** 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.
|
||
|
||
---
|
||
|
||
## Devices and groups
|
||
|
||
- **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
|
||
|
||
**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.
|
||
|
||
---
|
||
|
||
## Audio
|
||
|
||
- 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, outputs and palette
|
||
|
||
- **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.
|
||
|
||

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

|
||
|
||
---
|
||
|
||
## Further reading
|
||
|
||
- **[API.md](API.md)**: HTTP routes, the WebSocket `/ws`, and the driver message format.
|
||
- **README**: building, flashing and updating the controller and drivers.
|