Files
led-controller/docs/help.md
T

8.5 KiB
Raw Blame History

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.

For HTTP routes and the wire format the driver expects, see API.md. For running the app locally, 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 when you press it.

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

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.

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.


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.

Presets on the zone strip

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

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

Schematic: preset editor with name, pattern, colour swatches (one with a P badge for palette-linked), and action buttons.

Try previews without persisting on the device; Save & Send stores the preset and pushes definitions with save.


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.

Outputs (Edit mode)

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.


Sequences (Edit mode)

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.


Send Presets (Edit mode)

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.


Patterns

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

Schematic: palette modal with a row of swatches for the current profile.

Add or change swatches here; linked preset colours update automatically.


Mobile layout

On narrow screens, use Menu to reach the same actions as the desktop header (Profiles, Zones, Presets, Outputs, Sequences, Help, mode toggle, brightness, etc.).

Schematic: narrow layout with Menu and the same header actions in a dropdown.

Preset tiles behave the same once a zone is selected.


Further reading

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