A DIY wall-mount / desktop remote for Sonos speakers. Album art, synced lyrics, multi-room control, weather and a StandBy clock — on a 4″ or 7″ touchscreen, with over-the-air updates.
Features • Themes • Hardware • Install • Setup • Architecture • Contributing
If you find this project helpful, consider supporting me on Ko-fi!
Playback
- Full transport control — play/pause, skip, previous, shuffle, repeat, volume and mute
- Queue & library browsing — walk your Sonos library, playlists and favourites, jump to any track
- Multi-room — switch between Sonos zones, with live indicators showing which rooms are playing
- Speaker groups — create and break groups straight from the panel
- Line-in & TV audio — dedicated screens when a soundbar is on TV input or a device is on analogue line-in
Display
- Album art — ESP32-P4 hardware JPEG decoder, plus PNG and progressive-JPEG support, bilinear scaling and automatic dominant-colour extraction
- Synced lyrics — time-synced from LRCLIB, with auto-hide and colour matching
- Three player themes — see below
- StandBy clock screensaver — oversized overlapping digits tinted from the album art, with optional photo backgrounds
- Weather — current conditions plus a 6-hour forecast from Open-Meteo (no API key)
- Auto-dim — configurable idle timeout and dimmed brightness level
System
- Two screen sizes, one codebase — 4″ and 7″ builds from the same source
- OTA updates — install new firmware from the panel, with Stable and Nightly channels
- Browser installer — flash over USB from Chrome/Edge/Opera, no toolchain required
Switch anytime in Settings → General → Theme. Adding another is a single registry entry — see src/ui_theme.cpp.
| Theme | Look |
|---|---|
| SonosESP (default) | The original — blurred album art fills the screen behind the player |
| Ambient | Backdrop tinted from the artwork, artwork left with lyrics beneath it, pill-shaped room selector |
| Immersive | Full-bleed colour, compact header, and a large animated lyric stage where each line fades in |
SonosESP runs on GUITION ESP32-P4 + ESP32-C6 touchscreen boards. Two screen sizes build from the same codebase — the 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 RISC-V) | ESP32-P4 (400 MHz dual-core RISC-V) |
| Wi-Fi | 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. The 7″ is BETA — it builds from the same source and has been run on hardware, but has had far less testing. See docs/MULTI_SCREEN_SUPPORT.md.
- Open the Web Installer
- Choose your screen — 4″ (stable) or 7″ (BETA)
- Connect the board over USB-C
- Click Install and pick the serial port
- Unplug/replug when it finishes, then set up Wi-Fi on screen
Requires Chrome, Edge or Opera (desktop) — they support Web Serial. Firefox and Safari don't.
git clone https://github.com/OpenSurface/SonosESP.git
cd SonosESP
pio run -e esp32_4inch -t upload # 4" board
pio run -e esp32_7inch -t upload # 7" boardOnce installed, the panel updates itself: Settings → Firmware Update → Check for Updates. Pick Stable or Nightly in the channel dropdown. The device chooses the correct build for its own screen size.
- Power on — the Wi-Fi setup screen appears if nothing is configured
- Wi-Fi — tap Scan, pick your network, enter the password with the on-screen keyboard
- Find speakers — Settings → Speakers → Scan
- Play — select a room and you're controlling music
Wi-Fi credentials and all settings are stored in NVS and survive reboots and firmware updates.
- UI framework — LVGL 9.5, with resolution-relative scaling (
ui_scale.h) so one layout serves both panels - FreeRTOS tasks — separate tasks for UI, album art, lyrics, Sonos polling and the clock background
- Thread safety — mutex-protected shared state; all LVGL work happens on the UI thread
- Memory — PSRAM for artwork, lyrics and photo buffers; internal DMA SRAM carefully reserved for Wi-Fi/TLS
- Network — SOAP over HTTP for Sonos control, HTTPS for lyrics and weather, SSDP for discovery
- Image pipeline — hardware JPEG decode, software PNG and progressive-JPEG fallback, fixed-point bilinear scaling
- Reliability — layered SDIO crash defences serialise network access; see
ARCHITECTURE.md
Full reference: ARCHITECTURE.md · Release process: RELEASE.md
Contributions are welcome — please read CONTRIBUTING.md.
Found a bug or want a feature? Open an issue.
Real SonosESP installs in the wild — kitchens, offices, studios, dorm rooms.
Share yours: open a 🖼 Show off your build issue with a photo.
|
Living room · Brennan B3 Jukebox Sonos Beam 2 + 2 Symfonisk frames · @johnhenrick3-cpu |
Living room · Brennan B2 Jukebox Sonos Era 300 · @johnhenrick3-cpu |
|
Kitchen table · 7" variant (beta) Sonos Move 2 · @johnhenrick3-cpu |
Bedside table Sonos Ray + 2 Symfonisk lamps · @johnhenrick3-cpu |
| Want yours featured? Share a photo → | |
More builds and casual sharing in Show & Tell.
Thanks to everyone who has contributed to this project:
MIT — see LICENSE.
- LVGL — the embedded graphics library behind the whole UI
- PlatformIO — build system and toolchain
- LRCLIB — free synced-lyrics API
- Open-Meteo — free weather API, no key required
- LoremFlickr — random photo backgrounds for the clock screensaver
- ESP Web Tools — browser-based installer
- The Sonos UPnP/SOAP community for documenting the control API
Built with ❤️ and vibes • Report a bug • Request a feature • Install now
Keywords: Sonos controller · ESP32-P4 touchscreen · DIY Sonos remote · smart home wall panel · LVGL · ESP32 music controller · Sonos display · album art · synced lyrics