openHAB

# Denon HEOS Binding

This binding support the HEOS-System from Denon. The binding provides control of the players and groups within the network. It also supports selecting favorites and play them on players or groups within the HEOS-Network. The binding first establishes a connection to one of the players of the HEOS-Network and use them as a bridge. After a connection is established, the binding searches for all available players and groups via the bridge. To keep the network traffic low it is recommended to establish only one connection via one bridge. Connection to the bridge is done via a Telnet connection on port 1255.

# Supported Things

Bridge: The binding supports a bridge to connect to the HEOS-Network. A bridge uses the thing ID "bridge".

Player: A generic player is supported via this binding. Currently no differences are made between the players. A player uses the Thing ID "player"

Groups: The binding supports HEOS groups. A group uses the Thing ID "group"

# Discovery

This binding supports full automatic discovery of available players to be used as a bridge, players and groups. You need to add a Bridge device first (which is also auto-discovered by the binding) which can be any HEOS device in your network (preferably which has wired connection).

Important! Please note that only one bridge is required to establish a connection. Adding a second bridge can cause trouble with the connection.

It is recommended to use the UI to setup the system and add all players and groups. The bridge is discovered through UPnP in the local network. Once it is added the players and groups are discovered via the bridge and placed in the Inbox.

# Binding Configuration

This binding does not require any configuration.

# Thing Configuration

# Bridge Configuration

The bridge has the following configuration parameter

Parameter Description Required
ipAddress The network address of the Bridge yes
username The user name to login to the HEOS account no
password The password for the HEOS account no
heartbeat The time in seconds for the HEOS Heartbeat (default = 60 s) no

The password and the user name are used to login to the HEOS account. This is required to load the favorites, playlists and so on from personal settings. If no login information is provided these features can't be used.

Bridge heos:bridge:main "name" [ipAddress="192.168.0.1", username="xxx", password="123456"]

# Player Configuration

Player have the following configuration parameter

Parameter Description Required
pid The internal Player ID yes

For manual configuration a player can be defined as followed:

Thing heos:player:player1 "name" [pid="123456789"]

PID behind the heos:player:--- should be changed as required. It is recommended to use the Player PID. If the PID isn't known it can be discovered by establishing a Telnet connection (port 1255) to one player and search for available players (Command: heos://player/get_players) within the network. Another way is to use the UI to discover the Player via the bridge and get the PID. For further details refer to the HEOS CLI (opens new window) specification.

# Group Configuration

Player have the following configuration parameter

Parameter Description Required
members The members of the groups. These are the player IDs. IDs have to be separated by ";" yes

Groups will automatically appear in the Inbox if that Group is active. To do this, build your Group from the HEOS app, then the group will appear in the Inbox.

Thing heos:group:group1 "name" [members="45345634;35534567"]

# Defining Bridge and Players together

Defining Player and Bridge together. To ensure that the players and groups are attached to the bridge the definition can be like:

Bridge heos:bridge:main "Bridge" [ipAddress="192.168.0.1", username="userName", password="123456"] {
    player Kitchen "Kitchen"[pid="434523813"]
    player LivingRoom "Living Room"[pid="918797451"]
    group 813793755 "Ground Level"[members="434523813;918797451"]
}

# Channels

# Channels of Thing type 'player'

Channel ID Item Type Description
Control Player Play (also ON) / Pause (also OFF) / Next / Previous
Volume Dimmer Volume control / also accepts "DECREASE" & "INCREASE"
Mute Switch Mute the Player
Title String Song Title
Artist String Song Artist
Album String Album Title
Cover Image The cover of the actual song
Inputs String The input to be switched to. Input values from HEOS protocol
CurrentPosition Number:Time Shows the current track position in seconds
Duration Number:Time The overall track duration in seconds
Type String The type of the played media. Station or song for example
Station String The station name if it is a station (Spotify shows track name....)
PlayUrl String Plays a media file located at the URL
Shuffle Switch Switches shuffle ON or OFF
RepeatMode String Defines the repeat mode: Inputs are: "One" , "All" or "Off"
Favorites String Plays a favorite. The selection options are retrieved automatically
Playlists String Plays a playlist. The selection options are retrieved automatically
Queue String Plays from the queue. The queue items are retrieved automatically
ClearQueue Switch Clear the queue when turned ON

