Custom improvement of the offial HA integration for Denon HEOS

UPDATE January 2022: The official integration Denon HEOS had grouping features implemented as of Home Asssitant version 2021.12 and this custom integration should not be necessary anymore. It may be deprecated after a time of testing. OBS! If using the mini-media-player card for grouping, note that platform must be changed from 'heos' to 'media_player' for the speaker_group setting (see here). Feel free to continue using the custom integration, it may be used for testing other features like media browsing and similar.

--

The official integration for Denon HEOS in Home Assistant unfortunately lacks the grouping feature. Work is ongoing to add such features to the official integration, but due to some architectual discussions and the time it takes to conclude those, this custom integration allows HEOS-users to start grouping already today. Once this is implemented in the official integration, this custom integration will probably cease to exist.

The grouping feature is available as service calls join and unjoin but for the best user experience I recommend using the amazing mini-media-card which has the grouping feature working from UI/Lovelace.

DISCLAIMER: I am not the codeowner of the official HEOS integration and do not take credit for anything else but adding a grouping-hack while waiting for official support of the feature. Credits for the hard work belongs to Andrew Sayre who is the author of both the official integration and the PyHeos library.

Installation

There are different methods of installing the custom component. HACS is by far the simplest way for unexperienced users and is recomended.

HACS installation

The installation is not - and never will be - included in HACS as a default repo. Mainly since it is only meant as a temporary fix for the lack of grouping feature. However, it can be installed through HACS by adding this repo as a custom repository. When installed it will override the official integration and a warning for using custom integration should be shown in your Home Assistant log upon startup.

1. Make sure you have HACS installed in your Home Assistant environment.
2. Go to HACS, select Integrations.
3. Click on the three dots in the upper right corner and select Custom repositories
4. Copy/paste the URL for this repo https://github.com/tmjo/heos_custom into the URL-field, select Integration as category and then click Add.
5. You should now find the Denon HEOS (Custom) integration by searching for it. Install it from HACS.
6. Restart Home Assistant (a warning should be shown in log saying you're using a custom integration).
7. Continue to the Configuration-section.

Manual

1. Navigate to you home assistant configuration folder.
2. Create a custom_components folder of it does not already exist, then navigate into it.
3. Download the folder heos from this repo and add it into your custom_components folder.
4. Restart Home Assistant (a warning should be shown in log saying you're using a custom integration).
5. Continue to the Configuration-section.

Git installation

1. Make sure you have git installed on your machine.
2. Navigate to you home assistant configuration folder.
3. Create a custom_components folder of it does not already exist, then navigate into it.
4. Execute the following command: git clone https://github.com/tmjo/heos_custom heos_custom
5. Run bash links.sh
6. Restart Home Assistant (a warning should be shown in log saying you're using a custom integration).
7. Continue to the Configuration-section.

Configuration

Configuration is done through UI/Lovelace. In Home Assistant, click on Configuration > Integrations where you add it with the + icon.

Usage

This custom integration should work the same way as the official integration but has added a grouping feature to enable you to group you speakers - just like you can do it in the HEOS app on you mobile or tablet.

Either use the service calls join and unjoin, and be sure to check out the amazing mini-media-card which has the grouping feature working from UI/Lovelace. With that card you can control grouping easily from your UI.

Issues and development

Please report issues on github. Keep in mind that this is a temporary fix while waiting for a perfect official integration, so minor stuff should be expected.

If you're a pro, please consider to direct your contributions towards the official integration as that would be the best solution for all. Follow the progress on official work (by others) here and here.

Feel free to propose PRs for improvements to this custom workaround too, or other features we could include.