Open Hedda opened 3 weeks ago
home-assistant[bot]
commented
3 weeks ago Hey there @dmulcahey, @adminiuga, @puddly, @thejulianjes, mind taking a look at this feedback as it has been labeled with an integration (zha) you are listed as a code owner for? Thanks!
Hedda
commented
3 weeks ago Examples of Zigbee 3.0 devices that require QR-code or Install-Code (where most do work with ZHA):
Note! ZHA integration components currently only support parsing QR install codes (qr_code) from these manufacturers:
Some newer devices from other manufacturers use it too but don’t think zha/zigpy support parsing all their QR-codes as of yet(?):
Feedback
ZHA integration documentation really needs some easier/simpler steps to follow for how-to pair/join Zigbee 3.0 devices that require install-code or QR-code for secure commissioning.
I do not personally own any Zigbee 3.0 devices that require install_code or qr_code for secure commissioning to be paired and joined securely but I have seen the question on how-to do this being asked enough in recent days that I think that the ZHA integration documentation could do with some simpler step-by-step notes about this to help ZHA and Zigbee beginners.
If anyone here in the Home Assistant community would be willing to help those new to ZHA and Zigbee by adding some easy-to-follow how-to instructions in the ZHA integration documentation for new users pairing (joining) Zigbee devices that require install_code and/or qr_code to pair/join for secure Zigbee 3.0 device provisioning via QR-code and/or Intallation-code?
Please see existing ZHA integration documentation here which in my opinion is lacking for new users:
https://www.home-assistant.io/integrations/zha#action-zhapermit
For reference, the QR code / Install Code is used as a unique value and passcode for secured joining/pairing with compatible Zigbee Gateway implementations that supports this Zigbee 3.0 feature. These QR codes are printed somewhere on newer Zigbee 3.0 certified products and are needed during provisioning in order pair/join the Zigbee 3.0 device securely.
If anyone has such devices please help improve ZHA documention by editing this page via GitHub webpages and submit a PR:
https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/zha.markdown
Currently the end-user need to go to ‘Developer settings’ tab → Services → service → Zigbee Home Automation: Permit → first type in
source_ieeein the UI. INSTALL then use some QR code scanner/reader app on your mobile-phone/tablet to scan and parse the QR-code from the physical device to get the 91 character longinstall_codeand then copy or type that formated correctly manually too, and finally press ‘call service’ before even putting the device into pairing/joining-mode.If interested in simplify steps for this then suggest could base instructions of these copied from Zigbee2MQTT devices docs:
Adding devices that require an install-code or QR-code
Some newer Zigbee 3.0 devices require that you enter an install-code or QR-code for secure provisioning/commissioning. When scanning the QR code you will get a code, (e.g.
ZB10SG0D831018234800400000000000000000009035EAFFFE424793DLKAE3B287281CF11F550733A0CFC38AA31E802).1. To pair this device you have to install the device via its installation code. 2. The installation code can be obtained by scanning the QR-code with your smartphone, (note that the QR code is often on the outside of the device but can sometimes be found on inside of the battery cover, a separate sticker or in the manual in the package). 3. Then get the device into pairing mode. 4. In zigbee2mqtt navigate to "Settings" --> "Tools" and click on "Add install code". 5. Paste the code you got from the QR-code and confirm by clicking "OK" which will get zigbee2mqtt into pairing mode automatically. 6. Wait for your device to be joined
Tip; OpenHAB's user-manual also includes some more basic information on what install codes are and how/why need to use them:
https://www.openhab.org/addons/bindings/zigbee/#install-codes
I like to suggest that for the ZHA documentation it might be a good idea to put the steps for this in its own sub-section under the "Adding devices" sections, or maybe the ZHA developers might feel that it belongs in the troubleshooting section(?).
https://www.home-assistant.io/integrations/zha#adding-devices
Also suggest adding a link to the ZHA limitations section which in turn states that due to a limitation is is today only possible to use install_code and qr_code pairing/joining with Silicon Labs and Texas Instruments based Zigbee Coordinator adapters:
https://www.home-assistant.io/integrations/zha#limitations
or just add a comment like this;
Note! The current version support is limited to using QR-codes and install-codes for secure Zigbee device provisioning/commissioning with devices from Aqara, Bosch, Consciot, and Embrighten. You also need to use a Zigbee Coordinator that is based on Silicon Labs or Texas Instruments Zigbee stacks.
URL
https://www.home-assistant.io/integrations/zha
Version
2024.8
Additional information
If you are a Python developer then might I suggest you also help improve the user interface for this feature by adding some UI frontend elements to the ZHA integration in Home Assistant to make it easier for anyone to add Zigbee 3.0 devices that require qr_code and/or install_code for secure Zigbee device provisioning/commissioning via QR-code and/or install-code. See these feature requests:
https://community.home-assistant.io/t/zigbee-device-provisioning-by-scanning-qr-code-qr-camera-scanner-in-zhas-ui-config-and-companion-apps-to-include-new-zigbee-3-0-devices-to-home-assistants-zha-integration/231185
and
https://github.com/home-assistant/frontend/discussions/12272
Again, today the process and steps that each end-user needs to figure out on their own in order to provision Zigbee 3.0 devices securely via QR-code and/or Installation-code is anything but easy and the opposite to being user-friendly, when it could be made to be as easy as scanning the QR code of newer Z-Wave or Matter devices which also uses similar methods for secure commissioning via the mobile companion app camera scanning the QR-code. See this Samsung SmartThings Outlet video guide as proof-of-concept:
Back-story; Home Assistant already have the equivalent “Z-Wave SmartStart” (‘Smart Start’) to allow QR code camera scanning for devices provisioning feature for adding Z-Wave devices to Z-Wave JS.
Could the Home Assistant UI and companion apps also support QR code scanning to add new Zigbee 3.0 (ZB3) devices for secure ‘quick-start’ joining/pairing in UI of ZHA integration component using qr_code parameter?
I think enabling this would be in the spirit of streamlining experience as this could enable users of the ZHA integration to simply open Home Assistant’s UI or companion app on Android/iOS, scan the QR code of the Zigbee 3.0 device or its box to initiate device joining/pairing in Home Assistant ZHA.
This is a Zigbee feature that is already available in the frontend GUI of a few commercial gateways/hubs.
I also understand that the required underlying backend support for “qr_code” and “install_code” is already available Home Assistant core for the ZHA component integration and the “install code” can already be entered manually in the shell by a user via a “zha.permit" service which allows nodes to join the Zigbee network.
Silicon Labs EFR32 Mighy Gecko / Wireless Gecko EmberZNet reference:
https://www.silabs.com/documents/public/application-notes/an1089-using-installation-codes-with-zigbee-devices.pdf 35
What Is an Installation Code?
Zigbee installation codes, sometimes also referred to as “install codes,” are provided as a means for a device to join a Zigbee network in a reasonably secure fashion. The installation code itself is a random value installed on the joining device at manufacturing time, and is used to encrypt the initial network key transport from the Zigbee network’s centralized Trust Center device (the coordinator) to the joining device. With the creation of the Zigbee 3.0 standard in late 2016, all Zigbee devices capable of joining networks (as opposed to forming them) must support the use of installation codes during joining, as this is a requirement for Zigbee 3.0 compliance.
The installation code can be thought of as similar to the PIN code on Bluetooth devices when two devices are paired. The PIN code is provided as an authorization code for the parent device so that the joining device knows it is receiving information securely, such as when a hands-free headset is paired to a smartphone.
The installation code is typically printed on the case or packaging of the device, either as a hexadecimal string or in an encoded fashion such as a barcode or QR code, and provided through an out-of-band mechanism to the Trust Center device or its associated web/cloud interface, along with the 64-bit IEEE MAC address (“EUI64”) of the device. If this device-specific data is stored on a remote web server or cloud-based system, that remote system then securely transports that information to the Trust Center to establish security credentials for the joining device in advance of the in-band joining process.