Configuration

Configuration

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

Environment Variables

Copy the example file to get started:

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

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

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

Pulling the Current Workspace

./lightsctl.sh pull-workspace

Network Configuration

Static IP

For production setups, assign a static IP:

./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:

./lightsctl.sh harden

This enables:

• UFW firewall (allows SSH + QLC+ web UI only)
• Hardware watchdog (auto-reboot on hang)
• Unattended security upgrades
• USB device permissions for ENTTEC