Overview SONOS (Cloud API)

Important: This function module is currently intended for internal testing only.

This function block controls SONOS speakers through the official SONOS Cloud Control API. It is the successor to the "SONOS" block, which relies on third-party software. The old block remains available; for new projects this block is recommended.

Internet required: Control runs through the SONOS cloud. Both the controller and the speakers therefore need an internet connection. A one-time login with a SONOS account is required (see below).

Unlike the old block, this block also provides feedback (playback, volume, mute per zone) and supports additional functions such as grouping (party mode), play modes (shuffle/repeat/crossfade) and playing a stream URL or the line-in input.

Text to speech: The official SONOS API does not provide its own speech output. As with the old block, announcements use an external service that is currently still free of charge. Should this change, the function cannot be guaranteed. As an alternative, a custom audio file can be played through the "Audio clip" function.

Configuration: Zones, actions and account are edited through the dedicated dialog (the "Configure SONOS" button in the parameters). The settings are stored in the controller — the dialog is therefore only available while connected to the controller.



Login (one-time)
  1. Open the "Configure SONOS" dialog (the controller must be connected).
  2. In the "Account / login" section, click "Open SONOS login page" (or "Copy login link" and open it in a browser).
  3. Sign in with your SONOS account. After signing in, a code is displayed.
  4. Paste this code into the "Authorization code" field and close the dialog with "Save".
  5. The controller exchanges the code for a permanent access token. The status switches to "connected". The token survives a restart of the controller — a new login is only required after "Log out" or when the token has expired.

Inputs
FG Enable Optional enable. If the input is not connected, the block is enabled automatically. Without enable, no actions are triggered.

Outputs
ER Error counter Counts failed requests to the SONOS cloud (e.g. network errors, unknown zone).
CN Connected 1 = access token valid and last status poll successful, otherwise 0.

Zone addresses
Three addresses are generated per active zone. They are updated cyclically from the actual state of the speakers (feedback) and can also be written (control):
Playback 1 = playing, 0 = paused Writing: 1 starts playback, 0 pauses.
Volume 0 … 100 Writing sets the volume of the zone.
Mute 1 = muted Writing mutes or unmutes the zone.

Dialog: Zones
"Search zones" loads the speakers (rooms) found in the SONOS household. The order of the zones determines the generated addresses — do not reorder existing zones, otherwise the addresses shift. The name must match the room name in the SONOS app.

Dialog: Actions
An action triggers a function on a zone when a trigger address changes. The trigger address is added by dragging and dropping it from the address window into the table. For each row you set the trigger type (edge/telegram), the zone, the function and function-specific data.
Play / Pause / Play‑Pause — Start, pause or toggle playback.
Mute / Unmute — Mute the zone or turn the sound back on.
Next / Previous track — Skip track (not possible for every source, e.g. radio).
Volume + / − Step 1 … 100 Increase/decrease the volume relatively.
Volume = value Value of the trigger address Sets the volume to the value present on the trigger address (0 … 100).
Volume absolute Value 0 … 100 Sets the volume to the value given in the data field.
Favorite Name of the favorite Plays a SONOS favorite. Use "Load favorites/playlists" to pick the name from a list.
Playlist Name of the playlist Plays a SONOS playlist.
Text to speech (TTS) Text/language/volume Announcement over the current music, e.g. Lunch is ready/en/50. Uses an external service (see note above); limited text length.
Audio clip / chime empty = chime, otherwise URL|volume Plays a chime or a custom audio file (URL) over the current music. Example: http://…/announcement.mp3|60.
Add to group Name of the target zone Adds the zone to the group of the target zone (e.g. party mode).
Remove from group — Separates the zone from its group again.
Shuffle / Repeat / Crossfade 0 = off, 1 = on Sets the play mode (shuffle, repeat, crossfade).
Play stream URL Stream URL Plays an internet radio or stream URL.
Line-in — Switches to the speaker's line-in input (if available).

Dialog: Account
Poll interval 5 … 3600 s Interval at which the state of the zones is polled from the cloud (default 30 s). Smaller values react faster but generate more requests.
Debug 0 / 1 Additional messages in the controller trace for troubleshooting.
Log out — Deletes the stored access token. A new login is required afterwards.