Skip to main content

Documentation

Quick Start

3 min readEdit on GitHub

Get your Lights Pi up and running in minutes.

Prerequisites

  • Raspberry Pi 3B+ or Pi 4
  • MicroSD card (16GB+ Class 10)
  • ENTTEC DMX USB Pro (or compatible)
  • WiFi network credentials

Step 1: Prepare the SD Card

Flash Raspberry Pi OS Lite to your MicroSD card using the Raspberry Pi Imager. Enable SSH and configure WiFi during the imaging process.

Step 2: Clone and Configure

bash
git clone https://github.com/gfargo/lights-pi.git
cd lights-pi
cp .env.example .env

Edit .env with your Pi's hostname/IP and WiFi credentials:

bash
1PI_HOST=lights.local
2PI_USER=pi
3WIFI1_SSID=YourNetwork
4WIFI1_PSK=YourPassword

Step 3: Provision

Run the full setup command to install QLC+, configure the system, and harden security:

bash
./lightsctl.sh setup-full

This runs setup (base install) followed by harden (firewall, watchdog, unattended upgrades).

Step 4: Verify

bash
./lightsctl.sh doctor    # Full health check
./lightsctl.sh health    # Quick status
./lightsctl.sh open-web  # Open QLC+ web UI

Step 5: Install the Control Server (Optional)

Adds an AI-powered web UI at http://lights.local:5000 for natural-language commands, fixture groups, scene save/snapshot, and the live virtual console.

bash
./lightsctl.sh control-install

See Control-Server for full details on what this adds.

Step 6: Install the MCP Server (Optional)

Exposes the rig as a Model Context Protocol endpoint so Claude Desktop, ChatGPT, Cursor, or any custom agent can drive the lights via structured tool calls.

bash
./lightsctl.sh mcp-install

Then add http://lights.local:5001/mcp to your MCP client's config. See MCP-Server for the full tool catalog (48 tools as of v2.9.0) and client wiring examples.

Only install MCP if you actually want it. If you just want the web UI / Chat tab, skip this step. The Pi-health card will show lighting-mcp: not installed (muted, not red) — that's expected, not a failure.

Step 7: Install on Your Phone (Optional)

The control server UI is a PWA. On your phone? Add it to your Home Screen for a chromeless, native-feeling app:

  • iOS Safari: Share → Add to Home Screen
  • Android Chrome: Install app prompt (or menu → Install app)

See Mobile-and-PWA for the full mobile UX rundown.

Deploying Code Changes

Once provisioned, updates to lights-pi source (control server, scripts, fixtures, etc.) deploy from your workstation with:

bash
bash scripts/deploy.sh

This rsyncs control-server/, scripts/, and lightsctl.sh to the Pi and restarts lighting-control.service. After deploy, do a hard refresh in the browser (⌘⇧R on Mac, Ctrl⇧R on Windows/Linux) — the PWA service worker will otherwise serve stale CSS/JS.

./lightsctl.sh update is not how you deploy code — it only runs sudo apt update && apt upgrade on the Pi. See Troubleshooting → Common Pitfalls.

Next Steps

Was this page helpful?