HS4 beta

[sifuhall]

I have been using (and loving) the sonos plugin since 2011 and I consider it a "must have" for Homeseer.

I recently moved to a new house and am ready to begin setting up my all new home automation.

I plan on starting with HS4 and would like to know if there is a beta or test version of the sonos plug in.

I'm more than happy to buy it upfront just based on the amazing support dcorsus has provided in the past.

[dcorsus]

No HS4 version released yet, but I'm quite close. Have to admit, I have been saying that for a while now, but there is at least one more fix I need from the HS team and I have a list of about 20 more things to fix and then we're good to go.

[TimSRQ]

Great to hear. Thanks and waiting in anticipation!

[dcorsus]

I think HS has solved all the blocking issues by now, so getting close to release. Still a bunch of stuff to clean up, now working on help file as well.
A preview of things to come and please provide feedback


Sonos Controller Plug-In for HS4.

Go to http://board.homeseer.com/forumdisplay.php?f=1085 for on-line forum support! Please read the help file and take traces before you post questions on-line!
Introduction

Welcome to the HS4 compatible version of the Sonos Plugin. If you have been a user of the previous version, do read the next sections thoroughly as a bunch of things have changed, some features were deprecated.

If you run into an issue or you have a question, when you post on the forum, what is required is:
1. Recreate the issue with debug logging on, typically the log level set to “errors and events” is sufficient.
2. Log to disk! It is easy and makes sure that all info is present as using the HS log to cut/paste loses HTML tag information.
3. Post screen shots of your configuration, ie. Player table, events, HS device page.
4. Detail what exactly you are doing and what exactly is not working.
READ THIS FIRST!!

1. The Plugin does NOT start automatically when you start if for the first time, you MUST acknowledge the UELA. Click on: Plugins->SonosV4->Accept and read the information before you accept.
2. The first time (only) when the Plugin starts, it will check if a previous version of the PI was installed, just by looking for the Sonos.ini file in the \config directory. If it finds a previous install, you can elect (while you go through the “Accept” menu) to migrate the information. This will preserve device references and linkgroups but it will not migrate events, you still would have to redo those. This migration is irreversible, do NOT do this unless you made a backup. After migration, all HS3 related Sonos PI data will be gone!!!
3. A while back Sonos added a cloud-based control API. This API is officially supported whilst the UPNP interface, that this PI has been using for the last 10 year, was never officially supported. I suspect that over time, they might move their strategy to only allow player control through this API. It could mean that many functions of this Plugin will not work anymore. This new API is a cloud-based interface, so control commands come through a very secure and encrypted internet tunnel. This cloud-based connection has been there for many years, and I believe is very secure. I added support for this interface in this Plugin version, but this requires you to authenticate the Plugin with Sonos, using a secure authentication protocol. You would be asked for your Sonos credentials, but directly from the Sonos website, without any knowledge of your credentials or storage of any information (except for a random key) by the Plugin. For now, the Plugin only uses this cloud-based API to play AudioClips (see further in help file on AudioClip info).
4. In almost all cases where HS is not automatically updating the state of players, the problem is that you did not allow the Plugin to have full access through the firewall on the HS PC. This is only a Windows issue. If not the firewall, it typically is because the Homeseer database conflicts with the Sonos.ini file, almost always due to manual intervention, such as deleting devices in HS, moving installs etc. So, make sure you allow the Plugin proper firewall allowance and do not delete devices manually from the HS devices page, use the Plugin’s config (player table) to do that.
Feature differences compared to HS3

New

