Sonos is a premium wireless audio system designed for multi-room playback. TapHome communicates with Sonos speakers over the local network using UPnP/SOAP on port 1400 — no cloud connection or authentication is required. The template is universal and works with all Sonos speaker models (Era 100, Era 300, One, Five, Beam, Arc, Ray, Move, Roam, Sub, and others).
The template provides full playback control (play, pause, stop, skip), volume and mute management, play mode selection, sleep timers, and up to 10 preset buttons for playlists and radio stations. A set of 14 service attributes exposes device information and the currently playing track.
Configuration
The Sonos speaker connects over Wi-Fi. During TapHome template import, enter the speaker’s IP address (default placeholder 192.168.0.1). The speaker must be on the same network as TapHome CCU.
Sonos speakers support mDNS discovery with the hostname pattern
Sonos-{MAC}.local(MAC address without colons). Using a hostname prevents connectivity issues when the speaker’s IP address changes after a DHCP renewal.
Open the TapHome app and use the IP Scanner (Settings → Network → Scan). The scanner will discover devices on your network and show both the IP address and the mDNS hostname (e.g., Sonos-B8E9375A1C02.local). Use the hostname instead of the IP address for a more reliable connection.
Device capabilities
Volume control
The template exposes volume as a dimmer device. Volume is read via the RenderingControl GetVolume SOAP action (range 0–100) and divided by 100 to produce the 0.0–1.0 dimmer value. Writing a new volume sends SetVolume with the desired level. The volume is polled every 2.5 seconds.
Two additional PushButtons — Volume Up and Volume Down — provide relative volume adjustment. These are handled by CCU-side logic rather than direct SOAP actions, allowing integration with physical wall switches or smart rules.
Mute
Mute is exposed as a switch. The state is read via GetMute and written via SetMute on the Master channel. When mute is on, audio output is silenced without changing the volume level.
Playback control
Six PushButtons control playback transport:
- Play — sends AVTransport
Play(Speed=1) - Pause — sends AVTransport
Pause - Stop — sends AVTransport
Stop - Next — sends AVTransport
Nextto skip to the next track - Previous — sends AVTransport
Previousto go to the previous track - Play/Pause — toggles between play and pause based on the current transport state (handled by CCU-side logic)
Playback status
A read-only binary sensor reports whether the speaker is currently playing. The template reads GetTransportInfo and maps transport states: PLAYING and TRANSITIONING map to 1 (playing), while STOPPED, NO_MEDIA_PRESENT, and PAUSED_PLAYBACK map to 0 (not playing). Polled every 2.5 seconds.
Play mode
Play mode is a multi-value switch with six modes:
| Value | Mode | Description |
|---|---|---|
| 0 | Normal | Sequential playback |
| 1 | Repeat All | Loop the entire queue |
| 2 | Repeat One | Loop the current track |
| 3 | Shuffle No Repeat | Shuffle without repeating |
| 4 | Shuffle | Shuffle with repeat |
| 5 | Shuffle Repeat One | Shuffle, repeat current track |
Values 6–9 are unused padding slots in the multi-value configuration and have no function.
Sleep timers
Two PushButtons configure sleep timers via the AVTransport ConfigureSleepTimer action:
- Sleep in 1 hour — sets the timer to
01:00:00 - Sleep in 15 minutes — sets the timer to
00:15:00
After the timer expires, the speaker stops playback automatically.
Playlist and radio presets
The template provides 10 preset PushButtons — 5 for playlists and 5 for radio stations. Each button has a device variable that the user must configure with the name of the desired playlist or station. The script handles lookup, queue management, and playback automatically.
Playlists (buttons 1–5): Each playlist button uses a playlist_name device variable. The script searches the speaker’s Sonos playlists (Saved Queues) via the ContentDirectory SQ: container, matching by exact dc:title (case-sensitive). When a match is found, the script clears the current queue, enqueues the playlist, and starts playback.
To configure a playlist button:
- Open the TapHome app → navigate to the playlist device → Device Variables
- Set
playlist_nameto the exact name of a Sonos playlist - To create a Sonos playlist: Sonos app → queue tracks → Save Queue as Playlist
Only Sonos playlists (Saved Queues) are supported. Spotify, Apple Music, or other streaming service playlists cannot be used directly. To use tracks from these services, add them to a Sonos playlist first.
Radio stations (buttons 1–5): Each radio button uses a radio_name device variable. The script searches Sonos Favorites via the ContentDirectory FV:2 container, matching by exact dc:title (case-sensitive) and filtering for streaming radio protocol (x-sonosapi-stream).
To configure a radio button:
- Open the TapHome app → navigate to the radio device → Device Variables
- Set
radio_nameto the exact name of the station as it appears in Sonos Favorites - To add a station to Favorites: Sonos app → browse TuneIn or iHeartRadio → tap the heart/star icon
The name must match exactly (case-sensitive). Open the Sonos app, go to My Sonos → Favorites, and copy the station name character by character. Only streaming radio stations are supported — on-demand audio content from Favorites will not work.
Service diagnostics
The template exposes 14 service attributes from the device description XML (/xml/device_description.xml):
- Device info — model name, model URL, serial number, MAC address, hostname, UDN (Unique Device Name)
- Software — software version, software generation, hardware revision, API version, minimum API version
- Sonos config — room name, display name
- Now playing — current track (title, artist, album extracted from DIDL-Lite metadata via
GetPositionInfo)
The current track attribute decodes the XML-encoded TrackMetaData and returns a multi-line string with title, artist, and album information. If the metadata is not available (e.g., line-in input), it returns “Not supported”.
Additional capabilities
The Sonos UPnP API exposes 16 services with capabilities beyond what the template currently implements. The RenderingControl service supports bass, treble, and loudness adjustments, as well as night mode on soundbar models. The AVTransport service provides crossfade control, seek by time or track number, and full queue management (add, remove, reorder tracks). Multi-room group management, alarm scheduling, and EQ settings for surround/subwoofer configurations are also available. Portable models (Move, Roam) expose battery status. These capabilities can be added in a future template update.
Troubleshooting
Speaker not responding
- Verify the Sonos speaker is powered on and connected to Wi-Fi
- Try using the mDNS hostname (
Sonos-{MAC}.local) instead of the IP address — the IP may have changed after a DHCP renewal - Open
http://{speaker-ip}:1400/xml/device_description.xmlin a browser — if it responds with XML, the speaker is reachable - Check that TapHome CCU and the Sonos speaker are on the same network / VLAN
Playback commands fail with error 800
Sonos multi-room groups route all playback commands through the group coordinator. If the template targets a speaker that is not the coordinator, transport commands (Play, Pause, Next, Previous) will fail. Ensure the IP address in TapHome points to the group coordinator, or ungroup the speaker to make it a standalone device.
Volume changes not reflected
- Confirm the template is polling — volume is read every 2.5 seconds via
GetVolume - If another controller (Sonos app, Apple AirPlay) changed the volume, TapHome will pick up the new value on the next poll cycle
- Check that the speaker is not in a group where volume is controlled by the group coordinator
Sonos speakers accept UPnP commands only from devices on the same subnet. If TapHome CCU is on a different VLAN, ensure multicast/UPnP traffic is routed between the VLANs, or place both devices on the same network segment.