Skip to main content

Documentation

Home

3 min readEdit on GitHub

Welcome to the Lights Pi documentation. Lights Pi is a headless Raspberry Pi lighting controller for studio environments — providing network-based control of DMX lighting fixtures through QLC+, plus a natural-language control layer for voice and chat-driven scene generation.

What is Lights Pi?

Lights Pi turns a Raspberry Pi into a dedicated DMX lighting controller that anyone on your studio network can operate from a browser, phone, voice command, or LLM agent. No physical access to the Pi needed.

Key capabilities:

  • Control DMX fixtures through QLC+'s web interface
  • Generate lighting scenes with natural language ("make it warm and dim")
  • Manage fixtures and groups through a custom control server
  • Expose the rig over Model Context Protocol so Claude Desktop, ChatGPT, Cursor, or any MCP-capable agent can drive the lights
  • Mobile-first responsive UI, installable as a PWA on iOS and Android — see Mobile-and-PWA
  • Tab state persisted in the URL (?tab=chat, ?tab=cuelists, etc.) — bookmarkable and refresh-stable
  • Provision and manage your Pi remotely with lightsctl.sh

How It Works

  1. A Raspberry Pi runs QLC+ headless, connected to your fixtures via an ENTTEC DMX USB Pro
  2. The QLC+ web UI (port 9999) provides full fixture control from any browser
  3. A custom Flask control server (port 5000) adds AI-powered scene generation
  4. An MCP server (port 5001) exposes the same control surface to LLM agents over Streamable HTTP
  5. The lightsctl.sh CLI handles provisioning, deployment, and diagnostics from your workstation

Getting Started

New to Lights Pi? Start here:

  1. System-Requirements — Check what hardware you need
  2. Quick-Start — Get up and running in 15 minutes
  3. Hardware-Setup — Connect your DMX fixtures
  4. Configuration — Customize your setup
  5. Mobile-and-PWA — Install the UI on your phone for tablescape-side control

Documentation Sections

Getting Started

Guides for first-time setup, from SD card preparation through your first scene.

Usage

Day-to-day commands and troubleshooting for operating your Lights Pi.

Advanced

Hardware deep-dives, multi-universe setups, and configuration reference.

Contributing to Docs

These docs are sourced from the GitHub Wiki. To contribute:

  1. Click "Edit on GitHub" on any page
  2. Make your changes in the wiki editor
  3. Changes appear on the site within an hour (no deploy needed)

Need Help?

Was this page helpful?