Zigbee device provisioning by scanning QR Code = QR camera scanner in ZHA's UI config and companion apps to include new Zigbee 3.0 devices to Home Assistant's ZHA integration?

Feature Requests
, ,
1

Could the Home Assistant UI and companion apps support QR code scanning to add new Zigbee 3.0 (ZB3) devices for ‘quick-start’ joining/pairing in ZHA integration component using qr_code parameter?

Enabling this could allow users to 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.

As I understand backend support for “qr_code” and “install_code” is already available Home Assistant core for ZHA integration via a “zha.permit" service which allows nodes to join the Zigbee network.

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

This is a Zigbee feature that is already available in the frontend of a few commercial gateways/hubs.

The QR code tags can be used as IEEE address (as a kind of UUID value) for secured joining/pairing onboarding processes with compatible systems that support this Zigbee 3.0 feature. These QR codes or bar codes should be printed on newer Zigbee 3.0 certified products in order to make adding new devices more user-friendly.

Examples are Samsung SmartThings and Tuya devices:

Samsung_SmartThing_QR_code_Zigbee_device

Tuya_QR_code_Zigbee_device
Tuya_QR_code_Zigbee_device346×749 36.7 KB

This Zigbee device QR code for pairing/joining is a ‘newish’ (part of official Zigbee 3.0 specification since 2016) feature that is part of Zigbee 3.0 security model specification which allow users to add devices to their Zigbee network by scanning quick response QR codes (a.k.a. two-dimensional barcodes or 2D barcode) which contains Zigbee installation codes, (sometimes also referred to as “install codes”), which is the devices 64-bit IEEE MAC address (“EUI64”).

Note that this requires a Zigbee 3.0 coordinator hardware + firmware compatible with Home Assistant as well as support for Zigbee 3.0 joining via install codes in the zigpy radio library, which so far is only supported in the bellows and zigpy_znp libraries.

@dmulcahey question was asked in Refactor zha.permit service to allow joining using install codes by Adminiuga · Pull Request #40652 · home-assistant/core · GitHub by @Adminiuga if QR code scanning be embedded into ZHA UI as that pull request also added to Home Assistant core support for qr_code parameter.

Add extra parameters to allow joining ZB3 devices using install codes. Currently only supported with EZSP based or TI (using zigpy_znp) radios.

Three new parameters were added:

  • source_ieee – IEEE of the joining devices, must be used with install_code, can’t be used with qr_code param
  • install_code – Install code of the joining device, must be used with source_ieee, can’t be used with qr_code
  • qr_code – QR Code of the install code, containing IEEE and install code. Can’t be used with source_ieee or install_code

qr_code is experimental and since every vendor encodes ieee and install code differently, this would need to be added for every vendor, assuming it can be matched by a regex. Based on a limited samples of QR install codes current attempt is to support the QR codes from the following vendors:

  • Aqara
  • Bosch
  • Consciot
  • Embrighten

Proposal

Allow adding Zigbee 3.0 devices by scanning the QR code on the physical device or box it shipped in if it has a QR code.

As an example you can look at the latest Samsung SmartThings app which has added Zigbee QR scanner:

Samsung SmartThings app now has the option to scan several Zigbee 3.0 QR codes to configure multiple devices in a single go.

https://support.smartthings.com/hc/en-us/articles/205957620-Set-up-and-connect-the-SmartThings-Outlet

Consequences

To make this feasible for ZHA, QRcode scanning and new Zigbee device setup would really need to be implemented Home Assistant companion apps for Android and iOS to scan QR codes and sent to ZHA.

The install code must probably be entered into the coordinator before starting the discovery process(?).

If so this would need some kind of collaboration between companion app developers and HA core devs, I assume that a similar effort to how the new tags feature got added to Home Assistant is needed:.

Companion applications for Mac and Windows could also work with this in the future?

Alternatively one would perhaps use web-camera directly to Home Assistant?

This would officially only work with Zigbee 3.0 certified devices, or at least only those are required to support the feature. List here:

2

Note! The ZHA integration currently only support QR install codes (qr_code) from these manufacturers:

  • Aqara
  • Bosch
  • Consciot
  • Embrighten

Some newer devices from others use it too but don’t think zha/zigpy support parsing all QR-codes yet?

  • LEDVANCE SMART+ (OSRAM SMART+)
  • Samsung SmartThings
  • Sengled
  • Philips Hue
  • Amina (Amina S EV charger)

Examples of Zigbee 3.0 devices that require QR-code or Install-Code (where most do work with ZHA):

  • Bosch Smart Home Zigbee 3.0 products:
    • Bosch Radiator Thermostat II (BTH-RA) - Bosch Smart TRV (Thermostatic Radiator Valve)
    • Bosch Universal Switch II (BHI-US)
    • Bosch Door/Window Contact II (BSEN-C2) - IP45 rated for outdoor use
    • Bosch Wireless Motion Detector (RFPR-ZB-SH-EU)
    • Bosch Smart Water Alarm (BWA-1)
    • Bosch Outdoor Siren ( BSIR-EZ)
    • Bosch Twinguard (8750001213) - smoke, temperature, voc, co2, aqi, illuminance, siren
    • Bosch Smoke Alarm II (BSD-2)
    • Bosch Plug Compact EU (BSP-FZ2) - Schuko smart plug used in most (but not all) of Europe
    • Bosch Plug Compact FR (BSP-EZ2) - French Plug Type E grounded smart plug used in France
    • Bosch Phase-cut Dimmer (BMCT-DZ)
    • Bosch Relay, Potential Free (BMCT-RZ)
    • Bosch Light/Shutter Control Unit II (BMCT-SLZ)
    • Bosch Room thermostat II (BTH-RM) - Battery-operated model for Bosch Smart Home
    • Bosch Room thermostat II (BTH-RM230Z) 230V mains-powered model

