Community help wanted with adding some step-by-step information to ZHA integration documentation!
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 Installation-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
Today the process each end-user needs to figure out 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.
Currently the end-user need to go to ‘Developer settings’ tab → Services → service → Zigbee Home Automation: Permit → first type in source_ieee in 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 long install_code and then copy or type that formated correctly manually too, and finally press ‘call service’ before even putting the device into pairing/joining-mode.
You can help improve the documention by editing this page via GitHub webpages and then submit it:
https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/zha.markdown
If interested 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
OpenHAB user manual also includes some more basic information how and why to use install codes:
https://www.openhab.org/addons/bindings/zigbee/#install-codes
I like to suggest that 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.
By the way, 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:
and
Again, today the process and steps each end-user needs to figure out 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.
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.
Silicon Labs EFR32 Mighy Gecko / Wireless Gecko EmberZNet reference: