Эта страница является переводом страницы Sonos. Перевод выполнен на 100%.

---

iRidium for Sonos

A set of tools to create control interfaces using a driver for Sonos sound systems.

The documentation was updated on 13.10.2022

iRidium for Sonos is a driver with the help of which an interface can be created to control Hi-Fi system without scripts. A native driver is easy to work with.

Sonos driver allows to:

• work with devices in a group or separately,
• make up playlists and play radio,
• control a player,
• display all available information about a performer, a soundtrack or a radio station in any convenient format.

Example Sonos

Connection

To work with Sonos equipment in the project it is required to know the IP-address of the sound systems and enter it in the driver settings. Do the following:

1 Connect Sonos equipment, IP-address of equipment is assigned automatically via DHCP.

2 Download Sonos Controller software for Sonos and launch it. The network is automatically scanned and equipment is displayed in "Rooms" section.

3 Information about network settings of Sonos equipment can be entered in several ways:

3.1 For PC.

3.2 Mobile app.

3.3 Scanning local network with the help of special software, for example. Advanced Port Scanner.

As a result of scanning there will be a list of devices, select the required ones. Sonos systems are displayed in the "Manufacturer" section as Sonos,inc.

After IP-address is identified, pass on to settings in iRidium studio.

To connect to Sonos there must be no blocks on UDP or multicast on the router.

Connection of Streaming Services

To play media contents from streaming music services, do the following:

1. Go to the Sonos official app;
2. Add a streaming music service to the device Manage > Service Settings > Add (authorization in the system of the music service is required). After addition, they'll appear in the list of services of the Sonos account and all media contents of the service will be available in the Sonos app;
3. Choose required media contents and click on it with the right mouse button;
4. There will appear a context menu, choose Add to Sonos Playlist or Add to Sonos Favorites;
5. Go to i3 pro. The added media contents appeared in the project.

Working in iRidium

1 Create a project, select "Add driver". Select "Sonos" in the list that appears and add it.

The Sonos driver work with one device by default. To synchronize all Sonos devices they must be grouped with the help on an additional driver - Sonos group.

You can read more about working with native drivers here

2 Fill in the fields in driver properties required for work.

Driver Properties

• Name - driver name, do not change it in a ready interface;
• Driver Type - information about the type of the driver;
• Protocol - protocol of data exchange - TCP;
• Log Level - depth of logging;
• Host - IP-address of equipment;
• Port - connection port (by default -1443).

Setting Commands and Feedback Channels

To control equipment it is required to set commands (Commands) and feedback channels (Feedbacks). To send a command, drag'n'drop it on a graphic item and enter a value to send. To display feedback value drag'n'drop a feedback channel on a graphic item and choose how to output or display a value.

Read more about work with graphic items in the "Types of graphic items" article.

Commands

• Name - the name of a command;
• Type - a type of a command:
  • Control - a type of commands to control equipment;
  • Selection - a type of commands for navigation.

Control

Control. Action.

Name	Description	Value
Play	Play a track, pause.
Volume	Volume control.	0-100
Relative volume	Control of volume relative to the current value of the feedback channel “Volume”.	0-100
Mute	Sound off.	True or False
Next song	Play the next track.
Previous song	Play the previous track.
Seek	Rewind track.	Value used on an element of Level type with Duration feedback .
Seek relative	Rewind a track relatively to the current position on the time-line.
Group volume	Command to control volume in a group (for several devices).	0-100
Group relative volume	Control of volume relative to the current value of the "Volume feedback channel" in a group (for several devices).	0-100
Group mute	Sounf off in a group (for several devices).	True or False
Update state	Update the state of feedback channels.
Repeat	Repeat playlist.	True or False
Repeat one	Repeat the current track.	True or False
Crossfade	Sound fades at the end of a current track and the volume gradually increases at the beginning of the next track.	True or False
Shuffle	Play a random track

Selection

Selection. Selected List

Name	Description	Value
Explorer	Navigation command (realized with the help of Advanced List).
Explorer back	Command to get back to the previous folder/page (realized with the help of Advanced List)
Explorer root	Command to get back to the root page		Value
Queue	Command to choose a track from a queue	Value
Clear queue	Command to delete a track from a queue	Value

Feedback Channels

• Name - name of feedback channel;
• Type - type of feedback channel
  • Control - type of feedback channels to control equipment;
  • List - type of feedback channels of a play list.

For convenience feedback channels of a driver are divided into different categories depending on it purpose.

Control

Control - фидбеки управления.

Name	Description	Value
Play	Current play status (play/pause).	1 - Play status, 0 - Pause status.
Player name	Name of player.	Value
Volume	Current volume.	0-100
Mute	Status of the Mute parameter.	1 - Mute is active, 0 - Mute is inactive.
Group name	Name of group (united devices).	Value
Group Volume	Current group volume.	0-100
Group mute	State of group Mute parameter.	1 - Group mute is active, 0 - Group mute is inactive.
Error	Error.	Value
Playbackstate	Current state of player.	Play, Pause, Idle, etc.
Position milis	Current position on the time line (in milliseconds).	Value
Is coordinator	Feedback channel that shows the main device in a group	Value
Error status	It displays the current status of an error	1 - an error is found, 0 - an error is not found. The status of a feedback channel is stored till "Reset error" command is activated.

