[Sonos] [Media Players] [S1 & S2] Version [5.01]

Introduction & Manufacturer Profile

Sonos is a leading audio technology company that revolutionizes how people listen and connect to sound.

Since inventing wireless multi-room audio, we've continued innovating, creating wireless speakers, home cinema systems, headphones, architectural components, and whole home audio solutions that have defined categories, pushed the boundaries of what's possible, and delighted listeners all around the world.

Version History

Version 3.0

Initial Release

Version 4.0

Passed 'Works with Sonos' certification.

Version 4.05

Addresses issues with CPU Load on large systems.

Adds remaining time variable.

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.

Version 5.01

Added OAuth Authentication (required for both S1 & S2)

Added Search and Recently Played (Only works on S2 Devices).

Added new functionality for Playlists on S2 Devices.

Added Line-In, TV Mode, Night Mode and Speech Enhancement Events.

Removed Loudness and Stop Commands/Variables as they are no longer supported by Sonos.

System Requirements & Prerequisites

RTI System Requirements

Integration Designer: 11.9 or later.

XP FW: 22.3.31 or later.

Driver Information

This driver provides network control of Sonos Media Players.

If updating from V4.09, you will need to reprogram the Playlist variable for each player, and add a back button, As the playlist functionality has changed.

Authentication

The driver now requires the end user to give the driver permission to access their account.

This is achieved via the RTI dashboard.

Upload the project to the XP processor.

Once the driver has started up and discovered the local devices, point your browser at the XP processor by pasting http://xp.local/auth in your browser (or launch the URL provided by Integration Designer under the 'Driver Authentication Dashboard' section).

You should see the Sonos driver.

Click on Authenticate and have the end user sign in with their credentials and grant permission to the driver.

After a few moments, the driver will receive a token and will start to work.

Driver Configuration

Note: You can’t have a mix of S1 & S2 devices in the same system. The driver only works with a single household, so all players need to be from the same Sonos system.

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.

Driver Settings

Favorites list formatting

No Description: Only the title is displayed

Description in parenthesis: The title is displayed with the description in ().

Description on 2nd line: The title is displayed with the description on a 2nd line.

TV Mode Poll Rate

Frequency (in seconds) that the driver should poll a player in TV Mode for Night Mode/Enhance Dialog status changes.

Discovery Timeout

Number of seconds for the driver to wait for a response during startup.

On systems with a large number of Sonos devices, you may need to increase this value.

Recently Played Refresh Rate

Rate (in minutes) that the driver should refresh the recently played list. If you are not using the recently played list, this should be set to "None".

Search Settings

Title Text

String to display to indicate the user can search

Wait Text

String to display whilst search is being processed.

Image Type

None: Don't display any image in the search service list.

Badge: Display monochrome logo.

Icon: Display color logo.

Logo: Display white logo (Most compatible).

Clear Image Cache

The image URLs returned from the cloud service are cached to speed up future access.

Checking this box will result in the cache being cleared from persistent storage upon startup.

Template Page Names:

Default: Sonos

Secondary: Music Player

Works with Sonos

Version 5.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.

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 separated with a - and ending with a : followed by a single character (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' variables 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 app.

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.

The following functionality applies to both S1 and S2 devices

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.

The default Volume, Volume Up, Volume Down and Mute tags are associated with the Group Volume commands.

If a player is not in a group with other players, these commands will just act as the standard player volumes.

If a player is in a group with other players, these commands act as the group commands, so the volume commands will adjust all players in the groups volume relatively.

There is also a Player Volumes Popup command/variables that can be used to display a popup that you can use to show the individual players volume controls.

Favorites/Playlists

The driver keeps a copy of the Sonos Favorites and Playlists.

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.

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.

On S1 devices, Using the Select Playlist plays the chosen playlist on the Sonos player.

Line Input Selection

Commands exist to have any player play the Line Input of any other device.

TV Input Selection

Commands exist to switch a player to the TV Input (HDMI or Optical).

This requires the device to be in Home Theater Mode.

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 exists for removing that player from the group.

Transport Control

Visibility variables accompany 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.

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 an 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.

The following functionality is ONLY available on S2 devices.

Playlists

Using the Select Playlist will then show the contents of the playlist, along with Play and Shuffle options.

Selecting Play loads the chosen playlist on the Sonos player and starts playing it from the beginning.

Selecting Shuffle loads the chosen playlist on the Sonos player and starts playing it in Shuffle mode.

Selecting a track loads the chosen playlist on the Sonos player and starts playing it from the selected track.

Recently Played

Recently Played is only available if the option has been enabled in the Sonos App.

If you are not using Recently Played, then you need to set the driver configuration setting - Recently Played Refresh Rate to Never.

Otherwise set it to how often you want the recently played to be updated.

Be cautious as to how frequently it is updated as it can get to be quite a large amount of data to process.

To enable recently played in the Sonos App, go to Account/Privacy & Security/Personalization Services and enable Use Personalization Services.

Search

The driver uses the cloud API to search using user entered strings (via a virtual keyboard).

Search results are limited to a maximum of 5 items of each type.

For example, if you search for an artist, you may get results showing 5 albums, 5 individual tracks, 5 radio stations, 5 podcasts etc. related to the search string.

For a more in-depth search, you need to use the native Sonos apps.

Not all streaming services are searchable.

This is dictated by the license which Sonos has with each individual service.

The driver has no influence over this.

The following services are searchable so far –

Amazon Music (unlimited tier for album content).

Pandora

Sirius XM

YouTube Music (premium)

Deezer

Sonos Radio

Driver Events

Driver events will be triggered on a change in the players transport status.

Events are available for 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.

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

After a Sonos software update, the driver should reconnect to the updated devices within two minutes of the software update completing. If it doesn’t, reboot the processor.

System Testing

Integration Designer 11.11:

XP Processor Model: XP-8v

XP Processor Firmware: 24.3.29

Device Model(s): Port, Amp, Play 1, Era100

Support Contact

RTI Control

+ 1.952.253.3137

support@rticontrol.com