<div align="center">

SonosESP | ESP32-P4 Sonos Controller

A modern, touchscreen controller for Sonos speakers built with ESP32-P4

Features • Hardware • Installation • Contributing

☕ Support

If you find this project helpful, consider supporting me on Ko-fi!

</div>

---

Features

• 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

Hardware

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.

Installation

Web Installer (Recommended)

1. Visit the Web Installer
2. Connect your ESP32-P4 via USB-C
3. Click "Install Firmware" and select the COM port
4. Wait for installation to complete
5. Configure WiFi using the on-screen keyboard after reboot

Requires Chrome, Edge, or Opera browser with Web Serial support

OTA Updates (After Initial Install)

The device supports automatic Over-The-Air (OTA) firmware updates from GitHub releases:

1. Connect to WiFi via Settings
2. Navigate to Settings → Firmware Update
3. Tap "Check for Updates"
4. If an update is available, tap "Install Update"
5. Device will automatically download and install from GitHub releases

First-Time Setup

1. Power on - Device will show WiFi setup if not configured
2. WiFi Setup - Tap "Scan" to find networks, select yours, enter password
3. Sonos Discovery - Navigate to Settings → Speakers and tap "Scan"
4. Start Playing - Select a device and start controlling your music!

Key Components

• 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.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
• Clock Screensaver - Inactivity-triggered fullscreen clock with random Unsplash backgrounds
• OTA Updates - Stable and Nightly channels, 3-attempt retry loop with live countdown UI

Configuration

WiFi credentials are stored persistently in NVS (Non-Volatile Storage). Once configured via the UI, they survive reboots and power cycles.

Firmware Updates

• Automatic OTA updates from GitHub releases
• Version checking on demand
• Progress indication during download
• Safe rollback on failure

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Contributors

Thanks to these wonderful people who have contributed to this project:

<a href="https://github.com/OpenSurface/SonosESP/graphs/contributors"> <img src="https://contrib.rocks/image?repo=OpenSurface/SonosESP" /> </a>

Special thanks to:

• @BaileyLawson - First external contributor!
• @johnhenrick3-cpu - Outstanding community tester!

License

This project is licensed under the MIT License - see LICENSE file for details.

Acknowledgments

• 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

---

<div align="center">

Built with ❤️ and vibes • Report Bug • Request Feature

</div>