Stream, Radio - feedback channels to get data from a stream.

Namr	Description	Value
Container image	Display of image.	Value
Container name	Name of a radio station.	Value
Current show name	Name of a radio show.	Value
Container type	Type of contents to play (in most cases it is “Track”).	Value
Container service	Name of service.	Value
Current stream info	Track that is on (performer + the name of a track).	Value

Indicators show a capability to use a command.

Name	Description	Value
Can skip	Go to next track.	1 - the command is available 0 - the command is unavailable.
Can skip back	Go to previous track.	1 - the command is available 0 - the command is unavailable.
Can seek	Rewind track.	1 - the command is available 0 - the command is unavailable.
Can seek	Pause.	1 - the command is available 0 - the command is unavailable.
Can stop	Stop playing.	1 - the command is available 0 - the command is unavailable.
Can repeat	Repeat current playlist.	1 - the command is available 0 - the command is unavailable.
Can repeat one	Repeat current track.	1 - the command is available 0 - the command is unavailable.
Can crossfade	"Fading" of tracks effect.	1 - the command is available 0 - the command is unavailable.
Can shuffle	"Shuffle" effect.	1 - the command is available 0 - the command is unavailable.

Modes - state of playing modes.

Name	Description	Value
Mode repeat	Repeat the current playlist.	1 - the Repeat mode is active, 0 - the Repeat mode is inactive.
Mode repeat one	Repeat current track.	1 - the Repeat mode is active, 0 - the Repeat mode is inactive.
Mode crossfade	"Fading" of tracks effect.	1 - the Repeat mode is active, 0 - the Repeat mode is inactive.
Mode shuffle	State of "shuffle" mode.	1 - the Repeat mode is active, 0 - the Repeat mode is inactive.

Current track info - information about the current track.

Name	Description	Value
Service	Name of service that is used to paly a track.	Value
Album	Album name of the current track.	Value
Type	Type of contents (in most cases - “Track”).	Value
Image	Image/cover of the current track.	Value
Artist	Singer/performer of the track.	Value
Name	Name of current track.	Value
Duration (ms)	Duration of track in milliseconds.	Value
Time	Duration of track.	Format 00:00:00 (hours, minutes, seconds)
Time passed	Time from the track start.	Format 00:00:00 (hours, minutes, seconds)
Time remaining	Time remaining to the track end.	Format 00:00:00 (hours, minutes, seconds)
Name/Artist/Stream	A united value for the name of a track, radio statio and the name of a performer.	Value
Album/Show	A united value for the name of an album or radio show	Value

Next track info - information about the next track.

Name	Desciption	Value
Next track Service	Name of service that is used to play the next track.	Value
Next track Album	Album name of the next track.	Value
Next track Type	Type of contents (in most cases - “Track”).	Value
Next track Image	Image/cover of the next track.	Value
Next track Artist	Singer/performer of the next track.	Value
Next track Name	Name of the next track.	Value
Next track Duration (ms)	Duration of track in milliseconds.	Value
Next track Time	Duration of track.	Format 00:00:00 (hours, minutes, seconds)

List

Name	Description	Value
Explorer	displays folders/play lists/services/radio stations/tracks on the popup with the same name.	Value
Queue	displays a queue of tracks to play.	Value

Position mills. Display of Track Length on Level.

Dynamic changes of a track length is applied to the Level item.

To display the cover it's required to assign the feedback of "Position mills" driver to the "Max" token of the Level item. It is done the following way.

1 Drag'n'drop the feedback of Position mills on a required item.

2 Choose "More" line and then choose Max parameter.

Image (Current). Display of track cover on an item.

To display the cover of a playing track it's required to assign the feedback of Image (Current)' driver to Image token of an item (to display the cover of a radio station the same method is used), It is done the following way:

1 Drag'n'drop Image (Current) feedback on a required item.

2 Choose "More" line, then choose State 1, Image.

Some images of radio stations/services are not displayed - it's an error of Sonos protocol.

Is Coordinator. Work of Devices in Group.

Is Coordinator feedback channel determines the role of a device. 0 value means that the device works in the Slave, 1 means that the device work in the Master mode.

The principle of device work in a group means that there are two roles for devices:

• Master - the main device that repeats commands for other devices in a group;
• Slave - a subordinate device that gets commands from Master.

0 value means that the device works in the Slave, 1 means that the device work in the Master mode.

Update State. Updating Feedback Values

Update State is a command that clears feedback values and requests Sonos device to display current data. Sometimes there can be mal-synchronization when the driver works with Sonons devices, to get rid of it, use the following command.

It updates values of the following feedback channels: Service, Album, Type, Image, Artist, Name, Duration, Time passed, Time remaining, Duration (ms), Time.

Explorer Setting

“Explorer” popup is required to display folders/playlists/tracks. It's also used for navigation and selection of a definite playlist that is made with the help of the Sonos native app.

1 To create Explorer popup, draw Advanced List item.

