Zigbee Protocol Controller 1.6.0
|
This document is a user guide for the Zigbee Protocol controller (ZigPC). The primary role of ZigPC is to allow Zigbee devices to be monitored and controlled using the Unify Controller Language (UCL).
The Unify Framework provides a consolidated API to observe and control devices that communicate using different sensor network protocols (Zigbee, Z-Wave, and so on) with the help of Unify Protocol Controllers.
An MQTT broker is at the core of Unify Framework. It is used by Protocol Controllers to send and receive commands and information from other Unify components using the Unify Controller Language (UCL).
The Zigbee Protocol Controller (ZigPC) is an opinionated Zigbee gateway that act as a Unify gateway, as specified in the Unify Specification.
ZigPC uses the Zigbee Host-NCP model to relay messages from Unify to the end device where EZSP is used as the serial protocol to communicate with the NCP.
Running Unify with ZigPC requires the following equipment:
ZigPC is officially supported on a Raspberry Pi 4 running Debian Bookworm (A.K.A. Raspberry Pi OS).
For installation and setup, follow steps outlined in: https://www.raspberrypi.org/documentation/
Find more information about Raspberry Pi OS here: https://www.raspberrypi.org/downloads/raspberry-pi-os/
Supported radios: EFR32MG2X Supported EZSP protocol: UART (SPI not officially supported)
Currently supported Zigbee device provisioning methods:
See the Appendix section at the bottom of the guide for steps to configure example NCP and Z3Light device FW images.
All of the Unify components below (MQTT Broker, UPVL client and GMS client) should be installed before running the ZigPC. Running Unify with ZigPC requires using an MQTT Broker. Unify currently supports using Mosquitto MQTT (https://mosquitto.org/).
For installing please refer to the general installation method in Getting started.
After the packages are installed, the following services and libraries are available on the Raspberry Pi:
The Mosquitto MQTT broker is installed as a system service running in the background. It should be started before attempting to launch any Unify component. Otherwise, Unify components may not launch properly and may not communicate to each other properly.
The Mosquitto publish & subscribe tools can be used to interact with the Unify MQTT broker by providing a topic and a message payload (if publishing).
The Unify Framework Provisioning List (UPVL) maintains the UCL SmartStart topics (and its List, Update, and Remove subtopics. See UPVL User Guide for more details.
Unify IoT service that book-keeps groups data among different Protocol Controllers. It manages the ucl/by-group/# topic space. See GMS User Guide for more details.
Unify IoT service that stores and distributes OTA Firmware images for Protocol Controllers over UCL. It manages the ucl/OTA/# topic space. See Image Provider User's Guide for more details.
The Zigbee Protocol Controller application connects to the Mosquitto MQTT broker, sets up a PAN as a Zigbee Coordinator, and relays messages using the Zigbee NCP connected on a serial port.
The configuration used by the service can be found at etc/uic/uic.cfg
Running ZigPC on the command line If ZigPC is not running a system service
NOTE: Run
zigpc --help
to see a full list of supported parameters
NOTE: ZigPC serial argument point to the UART-EZSP port exposed by the Zigbee NCP. This path will be different based on the configuration of tty devices connected to your Raspberry Pi
NOTE: Ensure ZigPC is only running as a system service or via the CLI and not both
The ZigPC is an EZSP-based gateway application and can be run in a multiprotocol environment. Please see Multiprotocol Setup for details about the multiprotocol stack.
In summary, the radio should be configured as an RCP, as opposed to a standard Zigbee NCP. The CPCd application should run and point to the RCP. If encryption is enabled, please follow the guide above, but the encryption key will need to be flashed to the radio.
Once properly setup, Zigbeed is required to run. By default, it points to the 1st CPCd radio URL. If installing Zigbeed through Unify, a port will be opened at /dev/ttyZigbeeNCP which will forward all EZSP messages to the Zigbeed application.
After Zigbeed and CPCd are both properly set up, ZigPC can then be started and used in a multiprotocol context by pointing '–zigpc.serial' at the virtual USB port (/dev/ttyZigbeeNCP) created in the previous step.
The user can then configure the other protocols alongside ZigPC to run many protocols using the same radio.
By default, the ZigPC is configured for a singe protocol environment Therefore, the ZigPC will point to the same USB port as the CPCd application. When running ZigPC in a multiprotocol context, the serial port should be changed to avoid this conflict.
The Zigbee Protocol Controller performs network discovery and device servicing for sleepy and non-sleepy Zigbee devices. The following section outline some of the different functions ZigPC performs.
Unify uses a unique identifier when addressing nodes included by different protocol controllers called a Unified Node Identifier (UNID). ZigPC uses the Extended Unique Identifier of the device (EUI64) as part of the UNID to relay messages between Unify and Zigbee devices: zb-<EUI64_IN_BIG_ENDIAN>
For example, if the EUI64 of a device is 00-11-22-33-44-55-66-77
, the UNID will be: zb-0011223344556677
ZigPC currently only supports adding Zigbee devices using the Unify SmartStart List functionality. The currently supported format recognized by ZigPC is the Z3 Install Codes based Device-Specific key (DSK). See Unify Specification Section 3.7.1 for more details.
The Unify SmartStart List enables easily adding pre-provisioned devices to the network using a protocol-specific Device-Specific Key (DSK). The SmartStart List is managed by another Unify component called uic-upvl.
Currently, ZigPC uses DSKs that contain information from the out-of-band Zigbee 3.0 Installation Code method to permit a Zigbee device to join the network.
DSK Format:
ZigPC Accepts SmartStart entries that have the following DSK format in groups of two hexadecimal values:
For example, if the Zigbee device EUI64 (big endian) is 0x00 0xAA 0x11 0xBB 0x22 0xCC 0x33 0xDD and the install code (big endian) is 0x0A 0x0B 0x0C 0x0D 0xE 0xF 0x1 0x2 with a CRC of 0x7B8A, the DSK should be:
After a Z3 Install code-based SmartStart DSK has been recognized in the Unify published SmartStart List, ZigPC will extract and add the Install Code and EUI64 pair to ZigPC. When network-steering is performed on the joining node, ZigPC will validate using the Install Code based Link key extracted and allow the device to join the network.
See (AN1089: Using Installation Codes with Zigbee Devices)[https://www.silabs.com/documents/public/application-notes/an1089-using-installation-codes-with-zigbee-devices.pdf] for more details on how to setup Z3 Install Codes on joining devices.
UCL topics used:
ucl/SmartStart/List
The ZigPC network can be configured to accept device joins using the well-known key. ZigPC will open up the network and allow well-known key based joins when the NetworkManagement state add node
is requested:
UCL topics used:
ucl/by-unid/<DEVICE_UNID>/ProtocolController/NetworkManagement/Write
ucl/by-unid/<DEVICE_UNID>/ProtocolController/NetworkManagement
The parameters for the Zigbee network can be set in 2 ways:
Using the default network parameters as in the standard Z3GatewayHost application requires no additional input.
Optionally, the user may configure the radio parameters at the command line or in the zigpc configuration file. The "zigpc.use\_network\_args" flag must be set to "true" (or 1). The user must then supply the "zigpc.network\_panid", "zigpc.network\_channel" and "zigpc.network\_radio\_power". Please note, that ALL arguments must be supplied when the "use\_network\_args" option is set.
Running zigpc with the –help option will also describe how to use these settings.
ZigPC publishes the network status of devices through inclusion, interview, and regular function stages.
UCL topics used:
ucl/by-unid/<DEVICE_UNID>/State
ucl/by-unid/<DEVICE_UNID>/State/Attributes/EndpointIdList/Reported
Once added to the network, ZigPC performs device interviewing to retrieve the ZCL clusters supported per each endpoint on the device. After the device interview process finishes, bindings and attribute reports are configured to publish attribute updates to Unify. In addition, ZigPC publishes the commands supported by these ZCL clusters as UCL clusters.
UCL topics used:
ucl/by-unid/<DEVICE_UNID>/ep<ENDPOINT_ID>/<CLUSTER_NAME>/SupportedCommands
After the supported commands are published by ZigPC for a device endpoint, UCL commands can be sent to the Zigbee device. The UCL command received by ZigPC is mapped to a corresponding ZCL command and sent to the Zigbee device endpoint.
UCL topics used:
ucl/by-unid/<DEVICE_UNID>/ep<ENDPOINT_ID>/<CLUSTER_NAME>/Commands/<COMMAND_NAME>
ZigPC is able to publish commands generated by devices (either as command responses or as unsolicted stimuli) to the Unify broer. The ZCL command is parsed and mapped to UCL command before publishing under the device, endpoint, cluster combination.
UCL topics used:
ucl/by-unid/<DEVICE_UNID>/ep<ENDPOINT_ID>/<CLUSTER_NAME>/GeneratedCommands/<COMMAND_NAME>
Zigbee devices with attribute reporting configured will send ZigPC attribute reports for each attribute supported in each ZCL cluster under each endpoint. These attribute updates are published under the UCL Reported
topic when changes occur of after a timeout.
UCL topics used:
ucl/by-unid/<DEVICE_UNID>/ep<ENDPOINT_ID>/<CLUSTER_NAME>/Attributes/<ATTRIBUTE_NAME>/Reported
To disable bindings and reporting between end devices and the protocol controller, run zigpc with the '–zigpc.poll_attr_only' flag at runtime. This flag forces the protocol controller to poll endpoints using a 'ReadAttributes' command at a set interval (500ms by default). In this configuration, sending a 'ForceReadAttributes' MQTT message can also request the specific attributes desired from an endpoint.
Unify uses the ZCL Group ID format to send group commands to multiple devices spanning different protocols at the same time. ZigPC uses the ZCL Groups cluster functionality on each Zigbee endpoint to maintain the group membership. After an endpoint is added to the group using the UCL Groups/AddGroup command, ZigPC publishes the list of groups the endpoint is part of.
ZigPC uses the functionality provided by the Unify Group manager component called uic-gms. Once the group list is published by ZigPC, the uic-gms manages the group commands that can be sent through the Unify gateway.
ZigPC listens to the by-group topic space and services any groupIDs that is recognized by translating the UCL cluster command and sending this message as a multicast message to the Zigbee network.
UCL topics used:
ucl/by-group/<GROUP_ID>/<CLUSTER_NAME>/Commands/<COMMAND_NAME>
ZigPC supports OTA updates for nodes that have an OTA ZCL cluster. The OTA mechanism is based off the existing GSDK, OTA-Server plugin. For more information, see Silicon Labs' OTA Server-Client Application Note.
NOTE: It is expected that a device will have a bootloader to properly support OTA updates. See Silicon Labs' Bootloader User Guide for more details.
ZigPC handles sleepy end device (SED) communications with the use of the ZCL PollControl server functionality available on the SED. After the SED is interviewed by ZigPC, ZCL messages sent to SED will be stored until the SED PollControl server sends ZigPC a PollControl/CheckIn message. ZigPC will send a PollControl/CheckInrResponse as a reply to transition SED into fast-polling mode. This will allow ZigPC to unload/send any queued messages to the SED.
ZigPC publishing information related to the host process and NCP information to provide usage statistics to customers. The following metrics are being published currently:
UCL topics used:
ucl/by-unid/<DEVICE_UNID>/ProtocolController/SystemHealth/SupportedMetrics
ucl/by-unid/<DEVICE_UNID>/ProtocolController/SystemHealth/Request
The Zigbee Protocol Controller has the capability of updating the NCP radio it uses. In the configuration (either YAML file or command line argument, see configuration section for details), enable the "--zigpc.ncp_update" flag and set the "--zigpc.ncp_firmware_path" appropriately. The Protocol Controller will startup and automatically update the NCP with specified firmware. Run zigpc in debug mode to show progress updates.
For the following example, the UNID addresses used are as follows:
ZigPC Gateway UNID: zb-AAAAAAAAAAAAAAAA
Zigbee Device UNID: zb-0102030405060708
There are 3 command-lines terminals used in the following steps:
OPTIONAL: To see all messages sent to the broker, follow the steps to download and install the MQTT Explorer tool. After it is run on the host machine, connect to the MQTT broker on the Raspberry Pi.
To perform the below steps using the Unify Dev GUI tool, see Dev GUI User Guide.
NOTE: The following steps use the command line interface (CLI) exposed by Simplicity Commander stand-alone tool.
Create a random HEX sequence of 6,8,12, or 16 bytes (12, 16, 24, 32 characters respectively) and put it in a file containing the following text: Install Code: <RANDOM_HEX_SEQUENCE>
Use the Simplicity Commander CLI to flash the Install code to the Zigbee Device:
Validate the install code is present and extract the CRC corresponding to the install code by running the following command:
NOTE: Ensure ZigPC is running by this step.
Format the SmartStart DSK using the Z3Device's EUI64, install code, and install code CRC.
01-02-03-04-05-06-07-08
F6-4C-3E-6D-19-65-69-CE-4F-20-00-A4-00-69-B5-34
46-76
01-02-03-04-05-06-07-08-F6-4C-3E-6D-19-65-69-CE-4F-20-00-A4-00-69-B5-34-46-76
NOTE: Ensure the EUI64 used above corresponds to the device that is joining, not the example EUI64 used as an example`.
Access the Zigbee device EmberCLI using Studio or a serial terminal to perform cleanup of the device state.
NOTE: Ensure that Z3Device is not part of the network by entering the info
command and seeing panID [0x0000]
and nodeID [0xFFFE]
in the output:
Validate that a new MQTT topic has been published showing the Protocol Controller Network Management state as idle
:
in the output above, the ZigPC Gateway UNID can be seen from the topic as zb-AAAAAAAAAAAAAAAA
Dev GUI Method: Go to the Nodes tab to see the Protocol Controller UNID and state.
Use the Mosquitto publish tool to add a SmartStart entry using the DSK created above.
OPTIONAL: you can also specify the EUI64 of the ZigPC Gateway NCP (see User Manual below) in the "ProtocolControllerUnid" field:
Dev GUI Method: Go to the SmartStart tab and click on the "Add" key
Dev GUI Method: Fill in the DSK in the entry.
In the Z3Device, start the Network Steering plugin process by entering plugin network-steering start 0
on the Z3Device Ember CLI:
Z3Device should join the ZigPC network and assign a UNID using the following format: zb-<Z3DEVICE_EUI64_BE>
.
Validate that the UNID has been assigned by checking the Unify SmartStart list using the Mosquitto subscribe tool:
As seen, the Device UNID is "zb-0102030405060708".
Dev GUI Method: Go to the SmartStart tab and see the updated UNID field.
Validate that the ZigPC NetworkManagement state has transitioned back to idle (previous MQTT messages would have shown the NetworkManagement state has transitioned from "idle" -> "add node" -> "node interview" -> "idle"):
Validate that a new MQTT topic has been published showing Z3Device is online and functional:
Dev GUI Method: Go to the Nodes tab and see the updated Z3Device entry.
NOTE: The following steps use the command line interface (CLI) exposed by Simplicity Commander stand-alone tool.
--zigpc.tc_use_well_known_key true
etc/uic/uic.cfg
:Validate the following MQTT topic has been published showing the Protocol Controller Network Management state as idle
:
in the output above, the ZigPC Gateway UNID can be seen from the topic as zb-AAAAAAAAAAAAAAAA
Dev GUI Method: Go to the Nodes tab to see the Protocol Controller UNID and state.
Use the Mosquitto publish tool to request a Network Management state change to add node
:
Dev GUI Method: Go to the Nodes tab and click on the "States" dropdown and select the "add node" item.
ZigPC will now open the network to permit the Z3Device to join using the well-known key.
In the Z3Device, start the Network Steering plugin process by entering plugin network-steering start 0
on the Z3Device Ember CLI:
Z3Device should join the ZigPC network and assign a UNID using the following format: zb-<Z3DEVICE_EUI64_BE>
.
Validate that the ZigPC NetworkManagement state has transitioned back to idle (previous MQTT messages would have shown the NetworkManagement state has transitioned from "idle" -> "add node" -> "node interview" -> "idle"):
Validate that a new MQTT topic has been published showing Z3Device is online and functional:
Dev GUI Method: Go to the Nodes tab and see the updated Z3Device entry.
NOTE: The Zigbee device must be added using the SmartStart addition process discussed above. NOTE: ZigPC will publish the UCL cluster command support under for all endpoints discovered in the interview process.
Subscribe to the UCL cluster command topic space under a Z3Device endpoint: NOTE: Endpoint 1 (ep1) chosen for this example. Other endpoint support will be published based on device discovery
Dev GUI Method: Go to the Nodes tab and see Type
column to see the supported clusters.
NOTE: The Zigbee device must be added using the SmartStart addition process discussed above. NOTE: ZigPC will publish the UCL cluster support under for all endpoints discovered in the interview process.
Subscribe to the UCL cluster attribute topic space under one of the Z3Device endpoints: NOTE: Endpoint 1 (ep1) chosen for this example. Other endpoint support will be published based on device discovery.
Dev GUI Method: Go to a specific cluster tab (i.e. OnOff) see the main attribute State
column.
The UCL command format translates 1:1 to ZCL messages that is recognized by ZCL compliant Zigbee devices. To know the exact format of the UCL command, see the Unify specification and the DotDot specification.
See the supported commands for a UCL cluster. For this exercise, the endpoint 1, OnOff cluster will be selected.
The commands can be send to the Z3Device/ep1/OnOff cluster: Off, On, Toggle, OffWithEffect, OnWithRecallGlobalScene, OnWithTimedOff, WriteAttributes, ForceReadAttributes
Publish a UCL command to send to the Z3Device endpoint's OnOff cluster.
Dev GUI Method: Go to the OnOff tab and click on the Toggle
Command on the ep1 row.
On the Z3Device device, notice that a ZCL message has been received:
Subscribe to the UCL OnOff Attribute in the OnOff cluster to see the updated reported state:
Dev GUI Method: Go to the OnOff tab and see the OnOff State
icon is active.
Retry the same UCL command to send to the Z3Device endpoint's OnOff cluster.
On the Z3Device device, notice that a ZCL message has been received:
Subscribe to the UCL OnOff Attribute in the OnOff cluster to see the updated reported state:
NOTE: The Zigbee device must be added using the SmartStart addition process discussed above.
Send a Network Management state change to start removing a node:
ZigPC will try to perform a state change. If successful, the following message will be published:
As seen above, ZigPC requests that the UNID parameter should be passed in.
Send the UNID of the Z3Device to remove:
Validate that the Z3Device has left the network by entering info
on the Ember CLI and noticing a nodeID of 0xFFFE:
Validate that the NetworkManagement topic has shown the state transition from "remove node" to "idle":
To initialize an OTA update, you need the following:
Add the firmware image to the image-provider's specified folder. Update the images.json file with the firmware information.
NOTE: For this version of the Zigbee Protocol Controller, the UIID should be set to the UNID of the node that should be updated. Future releases will allow for a more involved UIID, which can reflect version and other information.
NOTE: The image-provider's images.json file needs to be updated after ZigPC is running to ensure that ZigPC receives the "image announce" message. Updating the images.json file automatically triggers this process.
The Silicon Labs' OTA-Client plugin on the Zigbee node should periodically poll ZigPC for new images (based on the "OTA Client Query Delay").
NOTE: If there is access to the CLI on the node, the command 'plugin ota-client request-image
' can manually send this request to ZigPC.
ZigPC has exposed the ProtocolController/SystemHealth
topic space to enable the publishing of information related to the ZigPC system, process, and Zigbee stack.
The following metrics are available:
Retrieve the metrics supported by the protocol controller diagnostics topic space.
Enable a metric using the Request
subtopic:
Validate metric requested being updated regularly:
ZigPC uses the following format for the UNID: zb-<EUI64-IN-BIG-ENDIAN>
where "zb-" is the current fixed prefix (subject to be configurable in later releases)
For example, the following Zigbee device having a EUI64 of 01 23 45 67 89 AB CD EF has the following device UNID zb-0123456789ABCDEF
.
ZigPC supports the following SmartStart Device-Specific Key (DSK) format:
<NODE_EUI64>
-<Z3_INSTALL_CODE>
-<Z3_INSTALL_CODE_CRC>
Examples of Supported ZigPC DSK:
00-11-22-33-44-55-66-77-AA-BB-CC-DD-EE-FF-00-11-88-99
00-11-22-33-44-55-66-77-AA-BB-CC-DD-EE-FF-00-11-22-33-44-55-66-77-88-99-12-34
ZigPC should have a Zigbee NCP attached via the serial UART connection.
EFR32MG1X or EFR32MG2X are the supported NCP Radios.
NCP Image supported by ZigPC from GSDK v4.1:
ZigPC currently uses the following functionality using Gecko SDK v4.0:
Device types types:
ZCL cluster types supported by ZigPC for attribute updates and command relays:
There are two ways to get the NCP image:
A single radio should be designated as a Zigbee Gateway NCP that ZigPC connects to.
The Gecko SDK provides ready-made NCP images available under the demo-applications package.
Follow section 2 from the following application note to build a NCP application using the Simplicity Studio IDE: AN1010: Building a Customized NCP Application
A Zigbee 3.0 Light device FW is used as an example device that can join the ZigPC network.
Follow the instructions in Section 4: Starting an Example Application in QSG106: Zigbee EmberZNet PRO Quick-Start Guide to create a Z3Light Application.
NOTE: before the Appbuilder project generation, ensure the following changes are made:
In the Plugins tab, ensure the "Binding Table Size" in the "Binding Table Library" plugin is bigger is considerable enough to accommodate ZCL groups (uses multicast bindings) and attribute reporting (to allow ZigPC to receive automated attribute updates). For the Z3Light project, this should be at least 16.
[OPTIONAL] In the Plugins tab, ensure the "Reporting Table Size" in the "Reporting" plugin is bigger than the number of attributes supported in each device endpoint cluster. For the Z3Light project, this should be at least 9.
NOTE: If the reporting table size is not sufficient to support all attributes, Unify IoT Services will need to use the ForceReadAttributes command to get updated attribute states
Follow the steps below to create and flash the Zigbee Z3Light Image:
For flashing device firmware onto the Zigbee radios, see Section 4.4: Compiling and Flashing the Application in QSG106: Zigbee EmberZNet PRO Quick-Start Guide.