Custom firmware and a companion service that turn a Waveshare ESP32-S3 Knob into a dedicated hi-fi controller.
See what's playing, adjust volume, skip tracks, and switch zones—all from a physical knob on your desk.
Now supports multiple music sources:
- Roon - Full zone control with album artwork
- Lyrion Music Server (LMS) - Squeezebox/LMS player control
- OpenHome/UPnP - Control OpenHome-compatible renderers
Click to watch video demo
- Hardware: Waveshare ESP32-S3-Knob-Touch-LCD-1.8 (~$50) - buy it at amazon to support my work.
- Music source: Roon Core, Lyrion Music Server, or OpenHome renderer on your network
- Docker host (NAS, Raspberry Pi, always-on computer) to run the control service
New to this? See the Getting Started from Scratch guide for detailed step-by-step instructions.
Use the Web Flasher in Chrome or Edge—no tools to install. Just plug in the knob via USB-C and click "Flash ESP32-S3".
Prefer command line? See Firmware Flashing for esptool instructions.
After flashing, future updates happen automatically over WiFi.
The control service (Unified Hi-Fi Control) connects your music source to the knob.
Docker (recommended)
On any Docker host (NAS, Raspberry Pi, etc.):
# docker-compose.yml
services:
unified-hifi-control:
image: muness/unified-hifi-control:latest
restart: unless-stopped
network_mode: host
volumes:
- unified-hifi-control-data:/home/node/app/data
volumes:
unified-hifi-control-data:docker compose up -dNote: The legacy image name
muness/roon-extension-knobstill works and receives the same updates.
Already have the Roon Extension Manager?
Find "Roon Knob" in the extension list and install it from there (Roon-only mode).
Go to Roon → Settings → Extensions and enable "Roon Knob Bridge".
Power on the knob. It creates a WiFi network called "roon-knob-setup". Connect to it, enter your WiFi credentials, and you're done.
The knob finds the extension automatically via mDNS.
| Action | What it does |
|---|---|
| Turn the knob | Volume up/down |
| Press the knob | Open zone picker |
| Tap the screen | Play/pause |
| Swipe up | Art mode (hide controls, show album art) |
| Swipe down | Exit art mode |
| Long-press zone name | Settings |
- Real-time now playing with album artwork
- Velocity-sensitive volume control (turn slow for fine adjustment, fast for quick jumps)
- Multi-zone support
- Automatic display dimming and sleep
- Over-the-air firmware updates
- WiFi setup via captive portal
| Display shows | Meaning |
|---|---|
| "WiFi: Setup Mode" | Connect to "roon-knob-setup" network to configure WiFi |
| "Extension: Searching..." | Looking for the extension—make sure it's running |
| "Extension: Connected" | Ready to use |
If mDNS doesn't work on your network, enter the extension URL manually in Settings (long-press zone name).
See DEVELOPMENT.md for building firmware, running the PC simulator, and contributing.
See PROJECT_AIMS.md for project goals and decision framework, and ROADMAP_IDEAS.md for user feedback and planned improvements.
Questions or issues? Open an issue, join the Roon Community discussion, or buy me a coffee.
This project is licensed under the PolyForm Noncommercial License 1.0.0.
Versions up to and including v2.2.2 were released under the MIT License.
For commercial licensing inquiries, see COMMERCIAL-LICENSE.md.
Thanks to gTunes from the Roon community for alpha testing, detailed feedback, and help with the velocity-sensitive volume control implementation.