Problem statement
Zigbee Green Power (ZGP) is the one feature gap that comes up whenever ZHA and Zigbee2MQTT are compared. Green Power devices are energy harvesting: battery-free wall switches, kinetic remotes and simple sensors that send a short, self-secured frame and go back to sleep. Friends of Hue switches (for example the Busch-Jaeger 6716 U), the Hue Tap and EnOcean modules all fall into this category, and they are sold in large numbers in markets where our community is strong.
Today these devices cannot be used with ZHA at all. The frames do reach the coordinator, but they were dropped before anything could act on them: the EZSP callback schema in bellows did not match the wire format, so frames failed to deserialize, and even once parsed there was no sink implementation in zigpy to pair a Green Power device or dispatch its commands. Users who want a Friends of Hue switch have to run Z2M, which is a choice they should not have to make on protocol grounds.
Closing this gap is the clearest single step towards the feature parity described in #93, and it lands in the shared zigpy layer, so every ZHA user benefits from it rather than only those on one radio.
Community signals
ZGP support has been the most requested missing zigpy feature for years. The tracking issue zigpy/zigpy#341 has collected well over 175 thumbs up, and it keeps resurfacing in forum threads, Discord and Reddit whenever someone buys a kinetic switch and discovers ZHA cannot see it.
Scope & Boundaries
In scope
- The Green Power sink role in zigpy: commissioning, pairing, notification dispatch, security and duplicate filtering, covering enough of the specification to serve the large majority of real devices
- Correct ZGP security: CCM* nonce construction, key protection and payload authentication verified against the published spec test vectors, plus frame counter based replay protection
- Persistence of commissioned Green Power devices and their frame counters, so a Home Assistant restart does not lose them
- Radio side forwarding for EZSP through bellows, covering the schema fixes across EZSP v4 to v18
- Exposing commissioned Green Power devices in ZHA, including a way for users to open a Green Power commissioning window from the UI
- SrcID addressed devices (ApplicationID 0b000), which is what every known consumer Green Power device uses
Foreseen solution
Land the ZGP work in stages rather than as one large change, so each layer can be reviewed and verified properly
- Stage 1: the radio agnostic parsing core in zigpy (types, frame parsing, crypto), validated against the specification's own test vectors
- Stage 2: the runtime on top of it (Green Power manager, device model, proxy table, controller wiring) plus database persistence
- Stage 3: EZSP forwarding in bellows, decoupled so it can be merged and released ahead of the zigpy runtime without breaking anything
- Stage 4: the ZHA side, so commissioned devices become entities and users can pair them from the Home Assistant UI
- Keep verifying against real hardware captures throughout, not only against round trip tests
Problem statement
Zigbee Green Power (ZGP) is the one feature gap that comes up whenever ZHA and Zigbee2MQTT are compared. Green Power devices are energy harvesting: battery-free wall switches, kinetic remotes and simple sensors that send a short, self-secured frame and go back to sleep. Friends of Hue switches (for example the Busch-Jaeger 6716 U), the Hue Tap and EnOcean modules all fall into this category, and they are sold in large numbers in markets where our community is strong.
Today these devices cannot be used with ZHA at all. The frames do reach the coordinator, but they were dropped before anything could act on them: the EZSP callback schema in bellows did not match the wire format, so frames failed to deserialize, and even once parsed there was no sink implementation in zigpy to pair a Green Power device or dispatch its commands. Users who want a Friends of Hue switch have to run Z2M, which is a choice they should not have to make on protocol grounds.
Closing this gap is the clearest single step towards the feature parity described in #93, and it lands in the shared zigpy layer, so every ZHA user benefits from it rather than only those on one radio.
Community signals
ZGP support has been the most requested missing zigpy feature for years. The tracking issue zigpy/zigpy#341 has collected well over 175 thumbs up, and it keeps resurfacing in forum threads, Discord and Reddit whenever someone buys a kinetic switch and discovers ZHA cannot see it.
Scope & Boundaries
In scope
Foreseen solution
Land the ZGP work in stages rather than as one large change, so each layer can be reviewed and verified properly