zigpy-deconz (ConBee/RaspBee adapter) and ZHA support for joining/pairing via install code and qr code?

[Hedda]

UPDATE: This is dependent on dresden-elektronik's deCONZ (ConBee) developers first adding support and documenting it, see:

• Does deCONZ serial protocol for ConBee/RaspBee Zigbee Coordinator adapters not support joining/pairing via install code and qr code? dresden-elektronik/deconz-serial-protocol#20

Back-story; Some users of Home Assistant’s ZHA integration with ConBee and RaspBee Zigbee Coordinator adapters from dresden elektronik have posted that they could not join/pair their Bosch Smart Home Zigbee devices that required an install code, and then some other users replied to that post saying that install code (and qr code?) support is not implemented in this zigpy-deconz radio library for zigpy which the ZHA integration depends on. Is that true?

zigpy-deconz/zigpy_deconz/zigbee/application.py

Line 108 in 80041b9

async def permit_with_key(self, node: t.EUI64, code: bytes, time_s=60):

Just reporting this issue reported in the Home Assistant community forum:

https://community.home-assistant.io/t/bosch-thermostat-2/492845/10

https://community.home-assistant.io/t/bosch-thermostat-2/492845/11

The first device in question was the Bosch Thermostat II 230 V (BTH-RA / BTH-RM230Z), however, I understand that some people using deCONZ or Zigbee2MQTT have reported the same issue with a few other Bosch-branded Zigbee devices, like Bosch Smoke Alarm II (BSD-2), Bosch Door/window contact II (RBSH-SWD-ZB), and Bosch BWA-1 water sensor, all of which require adding the install code to pair/join.

dresden-elektronik/deconz-rest-plugin#6476

dresden-elektronik/deconz-rest-plugin#6421

dresden-elektronik/deconz-rest-plugin#5190

I do not have a ConBee or RaspBee setup as Zigbee Coordinator myself any longer so can not replicate to confirm or deny but think this should be tracked if a feature is missing since supported by Silicon Labs and Texas Instruments based Zigbee Coordinator adapters via their respective radio library for zigpy.

PS: Both Silicon Labs (bellows) and Texas Instruments (zigpy-znp) radio libraries for zigpy do support install code (and qr code) or?

https://github.com/zigpy/bellows/blob/8549f277027245f5e63ce1341b7e6c5c75381899/bellows/zigbee/application.py#L845-L866

https://github.com/zigpy/zigpy-znp/blob/c4db8d1151b5a999ead73480faea4ea01b7cb7d7/zigpy_znp/zigbee/application.py#L338-L377

[puddly]

That's correct. There's no documented way to use install codes with the Conbee.

[Hedda]

Reposted to dresden-elektronik/deconz-serial-protocol#20 in hope @manup or someone else from Dresden Elektronik can assist.

[Hedda]

That's correct. There's no documented way to use install codes with the Conbee.

Is zigpy-deconz the only radio library for zigpy that doea not support this? Is there tests for this in the different zigpy radio libraries in order to check and track feature parity between them?

[puddly]

Is zigpy-deconz the only radio library for zigpy that doea not support this?

It's only supported on EZSP and ZNP coordinators. No other firmwares support it (and likely never will, aside from the Conbee).

[Hedda]

FYI, ChrisHae's reply to dresden-elektronik/deconz-serial-protocol#20 indicates this is in their roadmap for future deconz firmware.

Also updated the documentation for Home Assistant's ZHA integration to try to clearify that this is is a manufacturer limitation:

https://www.home-assistant.io/integrations/zha#limitations

"Support for commissioning Zigbee 3.0 devices via “Install Code” or “QR Code” via the ‘zha.permit’ service has so far only been implemented for ‘ezsp’ (Silicon Labs EmberZNet) or ‘znp’ (Texas Instruments) radio type in ZHA. Other radio types are missing support in their respective radio libraries for zigpy or manufacturer’s firmware commands/APIs."

[Hedda]

FYI, it seems deconz firmware support zigbee install codes as dresden-elektronik now implemented support in deconz-rest-plugin:

dresden-elektronik/deconz-rest-plugin#6791

Interestingly @SwoopX mentions in that PR that the code to derive the required hash is ported from the zigpy implementation.

dresden-elektronik/deconz-rest-plugin@24c7ff9

https://github.com/dresden-elektronik/deconz-rest-plugin/releases/tag/v2.22.0-beta

Enhancements: Enable usage of zigbee install codes dresden-elektronik/deconz-rest-plugin#6791

dresden-elektronik/deconz-rest-plugin#6476

dresden-elektronik/deconz-rest-plugin#6421

[Hedda]

FYI, Dresden-Elektronik developer has now updated deCONZ Serial Protocol documentation to 1.22 with info on install codes. See:

Originally posted by @manup in dresden-elektronik/deconz-serial-protocol#20 (comment)

Sorry this took a while, I had reworked the document since the former .docx based one was messy to update. The document references are in a bit rough shape but that's for another version. The new version 1.22 has now been uploaded http://deconz.dresden-elektronik.de/raspbian/deCONZ-Serial-Protocol_en_1.22.pdf

There is a new small section 6.2.3 Zigbee Install Codes which describes the basic usage.

As reference how it works in deCONZ the following sources might be helpful as well:

Calculating the derived Link Key from Zigbee Install Code (I think ZHA and Z2M already have similar code):
https://github.com/dresden-elektronik/deconz-rest-plugin/blob/master/crypto/mmohash.cpp

How the install code is processed by the REST-API and set to the firmware:
https://github.com/dresden-elektronik/deconz-rest-plugin/blob/0e2dc155e85893b439f354cd5d764e414ad0ed0c/rest_devices.cpp#L1090

Originally posted by @manup in dresden-elektronik/deconz-serial-protocol#20 (comment)

6.2.3 Zigbee Install Codes
The Serial Protocol and firmware doesn’t support Zigbee Install Codes directly. In order to join a
device via Install Code, a device specific Link Key needs to be derived from the Install Code by
the host application.
This 16-byte Link Key together with the device MAC address can than be configured by a Write Parameter Request (0×0B) for the Link Key parameter (0×19).
Once configured, during joining process, the device will receive the Network Key encrypted with
the Link Key instead of the global Truster Center Link Key.

A C++ OpenSSL reference implementation for the key derivation can be found at:
https://github.com/dresden-elektronik/deconz-rest-plugin/blob/master/crypto/mmohash.cpp

[puddly]

This has been implemented since https://github.com/zigpy/zigpy-deconz/releases/tag/0.22.0 in November 2023.

[Hedda]

This has been implemented since https://github.com/zigpy/zigpy-deconz/releases/tag/0.22.0 in November 2023.

@puddly Was it? Changelog does not mention "install code"? (I do not actually have a ConBee any longer so can not test myself).

ZHA docs need updating if device provisioning via install code and qr code is fully now supported via zigpy-deconz when using ConBee/RaspBee with the same functionality as available when using bellows (Silabs EZSP) and zigpy-znp (Texas Instruments ZNP):

• https://www.home-assistant.io/integrations/zha#limitations

"Support for commissioning Zigbee 3.0 devices via “Install Code” or “QR Code” via the zha.permit action has so far only been implemented for ‘ezsp’ (Silicon Labs EmberZNet) or ‘znp’ (Texas Instruments) radio type in ZHA. Other radio types are missing support in their respective radio libraries for zigpy or manufacturer’s firmware commands/APIs."