Introducing Zigbee Direct#
This page provides background on Zigbee Direct and discusses how to configure a Zigbee Direct sample application in Simplicity Studio.
What is Zigbee Direct#
Zigbee Direct is a protocol standard that enables Bluetooth Low Energy (BLE)-capable devices, like smartphones or tablets, to onboard and optionally control certain Zigbee devices on a network. The Zigbee Direct protocol describes two types of devices: Zigbee Virtual Device (ZVD) and Zigbee Direct Device (ZDD).
A ZVD acts as a full BLE device that communicates with the ZDD over BLE. ZVDs have the option to run a Zigbee stack as well, however, this is not a requirement. In practice, a ZVD could be a smartphone application that acts like a network controller and can commission and interact with other Zigbee Direct Devices on a network.
The other device type, ZDD, is a full Zigbee device running an additional BLE stack that enables BLE communications with the ZVD. A ZDD can be any kind of Zigbee device type including an End Device, Router, or Coordinator / Trust Center. Currently, Silicon Labs only implements the ZDD for EFR32 parts with GSDK 4.3 or higher.
The Zigbee Direct Protocol is composed of three main services:
Zigbee Direct Security Service: A mandatory service that establishes a secure BLE connection between the ZVD and ZDD.
Zigbee Direct Commissioning Service: A mandatory service that enables the ZVD to control certain actions of the ZDD.
Zigbee Direct Tunnel Service: An optional service that allows the ZVD to send and receive Zigbee Network Packets to and from the ZDD.
Zigbee Direct requires any Zigbee Stack running on the ZDD (or the ZVD if applicable) to be Zigbee Pro R22+ or higher and the BLE Stack to be at least 4.0-Certified by Bluetooth SIG and to support Bluetooth Low Energy.
Zigbee Direct Provisioning#
The provisioning session is used to establish the connection between ZVD and ZDD. A main use case of Zigbee Direct is to leverage the ZVD's BLE to provision the ZDD and commission it onto an existing network, or for a ZDD to provision and commission a ZVD onto an existing network.
Below is a state diagram showing the ZDD's provisioning.
In the first scenario, where a ZDD is unprovisioned and its BLE interface is turned on, the ZDD is in the Open to be Provisioned state. In this state the ZDD sends out BLE advertisements in hopes a ZVD receives the advertisements and establishes a BLE link between the ZDD and the ZVD. The ZVD then starts a provisioning session with the ZDD that establishes a secure BLE connection. Once the provisioning session is complete the ZVD will have access to the Zigbee Direct Commissioning service and can configure the ZDD with all the required network information needed for the ZDD to successfully join the existing network. However, if a ZDD is in the Open to be Provisioned state and times out without a successful provisioning with a ZVD, the ZDD will close its BLE interface and transition to BLE Interface OFF state. The ZDD will need to be power-cycled or have a user interaction to re-open the BLE interface again to transition back to the Open to be Provisioned state.
In the second scenario, where a ZDD is connected to a Zigbee network and the BLE interface is turned on, the ZDD is in Open to Connect ZVD state. This state allows any authorized ZVD to access the Zigbee network through the ZDD or allows an unprovisioned ZVD to establish a provisioning session with the ZDD.
Zigbee Direct Security Service#
As mentioned in Zigbee Direct Provisioning, a ZVD and ZDD require a safe and secure BLE session to communicate with one another. When a ZVD and ZDD perform a secure session handshake it returns a session key that is used to establish a secure BLE session and an authorization level that grants the ZVD various levels of access to the ZDD. The levels of access include Admin and Basic authorization levels, both of which require an additional authorization session with an authorization key. If there is no explicit authorization session, the ZVD will have the lowest level of access that is granted to the ZVD with a successful provisioning session. The authorization level will remain consistent as long as the secure BLE session established between the ZDD and ZVD is active. The authorization level can only be upgraded or downgraded by establishing a new secure BLE session.
Two different keys are used to establish a secure BLE session:
The ZVD’s privileges granted from a provisioning session with a ZDD are:
Access to an unprovisioned ZDD's Zigbee Direct Commissioning Service (a provisioned ZDD Commissioning Service is only available to ZVD with Admin authorization established).
Activities that may lead to providing either a Basic or Administration authorization key.
With only a provisioning session the ZVD will not have access to the Zigbee network and will need to establish a new secure session, also known as an authorization session, using the authorization key to gain network access. The Basic authorization key can be derived from the Network Key and the ZVD’s EUI64, while the Admin authorization key can be derived from the TC Link Key and the ZVD's EUI64. The ZVD should never have direct access to network or link keys due to security concerns, so instead the ZVD receives a hash of the network keys and the ZDD's EUI64 instead.
Zigbee Direct Security Service Implementation#
The Zigbee Direct Security Service is a mandatory BLE GATT service that is used to establish the secure BLE session between the ZVD and ZDD. This service does not rely on BLE-specific security. The BLE GATT contains three main Authenticate characteristics that support both Write Requests and Indication:
Authenticate SPEKE/Curve25519/AES-MMO-128/HMAC-AES-MMO-128 Authenticate
Authenticate SPEKE/Curve25519/SHA-256/HMAC-SHA-256 (This is reserved for future use but not required)
Authenticate ECDHE-PSK/P-256/SHA256/HMAC-SHA-256-128
The Authenticate characteristic is used to exchange four specific messages that make up the secure session handshake. This handshake results in a session key that is then used to establish a secure BLE session between the ZVD and the ZDD. Note that the ZDD needs to implement at least one of the three Authenticate characteristics mentioned above.
Below is an example of establishing a ZVD using the Security Service to establish a secure BLE session using characteristic Authenticate ECDHE-PSK/P-256/SHA-256/HMAC-SHA-256-128.
Before the secure session handshake, the ZVD and ZDD establish a BLE Link where their BLE security is set to LE Security Mode 1, Level 1: No Security (no authentication and no encryption).
The initiator, the ZVD, first generates its Public Key Point and private key and decides which pre-shared key it wants to use.
The ZVD then sends out the first message to the ZDD to initiate the session establishment handshake. The first message contains the Pre-shared key type, Public Key Point, and Identifier (EUI64).
The ZDD receives Message 1 and validates the Initiator's Public Key Point and generates its own private key and Public Key Point.
The ZDD responds with Message 2 that includes its own Public Key Point and its Identifier (EUI64). From here both the ZVD and ZDD derive the session identifier and the session key.
The last messages 3 and 4 are sent to confirm the session key is correct on both sides. After the four messages are complete the Secure BLE session has been established.
Zigbee Direct Commissioning Service#
Zigbee Direct Commissioning Service is a mandatory BLE GATT service containing several characteristics that allow the ZVD to control a ZDD on the network. This service requires that the ZVD and ZDD have an established secure BLE session with the correct authorization level to access the various BLE GATT characteristics. The only exception is the Read Request on the Commissioning Status Characteristics, which does not require any authorization level.
Below is a brief description of the mandatory BLE GATT characteristics in the Commissioning Service:
Out-Of-Band Commissioning is an exciting feature that allows the ZVD to provision a ZDD onto a network via BLE without the need to utilize the standard Zigbee association/joining process. This allows the ZVD to provide all the network parameters required for the ZDD to join the network before provisioning the ZDD onto the network. This eliminates the need for network scanning, key delivery, and prevents the ZDD from joining the wrong network.
Zigbee Direct Tunnel Service#
This is an optional BLE GATT service that is used to transport Zigbee Network Packet Data Units (NPDU) over the BLE interface. This service is a Trusted Link service provider that enables a ZVD to send Zigbee commands via BLE to a ZDD that can then execute it. This service requires a secure session established with the ZDD before it can access the ZDD Tunnel service. Note that the Zigbee Direct Tunnel service is not available for a ZDD operating as a Zigbee End Device.
The Tunnel Service has one GATT Characteristic, ZDTS NPDU, which includes BLE Procedures Write Request and Indication. The Authentication level required for the ZVD to access the ZDD's tunnel service is either a provisioning session, which receives limited messages and drops any NWK encrypted packets, or a Basic level authorization. Below is a high-level diagram showing the interaction of the ZVD and a ZDD Tunnel Service. Note that the Acks have been left out of the diagram for simplicity:
Essentially the ZVD creates a Zigbee command, transforms the Zigbee Command into a NPDU, and sends out a GATT Write Request to the ZDD.
Upon receipt of the Write Request, the ZDD transforms the NPDU into a standard Zigbee Command and executes the command. In the example above the ZDD sends out the ZCL Read Attribute command to the Zigbee Network.
Once the command has been completed and the ZDD has received the expected ZCL Read Attribute Response, the ZDD sends back a Write Response and Indication with the NPDU of the received message to the ZVD.
Finally, the ZVD transforms the NPDU into back into the Zigbee Command, ZCL Read Attribute Response.
Zigbee Direct Configuration Cluster#
This cluster provides an interface for configuring Zigbee Direct functionality. All commands received by this cluster must be unicast messages only. The Cluster Id is 0x003D. This cluster contains the Attribute Set Identifier 0x000 Zigbee Direct Information. The Interface State refers to whether the BLE interface is enabled, while the Anonymous join timeout represents the provisioning session timeout. Below is more information on the attribute set and commands to configure them.
Commissioning Devices onto a Network#
Commissioning a ZVD onto an existing ZDD network is a great example of how these various services work together. Below is a diagram that shows a ZVD joining the Zigbee Network through a ZDD. Note that this is the simplest use case where the Trust Center is Zigbee Direct aware, however it is possible to commission a ZVD onto a non Zigbee Direct aware Trust Center.
Before any ZVD can join the network, the Zigbee Network needs to be open for devices to join the network.
The ZVD creates a secure BLE session with the ZDD using one of the three pre-shared keys (Well Known Key, Install Code, or Variable Length Passcode).
Once the secure session is established the ZVD uses the tunneling service to send Zigbee Commands to the ZDD to request to join the network and request basic authorization privileges.
Once the Trust Center and ZVD exchange information, the Trust Center sends back the APS Transport Key command with the Basic Authorization Key.
Now the ZVD can terminate its previous provisioning session and establish a new secure session with the Basic authorization key and join the Zigbee network with Basic authorization level.
Silicon Labs Implementation#
Silicon Labs GSDK 4.3 release enables customers to create their own Zigbee Direct Device. A sample application is available in Simplicity Studio if you have a compatible part.
This sample application adds the following components and clusters:
Zigbee Direct Functionality Component: Includes both the Zigbee Direct Security Service and the Zigbee Direct Commissioning Service that is required for the ZDD.
Zigbee Direct Tunneling Functionality: Includes the optional Zigbee Direct Tunneling Service.
Zigbee Direct Command Line Interface Component: Includes the command line interface for relevant ZDD commands.
A Bluetooth GATT Configurator is available on the Configuration Tools tab. If you open it, you will see the BLE GATT services explained above:
In the Cluster Configurator, also on the Configuration Tools tab, under Zigbee Direct, is the Zigbee Direct Configuration Cluster. It provides the interface for configuring Zigbee Direct.
The Zigbee Direct Configuration Cluster contains the various attributes mentioned in previous sections.
