Denon HEOS

This driver controls up to 16 Denon HEOS Players (Device/Stream/Speaker/Zone) via the network.

Special Notes -

The use of Player is interchangeable with (Device, Stream, Speaker, and/or Zone), meaning a HEOS Link is one player, a HEOS drive is 4 players and so on.

Firmware in each Denon HEOS device should be that of 1.373.120(r93909) or greater.

All Music Service account information needs to be linked to the HEOS account using the Denon HEOS iDevice/Android app.

You should familiarize yourself with the operation of the Denon HEOS system before creating a project with this driver. The Denon HEOS system uses concepts that are unique to media players and the driver variable/command system will be extremely confusing to someone not familiar with the operation of the Denon HEOS system.

It is also highly recommended that the included sample file be reviewed and understood before proceeding the implementation of HEOS controls into any existing system. Failure to understand the capabilities of the driver and any limitations it may or may not have can result in a less than desirable experience.

Revision History
1.0 Initial release of the driver

1.01 Added separate Now Playing Station Text variable for selected player and players 1-16.

Added code for cover art retrieval when initial attempt fails.

Fixed initialization issue with acquiring Now Playing Queue.

1.02 Fixed initialization issue if a player is removed from the driver configuration.

1.03 Adjusted browse list code for changes in HEOS firmware.

Added Error Code text variable.

Added Direct Service commands, variables, and events.

Adjusted initialization routine allowing driver to fully initialize when players may be offline.

Added Connected Player variable.

Fixed Optical and Line input selection issue.

Added code for forcing Station names to show when available for station/stream selections.

Added Play URL command for direct access to manually coded URLs.

Added Play Browse Item URL command for direct access to items available in the browse menu structure.

Added Browse Item URL sent XPDiagnostics messages for acquiring info to use in the Play Browse Item URL command.

1.04 *Fixed issue where some server containers in browse lists would not display completely.

1.05 Adjusted code for an issue that may happen when players sync during initialization.

1.06 Fixed issue in driver where initializing Now Playing Media may not execute when a player is offline.

Fixed issue when HEOS may respond with a music service id of 0.

1.07 Fixed possible discrepancy when adjusting volume up/down between driver and HEOS app.

1.08 Maintenance Update.

1.1 **Added Tidal to Music Service functions, variables, and events.

Adjusted Now Playing Metadata and Image acquisition routines for more reliable displaying when driver receives incomplete data from HEOS.

Adjusted code for acquisition of cover art when streaming Rhapsody/Napster.

Adjusted code for invalid Deezer cover art acquisition.

Updated XP Firmware and Integration Designer requirements for latest versions.

Updated HEOS version information in this file.

1.11 Fixed issue where last song in browse menu selections may not work correctly.

1.12 Fixed issue if views don't initialize properly.

1.2 Various code optimizations.

Added music services to root browse list.

Added provisions for additional music services.

Adjusted UPnP discovery for special character compatibility.

Adjusted player list acquisition for systems using special characters.

Added direct access to aux inputs.

Removed Play URL command.

Expanded Dynamic Music Service count to 24.

Rebuilt the entire grouping mechanism.

Added Direct Player Browse List Context Selection command.

1.21 Adjusted notification event subscription routine.

Adjusted code for dynamic music service icon acquisition.

Added Denon HEOS White Paper to driver download.

1.22 Adjusted notification event subscription refresh rate.

Added Browse Top Level command.

Added Connection Type Configuration for each player.

Adjustments for more accurate Thumb Up/Down visibility.

1.23 Added Browse List - Acquiring List Visibility variable.

1.24 Fixed Player Connection Type naming in driver configuration.

Fixed issue with browsing Playlist content across music services where available.

Adjusted Play Browse Item URL to Play Browse Item URL - Stream Only.

Added Play Browse Item URL - General command.

Changed Browse Item URL XPDiagnostics message to Stream Only Browse Item URL.

Added General Browse Item URL XPDiagnostics message.

1.3 Fixed Selected Player Selected Boolean variable authoring issue.

Added APEX compatibility.

1.31 Driver Maintenance

1.32 Changed Player Connection Type to Player Control Point Setting.

1.33 Fixed delimitation issue with a few commands and new HEOS firmware.

1.34 Driver Maintenance with additional debugging capabilities.

1.35 Adjusted Player Queue routines to check for content before commands are executed.

1.36 Fixed initialization error when all 16 players are configured.

1.37 Fixes issue with Spotify Connect causing the driver to crash.

1.38 Fixed Event visibility for ID APEX source compatibility.

1.39 Fixed issue when driver gets stuck in a Connected but Not Initialized state.

