search

home-assistant / architecture

Repo to discuss Home Assistant architecture
315 stars 99 forks source link

QR code scanning Zigbee 3.0 (ZB3) devices embedded into ZHA UI to add installation codes for pairing #440

Closed Hedda closed 3 years ago

Hedda commented 3 years ago

Context

Could the ZHA integration component support QR code scan Zigbee 3.0 devices for pairing ZB3 devices using qr_code parameter?

This is a new 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”).

This QR code can be used for secured pairing 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.

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 https://github.com/home-assistant/core/pull/40652 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
  • 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.

Consequences

This would need either support in Home Assistant companion apps for Android and iOS to scan QR codes and sent to HA / ZHA.

As such this would need some kind of collaboration between companion app developers and HA core devs, similar to tags.

Companion applications for Mac and Windows could also work.

Alternatively one would 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:

Hedda commented 3 years ago

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.

Hedda commented 3 years ago

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

So the QR code contains a device-specific 64-bit IEEE MAC address (“EUI64”) encoded and stored differently by each manufacturer?

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.

balloob commented 3 years ago

This is a feature request. Please post this in the feature request forum.

Hedda commented 3 years ago

This is a feature request. Please post this in the feature request forum.

https://community.home-assistant.io/t/request-qr-code-scanning-zigbee-3-0-zb3-devices-embedded-into-zha-ui-to-add-installation-codes-for-pairing/231185

Maybe relative to frontend/UI core developers as well as to HA companion app developers:

I read that all Z-Wave Plus V2 (also known as Z-Wave 700 series or Z-Wave Gen7) has copied this concept and will require QR code install.

Some Z-Wave Plus (Gen5) "S2" capable devices also support this same pairing via QR codes.

Z-Wave call this feature "SmartStart" and the purpose is the same, quick and easy to add many devices in one g: