Zigbee Protocol Controller 1.6.0
|
This readme is intended for Unify Framework developers, who are trying to cross compile, install, and run ZigPC on a Raspberry Pi.
This guide describes how to cross compile the Zigbee Protocol Controller / ZigPC for Raspberry Pi using Docker on your work station. If you haven't already built the Unify docker image, follow the guide in the docker folder readme.md file.
The Zigbee Protocol Controller uses certain functionality in the GeckoSDK. The Gecko SDK can be downloaded through Simplicity Studio. The ZigPC uses the EmberZNet library provided through the Gecko Platform. See the [AN0822: Simplicity Studio User's Guide] (https://www.silabs.com/documents/public/application-notes/AN0822-simplicity-studio-user-guide.pdf) for more information. In summary, select the EmberZNet library at installation time or, when creating a new project, select "Manage SDKs" followed by "Customize Installation".
After EmberZNet/GeckoSDK is installed, locate its path (e.g., ~/SimplicityStudio/SDKs/gecko_sdk/). Currently, v4.0 is supported. Set the environment variable $GSDK_LOCATION to this path.
The Zigbee Protocol Controller imports a Silicon Labs Configurator based UC project as a static library. This project should be configured in combination with any ZCL support changes performed.
See the Zigbee Host Library Readme for more details.
Cross compilation builds currently supports only the Raspberry Pi OS Bookworm.
From the root of the Unify source directory, run the following:
Alternatively, use the provided runDocker.sh script in the docker directory. Fill out the GSDK_LOCATION and UIC_REPO paths in the script to properly set up the docker image.
To compile, run these commands from the top level Unify directory, inside the Docker container:
You can run the Raspberry Pi unit tests (and ZigPC binary) within Docker on the Host machine by using QEMU to emulate the ARM architecture, and binfmt in the kernel, to tell Linux OS to run the ARM binaries within QEMU.
To run the unit tests within Docker on the Host machine, run the following command in the Host (not in the Docker container):
NB: This command needs to be run once after each restart of the Host machine.
After enabling this you can run the unittests by issuing following command in the uic_arm64
docker image in the build directory:
For installing please refer to the general installation method in Getting started.
ZigPC is built on top of the Zigbee Host Wrapper Library. Currently this library is implemented as a Silicon Labs SLC project using the SiLabs Ember Application framework. Logs from the framework will be shown as a part of ZigPC console logs.
After ZigPC is launched, the logs from ZigPC will be associated with a timestamp, log level, and a tag in the following format:
LOG_TIMESTAMP <LOG_LEVEL> [LOG_TAG] LOG_MESSAGE
<LOG_LEVEL>
corresponds to the following:
<d>
: Debug log<i>
: Info log<w>
: Warning log<e>
: Error log<c>
: Critical logNOTE: Any log that doesn't follow the above format is assumed to be part of printed output from the Ember Application framework.
The following snippet is a snippet of example logs to expect:
The ZigPC>
prompt can be used to carry out common Protocol Controller functions. Typing "help" brings up the currently supported functions:
Changing the log levels can be achieved using the log_level command in the "ZigPC>" console on ZigPC. The following formats are supported for this command:
log_level <level>
log_level <tag>,<level>
<tag>
corresponds to any of the tags you see in the logs (i.e., mqtt_client)
<level>
corresponds to any one of the following (can be applied overall or to a particular log_tag):
The "Network Analyzer" perspective in Silicon Labs Simplicity Studio IDE v5 can be used to analyze the traffic on the Zigbee PAN.
Network activity can be observed based on the UCL commands relayed by ZigPC.
If you have not done so already, download Simplicity Studio v5 from https://www.silabs.com/products/development-tools/software/simplicity-studio on a host computer.
Devices in Simplicity Studio can be detected using any of the following methods:
If the host computer and one of the Zigbee devices are connected via Ethernet (using a Wireless Starter Kit for example: https://www.silabs.com/development-tools/wireless/efr32xg22-wireless-starter-kit), Simplicity Studio can capture network traffic using this interface. Either an end device or the gateway radio can be connected via Ethernet to perform network capture (since the serial USB connection, which ZigPC uses, can run independently of the Ethernet connection services).
Instructions:
Because the Gateway radio is connected to Raspberry Pi running ZigPC, a test end device should be connected to the host computer.
Instructions:
Using the top menu, select Window → Perspective → Network Analyzer.
Then, in the "Debug Adapters" window, right-click on the connected device and click "Connect", then click "Start capture".
This will trigger the Network Analyzer to record PAN events, as shown below:
The middle table, labeled "Transactions", can be used to get a high-level overview of messages sent on the network.
ZigPC uses Network key (NWK key) based on the install code. In typical Zigbee applications, the Ember CLI can be used to get this key. The CLI can be re-enabled at compilation time, however, the network information is also printed out at startup.
Look for the following pattern:
Extract the NWK key value ( ZZ ZZ ZZ ...
sequence in the log above) and add it as a Network Analyzer Security Key using the following instructions:
This NWK key can now decrypt network traffic after the node has joined the network.
For more information, see "Section 6: Using the Network Analyzer" in QSG106: Zigbee EmberZNet PRO Quick-Start Guide.
For example, the following decrypted transactions are seen when the SmartStart addition is performed to add an end device to the PAN using the Install Code based DSK:
It is possible to add custom ZCL info to ZigPC to add natively unsupported clusters or to override the functionality of default clusters. This step must be run at compilation time in order to properly include the necessary MQTT topics and other related ZCL information.
Add a custom XML file (or modify an existing XML file) in the shared components of the Unify framework. All XML files defining ZCL clusters are stored in the 'uic-dotdot' component under the 'dotdot-xml' folder. If a new XML file is added or if the name of an XML file changes, that change must be reflected in the library.xml file
ZigPC generates ZCL-cluster code and structures using ZAP. Ensure that the ZAP templates will generate for the new cluster by adding the name to: 'uic/applications/zigpc/components/zcl_util/zap/addon-helper.js Specifically, the 'SUPPORTED_CLUSTERS' and 'SUPPORTED_CLUSTER_ATTRIBUTES' lists must reference the new cluster.
ZigPC uses a custom zigbeeHost layer to manage the zigbee stack. Ensure that this layer can also access the new ZCL cluster by modifying the slcp file in 'uic/applications/zigpc/components/zigpc_gateway/libs/zigbee_host/src/libzigbee_host.slcp' Add the new cluster in the same format as all the existing clusters at this layer.
*Step 4: Re-generate all ZAP templates
Unify uses ZAP to generate ZCL cluster information (as discussed in step #2). Make sure that zap can find the library by modifying its configuration file.
Alternatively, compile with the cmake option 'ZAP_GENERATE' set to 'ON' to automatically re-generate zap output files as part of the compilation process.
Re-generate all zap output in the top level uic for the following components: uic_dotdot, uic_dotdot_mqtt, unify_dotdot_attribute_store
Re-generate all zap output in the zigpc level for the following components: command_mapper, zcl_util, zcl_command_parser, zcl_profiles, attribute_management
Please take a look at [https://github.com/SiliconLabs/zap] for more detailed information.
Re-generate the zigbee_host slcp, in the autogen folder. Set the STUDIO_ADAPTER_PATH to point to zap, which should already be configured to point to the custom xml. Otherwise, it will be necessary to edit the zap-config of the zigbee_host folder.
Please read [https://siliconlabs.github.io/slc-specification/1.0/] and [https://www.silabs.com/documents/public/user-guides/ug520-software-project-generation-configuration-with-slc-cli.pdf] for more information on using the slc_cli.
Compile ZigPC as normal. ZigPC should now support your custom cluster