The Favorites, Playlists, Queue selection options are queried automatically from the HEOS system (if you set up any in the HEOS app). This means the available options will be visible in a Selection, you don't have to specify them manually. You can send commands to these channels from rules by sending the name of the selected item (For example: Starting a favorite radio channel from rule).

# Example

Player LivingRoom_Control "Control" {channel="heos:player:main:LivingRoom:Control"}
Selection item=LivingRoom_Playlists     label="Playlist" icon="music"

# Channels of Thing type 'group'

Channel ID Item Type Description
Control Player Play (also ON) / Pause (also OFF) / Next / Previous
Volume Dimmer Volume control / also accepts "DECREASE" & "INCREASE"
Mute Switch Mute the Group
Title String Song Title
Artist String Song Artist
Album String Album Title
Ungroup Switch Deletes the group (OFF) or generate the group again (ON)
Cover Image The cover of the actual song
CurrentPosition Number:Time Shows the current track position in seconds
Duration Number:Time The overall track duration in seconds
Type String The type of the played media. Station or song for example
Station String The station name if it is a station (Spotify shows track name....)
Inputs String The input to be switched to. Input values from HEOS protocol
PlayUrl String Plays a media file located at the URL
Shuffle Switch Switches shuffle ON or OFF
RepeatMode String Defines the repeat mode: Inputs are: "One" ; "All" or "Off"
Favorites String Plays a favorite. The selection options are retrieved automatically
Playlists String Plays a playlist. The selection options are retrieved automatically
Queue String Plays from the queue. The queue items are retrieved automatically
ClearQueue Switch Clear the queue when turned ON

The Favorites, Playlists, Queue selection options are queried automatically from the HEOS system (if you set up any in the HEOS app). This means the available options will be visible in a Selection, you don't have to specify them manually. You can send commands to these channels from rules by sending the name of the selected item (For example: Starting a favorite radio channel from rule).

# Available inputs

Input names
aux_in_1
aux_in_2
aux_in_3
aux_in_4
aux1
aux2
aux3
aux4
aux5
aux6
aux7
line_in_1
line_in_2
line_in_3
line_in_4
coax_in_1
coax_in_2
optical_in_1
optical_in_2
hdmi_in_1
hdmi_arc_1
cable_sat
dvd
bluray
game
mediaplayer
cd
tuner
hdradio
tvaudio
phono

A current list can be found within the HEOS CLI protocol which can be found here (opens new window).

# Channels of Thing type 'bridge'

Channel ID Item Type Description
Reboot Switch Reboot the whole HEOS System. Can be used if you get in trouble with the system
BuildGroup Switch Is used to define a group. The player which shall be grouped has to be selected first. If Switch is then activated the group is built.

For a list of the commands please refer to the HEOS CLI protocol (opens new window).

# Dynamic Channels

Also the bridge supports dynamic channels which represent the players of the network. They are added dynamically if a player is found. The player and group channels are only shown on the bridge.

# Player Channels

Channel ID Item Type Description
{playerID} Switch A channel which represents the player. Please check via UI how the correct Channel Type looks like.

Example

Switch Player_1 "Player [%s]" {channel="heos:bridge:main:P123456789"}

The {playerUID} has either a P in front of the number which indicates that this is a player or a G to indicate this is a group.

# Full Example

# demo.things:

Bridge heos:bridge:main "Bridge" [ipAddress="192.168.0.1", username="userName", password="123456"] {
    player Kitchen "Kitchen"[pid="434523813"]
    player LivingRoom "Living Room"[pid="918797451"]
    group 813793755 "Ground Level"[members="434523813;918797451"]
}

# demo.items:

Player LivingRoom_Control "Control" {channel="heos:player:main:LivingRoom:Control"}
Switch LivingRoom_Mute "Mute"{channel="heos:player:main:LivingRoom:Mute"}
Dimmer LivingRoom_Volume "Volume" {channel="heos:player:main:LivingRoom:Volume"}
String LivingRoom_Title "Title [%s]" {channel="heos:player:main:LivingRoom:Title"}
String LivingRoom_Interpret "Interpret [%s]" {channel="heos:player:main:LivingRoom:Artist"}
String LivingRoom_Album "Album [%s]" {channel="heos:player:main:LivingRoom:Album"}
String LivingRoom_Favorites {channel="heos:player:main:LivingRoom:Favorites"}
String LivingRoom_Playlists {channel="heos:player:main:LivingRoom:Playlists"}

