# 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**. ![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: 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. ![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 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) 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. ![Schematic: palette modal with a row of swatches for the current profile.](images/help/colour-palette.svg) --- ## 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. ![Schematic: narrow layout with Menu and the same header actions in a dropdown.](images/help/mobile-menu.svg) --- ## 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.