Problem statement
Home Assistant Core is starting to migrate complex integrations out of Core in order to keep the event loop stable and to begin hardening Core. ZHA is currently the largest integration still running in Core and concerns were raised about feature parity with Z2M as Z2M is already encapsulated in a HA app and implements a feature ZHA does not currently support: Zigbee Green Power (ZGP).
Based on an initial analysis we've further explored the possible futures for the ZHA integration and to propose paths forward. This effort is part of our public OHF roadmap opportunity to #6 and home-assistant/epics#20 in particular.
At heart, we always aim to retain choice. This of course also holds true when further shaping support for one of our core protocols. So focusing on adding missing features to ZHA while thinking about further investigating potential shared formats for quirk definitions with the Z2M team is key.
After all, offering an easy and approachable solution to our Zigbee users always remains a cornerstone.
Community signals
The existence of two parallel Zigbee stacks in the Home Assistant ecosystem is not a failure of consolidation. It reflects two genuinely different philosophies about where Zigbee complexity should live.
ZHA was built as a native HA integration, communicates directly with Zigbee coordinator hardware through a family of radio-specific libraries and runs in-process with Home Assistant, meaning the Zigbee network is managed inside the HA process itself. The philosophy is targeting a more seamless integration: one install, one UI, everything managed through HA's own configuration surfaces.
Zigbee2MQTT (Z2M) takes another approach running as a separate, platform-agnostic service that translates device messages to MQTT for any platform like HA to consume. Because Z2M runs as a HA app when you restart Home Assistant the Zigbee network itself is not interrupted. Z2M is also a completely independent open-source project with its own community of developers, including users who (might) don't use Home Assistant at all.
These two stances, tight integration vs. platform independence, are both reasonable approaches and both accumulated large user bases result in a certain split after all.
Device compatibility is another aspect and the underlying device gap has a structural explanation. Both ZHA and Z2M compensate in case manufacturers deviate from the ZCL specification by using quirks/converters (ZHA using quirks as per-device Python scripts in the zha-device-handlers and Z2M using zigbee-herdsman converters). There are comments that the contribution barrier going with Z2M's converter approach is lower and thus leading to a faster growing Z2M device list - but that should be left for the contributor to decide. Having a more unified quirks format could definitely be a key win here.
Finally, from a user's perspective the setup complexity is perceived is differently. Getting Zigbee2MQTT set up with Home Assistant is a much more involved process. Whereas for Z2M a MQTT broker, the Z2M app and respective configurations are required, ZHA by contrast aims to work as a plug-in: connect a supported Zigbee coordinator and start adding devices.
Scope & Boundaries
This is wip and further slicing is needed
In scope
- Move ZHA out of HA Core and into an app
- Write automatic migration to HA app for HAOS users. Manual steps for Docker users
- Implement Green Power (ZGP) support
- Improve APIs to make adding new devices simpler so that the ZHA community can support new devices more quickly
Not in scope
Foreseen solution
- Implement enough of the Green Power (ZGP) specification to support the vast majority of Green Power devices (including e.g. Hue)
- Finish the existing ZHA app, currently in a functional proof-of-concept state
- Adding AI skills and documentation for supporting new devices
- Further improve APIs to make supporting new devices easier, especially manufacturers like Tuya
Risks & open questions
Risks
- Ensure backwards compatibility with existing (custom) quirks
- Critical to get right to solve the issues both ZHA and Z2M suffer from
Open questions
- What are potential hurdles (like app translations) along the way?
Appetite
wip as it needs further slicing of scope defined above
Execution issues
No response
Decision log
Problem statement
Home Assistant Core is starting to migrate complex integrations out of Core in order to keep the event loop stable and to begin hardening Core. ZHA is currently the largest integration still running in Core and concerns were raised about feature parity with Z2M as Z2M is already encapsulated in a HA app and implements a feature ZHA does not currently support: Zigbee Green Power (ZGP).
Based on an initial analysis we've further explored the possible futures for the ZHA integration and to propose paths forward. This effort is part of our public OHF roadmap opportunity to #6 and home-assistant/epics#20 in particular.
At heart, we always aim to retain choice. This of course also holds true when further shaping support for one of our core protocols. So focusing on adding missing features to ZHA while thinking about further investigating potential shared formats for quirk definitions with the Z2M team is key.
After all, offering an easy and approachable solution to our Zigbee users always remains a cornerstone.
Community signals
The existence of two parallel Zigbee stacks in the Home Assistant ecosystem is not a failure of consolidation. It reflects two genuinely different philosophies about where Zigbee complexity should live.
ZHA was built as a native HA integration, communicates directly with Zigbee coordinator hardware through a family of radio-specific libraries and runs in-process with Home Assistant, meaning the Zigbee network is managed inside the HA process itself. The philosophy is targeting a more seamless integration: one install, one UI, everything managed through HA's own configuration surfaces.
Zigbee2MQTT (Z2M) takes another approach running as a separate, platform-agnostic service that translates device messages to MQTT for any platform like HA to consume. Because Z2M runs as a HA app when you restart Home Assistant the Zigbee network itself is not interrupted. Z2M is also a completely independent open-source project with its own community of developers, including users who (might) don't use Home Assistant at all.
These two stances, tight integration vs. platform independence, are both reasonable approaches and both accumulated large user bases result in a certain split after all.
Device compatibility is another aspect and the underlying device gap has a structural explanation. Both ZHA and Z2M compensate in case manufacturers deviate from the ZCL specification by using quirks/converters (ZHA using quirks as per-device Python scripts in the zha-device-handlers and Z2M using zigbee-herdsman converters). There are comments that the contribution barrier going with Z2M's converter approach is lower and thus leading to a faster growing Z2M device list - but that should be left for the contributor to decide. Having a more unified quirks format could definitely be a key win here.
Finally, from a user's perspective the setup complexity is perceived is differently. Getting Zigbee2MQTT set up with Home Assistant is a much more involved process. Whereas for Z2M a MQTT broker, the Z2M app and respective configurations are required, ZHA by contrast aims to work as a plug-in: connect a supported Zigbee coordinator and start adding devices.
Scope & Boundaries
This is wip and further slicing is needed
In scope
Not in scope
Foreseen solution
Risks & open questions
Risks
Open questions
Appetite
wip as it needs further slicing of scope defined above
Execution issues
No response
Decision log