1. Deleting of devices: I added support to keep the HS data and plugin data consistent. If you now delete a device from the HS device management page, the Plugin will remove its data from its .ini file. However, I would still not recommend you use this, because if you say delete the master device, everything will be removed, and you cannot undo it. If you delete a device while the PI is not running, at startup of the PI, a consistency check will run and try to undo inconsistencies. If you suspect an issue, restart the plugin, a special log file named \html\Sonos4\Logs\SonosVerifactionLog.txt will be created an record fixed issues.
2. Manual speakerclients versus automatic: in HS2/3, each time you created a “Speak” event, you had to create a manual speaker client. In HS4, you will have the options to pick from a list of speaker clients, one for each group you created and one for each player. This PI will use the word grouping more as opposed to group to be more in line with the Sonos terminology.
3. Support for households: If you have S1 and S2 controlled players, you now have 2 households, and you cannot group these players. They are seen as totally different networks, so you cannot mix them. This Plugin will try to support that by doing things like you can only create groups with players who are in the same household or do events like play something from the database that exists only for that household.
4. Browse directly on player: I added an option, currently only for navigating content using the player control webpages, to navigate content directly on a player. The advantage is that any content that changed is immediately available. If Sonos were to add features, you would be able to use them without the need to change the Plugin. However, it is a bit slower, and the selection options might be confusing or not working. Work in progress and currently disabled!
5. Better access to pick ports for VLAN based networks: the HS3 version already had support to nail down the listening ports but it was only accessible by directly modifying the .ini file. You can now see and modify the settings through UI support. Note this is only of importance if you use VLANs and you need to nail these down.
6. More filtering capabilities for debug: weeding through the logs is increasingly becoming harder for me to do. You now have options to only log a single player or use some filters.
7. iFrame support of embedding the play controls into your own HTML screens: one of the big changes in HS4 is the UI interface whilst for HSTouch users, the MediaAPI, which worked reasonably well in HS2, was not working well in HS3, is gone in HS4. If you look at the layout of the player control webpage, it is divided in 3 pieces (player, queue, navigation). You can drop these parts individually as iFrames into your own HTML pages and might be a good substitute for HSTouch missing functions.
8. Support relative volume setting and group volume setting: by adding a “+” or “-“ character to your volume setting events you can indicate a relative over absolute volume adjustment. Adding a “G” character would make it a group volume command over individual player command.
9. Added capability to hide paired players and non-status devices. It reduces the clutter on your device management page, the PI can now mark paired devices as hidden. It is not perfect because you can still overwrite it to show hidden devices but there currently is no other option available to Plugin authors to hide devices completely.
10. Added AudioClip capability which helps to restore services (virtual queue based ex Amazon/Alexa ..) after the announcement is over.
11. Support for categories: you can now add all Sonos devices automatically to a category if you want.
12. Added support for Move and Roam: These battery style players will now have a device to show battery state, sleeping state, Bluetooth state and a control (W L)to wake up the player when in sleeping mode.
13. Access to Sonos native tools like “Network Matrix”.
14. Display your network information.
15. Added support for Night-Mode and Dialog-Level: players who support Home Theater systems, will have two additional HS devices to turn these features on/off.

Removed

1. Dropped dock support and audiobooks. Not sure anyone ever used this, so I removed it.
2. Dropped support for announcements where a device running a speaker client is physically connected to the input of a Sonos Player. If you still have a setup like that, you will need to create an event that: Issue a group action, speak to that client, and unlink. 3 actions in one event.
Changed

1. Automatic creation of music database(s) per household: the settings were removed, and local music database(s) are now created automatically, either at start-up of the PI or daily at 2:05 am.
2. Announcements functions are almost completely rewritten, use more of JSON style information to allow better scripting. All information pertaining to an announcement is now stored as a JSON structure and intent is to make this available through scripting or virtual devices. Work in progress.
3. Added summary device in JSON formatted for scripting: in HS3, the control device had a XML-ish string that showed art and state. In HS4, I am trying to move away from that and created a “summary” device, encoded as a JSON string that has all the relevant info for that player. Still work in progress.
4. Faster player state updates in HS. In the previous version, state was updated when artwork was retrieved and/or players reached ‘PLAY” state. This could sometimes lead to long delays, before the state changed. Retrieval of album art is now asynchronous so state gets updated immediately but info like track, album, art, summary will now update asynchronously as well. So, pay attention to that in your events/scripts! Moreover, when a player moves from pause/stopped state to play state, depending on the content, the player will buffer the incoming stream, which takes time. Sonos players transition from Stop->Transitioning->Play state. In the HS2/3 version of this PI, the transitioning state was suppressed making events easier, less transitions but at the cost of triggers/events firing on state transitions from Stop/Paused to Play. There is an option setting now, to take the transitional event into account which cause immediate change in the player state from Stop/Pause to Transitioning, which can be used to trigger.
5. Configure what the State device shows: In the previous version of the PI, the state device would hold an XML formatted string, that had art, artist, album info. This device information is also used in the HS devices page when you go to a “Grid View” and causes display issues. There is now an option setting, to select what you want this device to show. I recommend you set it to “State”. For those who used this info to script, I recommend you use the JSON formatted “Summary” device to script on. It has more information, including pairing information and source information. If you set it to “Legacy”, do note that this device will be updated many times as the information it holds is retrieved asynchronously.