OpenHAB and Zigbee2MQTT also have Zigbee implementations that support install-codes/QR-codes:

ZigBee 3.0 requires that devices use an install code to securely join the network. This must be added to the binding before the discovery starts. Install codes should be printed on the box the device came in, or possibly on the device itself. Note that there is no standard format for how these codes may be displayed on the device or its packaging. You may need to use a QR reader to read the code - again these are not standard in their format, although you should be able to find the address and install code in the displayed text.

The install code must be entered into the coordinator settings before starting the discovery process. The format is IEEE Address:Install Code in the following format -:

AAAAAAAAAAAAAAAA:CCCC-CCCC-CCCC-CCCC-CCCC-CCCC-CCCC-CCCC-DDDD

ZigBee 3.0 requires the install code to be 16 bytes long (8 blocks of characters) but some older systems using this method may use less bytes, but it should still be formatted as 2, 4, or 8 groups of 4 values. Note that the last four characters in the install code are the checksum and may be provided separately.

Silicon Labs EFR32 Mighy Gecko / Wireless Gecko EmberZNet reference:

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.

3

qr_code is experimental and since every vendor encodes ieee and install code differently, this would need to be added for every vendor, assuming it can be matched by a regex. Based on a limited samples of QR install codes current attempt is to support the QR codes from the following vendors:

  • Aqara
  • Consciot
  • Embrighten

@Adminiuga So the QR code always contains a device-specific 64-bit IEEE MAC address (“EUI64”) but what complicate this is that each manufacturer can encode and store this IEEE address differently?

Maybe as a proof-of-concept for testing one could use a QR code generator to translate the IEEE addresses of some some devices you already own to QR codes, print that and paste at the equipment to test it?

By the way, LEDVANCE and OSRAM are other manufacturer(s) who provides QR code for joining devices, they are marketing their implementation of this Zigbee technology feature as “SMART+”, see:

4

Maybe a bit of off-topic but relative FIY to HA mobile companion app developers and core developers:

I read that all Z-Wave Plus V2 (also known as Z-Wave 700 series or Z-Wave Gen7) will have this same
concept and all new Z-Wave Plus V2 devices will require having a QR code as an inclusion/join feature.

Even some Z-Wave Plus (Gen5) “S2” devices already support this pairing/joining feature via QR codes.

Z-Wave call this feature “SmartStart” and the purpose is the same, quick and very easy to add devices.

SmartStart aims to simplify the process of Including Z-Wave devices and builds upon the functionality that was introduced by S2.

By removing as much user interaction as possible, SmartStart now makes it a breeze to add new devices to your Smart Home system - simple scan the device QR code in the Z-Wave controller App and power on the device!

SmartStart also introduces further enhancements such as the “Provisioning List”. This allows multiple devices to be Included simultaneously simply by powering them all on. For system builders and installers this will be a huge help, because now all device QR codes can simply be added to the Provisioning List in the Smart Home controller prior to shipping to site. The installer or customer then powers on the Smart Home controller and all the devices and the system will set itself up automatically!

For further details on all that changes with Z-Wave SmartStart make sure to read this:

5

FYI, Sengled Home app for Android and iOS has a QR code scan feature for its Wi-Fi based devices:

750×1334 86 KB

2400×2400 519 KB

6

To join the device via an install code you need to know the joining device IEEE address and the Install code. So the assumption is that a QR code should contain at least these two bits of information.
However each manufacture probably going to provide this information using different formats.
Scan a QR code and post it to ZHA issue tracker. The code contains sensetive information, so you may want to change some digits, especially on those that look like the ieee address. But do not add extra digits or remove digits.

7

@Quatuor Yes that is what @Adminiuga wrote in Refactor zha.permit service to allow joining using install codes by Adminiuga · Pull Request #40652 · home-assistant/core · GitHub

I think that the developer implementing this would have to own some devices themselves to test it.

What did you think about the suggestion of a developer using a QR code generator to generate their own QR codes and test translate the IEEE addresses of some Zigbee 3.0 devices they already own but do not have QR codes, print that and paste at the equipment in order to test it if willing to try developing a proof-of-concept?

8

I followed the link-

This talked about “QR code scanning for pairing/joining new Zigbee 3.0 device to Home Assistant ZHA integration component via mobile companion apps”

By following this link, I have to do the setup for Home Assistant’s ZHA which uses “ZHA.permit service” (helps to join a new device using an install code of ZB3 devices with the following data attributes):

