Architecture

Architecture

Technical overview of how Lights Pi components fit together.

System Diagram

   Browser / phone / voice           ┌─────────── AI providers ──────────┐
              │                      │  OpenAI • Anthropic • Ollama       │
              │  WiFi / HTTPS        └─────────────┬─────────────────────┘
              ▼                                    │
       Raspberry Pi                                │
   ┌─────────────────────────────┐                 │
   │ nginx (80/443, optional)    │                 │
   │ landing page + reverse proxy│                 │
   └──────────┬──────────────────┘                 │
              │                                    │
   ┌──────────▼──────────────┐    HTTP+WebSocket   │
   │ Flask control server    │◄────────────────────┘
   │ (port 5000)             │
   │  • AI chat → DMX        │
   │  • Live virtual console │
   │  • Fixture groups       │
   │  • .qxf-aware channels  │
   │  • Scene save/snapshot  │
   └──────────┬──────────────┘
              │ persistent WebSocket
              ▼
   ┌──────────────────────────┐
   │ QLC+ headless (port 9999)│
   │  + .qxf fixture defs     │
   └──────────┬───────────────┘
              │ USB
              ▼
       ENTTEC DMX USB Pro
              │  DMX
              ▼
        DMX Fixtures (rig)

Services on the Pi

Service	Port	Purpose
qlcplus-web.service	9999	QLC+ headless with web UI
lighting-control.service	5000	Flask control server
nginx	80/443	Landing page + optional HTTPS reverse proxy
wifi-watchdog.timer	—	Auto-recovery for dropped WiFi (every 2 min)

Persistent WebSocket

The control server holds exactly one WebSocket to QLC+ for its entire lifetime. This is critical because QLC+ 4.14.x has a hard limit (~50) on concurrent WebSocket clients. Previous architectures that opened a new connection per request would exhaust this limit within minutes.

Key design decisions:

• Dedicated asyncio event loop in a daemon thread owns the WebSocket
• All Flask request handlers dispatch via asyncio.run_coroutine_threadsafe
• A background reader task continuously drains incoming messages
• On connection drop, the reader explicitly closes the socket (preventing CLOSE_WAIT leak) and the next request lazily reconnects

Fixture Definition Parser

control-server/fixture_definitions.py reads .qxf files and resolves a semantic role for each channel:

1. <Channel Preset="IntensityRed"> → role = red
2. <Colour>White</Colour> + name contains "Warm" → role = warm
3. Exact channel name match ("Strobe" → strobe)
4. Group classification (Shutter → strobe, Colour → macro)
5. Channels in Speed/Maintenance/Effect groups → role = null (never driven by color commands)

This metadata flows to:

• The AI prompt (so it picks correct channels per fixture)
• The UI (correct slider labels)
• apply_color_live() (drives only color-role channels, zeros everything else)

Scene Save Flow

1. User sends AI command → scene XML generated and applied live
2. scene_xml returned in the API response
3. User clicks 💾 → frontend sends XML + name to POST /api/scenes/save
4. Backend injects the <Function> element into the workspace's <Engine>
5. Scene gets the next available ID and appears in the Scenes tab immediately
6. Persists through reboots (it's in the .qxw file QLC+ loads on boot)

File Locations on Pi

Path	Purpose
/home/<user>/.qlcplus/default.qxw	Active workspace (loaded by QLC+ on boot)
/home/<user>/.qlcplus/fixture_groups.json	Persisted fixture groups
/home/<user>/control-server/	Flask app source
/home/<user>/control-server-venv/	Python virtual environment
/usr/share/qlcplus/fixtures/	System fixture definitions (.qxf)
~/.qlcplus/fixtures/	User fixture definition overrides
/home/<user>/lightsctl.sh	CLI entry point (deployed from workstation)
/home/<user>/scripts/	Supporting scripts and libraries