1.40 Added additional inputs for direct access.

Adjusted driver to check for login status during normal operation.

1.41 Added direct access to HEOS Favorites 1-20 via the Recall HEOS Favorite Preset command

1.42 Added HDMI In 3 & 4 functions, variables, and events for HEOS AVR & BAR

1.43 Adjusted incomplete packet combining routines for more reliability.

Fixed compatibility issue with secure cover art URLs (Amazon, etc.).

* Exception - lists containing more than 2500 items do not apply.

** Current Service Direct variables will need to be re-dragged to UI for added direct service updates.

Driver Configuration

Connection Settings

Connection Type - UPnP. The Denon HEOS driver uses UPnP to discover the HEOS devices on the network. All HEOS devices on the network need to be configured in the Player Settings section of the driver configuration. Up to 16 HEOS Players are supported in this driver.

Login Settings

HEOS Username - Enter the username for the HEOS account.

HEOS Password - Enter the password for the HEOS account.

Player Settings

Player (1-16) Friendly Name - Enter the Friendly Name of the HEOS device. This is the name given the HEOS device during the setup process with the HEOS iOS/Android app. Each player should have a distinct name, and the name should not be used for any other device on the network that supports UPnP. All HEOS devices on the network need to be configured in the driver.

Player (1-16) Control Point Setting - Select whether to use the HEOS player as a control point. It is not recommended to use wireless players as control point devices.

If a wireless player is set to be used as a control point, the driver may perform poorly or not at all.

RTI is not responsible for improperly configured systems, so proceed with caution when using this combination.

Driver Notes

- This driver connects and communicates to an individual HEOS device (Control Point). When the driver looks for the devices on the network it attempts to establish a connection and acquire full list of players from the first device discovered. If some devices are not available, the driver will list them as "Offline" in the player selection list and Player (Text) variables.

- All players configured in the system should have distinct names. No two players should be named the same unless creating a stereo pair (see additional HEOS White Paper included in driver download), nor should any player be named the same as any other UPnP capable device on the network. The names of the HEOS devices on the network need to be entered in the driver configuration exactly as they are named in the HEOS system. Failure to do so can cause connectivity and initialization issues.

- The driver must complete its initialization routine before any control commands can be issued. If needing to issue commands to HEOS devices during the startup process, the Initialization Finished event must be used to execute these commands. The driver locks out many of the control features while it is not initialized or in the initializing process. Use of the Players Found Status, Connection State, and Initialization Variables is recommended. The combination of these variables provides much of the information needed for seeing when the HEOS devices can be controlled.

- The driver uses the capabilities of Selected Players and Selected Groups. Players and Groups can interact with each other depending on how the system is configured. When players are in a group, the group has a leader. If a player is selected from the Player List or by using the Set Selected Player command and is in a group, the Leader will take over the controls and the Group Name should be used on the user interface.

- The Browse Lists in the driver are available only for Selected Players. Browse Lists are not tied to any specific players, therefore the user must have a way to select a player from the Player List or via the Set Selected Player.

- Direct Player commands and feedback are intended for use where the selected capabilities are not needed. An example would be transport controls on an RK1+ Keypad with no display capabilities and in a dedicated area where only one player is available.

- The Music Services are acquired from the HEOS system during initialization. The driver supports up to 24 Music Services. Some Music Services are currently not available or fully implemented through the HEOS 3rd party control, therefore they may not be available in the driver or may not work correctly. The graphics for the Music Services – Dynamic image variables are provided by Denon and cannot be adjusted from within the driver. Music Services availability and positions may change from time to time, therefore it is not recommended that specific graphics are used for displaying the services when using the Music Services – Dynamic commands and feedback. The text variables for displaying the Music Service names are also acquired directly from the HEOS system and are not adjustable from within the driver. See the Browse Original pages in the included sample file.

- Driver version 1.03 adds the ability to select a music service directly for browsing. Use the Select Music Service - Direct commands for these operations. There are also corresponding visibility and current service variables in the driver for these direct commands. This feature allows for the creation of buttons that do not dynamically change based upon the current music services available payload the driver receives, but selection of a direct service does require that the service was originally active on the system when the current music services available payload was received. See the Browse New pages of the included sample file.

- Driver version 1.2 adds available Music Services to the root level of the browse list.

- As of HEOS firmware version 1.289.95 (r64485), the Denon HEOS app shows a separate service for USB Music. Currently USB Music selection through the third-party API is only available in the Local Music browse menu structure.

- The driver supports the ability to dynamically change the way Browse and Player Queue Lists are viewed. Browse lists can show or hide Song, Album, and Artist information independently. Player Queue Lists can show or hide List Item, Song, Album, and Artist information independently. It is recommended that these commands and feedback are provided on the user interfaces capable of displaying lists.