zbee
zbee1117×535 35.6 KB

For the above attributes(especially, for install code) please let me know where to add these attributes in home assistant .

9

@DKumari this thread is a feature request as developers first have code support for QR scanning into Home Assistant’s UI, companion apps as well as code frontend support for ZHA UI to use such features.

Maybe @Bram_Kragten @dmulcahey @zacwest or David Luhmer (David-Development) would be willing to advise as they recently added Tags scanning support to Home Assistant’s UI and Android/iOS companion apps?

10

The screenshot is from Zigbee Home Automation - Home Assistant therefore it is logical to expect those attributes are related to zha.permit services which you can call (or you could call any other service) from Developers tab → Services → zha.permit and supply the service data

image
image1001×618 45.5 KB

11

Hi @Quatuor,

Basically, I used CC2531 with z-stack firmware version as- 3.0.x from the link to flash the CC2531.

https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/Z-Stack_3.0.x/bin/CC2531_20190425.zip

After flashing we connected the Home Assistant with CC2531 and followed the same procedure as mentioned above. I am able to see the ZHA.permit service in ZHA. But, not getting any of the allowed attributes as mentioned by you in the above image.
Please let me know if I missed something.

12

What do you mean by “not getting any of the attributes”??? you don’t get them, you supply them to the service call.

13

Is there any specific format to supply those attributes. Please let me know the exact format of it by giving an example

14

Like in the screenshot above??? https://community-assets.home-assistant.io/original/3X/6/3/637579ccb38f0e5f83b6b1868ad475e965ec1764.png

source_ieee: 11:22:33:44:55:66:77:88
install_code: 1234-5678-1234-5678-AABB-CCDD-AABB-CCDD-EEFF
15

Just following up, any chance some support will be added to Zigbee tuya devices?
I got two of these 2021 Tuya Zigbee 3.0 Smart LED Controller RGB+CCT 6pin Light Strip Controller Support tuya Zigbee and voice control accessories|RGB Controlers| - AliExpress, and I can’t figure out how to get it to work with homeassistant. The QR code scans into this format NB-###############$ZN######, where # is a digit between 0-9 (or this regex pattern ^NB-[\d]{15}\$ZN[\d]{6}$ ).
I tried parsing it manually into ieee and install code, but I may be lacking some knowledge here. Would love to contribute somehow if I could figure it out.

16

FYI, regardless if any Zigbee device could be joined via install code or not the device still needs to be already be supported by both the zha component’s Zigbee gateway application code as well as the zigpy libraries that it depends on as its underlying Zigbee framework, so a prerequisite question that you may have already answered yourself is if that specific device already works in zha + zigpy. See:

and

Also, the device itself might also need a custom device handler (quirk) before it will expose attributes:

1 Like
17

I’m confused. Has this been implemented or not? I see that I can add the qr_code parameter for zha.permit (Zigbee Home Automation - Home Assistant). Is this text that I need to add manually to the config file, or can I scan the QR code directly into HA? I don’t see a scanner, but wanted to confirm.

18

Support for joining via QR code is implemented in ZHA integration’s backend (i.e. the zha component in Home Asssistant’s core and the zigpy libraries that zha depends on), but scanning QR codes with a camera and parsing is not implemented in Home Assistant frontend(s) or in the Android and iOS companion apps for Home Assistant:

That is, the actual frontend UI parts to enable scanning of QR tags and handing over to qr_code for the zha integrations is still missing from the UI frontend for the ZHA integration.

For Z-Wave JS both frontend scanning/parsing and backend is missing for Z-Wave SmartStart inclusion, however the Z-Wave JS integration developers have added it to their roadmap wish list:

Update: FYI, QR-scanning has now also been added for Matter devices but still not yet for ZHA/Zigbee

19

FYI, it looks like @raman325 has started working on adding Z-Wave SmartStart provisioning support to zwave_js WS API in Home Assistant core. Hopefully, it will also lead to ZHA frontend support later as well:

https://github.com/home-assistant/frontend/pull/10726

home-assistant/core#59037

Also FYI; Z-Wave SmartStart QR scanning has been implemented in ZwaveJS2Mqtt’s as proof-of-concept, (feature in UI is however not named “Z-Wave SmartStart” but instead “Inclusion by QR Code”).

https://github.com/zwave-js/node-zwave-js/discussions/3381

20

FYI, QR scanning backend and frontend parts now added to the Z-Wave JS integration for SmartStart.

Both promoted in the latest release + also demoed in Home Assistant’s State of the Open Home video:

(Demo of Z-Wave SmartStart QR scanning starts at around 45 minutes and 30 seconds into the video).

https://www.home-assistant.io/blog/#z-wave-js-smartstart-and-entity-categories

"Z-Wave JS SmartStart and entity categories

Setting up your Z-Wave device with Home Assistant is now easier than ever, as Z-Wave JS now supports Z-Wave SmartStart!

When you have a SmartStart capable Z-Wave stick and device, you can now set up the device by simply scanning the QR code on the device, using your webcam, or using your mobile phone with the Home Assistant Companion app.

Including devices to your Z-Wave network has never been easier."

image
image860×923 106 KB