led-controller

LED controller web app for managing profiles, zones, presets, and colour palettes, and sending commands to LED devices over ESP-NOW (peer-to-peer on 2.4 GHz Wi‑Fi radio).

• Bridge ESP32: routes Pi traffic to drivers. The Pi connects over WebSocket (bridge_transport: wifi, bridge_ws_url e.g. ws://192.168.4.1/ws) or USB serial (bridge_transport: serial, bridge_serial_port).
• LED drivers: announce on boot via ESP-NOW broadcast; the controller registers them (MAC-keyed) and pushes group membership.
• Optional Wi-Fi drivers on the LAN still work over UDP discovery + outbound WebSocket.
• Architecture (diagrams): docs/espnow-architecture.md
• Wire format (byte layouts): docs/espnow-binary-protocol.md (≤250 bytes per ESP-NOW frame; Pi ↔ bridge uses JSON devices envelope)

Run

• One-time setup for port 80 without root: sudo scripts/setup-port80.sh
• Start app: pipenv run run (FastAPI + uvicorn; override listen port with PORT)
• Dev mode (uvicorn --reload on src/ + browser refresh via dev-live-reload.js): pipenv run dev
• Regenerate docs/help.pdf from docs/help.md: pipenv run help-pdf (requires pandoc and chromium on the host)

UI modes

• Run mode: focused control view. Select zones/presets and apply profiles. Editing actions are hidden.
• Edit mode: management view. Shows Zones, Presets, Patterns, Colour Palette, and Send Presets controls, plus per-tile preset edit/remove and drag-reorder.

Profiles

• Applying a profile updates session scope and refreshes the active zone content.
• In Run mode, Profiles supports apply-only behaviour (no create/clone/delete).
• In Edit mode, Profiles supports create/clone/delete.
• Creating a profile always creates a populated default zone (starter presets).
• Optional DJ zone seeding creates:
  • dj zone bound to device name dj
  • starter DJ presets (rainbow, single colour, transition)

Preset colours and palette linking

• In preset editor, selecting a colour picker value auto-adds it when the picker closes.
• Use From Palette to add a palette-linked preset colour.
• Linked colours are stored as palette references and shown with a P badge.
• When profile palette colours change, linked preset colours update across that profile.

API docs

• Main API reference: docs/API.md

Driver pattern modules

Pattern .py sources live under led-driver/src/patterns. The Pi app resolves that path via util.driver_patterns.driver_patterns_dir(). If you deploy without that tree next to the app, set LED_CONTROLLER_PATTERNS_DIR to the directory that contains those files.