Zonal Documentation
Everything you need to deploy, configure, and operate Steeplestack Zonal: the automated SPL monitoring and gain control system for Q-SYS venues.
Install the controller, activate your license, and have your first zone online in under an hour.
Platform-specific instructions for Windows, Linux (binary + DEB), and Docker.
Provision a Raspberry Pi + UMIK-1 monitor from the dashboard with one command.
Connect Zonal to your Q-SYS Core via TCP JSON-RPC and map named gain components.
Run the full stack (controller + MQTT broker) with Docker Compose. Multi-zone config included.
Mutual TLS authentication for MQTT, role-based access control, and certificate management.
Activate a license key, manage renewals, and configure headless / CI deployments.
System overview
Zonal is an Nx monorepo (TypeScript / Node.js) with three main components:
- Controller — Fastify server that connects to your Q-SYS Core via TCP JSON-RPC, manages the MQTT broker, and serves the web dashboard.
- Dashboard — Next.js 15 web UI with real-time SPL charts, zone settings, scheduling, user management, and monitor provisioning.
- Monitor — Node.js app that runs on a Raspberry Pi, reads audio via ALSA, applies A-weighting DSP, and publishes SPL to MQTT every 5 seconds.
Data flow
Pi Monitor (ALSA → A-weighted SPL)
↓ MQTT / mTLS (port 8883)
Zonal Controller (averages SPL, applies gain logic)
↓ TCP JSON-RPC (port 1710)
Q-SYS Core (adjusts named gain component)