ZWave Entity IDs June 15, 2017 two minutes reading time

ZWave entity_ids have long been a source of frustration in Home Assistant. The first problem we faced was that depending on the order of node discovery, entity_ids could be discovered with different names on each run. To solve this we added the node id as a suffix to the entity_id. This ensured that entity_ids were generated deterministically on each run, but additional suffixes had to be added to handle edge cases where there would otherwise be a conflict. The resulting entity_ids worked, but have been difficult to work with and makes ZWave a strange exception among other Home Assistant components.

Thanks to the awesome work of @turbokongen, a growing number of ZWave configuration options are now available from the new ZWave panel in the Home Assistant frontend. Among these new features is support for renaming of ZWave nodes and their underlying values. (These renames are persisted in zwcfg_*.xml) This is important, because these items are combined to form the Home Assistant entity name, which is used to generate the entity_id. Now that these options are available, ZWave users can rename nodes and values, influencing the entity_ids that are generated by Home Assistant.

Now that users are able to control these names, we will be making changes to how the entity_ids are generated for ZWave entities. The ZWave entity_ids are going to switch back to using the standard entity_id generation from Home Assistant core, based on the entity names. Moving forward, if there is a conflict when generating entity_ids, a suffix will be added, and it will be the responsibility of the user to rename their nodes and values to avoid the conflict. This is the same as any other platform in Home Assistant where two devices are discovered with the same name.

With the release of 0.47, this feature will be opt-in. Setting new_entity_ids: true under zwave: in your configuration.yaml will enable the new generation. After 0.48 this feature will become opt-out. From 0.48 onward, unless you’ve declared new_entity_ids: false you will switch to the new entity_id generation. At an undecided point in the future, the old entity_id generation will be removed completely.

I’m sure all ZWave users understand that the current entity_ids aren’t easy to use. They’re annoying to type in configuration.yaml, and break if a node needs to be re-included to the network. We know that breaking changes are painful, and so we’re doing what we can to roll this change out as smoothly as possible. The end result should be a dramatic simplification of most ZWave configurations. We hope that this change will ultimately make ZWave much easier to work with, and bring ZWave configuration just a little closer to the rest of the Home Assistant platforms.