Configuration Settings


If you are having trouble discovering your players on your network or the player status is not being updated, check your firewall!! The plugin needs to have full access. The plugin also needs to run as administrator if installed in a protected Windows directory ex “Program Files x86”.

If you start the plugin for the first time on a Windows install, typically a firewall pop-up will show. DON’T IGNORE IT! Make sure the plugin has full access to local and public defined networks.




On the top of the Homeseer web page, click on the “PLUGINS” button, select “Sonos4” and click on “Settings”. Clicking on any of the players will open the Player Control Page for that player.




If the Sonos4 option is not showing, refresh your browser or check whether the plugin is installed properly.

Click on “Settings” and you will be presented with the configuration options. Note on top, that you have different tabs to select from.




Content Navigation Settings




All Sonos players have a database holding information about content they have discovered on your local network or favorites you have saved. The database does not have any information on external services, such as Pandora, Spotify or Amazon/Apple music. You cannot navigate external content except directly on the Sonos apps.

When this plugin was created a decade ago, most users would have local content and there were no such things as premium services. With slower networks and processors, this plugin would query the player, typically at night and retrieve the database information from the player and create a local database on your HS PC. This allowed for speedy navigating of content for cases where you create events based on track, album, artist information.

As of the HS4 version of this plugin, I removed the options around how and when to create this database, this now happens automatically when the plugin starts or once a day. If you have multiple households, or a split S1/S2 controller setup, the plugin will make a database for each household.

You can find the databases in the subdirectory \html\SonosV4\MusicDB and they are named “SonosDB_<householdname>.sdb”.

To support creating events based on radio stations you like, the plugin will store all information associated with a radiostation when you play them. This means that the plugin will learn about the radio stations you have played, and that information will be stored in another database, called the “radiostation database”. You can find that database in the same subdirectory and named “SonosRadioStationDB.sdb”.

You have the option to immediately kick off a retrieval of the database (create music database now) or delete the existing databases if you suspect a corruption.

The local music database is constructed around retrieving specific objects such as artist, albums, tracks, genre, favorites, radio stations and saved queues. As Sonos over the last few years seems to introduce a lot more services at a much higher pace, I am anticipating that they will roll out new services that will not be captured in the local database. The option “Browsing directly on player”, I added to avoid that I have to rewrite the plugin each time a service is added. Currently that option is disabled as it is work in progress, right now, not giving any benefit.

The “Max Navigation Items” setting affects the player control page only. When you start navigating, and say you select tracks and you have 30,000 tracks, this will prevent that your browser sits there for many minutes trying to download 30,000 items, including their album art.
Volume Settings




Sonos has a volume range from 0 to 100. If you create events or use the volume up/down features, here you can define the volume step.

Device Display Settings




There are a few differences between the HS3 version of this plugin and this version. The “State” device, for those coming from HS3, held a bit of a summary of what was playing (track, album, artist, art, state). In HS4, there is now a device grid view and this is causing display issues. If you do like the HS3 style, select “legacy”.
The default setting is “State” but if you like to show something different in the tiled-view, you can select to show Track or Track&Artist.

If you used the State information in HS3 to do scripting, you will find a “Summary” device in this version of the plugin, that is JSON formatted and holds a lot more information as compared to what was available in the HS3 version of the plugin.
Speaker Client Settings




When you create a “Speak Something” or “Play an Audio File” event action, in order to guide this PI where and how you want this action to be executed, you must select a Speaker Client. As of this version of the PI, you do not have to create a manual speaker client anymore and just select from the available list. This PI will create a speaker client for each announcement group you have created and for each on-line player that is not (slave) paired. However, if you have set HS to use a different userid/password from default/default and you have unselected the “No Password Required for Local (same subnet) Login” then this PI needs a matching password to create this speaker clients. You would have to enter it here. If you change the userid/password, click on “Reauthenticate Speaker Clients” or restart the PI to make this change effective.

Debug Settings




There are two very distinct sections in this PI you can log information from:
1. The generic functions in the PI under “Sonos Plugin Debug Settings”. Almost all traces you will be asked to do, will be around these functions. For normal operations I would recommend you set the level to “Errors Only” and for debugging, you would typically set it to “Events and Errors”. Hardly ever do you need the “Verbose” level. So, unless I asked, do not use it, too much logging, too much effort for me to inspect log.
2. Functions specify solely to discover and communicate with the players, a protocol called UPNP or DLNA. Its functions are grouped under “UPNP Debug Settings”. Hardly ever will I need information from here, so leave this to “Errors Only”. So, unless I asked, do not use it, too much logging, too much effort for me to inspect log.

