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:
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.
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:
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.
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:
The reply will be visible in a JSON format:
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.
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:
Open the Heos.vb script and in the following section the values accordingly your needs:
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.3 of the script is tested with 2 individual speakers running in the same Heos App. Both speakers are not assigned to a speaker group.
Newest features (>= version 2.3)
A Repeat virtual device is added with the following features:
- Off
- On One
- On All
A Shuffle virtual device is added withthe following features:
- Off
- On
When the HEOS username and password are added to script, the Favorites from the useraccount will be shown in a dropdown, per speaker.
Because of a bug in Homeseer, I’m not able to run a function when an entry from the dropdown menu is chosen. As a (temporary) workaround, I’ve created an additional virtual device that will “Run” the chosen favorite. In case someone has an idea to fix this right away, please add a comment.
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 volumeAdd player state buttons (play/pause/stop, etc)Add play type buttons (normal/shuffle/repeat, etc)“Result” device can be removedWith 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:
| 09-04-2020 | v2.3
Tested on Windows 8/10 with HS3 Pro v3.0.0.548 and
|
|
| 06-09-2018 | v2.0
Tested on Windows 8/10 with HS3 Pro and
|
|
| 02-09-2018 | v1.0
Tested on HS3 3.0.0.312 (Win8) and 3.0.0.435 (Win10) |
|
Downloads:
Heos v2.3 (45.4 KiB, 0 hits)
Heos v2.0.vb (26.5 KiB, 2,276 hits)
HEOS v1.0 (18.1 KiB, 1,745 hits)
Hi, Wow this is great! I’ve been wanting to do this for a long time and you’ve already done it! You’ve already done the heavy lifting and it’s a simple matter for me to tweak it to my situation and add a few features. Thanks do much for sharing!!
Very interesting Rutger, thanks for sharing!
May I ask about the extend of the functions that can be used?
I’ve looked at the HEOS CLI documentation (V1.13 dated 10/31, 2018).
It’s nice, but I’m missing a lot of functionality. For example: power on/off/standby……..isn’t there.
Am I using an old document or am I “missing the point of this interface”?
Hi Ton,
Tnx for the feedback. I’m currently in the transition to make the script ready for HS4, however since there are bugs in HS4 regarding creating buttons, additional features will come later.
In case you want to have certain features, I can put them on top of the list.
Kind regards,
Rutg3r
Will this work on HS3 installed on linux?
Hi Andre,
The script is tested on Windows. I don’t have any experience with HS3 on Linux unfortunately.
will this also allow me to select which “station” to play for example change from line in, to pandora, and back?
Hi Jimmy,
According the CLI command guide from HEOS: http://rn.dmglobal.com/euheos/HEOS_CLI_ProtocolSpecification.pdf chapter 2.1.3, it should be possible to create such a feature, but it isn’t yet available in my script.