jn-se / node-red-contrib-heos

A Node-RED node for integration of HEOS devices like Denon Home.

node-red-contrib-heos

• Introduction
• Installation
• Getting Started
• HEOS Nodes
  • Generic Nodes
  • Specifc Nodes
• Roadmap
• External Documentation

Introduction

A HEOS Node for Node-RED.

Use this node to integrate your HEOS devices into your Node-RED flows. HEOS ist the multiroom audio system by Denon.

Denon HEOS vs. Denon Home

This node supports the legacy Denon HEOS (HS) devices and as well the newer Denon Home devices. Both the Denon HEOS and the Denon Home devices are based on the HEOS system.

Installation

If you have already Node-RED installed you can install the HEOS nodes via the editor. Go to the Node-RED menu and Manage palette. Then select the Install tab and search for the package node-red-contrib-heos.

Getting Started

This package offers nodes to send commands to the HEOS network and listen for responses.

HEOS devices are normally autodiscovered in the network. So there is no need to configure a gateway if your Node-RED installation has access to your network and can search for HEOS devices.

The connection it established to an arbitrary HEOS device in your network that will then act as the gateway. The commands for a player are not adressed to a specific HEOS devices with an IP adress. Instead all commands are send to the gateway device but all commands are equipped with a playerID as recipient. The HEOS network will itself route the command to the appropriate player.

Use the Quickstart Guide and follow the steps to set up your first HEOS flow in a few minutes.

There are also some example flows available in the examples folder:

• Get Players: heos-get-players.json
• Set Player State: heos-set-player-state.json
• Set Player Volume: heos-set-player-volume.json
• Listen for Change Events: heos-listen.json

HEOS Nodes

This package offers two types of nodes:

• Generic nodes
• Specific nodes

Generic Nodes

HEOS Command Node

Send a custom command to the HEOS network.

HEOS commands include the following configurations:

• Command Group: The group of the command.
• Command: The command.
• Attributes: The configuration details for the specific command.

So this node is completely generic and can send any command to the HEOS network. For a complete reference of available commands please see the HEOS CLI reference linked at the bottom of this page.

For example to play or stop music use the following node configurations.

Play music

Configuration Item	Value
Command Group	player
Command	set_player_state
Attributes	{"pid":your-player-id,"state":"play"}

Stop music

Configuration Item	Value
Command Group	player
Command	set_player_state
Attributes	{"pid":your-player-id,"state":"stop"}

HEOS Listener Node

Listen for specific change events in the HEOS network.

HEOS change events include the following configurations:

• Command Group: The group of the command.
• Command: The command.

So this node is completely generic and can get any change event available in the HEOS network. For a complete reference of available events please see the HEOS CLI reference linked at the bottom of this page.

The data of the change event can be read from the output in the msg.heos attribute.

For example to register player state events (like play, pause and stop) or player volume events use the following node configurations.

Get Player State Events

Configuration Item	Value
Command Group	event
Command	player_state_changed

Get Player Volume Events

Configuration Item	Value
Command Group	event
Command	player_volume_changed

Specific Nodes

Specific nodes are more easy to use than the generic command node. Simply configure the playerID and the command.

Nodes available:

• HEOS Player State Node
• HEOS Player Volume Node

More nodes will follow in the next releases.

HEOS Player State Node

Send a player state command that allows you to quickly send states to a player.

Allowed states are:

• play
• pause
• stop

HEOS Player Volume Node

Send a player volume command that allows you to quickly change the volume level of a player.

Allowed levels are integer values between 0 and 100.

Roadmap

This node is currently under development. There is a roadmap of some tasks to be done for the next releases.

Version 1.x

• Review & stabilization.
• Add tests.
• Add more nodes.
• Review player groups and check generel conditions.

External Documentation

• HEOS API: HEOS CLI Protocol Specification (2021)

node-red-contrib-heos's Issues

Messages through command node

For easier setup with several HEOS devices it should be possible to send messages through command node. Now all messages are gone after the command node.
That way the pid could be set earlie and using same nodes for all HEOS devices instead of having one node for each function on each device.

Add Generic Node for HEOS Commands

A generic Node for all HEOS commands should be available.

Can be used for the following commands with a wizard mode:

• System Commands
• Player Commands
• Group Commands

Furthermore a custom command can be defined in the node following the standard HEOS CLI format.