Sonos Media Player Driver

The driver should be a replacement for the previous version of the driver.

Version History

Version 3.0: Initial public release.

Version 3.31: Beta test.

Version 4.0 Passed 'Works with Sonos' certification.

Version 4.01 updated instructions

Version 4.05 addresses issues with CPU Load on large systems(see below), adds remaining time variable, and fixes issue where feedback would sometimes not populate on startup.

Version 4.09: Fixed connection issue after a Sonos firmware update. Fixed SiriusXM title feedback. Fixed playback appearing to continue after a player is taken offline.

Driver Features

This driver provides network control of Sonos Media Players. It was built and tested using a pair of Play:3, 2x Amp, a Port.

System Requirements & Prerequisites

RTI System Requirements

Integration Designer: 11.4.1

XP FW: 23.5.11

Manufacturer’s Device Requirements

S1/S2 players

Driver Configuration

Device Names

Number of Players

– Set the number of players you wish to control.

Player

– Name: Give the player a display name (this does not need to match the Sonos defined name).

– Serial Number: The serial number as displayed in the desktop app.

Template Page Name:

Default: Sonos

Secondary: Music Player

Works with Sonos

Version 4.0 of the driver has undergone certification by Sonos. This means Sonos have tested the driver on RTI hardware to ensure it meets their requirements for both functionally and reliability.

**New with 4.09**:The driver now discovers all Sonos players on the network, whether you wish to control them or not. This is because the "coordinator" (the device which commands must be sent to) can be a device that you don't actually wish to control. This resolves the issue with previous versions of the driver where it would lose control after grouping/ungrouping. As a result of this, the more Sonos devices on the network, the more demand it will place on the XP processor.

To be clear: This does NOT mean you need to add every Sonos device on the network to the driver config. Only add devices you wish to control.

Identifying Players

The driver doesn't need any network information, feel free to keep the system using DHCP.

The driver needs to know the serial numbers of the players. The serial number can be found on the device or in the 'About My Sonos System' of any of the apps. It’s 19 characters long starting with 6 pairs of characters and ending with a single character. They should be separated by dashes, colons, or hashtags (See the very end of this file for a more detailed description).

Note: ENTER THE SERIAL NUMBER AS IT APPEARS IN THE DESKTOP APP.

A subwoofer does not need to be added to the configuration as it will never need to be sent commands on its own. Surrounds don't need to be configured either if they are always surrounds. The driver can adjust to surround speakers going back and forth from being surrounds to individual speakers to stereo pairs but this does increase the amount of processing power the driver uses so if they will always be surrounds feel free to leave them out of the configuration.

The names in the configuration will show when programming in ID. When the system is running there are two 'Name' variable to choose from. You can either use the name for the player given in the configuration or the current name of the player in the system itself.

**Important note**: Only players which you wish to control should be put in the driver properties, this will help alleviate some CPU load from the driver.

Stereo Pairs

When two players are to be connected in a stereo pair you have to be cautious. You cannot do this in the driver, it has to be done in the app but the order in which you perform the steps is important. Stereo pairs are created in the Settings menu in the apps. You select one of the players and go to the selection called Create Stereo Pair. There you will select the device to be the other half of the pair. Once you've done that it will ask you to select which one of the two will be the left speaker in the pair. This seems very obvious and innocent but has some important ramifications. The device selected as the left speaker also becomes the Coordinator, or master of the pair and all the commands must go to it. The other speaker is considered 'invisible' in the system and cannot respond to any commands. The driver can only send commands to devices in its configuration so if you create a stereo pair you only have to have one of them in the configuration, but it MUST BE the master (or left speaker) of the pair. This may not be the player that remains in the app. If both players are left in the configuration the driver will automatically send commands to the correct player.

Audio Player Control

The driver gives you all the audio controls for up to 32 players, including a 'selected' player: Transport, volume, play mode (shuffle, repeat) etc. It also allows you to choose any of the programmed 'Favorites' in the Sonos System.

Favorites/Playlist

The driver keeps a copy of the Sonos Favorites and Playlist. The main interface to this list is through the Favorites List and Playlist variables. Selecting an item in this list using the Select Favorite from List command plays the chosen favorite on the Sonos player. Using the Select Playlist plays the chosen playlist on the Sonos player.

There are 2 functions, 'Select Favorite' and 'Select Favorite Ex'. The 'Ex' function adds the ability to determine how the favorite is added to the queue. You can add to the end, replace the queue, play now or play next.

Favorite Icon Metadata

The icons are no longer part of the official Sonos API. They remain in the driver, but will always be blank.

Line Input Selection

Commands exist to have any player play the Line Input of any other device. You can also send a command to switch a Playbar to its optical input.

Groups

Any player can be synced to any other. When a player is following another its ‘is a follower’ variable will be set, when it is a Group Master its Group Master variable will be set. There are also boolean variables that will tell which players are following a given player (or the selected player). A separate command exits for removing that player from the group.

Driver Events

Driver events will be triggered on a change in the players transport status. Events are available for Stop, Pause, Play and Buffering. An additional event is available for a change in song title.

A driver event will also be triggered every time a player is sent a volume up or down command. This will help when volume commands are being sent to selected players, one of which is a Sonos Connect. In that situation the events can trigger macros that will change volume on your receiver. Similar events exist for the mute command.

Transport Control

Visibility variables accompanying each of the transport commands. Using the variables allow you to display only the buttons for currently relevant commands. For instance, the Show Previous Command will be false when a Pandora station is playing. If you use that as visibility on a Skip Back button it will disappear when a Pandora Station is playing. In addition a similar variable is available for Repeat and Shuffle; using that variable will allow your repeat buttons to only appear when they are relevant.

Template Information

The driver uses the following template: Sonos, Music Player

Music Service Provider Logos

The driver provides an index to a list of music service provider logos. This allows you to display the current streaming source (Spotify, Apple Music etc). Currently these logos are provided as a image group in a zip file shipped with the driver. To make use of this in your own project file you will need to unzip the images into your Integration Designer bitmap folder. The sample project shows how to use this new feature.

Limitations

Previous versions of the driver allowed you to get creative with how you entered the player serial numbers. This is no longer the case. You must paste in the serial number exactly as it appears in the Help -> About menu of the desktop app.

For example: 38-42-0B-22-A9-E1:E

System Testing

Integration Designer: 11.4.1

XP Processor Model: XP6s/XP8v

XP Processor Firmware: 23.5.11

Device Model(s): Port, Amp, Play:3, Play:5

Device FW: S2