A new house, a new setup of almost everything. The oversized audio/video receiver Pioneer VSX-922 with 6 surround speakers is too much. I barely used it the last years and the WAF for all the external speaker is below zero… Wireless speakers like Sonos are booming and other manufactures want to join the ride as well. Most people in my neighourhood do have Sonos all around the house, but for multiple purpose solutions, Sonos is not the best option for me, therefor I did a lot of comparisons and HEOS had a match.

Because I’d never experience with a wireless speaker for longer than a few listening minutes, I didn’t know when size of speaker the best choice was. I started with the HEOS 3 HS2, which should for for smaller and medium sized rooms.

After 2 weeks of owning this speaker, I’m very positive of it and didn’t expect the high quality of played music, from severa sources. this speaker has also an USB and analog aux input and the app can connect to several online stations, like Spotify, TuneIn, Soundcloud as well to a local network music server, etc.

Controlling the music via the app is nice, but we want to check and control what is going on, from our home automation system. The Command Line Interface (CLI) protocol, which allowes external seystem to control systems to manage, browse, play, and get status from the Denon HEOS products. The control system sends commands and receives responses over the
network connection. The CLI commands and responses are in human readable (ascii) format. The command is a text string and the responses are in JSON format. The commands and responses for browsing music servers and services use a RESTFUL like approach while other commands and responses are more static.

The HEOS products can be discovered using the UPnP SSDP protocol. Through discovery, the IP address of the HEOS products can be retrieved. Once the IP address is retrieved, a telnet connection to port 1255 can be opened to access the HEOS CLI and control the HEOS system. It doens’t matter if a static or dynamically IP addres is used for the HEOS device.

HEOS CLI commands are in the following general format:
heos://command_group/command?attribute1=value1&attribute2=value2&…&attributeN=valueN
Command string delimiter is “\r\n”.
Note: Special characters, i.e ‘&’, ‘=’, and ‘%’ in attribute/value needs to be encoded to ‘%26(&)’, ‘%3D(=)’, and ‘%25(%)’. Most of the time, controllers use the same string that is received in previous command response. For example, while preparing ‘play_stream’/’add_to_queue’ command, controllers will use the strings obtained in ‘browse’ command response. Those strings are already encoded. So, controllers are not required to perform any special action. However, controllers might need to decode the encoded strings before they can be properly displayed on the controller GUI.

The responses to commands are in JSON format and use the following general structure:
Heos-JSON1
Some command responses will not include a payload. If the “result” of the command is “fail” then the “message” information contains the error codes for the failure. The error codes can be
found in section ‘Error Code description’. Some commands will also cause unsolicited events. For example, sending the ‘player/clear_queue’ command will cause the Player Queue
Changed event and could also cause the Player State Changed event. When the actual response can’t be populated immediately, a special response will be sent back as shown below. This usually occurs during browse/search as CLI needs to retrieve data from remote media server or online service.

Heos-JSON2

Test telnet connection

To test the network connection to the HEOS speaker, you can setup a telnet connection the the IP address of the speaker, with port 1255.

In your router, check the IP address of the HEOS speaker, or use the HEOS app: go to tab Music, and click on the settings icon in the top left corner. Go to “My devices”, select the speaker, go to “Advanced” and check the IP address.

In Putty it looks like this. Select connection type “Telnet”, enter the IP addres and port 1255 and click Open:

Heos-Putty

An “empty” telnet connection is now established. It look like the connection is not made, but actually it’s active now. When no connection is made, Putty will close the application by itself.

Heos-Putty-open

To test a HEOS command, enter without quotes the following command: “heos://player/get_players”. The best option is copy the text from here (or notepad) and paste it into the Putty screen with your mouse (right click in the Putty screen). The pasted text will appear and you can press Enter to activate it:

Heos-Putty-command

The reply will be visible in a JSON format:

Heos-Putty-Reply

To have this in a more readable output, it can look like this:

{  
   “heos”:{  
      “command”:“player/get_players”,
      “result”:“success”,
      “message”:“”
   },
   “payload”:[  
      {  
         “name”:“Huiskamer”,
         “pid”:-12345678,
         “model”:“HEOS 3”,
         “version”:“1.466.190”,
         “ip”:“192.168.178.16”,
         “network”:“wired”,
         “lineout”:0,
         “serial”:“ABCD1234567890”
      }
   ]
}

All CLI protocol commands are visible in the following document: http://rn.dmglobal.com/euheos/HEOS_CLI_ProtocolSpecification.pdf

 

Register for change events?

No. At least the HEOS 3 HS2 speaker support automatic sending of events via the telenet connection with command “heos://system/register_for_change_events?enable=on”. With this command the speaker will send a data change by itself. This could be really interesting, when it was populating ALL changed information, but it isn’t.

