Skip to content
Dan edited this page Jun 21, 2015 · 21 revisions

Documentation of the Sonos binding Bundle

Introduction

Note: The Sonos binding communicates with the Sonos devices through the UPNP (Universal Plug And Play) protocol. Users of this binding might wish to familiarise them with the protocol and slang. UPNP defines a subscription model whereby a UPNP client can subscribe to UPNP Events that are transmitted by a UPNP device. Sonos Players do emit quite a bit of Events and some are used to capture status variables (see below).

Sonos Players support multi-room audio. Sonos achieves this by grouping Sonos Players into Zone Groups, and having a Player, the group coordinator, play music which is "streamed" to all the Players part of the Group. That way you can walk from room to room with the same music playing everywhere. Even more, since some Sonos Player models have a line-in socket, you can plug any device into such a Sonos Player, and have its content streamed to any other Player. For example, you can connect a CD player to a Sonos in the basement, and have that music streamed to the Sonos in the bedroom. Or, alternatively, you can connect the line-out of your openHAB system to the line-in of a Sonos, and use some text-to-speech scripts and rules to create a public address system.

Sonos Players also support playlists, music streaming services like Spotify, Rapsody,… as well as alarm clocks that you can program to wake up with your favourite music

Sonos !ZoneBridges are not supported.

For installation of the binding, please see Wiki page Bindings.

Generic Item Binding Configuration

In order to bind an item to a Sonos Player, you need to provide configuration settings. The easiest way to do so is to add some binding information in your item file (in the folder configurations/items`). The syntax for the Sonos binding configuration string is explained here:

The format of the binding configuration is simple and looks like this:

sonos="[<command>:<sonos id>:<sonos command>], [<command>:<sonos id>:<sonos command>], ..."

for Items that trigger action or commands on the Sonos Player, and

sonos="[<sonos id>:<sonos variable>], [<sonos id>:<sonos variable>], ..."

for either Number or String Items that rather store a status variable or other from the Sonos Player

where the <sonos id> corresponds with the UDN (UPNP Unique Device Name) - or - the configuration in openhab.cfg where one can configure the Sonos players, which looks like this

sonos:<sonos id>.udn=[UDN]

and where <sonos command> is the command to be sent to the Sonos Player when <command> is received. Some <sonos commands> take input variables, which are taken from the current Item variable. In case status variables are used then any value received from the Sonos Player for the defined <sonos variable> is used to update the Item

Sonos Commands

The Sonos Player is very complete but also complex device. For a perfect integration within OpenHAB it is assumed that the user will be using the Sonos Desktop Controller software to define playlists, browse music and so forth, e.g. anything which requires user input or interactivity. Therefore the Sonos Commands supported from within openHAB are mostly limited to those actions that require little or no user interaction

Valid <sonos command>'s are:

Command Item Type Purpose Note
add String add another Sonos Player to this Player's group String is the id of the player to add
alarm OnOff set the first occurring alarm either ON or OFF Alarms have to be first defined through the Sonos Desktop Controller
favorite String play the named favorite entry the entry has to be defined in the Sonos Favorites List in the Sonos Desktop or Mobile Controller (since 1.8)
led OnOff get or set the white led on the front of the Player
mute !OnOff get or set the mute state of the Master volume of the Player
next OnOff skip to next track both ON and OFF can be used to trigger this command
pause OnOff pause playing music both ON and OFF can be used to trigger this command
play OnOff play music both ON and OFF can be used to trigger this command
playline String play the line-in stream of the the named sonos UIN UIN is the "RINCON..." identifier string
playlist String play the named playlist from favorites the playlist has to be -pre-defined/created in the Sonos Controller software
playuri String play the named URI the URI is either in the "//host/folder/filename.mp3" format or either in the "x-...-..." format used for other types of sources used by Sonos. This command clears the current queue
previous OnOff skip to previous track both ON and OFF can be used to trigger this command
publicaddress OnOff put all Players in one group, and stream audio from the line-in from the Player that triggered the command both ON and OFF can be used to trigger this command
radio String play the named radio station the station has to be defined in the list of Favorite Stations in the Sonos Desktop Controller
remove String remove the named Sonos Player from this Player's group String is the id of the player to remove
restore OnOff restore the state of all Players both ON and OFF can be used to trigger this command
standalone OnOff make the Sonos Player 'leave' its group and become a standalone Player
save OnOff save the state (group membership, current track, position in track, volume) of all the Players both ON and OFF can be used to trigger this command
snooze Decimal snooze the alarm, if running, with x minutes
stop OnOff stop playing both ON and OFF can be used to trigger this command
volume Percent get or set the volume of the Player

Sonos Status Variables

Valid <sonos variable>'s are:

Variable Item Type Purpose Note
alarmproperties String Properties of the alarm currently running
alarmrunning OnOff set to ON if the alarm was triggered
currenttitle String title of currently playing song
currentartist String artist of currently playing song
currentalbum String album of currently playing song
currenttrack String the track or radio station currently playing
linein OnOff set to ON if the line-in of the Player is connected
localcoordinator OnOff set to ON if this Player is the zone group coordinator
transportstate String the transport state of the Player (STOPPED, PLAYING,…)
zonename String Name of the Zone the Sonos Player belongs to
zonegroup String XML formatted string with the current zonegroup configuration
zonegroupid String Id of the Zone group the Sonos Player belongs to

Examples

Here are some examples of valid binding configuration strings:

sonos="[ON:office:play], [OFF:office:stop]"
sonos="[office:currenttrack]"

As a result, your lines in the items file might look like the following:

Switch ledstatus     "LedStatus"     (Sonos)   {sonos="[ON:living:led], [OFF:living:led]", autoupdate="false"}
String currenttrack  "CurrentTrack [%s]"  (Sonos)   {sonos="[RINCON_000E581369DC01400:currenttrack]", autoupdate="false"}
String radiostation  "RadioStation [%s]"  (Sonos)   {sonos="[living:radio]", autoupdate="false"}
Switch PlayLivingRoom "Play/Pause"        (Sonos)   {sonos="[ON:living:play],[OFF:living:pause]"}
Switch next		  "Next track"        (Sonos)   {sonos="[ON:living:next]"}

Favorites item example:

String Sonos_Office_favorite  						(Sonos)   {sonos="[office:favorite]"}

Favorites sitemap example:

Switch item=Sonos_Office_favorite mappings=["Ben Harper Radio"="Ben Harper","Today's Hits Radio"="Hits","Today's Alternative Radio"="Alt"]

Troubleshooting

Sonos commands take time to execute. If applied to fast, the SONOS player will ignore the command and indicated this by an error message in the OSGi console. Especially the "group" and "radio" command need several seconds to execute. Also the timing is not predictable and the worst case has to be determined experimentally. In rules you may use "Thread::sleep(x) //(x: ms)" to delay the execution of SONOS command accordingly.

The volume button on the loudspeakers create events and can trigger respective rule. Note: the "Play/Pause" button will not create related events.

UPNP Problems

Note:The binding is making use of a buggy UPNP library that result in memory leaks which may crash OPENHAB occasionally.

Installation

###Linux / OS X

###Windows


##Configuration

User Interfaces


Community

(link to openHAB forum)

Development



Misc


Samples

A good source of inspiration and tips from users gathered over the years. Be aware that things may have changed since they were written and some examples might not work correctly.

Please update the wiki if you do come across any out of date information.

Collections of Rules on a single page

Single Rules

Scripts


Release Notes

Clone this wiki locally