Protocol Specs

Table Of Contents

1. Overview

The Denon HEOS is a network connected, wireless, multi-room music system. The HEOS Command Line Interface (CLI) allows external

control systems to manage, browse, play, and get status from the Denon HEOS products. The HEOS CLI is accessed through a telnet

connection between the HEOS product and the control system. 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.

1.1 Supported music services

Supported online music services through CLI interface include Deezer, iHeartRadio, Napster, Pandora, Rhapsody, SoundCloud, SiriusXM,

Tidal, TuneIn, Amazon Music.

Other supported music sources include Local USB media, Local DLNA servers, HEOS Favorites, HEOS Playlists, HEOS History, HEOS aux

inputs.

2. Connection

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. The HEOS product IP address can also be set statically and manually programmed into the control system. Search target name

(ST) in M-SEARCH discovery request is 'urn:schemas-denon-com:device:ACT-Denon:1'.

The control system should use various Get commands to determine the players and groups currently in the HEOS system.

Controller software can control all HEOS speakers in the network by establishing socket connection with just one HEOS speaker. It

is recommended not to establish socket connection to each HEOS speaker. This is to decrease network traffic caused by establishing

socket connection to each HEOS speaker. Controller software can open multiple socket connections to the single HEOS speaker. Typically

controllers will use one connection to listen for change events and one to handle user actions.

2.1 Controller Design Guidelines

2.1.1 Driver Initialization

In order to reduce number of UPnP devices running on the network, HEOS Speaker runs CLI module in a dormant mode. HEOS speaker

spawns CLI core modules when the controller establishes the first socket connection to the speaker. What it all means for controller?

Inability of CLI module to process player commands. This is because, by nature of UPnP, CLI module need some time to discover

all players before they can be identified by their unique Id (pid)

Spew of events when controller initially connects to the speaker. In order to avoid excessive event handling in a event driven

controller system, the following initialization sequence is suggested:

Un-register for change events. By default speaker doesn't send unsolicited events but still it is a good idea to send

un-register command.This is done through 'register_for_change_events' command.

If user credentials are available, sign-in to HEOS user account. This is done through 'sign_in' command.

Retrieve current HEOS ecosystem status. This is done through commands like 'get_players', 'get_sources', 'get_groups',

'get_queue', 'get_now_playing_media', 'get_volume', 'get_play_state' etc.

If controller design involves disconnect and reconnect to HEOS speakers through CLI, it is recommended to keep a idle

connection to HEOS Speaker thus avoiding CLI module to set back to dormant mode.

2.1.2 Caveats

2.1.2.1 Compatibility

Please take a look at the following suggestions to avoid breaking controller code due to future enhancements

The 'message' field part of HEOS response is a string. The attribute value pair in this message string is delimited by '&'. Further the

attribute name and value is separated by '=' sign. Please note that new arguments can be added in the future.

New JSON objects may be added to the 'payload' as part of future enhancements.