A touchscreen Sonos controller for ESP32-P4.
A wall-mount or desktop remote for Sonos speakers: album art, synced lyrics, full library browsing, multi-room control, weather and five screensaver clock faces — on a 4″ or 7″ panel, with over-the-air updates.
Features · Music sources · Themes · Screensaver · Hardware · Install · Setup · Troubleshooting · Contributing
- Full transport control — play and pause, skip, previous, shuffle, repeat, volume and mute
- Complete library browsing — every source the speaker exposes, not a fixed list. See Music sources
- Multi-room — switch between Sonos zones, with live indicators showing which rooms are playing
- Speaker groups — create and break groups from the panel
- Line-in and TV audio — dedicated screens when a soundbar is on TV input or a device is on analogue line-in
- Sleep timer — the Sleep button at the bottom of the Amber player stops the music after 15 to 90 minutes, with +15 and Turn off. It sets the speaker's own timer, so one set by voice or in the Sonos app shows on the panel too
- Album art — ESP32-P4 hardware JPEG decoder, with PNG and progressive-JPEG support, bilinear scaling and automatic dominant-colour extraction
- Synced lyrics — time-synced from LRCLIB, with auto-hide and colour matching
- Accented characters throughout — titles, artists, lyrics, menus, dropdowns and the on-screen keyboard all render Latin-1 and Latin Extended-A correctly (Beyoncé, Björk, Sigur Rós) rather than substituting plain letters
- Three player themes and five screensaver faces — see below
- Queue and Rooms as overlays — both open over the player instead of replacing it, so the transport stays reachable
- Per-speaker volume — adjust the selected room from the Speakers list or the Rooms overlay
- Battery levels — Move and Roam show their charge in the Speakers, Groups and Rooms lists and at the bottom of the Amber player: green from 50%, yellow below that, red and blinking under 20%
- Weather — current conditions and a 6-hour forecast from Open-Meteo, no API key
- Auto-dim — configurable idle timeout and dimmed brightness, down to 1% on the 4″. While the clock screensaver is up, a new track no longer lights the screen
- Two panel sizes, one codebase — 4″ and 7″ build from the same source, with type and spacing scaling to the panel rather than being authored twice
- OTA updates — install new firmware from the panel, on Stable or Nightly channels, with resumable downloads
- Browser installer — flash over USB from Chrome, Edge or Opera; no toolchain required
- Restart history — Settings → General lists the last eight restarts and why each happened, so a panel that restarted overnight can say why. See Troubleshooting
The Sources screen lists what your household actually has. It is built by asking the speaker at runtime rather than from a hardcoded list, so a system with no music share does not show an empty Music Library, and a container Sonos adds in future appears without a firmware update.
| Source | Contents |
|---|---|
| Music Library | Artists, album artists, albums, genres, composers, tracks and imported playlists from your network share |
| Music Shares | The SMB/NAS shares indexed by Sonos |
| Sonos Playlists | Saved queues |
| Favorites | Everything saved in the Sonos app, including streaming-service playlists and mixes |
| Internet Radio | Radio stations and radio shows |
| Queue | What is queued right now |
| Line-In | Analogue input, on players that have one |
Browsing supports arbitrary nesting with a back arrow and a breadcrumb showing where you are, so a deep path like Music Library → Artists → an artist → an album stays navigable. Long lists load in pages rather than truncating, so a 500-track queue is fully reachable.
Streaming services. Content you have saved — favourites and playlists from Spotify, Apple Music, YouTube Music and others — plays directly, because the speaker resolves it with credentials it already holds. SonosESP never asks you to sign in to anything. Searching a service's full catalogue is not supported; add what you want in the Sonos app and it appears here.
Switch in Settings → General → Theme. Adding one is a single registry entry — see src/ui_theme.cpp.
| Theme | Look |
|---|---|
| Amber (default) | Flat warm panel with one gold accent. Artwork edge to edge down the left with a shelf beneath it for the next track or the synced lyric; every control permanently visible on the right, with the speaker's battery and the sleep timer along the bottom |
| SonosESP | The original: blurred album art fills the screen behind the player. The backdrop can be turned off in Display settings |
| Immersive | Full-bleed colour, compact header, and a large animated lyric stage where each line fades in |
Ambient was removed in v2.0.0. Amber covers the same ground — a flat panel with the lyrics off the artwork — and does it to a drawn design. Devices set to Ambient move to Amber automatically; nothing else changes theme.
The panel falls back to a clock after an idle timeout. Switch faces in
Settings → Clock → Theme; each supports the optional photo background and the
weather overlay. Adding one is a single registry entry — see
src/clock_face.cpp.
| Theme | Look |
|---|---|
| Amber (default) | Hours over minutes with a seconds hairline, a weather column, a 6-hour rail, and the paused track in the corner. Matches the Amber player |
| Horizon | Centred clock over an ambient glow, one-line weather summary, 6-hour forecast as pill chips |
| Orbit | Clock alongside a live sun-path arc tracking real sunrise and sunset, forecast drawn as a temperature curve |
| Monolith | Hours stacked over minutes, a details column for humidity, wind, UV and sun times, and a forecast rail |
| StandBy | Oversized overlapping digits tinted from the current album art |
With a sleep timer running, the Amber face's now-playing line says when the music stops: UNTIL 22:15. Touch the screen at any time to return to the player.
SonosESP runs on GUITION ESP32-P4 + ESP32-C6 touchscreen boards. Both panel sizes
build from the same codebase, and the installer and OTA select the right image
automatically (firmware-4inch.bin / firmware-7inch.bin).
| 4″ — stable | 7″ — beta | |
|---|---|---|
| Board | GUITION JC4880P443C | 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 |
This firmware targets these specific GUITION boards and will not 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 runs on hardware, but has had considerably less testing. GUITION also ship two different LCD panels under the same 7″ product code — a first-boot wizard detects which one is fitted. See docs/MULTI_SCREEN_SUPPORT.md.
- Open the web installer
- Choose your screen size — 4″ (stable) or 7″ (beta)
- Connect the board over USB-C
- Select Install and pick the serial port
- Unplug and replug when it finishes, then set up Wi-Fi on screen
Requires Chrome, Edge or Opera on desktop — these support Web Serial. Firefox and Safari do not.
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. Choose Stable or Nightly in the channel dropdown; the device selects the correct build for its own panel.
Interrupted downloads resume rather than restarting. If a transfer stalls, the panel
reconnects and continues from the byte it reached, so an unreliable connection no
longer means starting the image again. Resuming from 47%… is the recovery working —
let it run. See Troubleshooting
if it still fails.
- Power on — the Wi-Fi setup screen appears if nothing is configured
- Wi-Fi — select Scan, choose your network, enter the password on the on-screen keyboard
- Find speakers — Settings → Speakers → Scan
- Play — select a room
Wi-Fi credentials and all settings are stored in NVS and survive reboots and firmware updates.
Device not appearing over USB? Update stopping partway? Blank screen after an update?
The two that catch people out most often:
- The board has two USB-C ports and only one talks to a computer. If nothing appears on your PC, try the other port first.
- Wi-Fi is 2.4 GHz only. A combined 2.4/5 GHz network using one name is a common reason setup fails.
- UI framework — LVGL 9.6, with resolution-relative scaling (
ui_scale.h) so one layout serves both panels - FreeRTOS tasks — separate tasks for UI, album art, lyrics, Sonos polling, touch sampling 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 reserved for Wi-Fi and 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
Release process: RELEASE.md
Contributions are welcome — please read CONTRIBUTING.md.
Found a bug, or want a feature? Open an issue.
Real SonosESP installs — 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.
If you find this project useful, you can support its development on Ko-fi.
MIT — see LICENSE.
- LVGL — the embedded graphics library behind the UI
- PlatformIO — build system and toolchain
- LRCLIB — free synced-lyrics API
- Open-Meteo — free weather API, no key required
- LoremFlickr — photo backgrounds for the clock screensaver
- ESP Web Tools — browser-based installer
- The Sonos UPnP/SOAP community for documenting the control interface
Troubleshooting · Report a bug · Request a feature · Install
Sonos controller · ESP32-P4 touchscreen · DIY Sonos remote · smart home wall panel · LVGL · ESP32 music controller · Sonos display · album art · synced lyrics