Documentation

Configuration

All Lights Pi configuration is managed through environment variables in the .env file.

Environment Variables

Copy the example file to get started:

bash

cp .env.example .env

Required Variables

Variable	Description	Example
`PI_HOST`	Hostname or IP of your Pi	`lights.local`
`PI_USER`	SSH username	`pi`
`WIFI1_SSID`	Primary WiFi network name	`MyNetwork`
`WIFI1_PSK`	Primary WiFi password	`secret123`

Optional Variables

Variable	Description	Default
`PI_HOSTNAME`	mDNS hostname set on the Pi	`lights`
`QLC_PORT`	QLC+ web UI port	`9999`
`SSH_KEY`	Path to SSH private key	—
`BACKUP_STORAGE`	Local backup directory	`./backups`
`WIFI2_SSID`	Secondary WiFi network	—
`WIFI2_PSK`	Secondary WiFi password	—
`AI_PROVIDER`	AI backend: `openai`, `anthropic`, or `ollama`	`openai`
`AI_API_KEY`	API key for the chosen provider	—
`AI_MODEL`	Model name (e.g. `gpt-4.1`)	`gpt-4.1`
`AI_SCENE_STYLE`	Default scene style	`complete`

MCP Server Variables (Optional)

Used by lighting-mcp.service when the MCP server is installed.

Variable	Description	Default
`MCP_HOST`	Bind address for the MCP HTTP server	`0.0.0.0`
`MCP_PORT`	Port the MCP endpoint listens on	`5001`
`MCP_PATH`	Streamable HTTP mount path	`/mcp`
`CONTROL_URL`	Where the MCP server reaches the Flask control server	`http://localhost:5000`
`MCP_BEARER_TOKEN`	Reserved for bearer-token auth — scaffolded, not yet enforced	—
`MCP_HTTP_TIMEOUT`	Seconds for upstream Flask calls	`30`

Note: Use PI_HOSTNAME, not HOSTNAME — the latter is a macOS shell builtin.

QLC+ Configuration

QLC+ workspaces (.qxw files) define your fixture layout, scenes, and show sequences.

Deploying a Workspace

bash

./lightsctl.sh deploy-workspace my-show.qxw

Pulling the Current Workspace

bash

./lightsctl.sh pull-workspace

Network Configuration

Static IP

For production setups, assign a static IP:

bash

./lightsctl.sh static-ip 192.168.1.100/24 192.168.1.1

Dual WiFi

Configure a backup WiFi network by setting WIFI2_SSID and WIFI2_PSK in your .env file. The Pi will automatically fall back to the secondary network if the primary is unavailable.

Security Hardening

The harden command applies security best practices:

bash

./lightsctl.sh harden

This enables:

UFW firewall (allows SSH + QLC+ web UI). Additional ports are opened automatically when control-install and mcp-install run.
Hardware watchdog (auto-reboot on hang)
Unattended security upgrades
USB device permissions for ENTTEC

Was this page helpful?