Log to Disk option: you can of course use the built in HS functions to look at log entries, cut/paste them, search in them or select parts of it. Sometimes the information is many log pages long, or more critically, in order to show the log information using HTML in your browser, XML / HTML tags are removed from the display. More often than not, this information is important, so the option to log to disk will have all data in its raw format and might be easier to grab and upload as an attachment to your forum posts.
Important to know is how the checkbox selected/unselected works!! When you toggle it from on->off, the memory stream will be written to disk so if you want to make sure that the last piece of info is in the file, turn it off first. When you toggle it from off->on, it will rename the current log file with extension .bak and create a fresh log file. So if you only want to capture relevant log info, you either turn it on or if it was on you toggle from on->off->on which will force a new file to be created. Once you are done, you toggle off again and now you have just the relevant information to upload, making analysis most efficient.
Group Table Settings

[prsmith777]

Announcements functions are almost completely rewritten, use more of JSON style information to allow better scripting: still work in progress but all information pertaining to an announcement is now stored as a JSON structure and intent is to make this available through scripting or virtual devices. Work in progress.

Thanks for all your hard work.

So no more INI files?

Curious to see how the JSON implementation will work with scripting. I utilize scripting now to alter my announcement playlist on the fly based on room occupancy. Hopefully I will still be able to do this with JSON.

Still on HS3 for the foreseeable future, but getting this plugin working in HS4 is one less reason not to make the jump

[dcorsus]

Thanks for all your hard work.

So no more INI files?

Curious to see how the JSON implementation will work with scripting. I utilize scripting now to alter my announcement playlist on the fly based on room occupancy. Hopefully I will still be able to do this with JSON.

Still on HS3 for the foreseeable future, but getting this plugin working in HS4 is one less reason not to make the jump

still .ini file but wrt announcement no more individual entries for names, source and dest info. No more unreadable strings but one Json string that you should easily serialize /deserialize and use classes to compose the linkgroup. Plan is to have a call into the PI over modifying the ini file. I can paste an example when I get back home later today.

Other intent is to work without having to define linkgroups and/or use virtual devices

[prsmith777]

still .ini file but wrt announcement no more individual entries for names, source and dest info. No more unreadable strings but one Json string that you should easily serialize /deserialize and use classes to compose the linkgroup. Plan is to have a call into the PI over modifying the ini file. I can paste an example when I get back home later today.

Other intent is to work without having to define linkgroups and/or use virtual devices

Example would be great.

I think virtual devices would be a good idea. Im guessing you would have virtual devices for each sonos room that would store whether to make announcement in that room or not. Maybe also incorporate volume setting and any linkages with other rooms as well. Might be able to avoid scripting altogether this way which would appeal to broader audience.

[dcorsus]

Example would be great.

I think virtual devices would be a good idea. Im guessing you would have virtual devices for each sonos room that would store whether to make announcement in that room or not. Maybe also incorporate volume setting and any linkages with other rooms as well. Might be able to avoid scripting altogether this way which would appeal to broader audience.

Not sure I follow. Any time you have something dynamic, say a virtual device which MUST have some value, you are doing some form of scripting. If the virtual device always has the same value, you should create linkgroups. I guess you could do a lot of event logic but at some point, which one is easier?

Here's an example of 3 different kind of linkgroups: a regular, one that uses the audio-input on a player and one that uses the new Audio Clip feature

[linkgroup]
LG1={"destinationInfo":[{"udn":"RINCON_347E5C00D79101400","muteOverride":false,"v olu me":""},{"udn":"RINCON_000E58C174F201400","muteOverride":t ru e,"volume":""},{"udn":"RINCON_48A6B865C03D01400","muteOver ri de":true,"volume":"+10"}],"name":"LG1","sourcePlayer":"RINCON_48A6B8E0423E01400"," tts Option":"ttsregular"}

Audio In={"destinationInfo":[{"udn":"RINCON_347E5C00D79101400","muteOverride":false,"v olu me":""},{"udn":"RINCON_949F3ED52BEE01400","muteOverride":f al se,"volume":""}],"name":"Audio In","sourcePlayer":"RINCON_48A6B865C03D01400","ttsOption": "t tsregular"}

