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
- Music Browsing - Navigate your Sonos library, playlists, and favorites
- Multi-Room - Switch between multiple Sonos devices
- WiFi Configuration - Easy on-screen WiFi setup with built-in keyboard
- OTA Updates - Automatic firmware updates from GitHub releases
- Thread-Safe - FreeRTOS tasks with proper synchronization
- Performance Optimized - PSRAM allocation, efficient string handling, robust networking, fast fixed-point math
This project requires the GUITION JC4880P433C development board:
| Component | Specification |
|---|---|
| MCU | ESP32-P4 (400 MHz dual-core) |
| WiFi Module | ESP32-C6 (via ESP-Hosted) |
| Display | 800×480 RGB LCD with ST7701 driver |
| Touch | GT911 capacitive touch (I2C) |
| Flash | 16 MB |
| PSRAM | OPI PSRAM |
| Interface | USB-C |
Note: This firmware is specifically designed for the GUITION JC4880P433C board. It will not work on other ESP32 boards without significant modifications.
- Visit the Web Installer
- Connect your ESP32-P4 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 discovery
- UI Framework - LVGL 9.4.0 with custom theme
- 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
- OTA Updates - Automatic firmware updates from GitHub releases
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.
Thanks to these wonderful people who have contributed to this project:
Special thanks to:
- @BaileyLawson - First external contributor! Added HTTPS album art support, dual buffers, speaker scanning fixes, and more.
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
- Sonos UPnP/SOAP API documentation and community
Built with ❤️ and vibes • Report Bug • Request Feature