# demo.sitemap

Frame label="LivingRoom" {
    Default item=LivingRoom_Control
    Default item=LivingRoom_Mute
    Default item=LivingRoom_Volume
    Default item=LivingRoom_Title
    Default item=LivingRoom_Interpret
    Default item=LivingRoom_Album
    Selection item=LivingRoom_Favorites label="Favorite" icon="music"
    Selection item=LivingRoom_Playlists label="Playlist" icon="music"
}

# Detailed Explanation

This section gives some detailed explanations how to use the binding.

# Grouping Players

Players can be grouped via the binding. The easiest way to do this is to use the created Group type Thing. To group them simply use the Ungroup channel on the Group. Switching this Switch ON and OFF will group and ungroup that Group. The first player which is selected will be the Group leader. Therefore changing play/pause and some other things at any player (which is included in that group) will also change that at the whole group. Muting and Volume on the other hand can be changed individually for each Player also for the group leader. If you want to change that for the whole group you have to do it via the Group thing.

# Inputs

To play inputs like the Aux_In it can be played at each player or group. It is also possible to play an input from another player at the selected player. To do so, first select the player channel of the player where the input is located (source) at the bridge. Then use the input channel of the player where the source shall be played (destination) to activate the input.

# Example

Player A = Kitchen (destination) Player B = Living Room (source)

Items:

Switch HeosBridge_Play_Living "Living Room" (gHeos) {channel="heos:bridge:ed0ac1ff-0193-65c6-c1b8-506137456a50:P918797451"}
String HeosKitchen_Input   (gHeos) {channel="heos:player:918797451:Inputs"}
String HeosKitchen_InputSelect "Input"  (gHeos)

Rule for kitchen:

rule "Play AuxIn from Living Room"
when
    Item HeosKitchen_InputSelect received command
then
    if (receivedCommand.toString == "aux_in_1") {
        sendCommand(HeosKitchen_Input, "aux_in_1")
    }
    if (receivedCommand.toString == "LivingRoom") {
        sendCommand(HeosBridge_Play_Living, ON)
        sendCommand(HeosKitchen_Input, "aux_in_1")
        sendCommand(HeosBridge_Play_Living, OFF) //Switch player channel off again to be sure that it is OFF
    }
end

Sitemap:

Switch item=HeosKitchen_InputSelect mappings=[aux_in_1 = "Aux In" , LivingRoom = "Living Room"]

# The Online status of Groups and Players

The online state of a Thing can be helpful for groups to control the visibility of group items within sitemap. So if the group is removed the visibility of those items is also changed.

# Example

First you have to define a new Item within the Item section which is used later within the Sitemap:

Items:

String HeosGroup_Status

Then we need a rule which triggers the state if an Item goes Online or Offline.

Rules:

rule "Online State Heos Group"

when
    Thing "heos:group:1747557118" changed
then
    var thingStatus = getThingStatusInfo("heos:group:1747557118")
    sendCommand(HeosGroup_Status, thingStatus.getStatus.toString)
end

Sitemap:

Frame label="Heos Group" visibility=[HeosGroup_Status==ONLINE] {

    Default item=HeosGroup1_Player
    Default item=HeosGroup1_Volume
    Default item=HeosGroup1_Mute
    Default item=HeosGroup1_Favorites
    Default item=HeosGroup1_Playlist

    Text item=HeosGroup1_Song {
        Default item=HeosGroup1_Song
        Default item=HeosGroup1_Artist
        Default item=HeosGroup1_Album
        Image item=HeosGroup1_Cover url=""
    }

}

# Rule Actions

Multiple actions are supported by this binding. In classic rules these are accessible as shown in the example below:

 val actions = getActions("heos","heos:bridge:bridgeId")
 if(null === actions) {
        logInfo("actions", "Actions not found, check thing ID")
        return
 } else {
        actions.playInputFromPlayer(-3213214, "aux_in_1", 89089081)
 }

# playInputFromPlayer(sourcePlayer, sourceInput, destination)

Allows to play a source from a player to another player.

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← Deutsche Bahn →