2 Create 3 “Templates” popups. Name them TplFavorite (to display the “Playlists” and “Favorites” folders), TplRoot (to display the contents of the “Playlists” folder) and TplPlayList(to display the contents of the “Favorite” folder). Create “Label” items on each popup - they are a sort of templates where folders, info about playlists, covers and track names are displayed.

An example of Label item created for TplFavorite popup.

3 After creating items, go back to the Advanced List item.

4 Go to the template settings by pressing the “Template setting” button.

5 Add popups with templates. Write type in the Code line as shown in the picture.

6 To set a template open it with a double click. Then add labels to it. Let's have a look at the setting of “TplFavorite” template. Enter favorite in the Type line then add other labels with required tokens: lbl.Name.Text; lbl.Type.Text; lbl.NextImage 1.State 1.Image.

After tokes are added write a value for each of them. To write in the Value line click 3 times on the line, Value for labels:

• lbl.Name.Text - name
• lbl.Type.Text - description
• lbl.NextImage - imageUrl

7 Set labels of the remaining “TplRoot” and “TplPlayList” templates in the same way.

“TplRoot”, enter Directory in the Type field. Create lbl.Name.Text label, enter name in the Value field.

TplPlayList, enter playlist in the Type field. Create labels:

• lbl.Name.Text, enter name in the Value field.
• lblTrackCount - enter trackCount. in the Value field.

8 After setting labels and templates, assign “Explorer” command and feedback channels to the Advanced list item.

To assign a command, click on Advanced List item and then click + in the programming window next to Press event,

Then choose Send tag in the window that appears and assign Select Item -> Commands -> Explorer.

Assign a feedback channel by clicking on the Advanced list item. Then go to the Data Source (next to Template setting). Choose Driver -> Feedbacks -> Explorer. On this stage the setting of Explorer popup is completed.

Queue Setting

“Queue” popup is required to display information about tracks in the queue to play add to select a required track from the queue.

1Create Advanced List item. CreateTplQueue template (to duplsay info about tracks to play in the queue для). The template has the followinf labels:

• lblName

lblType lblNextImage1

2 Set the template and labels.

Tpl.Queue, enter playlisttrack in the Type feld. Create labels:

• lbl.Name, enter name in the Value field;
• lblType- enter descri in the Value field;
• lblNextImage 1- enyer imageUrl in the Value field

3 Drag'n'drop Queue command and feedback channel on the Advanced List.

Assigning a command:

Assigning a feedback channel:

Sonos group

The "Sonos groups" driver is meant to control Sonos devices in a group.

This driver is an addition to the Sonos driver for sound system and is not meant to be used by itself in a project.

Driver Properties

• Name - the name of the driver, do not change it in the ready interface;
• Driver Type - information about the type of the driver;
• Protocol - protocol to exchange data - TCP;
• Log Level - depth of logging.

Setting Commands and Feedback Channels

To control equipment it is required to set commands (Commands) and feedback channels (Feedbacks). To send a command, drag'n'drop it on a graphic item and enter a value to send. To display feedback drag'n'drop a feedback channel on a graphic item and choose how to output or display a value.

Read more about work with graphic items in the "Types of graphic items" article.

Commands

• Name - the name of a command;
• Type - the type of a command:
  • Group - a command to group devices;
  • Ungroup - a command to ungroup devices;
  • Select - a command to choose devices for grouping.

Feedbacks

• Name - the name of a feedback channel;
• Type - the type of a feedback channel:
  • Players - the list of the current state of devices (grouped or ungrouped).

Setting Popup groups

“Popup groups” popup is required to select and group / ungroup devices in a list.

1 Create Popup groups popup and add Advanced List to it.
2 Create 2 “Templates” popups. Name them TplPlayer (an item meaning one device), TplGroup (an item meaning a group of devices). Create “Lable” items on each popup. They are a sort of templates where informaton about groups is displayed (name, number of devices, coordinator).

An example of Label itmes for TplGroup popup:

An example of Label itmes for TplPlayer popup:

3 After creating items, go back to the Advanced List item.

4 Go to the template settings by clicking the “Template setting” button.

5 Add popups with templates. Write type in the Code line as shown in the picture.

6 To set a template, open it with a double click. Then add labels to it. Let's see how to set “TplGroup” template. Enter group in the Type line (for TplPlayer Type = player), then add the following labels with required tokens: lbl.Name.Text, Selection.Value, lbl.Name 1.Value. After adding labels, write a Value to each of them. To write in the Value lines, double-click on the label line. Value labels:

• lbl.Name.Text - name,
• Selection.Value - selected,
• lbl.Name 1.Value - coordinator.

7 After setting labels and templates, assign “Select” command to the Advanced list item.

To assign a command, click on Advanced List item and then click + in the programming window opposite the Release event,

Then choose Send tag in the window that appears and assign Select Item -> Commands -> Select.

8 Assign Players feedback channel to the item. To do it, click on Advanced List item then go to Data source (it is next to Template setting). Select Driver -> Feedbacks -> Players.

9 Add 2 buttons to a popup (a button to group and ungroup devices) and drag'n' drop on them corresponding commands Group and Ungroup sending any value to a channel.