- Player Queues can only be up to 300 items long in the HEOS system. It was however noticed during development of the driver that the Player Queue could contain 301 items. The 301st item however could not be selected from the Player Queue list, therefore the driver limits displaying any items above 300 in the Player Queue Lists.

- Player Queue count variables are provided in the driver. These variables are best suited to be displayed on any user interface pages with Browse Lists so that the end user/operator can see how many items are currently in the Player Queue they are adding items to.

- The Play URL command is intended for playing direct URLs from websites. – No longer supported by HEOS -

- The Play Browse Item URL - Stream Only command is intended for playing a direct stream that can be selected through the browse menu structure. To acquire the Stream URL information for the Play Browse Item URL - Stream Only command, please refer to the Stream Only Browse Item URL = information that is printed in the XPDiagnostics log page with the Denon HEOS driver set to a medium log level. The Play Browse Item URL - Stream Only command is actually the original Play Browse Item URL command so that systems already using this command to access streams directly will still work.

- The Play Browse Item URL - General command is intended for playing a direct browse menu item that can be selected through the browse menu structure. To acquire the URL information for the Play Browse Item URL command, please refer to the General Browse Item URL = information that is printed in the XPDiagnostics log page with the Denon HEOS driver set to a medium log level. This command is entirely new and will not work with URLs acquired using previous versions of the driver. URLs for this command MUST be acquired from the General Browse Item URL = information in XPDiagnostics.

- The Play Browse Item URL - Stream Only and the Play Browse Item URL - General commands are useful for directly selecting a specific Pandora station in the Pandora user account or directly playing an album or playlist that would be added to the Now Playing Queue. Many Browse Item URLs do not change once the HEOS system is set up, but they are system specific and there is still the possibility that access to a direct browse menu item could change at the discretion of Denon or the HEOS system.

- When using the Play Browse Item URL - General command, the driver will automatically replace the player or selected player PID. It is NOT necessary the pid=<player ID> be removed or replaced from the URL prior to pasting the URL into the command parameter.

- Search features are currently not available in the driver.

- Some features in the Denon HEOS app are currently not available in the HEOS 3rd party API.

- The driver imposes a 2500 item limit to browse list folders. The time to process browse list folders of various sizes will vary. Also keep in mind that browse lists are view based, so if simultaneously navigating large browse lists on from multiple UI devices, the system may seem unresponsive during these processes. It is highly recommended that the end user understands this as they may perceive the system as not working.

- Features that are available in the HEOS 3rd party API but are not in the driver yet have been currently omitted for reasons notwithstanding but may become available in future driver updates.

Special Grouping notes

- If setting up a system with multiple players, be sure to ungroup all players prior to reinitializing the driver when possible. It has been noted that if players are grouped while the driver initializes, some feedback from the HEOS system may be inaccurate and cause the driver to stall on its initialization process. If the system has any grouped players and does stall during initialization, please ungroup all players using the Denon HEOS app. Once that is done, the driver should be able to finish initializing properly.

- The entire grouping routine has been re-coded in version 1.2. The existing variables and functions will still work. Grouping is no longer dynamic in the sense that a group is created on the fly and takes the first available group slot. Instead, the driver now creates a separate group ID based off each player configured in the system. The actual group ID corresponds with the position the player is entered in the driver configuration, meaning group 1 corresponds with player 1, group 2 corresponds with player 2, and so on.

- When creating groups, it is no longer necessary to add the group leader to the Selected Group Player Add/Remove Queue as the leader is known for the selected group based off the selected group variable.

- Players cannot be grouped to multiple groups simultaneously.

- When adding/removing players from a group, it may be needed to refocus the group selection on the user interface to sync up all the group variable changes.

Special Notes -

The use of Player is interchangeable with (Device, Stream, Speaker, and/or Zone), meaning a HEOS Link is one player, a HEOS drive is 4 players and so on.

Firmware in each Denon HEOS device should be that of 1.373.120(r93909) or greater.

All Music Service account information needs to be linked to the HEOS account using the Denon HEOS iDevice/Android app.

You should familiarize yourself with the operation of the Denon HEOS system before creating a project with this driver. The Denon HEOS system uses concepts that are unique to media players and the driver variable/command system will be extremely confusing to someone not familiar with the operation of the Denon HEOS system.

It is also highly recommended that the included sample file be reviewed and understood before proceeding the implementation of HEOS controls into any existing system. Failure to understand the capabilities of the driver and any limitations it may or may not have can result in a less than desirable experience.