A modern, touchscreen controller for Sonos speakers built with ESP32-P4
Features • Hardware • Installation • Contributing
If you find this project helpful, consider supporting me on Ko-fi!
- Full Playback Control - Play, pause, skip, volume, shuffle, and repeat
- Queue Management - Browse and manage your playback queue
- Album Art Display - Hardware JPEG decoder + PNG support with bilinear scaling and automatic dominant color extraction
- Synced Lyrics Display - Time-synced lyrics from LRCLIB overlaid on album art with smart auto-hide, scroll effects, and color matching
- Clock Screensaver - Full-screen clock activates after inactivity with random ambient background images, tap to dismiss
- Music Browsing - Navigate your Sonos library, playlists, and favorites
- Multi-Room - Switch between Sonos zones with live playing indicators showing which rooms are active
- OTA Updates - Firmware updates from GitHub with Stable and Nightly release channel selection, auto-retry on low memory
SonosESP runs on GUITION ESP32-P4 + ESP32-C6 touchscreen boards. Two screen
sizes build from the same codebase — the web installer and OTA pick the right
firmware automatically (firmware-4inch.bin / firmware-7inch.bin).
| 4″ — stable | 7″ — BETA | |
|---|---|---|
| Board | GUITION JC4880P433C | GUITION JC1060P470C |
| Display | 800×480, ST7701 (MIPI DSI) | 1024×600, JD9165 (MIPI DSI) |
| Touch | GT911 capacitive (I²C) | GT911 capacitive (I²C) |
| MCU | ESP32-P4 (400 MHz dual-core) | ESP32-P4 (400 MHz dual-core) |
| WiFi | ESP32-C6 (via ESP-Hosted) | ESP32-C6 (via ESP-Hosted) |
| Flash / PSRAM | 16 MB / 32 MB OPI | 16 MB / 32 MB OPI |
| Interface | USB-C | USB-C |
Note: This firmware targets these specific GUITION boards and won't run on other ESP32 boards without significant changes.
The 4″ is the production target (thousands of installs in the wild). The 7″ is BETA — code-complete and building from the same source, but not yet validated on physical hardware. Flash it only if you own the board and can report back. See docs/MULTI_SCREEN_SUPPORT.md.
- Visit the Web Installer
- Choose your screen — 4″ (stable) or 7″ (BETA)
- Connect your ESP32-P4 board via USB-C
- Click "Install Firmware" and select the COM port
- Wait for installation to complete
- Configure WiFi using the on-screen keyboard after reboot
Requires Chrome, Edge, or Opera browser with Web Serial support
The device supports automatic Over-The-Air (OTA) firmware updates from GitHub releases:
- Connect to WiFi via Settings
- Navigate to Settings → Firmware Update
- Tap "Check for Updates"
- If an update is available, tap "Install Update"
- Device will automatically download and install from GitHub releases
- Power on - Device will show WiFi setup if not configured
- WiFi Setup - Tap "Scan" to find networks, select yours, enter password
- Sonos Discovery - Navigate to Settings → Speakers and tap "Scan"
- Start Playing - Select a device and start controlling your music!
- FreeRTOS Tasks - Separate tasks for UI, album art, lyrics, and Sonos polling
- Thread Safety - Mutex protection for shared resources
- Memory Management - PSRAM for album art and lyrics, heap monitoring
- Network Layer - HTTPClient for SOAP requests, HTTPS for lyrics/art, UDP for SSDP discovery
- UI Framework - LVGL 9.5 with custom theme; resolution-relative scaling (
ui_scale.h) so one layout fits both the 4″ and 7″ panels - Image Processing - ESP32-P4 hardware JPEG decoder + software PNG decoder, custom bilinear scaling with fixed-point math
- Lyrics System - Time-synced LRC parsing with HTTPS fetching, auto-hide, and retry logic
- Clock Screensaver - Inactivity-triggered fullscreen clock with random Unsplash backgrounds
- OTA Updates - Stable and Nightly channels, 3-attempt retry loop with live countdown UI
WiFi credentials are stored persistently in NVS (Non-Volatile Storage). Once configured via the UI, they survive reboots and power cycles.
- Automatic OTA updates from GitHub releases
- Version checking on demand
- Progress indication during download
- Safe rollback on failure
Contributions are welcome! Please read CONTRIBUTING.md for guidelines.
Real SonosESP installs in the wild — kitchens, offices, studios, dorm rooms.
How to share yours: open a 🖼 Show off your build issue with a photo. Selected builds get featured in the mosaic below.
|
Your build here? Share a photo → |
More builds and casual sharing in Show & Tell (Discussions tab).
Thanks to these wonderful people who have contributed to this project:
This project is licensed under the MIT License - see LICENSE file for details.
- Built with LVGL - Amazing embedded graphics library
- PlatformIO - Best embedded development platform
- LRCLIB - Free synced lyrics API
- Unsplash - Beautiful random background photos for the clock screensaver
- Sonos UPnP/SOAP API documentation and community
Built with ❤️ and vibes • Report Bug • Request Feature