[REQUEST] ZGP (Zigbee Green Power) specification support #341
Description
Please add support for Zigbee Green Power device specification (ZGP clusters/endpoint standard subset) in zigpy + radio libraries.
https://csa-iot.org/all-solutions/green-power/
Note to end-users! If you are a non-developer (e.g. only an end-user of the Zigbee Home Automation integration in Home Assistant) then please do not post replies there to only ask for status. Instead you should just give a thumbs-upemoji to comments and posts, but please do not post "+1" or "me too" or "what is status" and other comments to this issue that will not directly related to the development of ZGP support in zigpy, or it will at least not encurage developers to work on this. As non-developers (i.e. end-users) please instead read and post to the Home Assistant's community feature request for general status questions or or off-topic discussions that are not directly constructive to developers for continuing with development of ZGP support in the zigpy library, so see -> https://community.home-assistant.io/t/zha-integration-to-get-full-support-for-zgp-zigbee-green-power-devices/277149
Zigbee Green Power is a Zigbee standard based on energy-harvesting technologies and is part of the larger Zigbee PRO standard. Full stack for ZGP commands is needed in zigpy and its radio libraries for zha to support batteryless Zigbee Green Power devices.
If goal is for zigpy library to become fully compliant with Zigbee 3.0 it needs to at least support ZGP v2, and if would allow using zigpy as a Zigbee Router (ZR) device then it also needs to at a minimum include ZGPB/GPB (Zigbee Green Proxy Basic) support too.
Summery; ZGP (Zigbee Green Power), a.k.a. "Zigbee GreenPower", is a subset feature of Zigbee that allows for extreme low-power and energy-harvesting technology to be used directly with the Zigbee stack. Using Zigbee Green Power, certain home automation wireless devices (end devices) may be powered by either different self-powered energy harvesting solutions or switches and sensors that can operate for up to a decade on a single battery coin-cell battery. Energy harvesting technology enables the maintenance-free battery-less devices (end devices) such as switches and remotes operating in a Zigbee network.
Zigbee Green Power is compatible with any Zigbee 3.0 device, but not all Zigbee 3.0 products are certified as Green Power Combo. Zigbee Green Power V2 is included as a subset in the Zigbee 3.0 specification (ZB3), while Zigbee Green Power V1 Green Power was a subset of an earlier Zigbee PRO standard.
Basic terms:
- ZGPD/GPD - Zigbee Green Power Device - a common Green Power device, which send specific Green Power packets (GPDF - Green Power Data Frames)
- ZGPS/GPS - Zigbee Green Power Sink - a Green Power device, which translates and transfers Green Power cluster commands to the relevant endoint
- ZGPB/GPB - Zigbee Green Proxy Basic - a Green Power device, which receives Green Power packets (GPDFs) and transmits Green Power Cluster commands; all Zigbee 3.0 routing devices must implement this
- GPCB - Green Power Combo Basic - Zigbee Green Power Combo Basic device includes two roles: Green Power Proxy and Green Power Sink.
"During commissioning ZGPD reports his device ID. ZGPS should check if there are appropriate local endpoints, which can communicate with such ZGPD device ID. This process is called ZGPS functionality matching. Matching table declares for each supported ZGPD device ID there are requirements to local endpoint in order to ZGPS functionality matching to succeed."
https://csa-iot.org/all-solutions/green-power/
https://csa-iot.org/all-solutions/green-power/green-power-faq/
https://zigbeealliance.org/wp-content/uploads/2019/11/Green-Power-White-Paper.pdf
ZGP (Zigbee Green Power) technology for battery-less self-powered or energy-harvesting devices. ZGP specification is a part of the official Zigbee 3.0 standard specifications and is supported by modern Zigbee Coordinator adapters (at least Texas Instruments and Silicon Labs). ZGP based devices are something also referred to as Green Power Device (GPD) or Green Power Devices (GPDs).
https://www.ti.com/lit/an/swra615a/swra615a.pdf
https://www.silabs.com/documents/public/user-guides/ug103-15-green-power-fundamentals.pdf
https://www.silabs.com/documents/public/user-guides/ug392-using-sl-green-power-with-ezp.pdf
https://developer.nordicsemi.com/nRF_Connect_SDK/doc/zboss/3.8.0.1/group__zgp__api.html
https://infocenter.nordicsemi.com/pdf/15-02016-010-GP_Errata_for_GP_Basic_PICS_DSR_Nordic.pdf
https://www.nxp.com/docs/en/user-guide/JN-UG-3095.pdf
And devices:
The reason for the request is that you can already buy many Zigbee Green Power (ZGP) enabled switches/remotes made for home automation, and they are in fact very popular since Philips Hue has several ZGP devices in several pf their product series/lineups.
According to the Zigbee Cluster Library Specification revision 7 (ZCL7), every Zigbee 3.0 device with routing capabilities (router or coordinator) must implement Green Power Basic Proxy (GPBP) v1.1.1 functionality for forwarding compatibility to be granted Zigbee 3.0 Certification in order to further support Zigbee Green Power capabilities.
Should be noted that a Zigbee coordinator can not normally connect directly to those Zigbee Green Power enabled switches/remotes as you need to bind them to a mains-powered device like a Zigbee lightbulb or a relay.
https://www.fierceelectronics.com/iot-wireless/zigbee-r-3-0-power-green
https://www.owon-smart.com/news/what-is-zigbee-green-power/
The requirements to run a Zigbee Green Power is found in the document from Texas Instruments:
See zigbee-herdsman PR #92 for proof-of-concept as ZGP is already supported in zigbee-herdsman / Zigbee2mqtt (Z2M) projects:
- Green Power support Koenkk/zigbee-herdsman#92
- https://github.com/Koenkk/zigbee2mqtt.io/blob/develop/docs/devices/GreenPower_On_Off_Switch.md
Most common examples of Zigbee Green Power devices for home automation are rocker wall switches. Certified ZGP products:
- https://zigbeealliance.org/zigbee_products/?product_type=certified_product&se=green+power
- https://zigbeealliance.org/news_and_articles/alliance-augments-its-green-power-program/
Most popular are devices based on Zigbee 3.0 pre-certified PTM215ZE/PTM215Z and PTM216Z modules from EnOcean:
- https://www.zigbee2mqtt.io/devices/PTM_215ZE.html
- https://www.zigbee2mqtt.io/devices/PTM_215Z.html
- https://www.zigbee2mqtt.io/devices/PTM_216Z.html
EnOcean PTM215ZE/PTM215Z and PTM216Z modules use energy converter for motion energy harvesting for battery-less operation that is sold to OEM/ODM radio modules which create products:
- EnOcean self-powered Zigbee product series and modules for OEM
- [EnOcean Easyfit Single / Double Rocker Wall Switch for Zigbee - EWSSZ / EWSDZ] (based on EnOcean PTM 215ZE)(https://www.enocean.com/en/products/enocean_modules_24ghz/easyfit-single-double-rocker-wall-switch-for-zigbee-ewssz-ewsdz/)
- [EnOcean Easyfit Single / Double Rocker Wall Switch for Zigbee - EWSSZG / EWSDZG] (based on EnOcean PTM 215ZE)(https://www.enocean.com/en/products/enocean_modules_24ghz/easyfit-single-double-rocker-wall-switch-for-zigbee-ewsszg-ewsdzg/)
- EnOcean PTM 215ZE / PTM 215Z (PTM215ZE/PTM215Z) module
- EnOcean PTM 216Z (PTM216Z) module
- EnOcean PTM 536Z (PTM536Z) Transmitter module with enhanced security features
- EnOcean PTM 535ZB (PTM535ZB) Transmitter module with enhanced security features with both ZGP and BLE radio
- EnOcean PTM 535Z (PTM 535Z) Transmitter module with enhanced security features
- EnOcean 2 click Clickboard from MikroElektronika for TCM 515Z (TCM515Z)
Friends of Hue partnership switches from ABB (Sweden), Illumra (USA), Kichler (USA), MAKRIS by Imoon (Italy), Vimar (Italy), Busch-Jaeger (Germany), Senic (Germany), Niko (Belgium), Sunricher (Hong Kong), Koizumi (Japan), Legrand (France), and John Lewis (UK) which I believe all use either the older EnOcean PTM 215ZE module or the newer EnOcean PTM 216Z module.
- https://zigbeealliance.org/zigbee_products/ptm215z-foh/
- https://www.signify.com/global/our-company/news/press-releases/2018/20180830-new-switch-and-new-luminaire-partners-offer-more-choice-in-design-and-control-of-your-philips-hue-smart-lights
- https://community.smartthings.com/t/theyre-here-new-green-energy-battery-free-wall-switches-for-hue-bridge-illumra-busch-jaeger-etc/135280
- https://www.docs.lighting.philips.com/en_gb/oem/download/xitanium/SCP_PHIL_170248_PMT215Z_table_A03.pdf
- https://www.docs.lighting.philips.com/en_gb/oem/download/connected-lighting-solutions/switch-commissioning-weblink1.pdf
Phoscon (dresden elektronik) posted these instructions for paring Friends of Hue switches with their deCONZ solution here:
Examples Philips Hue compatible ZGP switches:
- Philips Hue Click - Same as Philips Hue Tap wall-switch below?
- Philips Hue Tap (Wall Switch version)
- Philips Hue Tap Switch (Remote Control version) Model 9290011152X
- Philips UID8450 single-rocker switch (UID8450/10) and UID8460 double-rocker switch (UID8460/10) ZigBee Green Power switch and scene selector
- ABB smart light switch for “Friends of Hue”
- Illumra ZBT-S1AWH (single rocker, white) for “Friends of Hue”
- Niko Friend of Hue Smart Switch (Niko 91004) (based on EnOcean PTM 215Z)
- NodOn - Philips Hue Battery-less switch (CWS-4-1-01_HUE)
- Vimar - Friends of Hue RF Switch (Vimar 03906)
- Feller 4120.2.S.FMI.61
- Senic GIRA Friends of Hue Switch
- Senic GIRA Friends of Hue Outdoor Switch
- Sunricher Kinetic Switch 4 (SR-ZGP2801K4-FOH)
- Sunricher Battery Switch (SR-ZGP2801K4-FOH-E)
- LED TRADING Dimmer Switch
- LED TRADING Zigbee Push Button Coupler ( LED-Trading 9125)
- Legrand Batteryless Switches
- https://zigbeealliance.org/zigbee_products/batteryless-2-on-off-switch-green-power/
- https://zigbeealliance.org/zigbee_products/batteryless-2-toggles-switch-green-power/
- https://zigbeealliance.org/zigbee_products/batteryless-toggle-switch-green-power/
- https://zigbeealliance.org/zigbee_products/batteryless-shutter-switch-green-power-2/
- https://zigbeealliance.org/zigbee_products/batteryless-on-off-switch-green-power/
- Trio2sys PLANA - COMPATIBLE ENOCEAN ZIGBEE GREEN POWER COMPLETE SWITCH 2 KEYS
- Busch-Jaeger - Friends of Hue light switch
There are even a few Tuya made self-powered ZGP-based devices like these that do not require batteries:
Technical and developer documentation:
- https://zigbeealliance.org/wp-content/uploads/2019/11/Green-Power-White-Paper.pdf
- https://www.silabs.com/community/wireless/zigbee-and-thread/knowledge-base.entry.html/2020/02/13/zigbee_green_power-fKk4
- https://www.nxp.com/docs/en/user-guide/JN-UG-3095.pdf
- https://training.ti.com/zigbee-green-power-enable-battery-less-devices
- https://www.qorvo.com/resources/d/qorvo-zigbee-green-power-multi-sensor-comparison-to-battery-powered-zigbee-devices-white-paper
PS: If an end-user of Home Assistant wants to use ZGP (Zigbee Green Power) then they can not use the ZHA integration, and instead they as a workaround need to look at third-party Zigbee gateway/bridge/hub solutions that support ZGP, such as example Zigbee2MQTT, deCONZ/Phoscon, or commercial Zigbee gateways/bridges/hubs such as the Philips Hue Hub.