Audio Clip={"destinationInfo":[{"udn":"RINCON_48A6B865C03D01400","muteOverride":false,"v olu me":"+10"}],"name":"Audio Clip","sourcePlayer":"","ttsOption":"ttsaudioclip"}

Your classes would look like:


<JsonObject(MemberSerialization.OptIn)>
<Serializable()>
Public Class LGInfo
<JsonProperty(PropertyName:="name")> Public Property name As String = ""
<JsonProperty(PropertyName:="sourcePlayer")> Public Property sourcePlayer As String = ""
<JsonProperty(PropertyName:="ttsOption")> Public Property ttsOption As String = "ttsregular"
<JsonProperty(PropertyName:="destinationInfo")> Public destinationInfo As LGDestinationInfo()
End Class

<JsonObject(MemberSerialization.OptIn)>
<Serializable()>
Public Class LGDestinationInfo
<JsonProperty(PropertyName:="udn")> Public Property udn As String = ""
<JsonProperty(PropertyName:="muteOverride")> Public Property muteOverride As Boolean = False
<JsonProperty(PropertyName:="volume")> Public Property volume As String = ""
End Class

[goldriver]

dcorsus Hi, any ETA for the HS4 release ? been watching this thread for a while and not much movement for the last month or so ...

[dcorsus]

dcorsus Hi, any ETA for the HS4 release ? been watching this thread for a while and not much movement for the last month or so ...

Writting help file now. Still need to do some code around link/unlink. In another thread trying to get some insights from other PI authors on how to migrate events, seems not possible (in my case)

[sifuhall]

Glad to hear that. I will be moving to HS4 when this is released.

[dcorsus]

Update 6/4/2021

I think I'm done, appart from some migration code for which I'm waiting on the HS team to see if they can help out, the coding should be done. The documentation needs another weekend of focus and should be done.

I'm looking for a few individuals who are familiar and flexible to take something in, provide proper traces and descriptions when something seems off or bluntly doesn't work and can take direction in a timely fashion to trace something in more detailed. Users w more complex Sonos setups are welcome as well, but if you are novice in the art of beta testing, perhaps you want to sit this one out.

For those interested, PM me, and tell me why you are interested, what you want to get out of being a beta tester. I'll try to get an installer package created, that you would have download manually, perhaps install manually, I need to check if downloading the package in the installer subdirectory is enough to let the built in installer unpack it and create subdirectories etc.

I'll create a sticky post where we can post issues/questions, but make sure when new threads get created that we refer to the HS4 version.

Who's ready?

[sifuhall]

Update 6/4/2021

I think I'm done, appart from some migration code for which I'm waiting on the HS team to see if they can help out, the coding should be done. The documentation needs another weekend of focus and should be done.

I'm looking for a few individuals who are familiar and flexible to take something in, provide proper traces and descriptions when something seems off or bluntly doesn't work and can take direction in a timely fashion to trace something in more detailed. Users w more complex Sonos setups are welcome as well, but if you are novice in the art of beta testing, perhaps you want to sit this one out.

For those interested, PM me, and tell me why you are interested, what you want to get out of being a beta tester. I'll try to get an installer package created, that you would have download manually, perhaps install manually, I need to check if downloading the package in the installer subdirectory is enough to let the built in installer unpack it and create subdirectories etc.

I'll create a sticky post where we can post issues/questions, but make sure when new threads get created that we refer to the HS4 version.

Who's ready?

I'm glad to help in any way needed. I have sent a PM as well.

[dcorsus]

For this of you who reached out to me via PM, I will send you a zip file called Sonos4.zip.

Unzip this file first, there are two files inside:

1. Sonos4v4_0_0_0.zip
2. updater_override.json

Steps:

1. put both file in the HomeSeer home directory.
2. Go to the Plugins->Add section and you should see ONLY the Sonos4 PI under HS4 PIs, This is because the update_override file points the updater locally.
3. Select the PI and install it
4. Activate it
5. Refresh your browser to get the links updated
6. navigate Plugins->Sonos4->Accept and go through acceptance. SKIP the migration questions unless you intent to test this!!!!!!
7. When done, delete the updater_override.json file and Sonos4v4_0_0_0.zip from the HS root directory and all should be fine

Once the PI is installed, all subdirectories are created and we may not need to go through this step.

When I deliver new version of the PI, the names will change but the principle will remain the same.

The help file is all but complete, but I think the most important section about how to run it and what has changed is done. I wanted to get this out for those who have too much time on their hands this weekend