When this “change_event” command is activated, the following events are at least visible:

  • You can see that the track duration/timers is updating every few seconds.
  • You can see when I change the volume on the speaker itself (with the button on top of it)
  • You can see when I go the the next track in the app.

I would expect, when I changed the played track, that the artist, album, image url of album cover, etc, was populated as well, but it wasn’t. Because these changes are not visible directly, I decided to grab all “current” information from the speaker via a script “manually” and not based on event change. When the event updating is working in the future as expected, I just have to read every reply from the telnet connection and bases on the type of message, update the affected devices, which is in the end much simpler.

Heos-eventsON1

Prepare speaker name

In the HEOS app, configure your speaker with a decent name. This is especially usefull when having a mutiple speaker setup. The Homeseer script, will use the speaker name as a prefix to create the virtual devices. When you have set the speaker name to for example “Living”, it make much more sense then the default name “HEOS 3”.

 

Homeseer scripting

In C:\Program Files (x86)\HomeSeer HS3\Config\settings.ini, the following minimum requirements has to be visible:

ScriptingReferences=System.Core;System.Core.dll

If this is not the case:

  • Close Homeseer
  • Edit the settings.ini file (in \Config folder) with above information (use a comma seperator if you need to extend the existing entry)
  • Save the file
  • Start Homeseer

 

As decided, the automatic event updating is not as expected, so we will grab the reply from the CLI commands and rebuild the reply and update the affected virtual devices.

The script will make a telnet connection in the background (without Putty) to one HEOS speaker. Based on this it can grab the other speakers as well if applicable.

In the script, only the IP address has to be changed.

Create a recurring event in Homeseer, that will run this script, like this:

Heos-event

Open the Heos.vb script and in the following section the values accordingly your needs:

HEOSv2-UserChange
Save the script file.

When the script will run for the first time, it will use a command (which is used in the Putty example as well) to grab the speakerdata. Based on the name of the speaker the virtual devices are created when the Root device “<speaker name>_Root Device” isn’t available. From the 2nd run and further, the script will see that the Root device is already created and will update the virtual devices when applicable. When there is no update made on a certain virtual device, the device-last-change will not be updated.

The Root device don’t have a special function like Z-Wave devices have, but will contain the number of created sub virtual devices as a device value. It can be used later to extend the existing sequence to add more virtual devices.

In version 2.0 of the script this can be the result (you will see 2 speakers).

The “Office” speaker is currently playing media, therefor the Player State is set to “Play” and even the Album Cover is visible. The “living” speaker is not playing media, so the Player State is automatically set to “Pause” and no Album Cover is visible.

Version 2.0 of the script is tested with 2 individual speakers running in the same Heos App. Both speakers are not assigned yet to a Group.

HEOSv2-devices1HEOSv2-devices2HEOSv2-devices3

Some JSON objects are renamed to make it better visible, like the “ID” ones.

JSON object “Image_Url” is for example renamed to “Album Cover”. In specific JSON replies, not all objects are populated in Homeseer. You don’t want to see if all commands are received successfully, so for example for the “Player State”, the actual value “play or pause” is updated in Homeseer and not the command state and the received message from Telnet.

 

To do improvements:

  • Add volume buttons (up/down/toggle mute) to control speaker volume
  • Add player state buttons (play/pause/stop, etc)
  • Add play type buttons (normal/shuffle/repeat, etc)
  • “Result” device can be removed
  • With first script run, when a speaker is not playing any media, the “Track” info is not available in the JSON output and therefor the virtual device for this will not be created.
  • Test the script as well when speakers are grouped in the Heos app
  • Test the script when the Telnet connection is not closed after each script run

 

Release notes:

06-09-2018 v2.0

Tested on HS3 3.0.0.435 with

  • HEOS 3 HS2 speaker
  • HEOS 5 HS2 speaker
  • Grabbing information from all available HEOS (HS2) speakers in the network.
  • Volume buttons (up/down/mute/unmute) for each speaker device
  • Player State added buttons (play/pause/stop, etc) for each speaker device
  • “Track ID” device is created no matter the player state.
02-09-2018 v1.0

Tested on HS3 3.0.0.312 (Win8) and 3.0.0.435 (Win10)

  • Working with one speaker for now (2nd speaker is purchased)
  • Grabbing most useful information from one speaker and played media
  • Floor naming will be done in the format “Heos” & “name of speaker” ==> “Heos_Living”, for better overview

 

 

Downloads:

  Heos v2.0.vb (26.5 KiB, 64 hits)

  HEOS v1.0 (18.1 KiB, 64 hits)