Before we move on, this tutorial assumes the reader is over the "ZigBee 3.0 Tutorial - Light and Switch from Scratch". It's highly recommend to have a basic understanding about Zigbee concepts before starting this tutorial.
The intent of this document is to give a general description of how can a cluster be used, necessary low-level peripheral drivers be implemented and than interacted with via a Zigbee Network. The article will use the HA Light Sensor cluster as an example and the Thunderboard Sense 2, TB2 for short, based light sensor will feed the cluster with data. The Tutorial steps 1 and 2 describe the process of creating the firmware of the sleepy end device based on examples provided by Silicon Labs.
It is a good excercise to follow steps 1 and 2 as you go along this tutorial but it is not required since the complete project files are attached to the article.
The purpose of this project is to show:
- integratation of a sensor driver into EmberZNet stack
- configuring reporting its measured values manualy
- configuring the device as a Sleepy End Device
The project is based on the Si1133 UV Index/Ambient Light Sensor. The sensor is mounted to the TB2, therefore it doesn't require any additional connection. The sensor communicates on the I2C protocol. The sensor's driver originates from an example project. It's outside the scope of this tutorial to describe how the driver works.
Designing a Zigbee network and processing the reported data is also outside the scope of this document. In this example, data just will be visualized by terminal as text. At the end of this KBA, there will be a Test Chapter, where the chapter will describe the creation of a lightweight ZigBee network, where the reader can examine the newly implemented Light Sensor provided data.
High-level description about the firmware
join to a network manually
sleep for 10 seconds
measure the ambient light
store the measured value into Illuminance Measurement cluster
How do you switch antenna paths on EFR32MG21 and MGM210x in EmberZNet stack, and what are the defaults?
Answer
The value of antennaConfig.defaultPath in halInitAntenna() determines which antenna is in use.
At the time of publication of this article (EmberZNet 6.7.5), the RF2G4_IO2 pin is selected by default on both EFR32MG21 and MGM210x.
EFR32MG21
In EFR32MG21, the 2.4 GHz antenna interface consists of two single-ended pins, RF2G4_IO1 and RF2G4_IO2. See Figure 1.
Figure 1.
EFR32MG21 chip pinout.
MGM210P
The MGM210P module has a built-in antenna on non-exposed pin RF2G4_IO1 and an external antenna attached to RF2G4_IO2 pin. See Figure 2.
Figure 2.
MGM210P module pinout.
MGM210L
The MGM210L includes a built-in PCB trace antenna and does not support the use of an external, alternative antenna.
The following Figure 3. shows the lack of the RF pin.
Figure 3.
MGM210L module pinout.
Path configuration
After the antennas and default paths are clarified, take a look at the application where this setting is applied. The stack first initializes the antenna GPIOs prior to any other radio settings being applied.
This is done by the EmberStatus halInitAntenna(void) function through the Antenna Stub plugin.
It can be found in "...\v2.7\platform\base\hal\plugin\antenna-stub\antenna-stub.c ". See Figure 4.
Figure 4.
Code snippet from antenna-stub.c .
The antennaConfig.defaultPath can be
0 for selecting RF2G4_IO1
non-zero for selecting RF2G4_IO2
The following table maps the above values with the corresponding pin configurations. See Table 1.
Table 1.
Path mapping.
The BSP_ANTDIV_SEL_LOC macro is defined to 1 in antenna.h, which means that the default path is the external U.FL for MGM210P and built-in PCB trace antenna for MGM210L.
Our technical support teams are happy to review any schematics, layouts and physical PCBs and provide any recommendations we may have.
Please note however, that all feedback is provided on an AS-IS basis, without any warranties of any kind. This means that you are solely responsible for all aspects of a design prior to all manufacturing. Similarly, our advice is based on our experience with similar designs, rather than any testing or verification of your design. Our review should not be considered as any kind of guarantee of performance. You are solely responsible for testing and verification, and we strongly recommend that you do so prior to committing your design to production.
When the customer or the FAE wants to create a support case in Salesforce for a hardware design review, it is important that he or she has reviewed the following expectations for thorough and efficient reviews of the Wireless SoCs and modules.
Provide a short description of the product's use case.
Schematic review submission checklist
The schematic should be provided in a searchable PDF format as it allows the reviewers to search for a particular net or component in a multi-page schematic.
The entire schematic of the design is preferred, however, if that is not possible due to confidentiality, then provide details in the case description about power supply used, host MCU part number, and other radio part numbers, if any, for a thorough review. For example, if there is a WiFi part in the design, but not visible in the schematic provided, then the feedback we provide will be incomplete as co-located radios on a single PCB requires additional software and hardware changes to improve coexistence between the radios.
Provide part numbers of all components connected to the EFR32 in case they are not mentioned in the schematic itself as the component characteristics can differ with size and can affect the expected performance, for example, RF performance due to de-tuning of the matching network. Additionally, provide the datasheets of the crystals - HFXO and LFXO (where applicable) as there can be multiple variants of a crystal and it can be confusing to find the correct datasheet if the complete part number is not provided.
In addition to datasheet recommendations, review the following documentation and follow the schematic guidelines as much as possible to achieve optimal performance.
Silicon Labs' reference board schematic for the part. The component values in the reference designs were chosen to meet datasheet specifications.
Layout review submission checklist
The layout should be provided in Gerber file format for all layers including solder mask, paste, and drill files. Typically, Gerber files are provided to the PCB manufacturer so it's important that the final design files are reviewed rather than the CAD file itself in order to identify any anomalies that can cause manufacturing or performance issues.
In addition to datasheet recommendations, review the following documentation and follow the layout guidelines as much as possible to achieve optimal performance, especially for RF.
If the design has been reviewed before by the wireless hardware team in a different portal case, create the new case with the previous case (in which the same design was reviewed) listed as parent case. It is important to link similar cases together for traceability.
The StandardizedRfTesting sample application demonstrates the RF testing through TIS (Total Isotropic Sensitivity) / TRP (Total Radiated Power) interfaces. This sample is initial released in the 6.7.x EmberZnet SDK and can be used for customer's Zigbee product to pass the TIS / TRP RF testing. This article introduces how to build the StandardizedRfTesting sample and demonstrates how it works on Silabs BRD4162 radio boards.
Regarding the test procedure of the TIS / TRP is out of the scope of this KBA, please refer to the Zigbee Alliance specification "docs-19-01701-00-Zigbee RF Performance (TRP/TIS) Specification & Test Plan" for more information.
Setup
You will need
Hardware:
2 WSTK main board (BRD4001A)
2 radio boards, the brd4162 radio board is used in this exercise
Software:
EmberZNet SDK version 6.7.5 or higher
Generate and build the sample
Launch Simplicity Studio v4 if you haven’t already and go to the Launcher view to start from the home screen.
Click File > New > Project This will launch the New Project Wizard.
Select Silicon Labs AppBuilder Project and press Next >
Locate the ZCL Application Framework V2 and select it, click Next >
Select EmberZNet 6.7.5.0 GA SOC 6.7.5.0 and click Next >
Select StandardizedRfTesting and click Next >
The Project Configuration page will come up, give your project a name. Leave the location as default. Click Next >
Finally, you will arrive at the Project Setup screen. Here we will select the parts and compiler we are using for this project. They are as follows:
Select Board: EFR32MG12 2.4 Ghz 10dBm Radio Board (BRD4162A Rev A00) and the part number will be selected automatically
Compiler: You can use gcc or IAR ARM to compile this project, for this exercise we use gcc: GNU Arm v7.2.1
Click the Finish button and wait for your project to be generated.
Click the Generate button to generate all of the files for your application.
Once generated, you will see a Generation validation dialog box. Make sure that you don't overwrite callbacks.c file as shown in this image. Click OK.
A Generation successful message should appear next. Click OK.
Click on your StandardizedRfTesting project and build using the hammer icon in the toolbar. Once built successfully, you will see the .s37 binary file in the project.
How it works
One verification test is to flash two WSTK radio boards with the StandardizedRfTesting firmware example as shown above in figure 1. One radio board works as DUT and another one works as Command Module. We can use the Command Module to attempt to communicate over the air with the DUT. This will verify that the DUT will be able to communicate with the test controller via OTA commands. The suggested process for this is:
Flash one WSTK radio board (DUT) with StandardizedRfTesting firmware and appropriate bootloader.
Flash another WSTK radio board (Command Module) with StandardizedRfTesting firmware and appropriate bootloader.
Power on the two radio boards. Connect the Command Module to laptop with USB cable.
Open the console of the Command Module: StandardizedRfTesting> cust find
If Command Module is successfully communicating with the DUT over the air, you will see this on the Command Module console: FIND ACK
If Command Module is no over the air communication, you will see the following on the Command Module console: NO PING ACK
Here is an example to show the CLI commands used during the TIS testing:
//The commands used in the TIS test case command flow:
cust find
cust rping
cust rhardwareversion
cust rsoftwareversion
cust rsetchannel 0x00 0x00 0x10 0x00 // Set channel 12 for DUT
cust lsetchannel 0x00 0x00 0x10 0x00 // Set channel 12 for Command Module
cust lgetchannel
cust lsetpower 0x0A // Set tx power to 10dBm for Command Module
cust lgetpower
cust rstart
cust rend // Reset report count on DUT
cust rstart
cust silabs tx 100 // Send 100 packets to DUT, wait until the complete log
cust rend // Get the report count on DUT
The prefix “r” and “l” of the command mean the command impacts on remote device (DUT) or local device (Command Module) respectively. For example:
“cust rsetpower 0x14”, which means set the tx power for remote device.
“cust lsetpower 0x14”, which means set the tx power for local device.
Regarding the four parameters of the rsetchannel/lsetchannel commands, which is the 32 bits channel mask (0xFFFFFFFF) split into 4 bytes. The bit0 is on behalf of channel 0, bit1 is on behalf of channel 1, bit2 is on behalf of channel 2, etc. So the 0x00001000 means channel 12. Here is some more example:
“total” is the total number of packets received in hex (here 0x1388 = 5000d). “totalRssiMgnitude” is the total RSSI in hex (here 0x5B8D8 = 375000). Avg RSSI can be found by dividing totalRssiMgnitude by total (0x5B8D8/0x1388 = 375000/5000 = -75.00 dBm). totalLqi is also available here, but the RSSI is more useful since it is what is used by the upper level tester to calculate the relative RX antenna pattern.
Note: The RF testing should be operated in shield room.
Conclusion
This KBA introduces how to build the StandardizedRfTesting sample step by step and demonstrates how to use the StandardizedRfTesting firmware for pre-test before sending your product to the test house. More info about the other related CLI commands you can refer to the source code in StandardizedRfTesting_callbacks.c file.
Telegesis modules are low-power 2.4 GHz ISM band transceivers based on EM35x single chip Zigbee / IEEE 802.15.4 solutions. The unique AT-style command line interface allows developers to quickly integrate meshing radio technology.
On this page you will find the firmware for these transceivers. While the R309 firmware is the latest firmware, you can find versions as far back as the R303 firmware. We also have a change log attached outlining version by version changes.
Information on the Telegesis modules and kits can be found at this link.
Documentation on the Telegesis modules and kits can be found here.
PTI (Packet Trace Interface) Capture is a light-weight command line utility that captures network traffic information via the Packet Trace Interface on Silicon Labs EFR32 and EM3xx devices.
This utility provides the equivalent network capture functionality of Simplicity Studio's Network Analyzer tool without opening the GUI, therefore making it useful for a large capture over a long time with minimal involvement of your computer's resources.
The latest release of the silabs-pti-capture.jar software can be found at:
For assistance, please refer to the user guide (README.md).
For more information on the Packet Trace Interface and why you should use it, please refer to this related KBA on Why should I enable the PTI peripheral.
Zigbee & Thread Knowledge Base
Illuminance measuring with Thunderboard Sense 2 - Overview
Project Overview | Next step
Before we move on, this tutorial assumes the reader is over the "ZigBee 3.0 Tutorial - Light and Switch from Scratch". It's highly recommend to have a basic understanding about Zigbee concepts before starting this tutorial.
The intent of this document is to give a general description of how can a cluster be used, necessary low-level peripheral drivers be implemented and than interacted with via a Zigbee Network. The article will use the HA Light Sensor cluster as an example and the Thunderboard Sense 2, TB2 for short, based light sensor will feed the cluster with data. The Tutorial steps 1 and 2 describe the process of creating the firmware of the sleepy end device based on examples provided by Silicon Labs.
It is a good excercise to follow steps 1 and 2 as you go along this tutorial but it is not required since the complete project files are attached to the article.
The purpose of this project is to show:
The project is based on the Si1133 UV Index/Ambient Light Sensor. The sensor is mounted to the TB2, therefore it doesn't require any additional connection. The sensor communicates on the I2C protocol. The sensor's driver originates from an example project. It's outside the scope of this tutorial to describe how the driver works.
Designing a Zigbee network and processing the reported data is also outside the scope of this document. In this example, data just will be visualized by terminal as text. At the end of this KBA, there will be a Test Chapter, where the chapter will describe the creation of a lightweight ZigBee network, where the reader can examine the newly implemented Light Sensor provided data.
High-level description about the firmware
HW and SW requirements:
Software
Hardware
WSTK
Radio Board
Thunderboard Sense 2 development board
Tutorial Steps
Tutorial - Step 0: Overview
Tutorial - Step 1: Appbuilder
Tutorial - Step 2: Driver integration
Tutorial - Step 3: Testing
Documents and further readings
UG309: Thunderboard Sense 2 User's Guide
EFR32MG12 datasheet
Reference Manual for ERF32MG12
ZigBee Cluster Library Specification
ZigBee Lighting & Occupancy Device Specification
How does the polling mechanism work?
Peripheral utilization on EFR32MG by EmberZNet stack
Reporting Plugin functionality in the EmberZNet Application Framework
How do I Speed Up My ZigBee OTA Update for Sleepy End Devices?
Enabling sleep mode of the MX25 series SPI flash
Si1133 UV Index Sensor Electrical and Optical Design Guide
Si1133/Si115x Optical Sensor Example Project on 32bit MCU
Project Overview | Next step
Switching antenna path on Series 2 devices (EFR32MG21, MGM210) in EmberZNet stack
Question
How do you switch antenna paths on EFR32MG21 and MGM210x in EmberZNet stack, and what are the defaults?
Answer
The value of antennaConfig.defaultPath in halInitAntenna() determines which antenna is in use.
At the time of publication of this article (EmberZNet 6.7.5), the RF2G4_IO2 pin is selected by default on both EFR32MG21 and MGM210x.
EFR32MG21
In EFR32MG21, the 2.4 GHz antenna interface consists of two single-ended pins, RF2G4_IO1 and RF2G4_IO2. See Figure 1.
Figure 1.
EFR32MG21 chip pinout.
MGM210P
The MGM210P module has a built-in antenna on non-exposed pin RF2G4_IO1 and an external antenna attached to RF2G4_IO2 pin. See Figure 2.
Figure 2.
MGM210P module pinout.
MGM210L
The MGM210L includes a built-in PCB trace antenna and does not support the use of an external, alternative antenna.
The following Figure 3. shows the lack of the RF pin.
Figure 3.
MGM210L module pinout.
Path configuration
After the antennas and default paths are clarified, take a look at the application where this setting is applied. The stack first initializes the antenna GPIOs prior to any other radio settings being applied.
This is done by the
EmberStatus halInitAntenna(void)
function through the Antenna Stub plugin.It can be found in "...\v2.7\platform\base\hal\plugin\antenna-stub\antenna-stub.c ". See Figure 4.
Figure 4.
Code snippet from antenna-stub.c .
The antennaConfig.defaultPath can be
The following table maps the above values with the corresponding pin configurations. See Table 1.
Table 1.
Path mapping.
The
BSP_ANTDIV_SEL_LOC
macro is defined to 1 in antenna.h, which means that the default path is the external U.FL for MGM210P and built-in PCB trace antenna for MGM210L.Hardware Design Review submission expectations for EFR32MGxx based designs
Our technical support teams are happy to review any schematics, layouts and physical PCBs and provide any recommendations we may have.
Please note however, that all feedback is provided on an AS-IS basis, without any warranties of any kind. This means that you are solely responsible for all aspects of a design prior to all manufacturing. Similarly, our advice is based on our experience with similar designs, rather than any testing or verification of your design. Our review should not be considered as any kind of guarantee of performance. You are solely responsible for testing and verification, and we strongly recommend that you do so prior to committing your design to production.
When the customer or the FAE wants to create a support case in Salesforce for a hardware design review, it is important that he or she has reviewed the following expectations for thorough and efficient reviews of the Wireless SoCs and modules.
How to build and use the StandardizedRfTesting sample in EmberZnet SDK?
Description
The StandardizedRfTesting sample application demonstrates the RF testing through TIS (Total Isotropic Sensitivity) / TRP (Total Radiated Power) interfaces. This sample is initial released in the 6.7.x EmberZnet SDK and can be used for customer's Zigbee product to pass the TIS / TRP RF testing. This article introduces how to build the StandardizedRfTesting sample and demonstrates how it works on Silabs BRD4162 radio boards.
Regarding the test procedure of the TIS / TRP is out of the scope of this KBA, please refer to the Zigbee Alliance specification "docs-19-01701-00-Zigbee RF Performance (TRP/TIS) Specification & Test Plan" for more information.
Setup
You will need
Hardware:
2 WSTK main board (BRD4001A)
2 radio boards, the brd4162 radio board is used in this exercise
Software:
Generate and build the sample
Click File > New > Project This will launch the New Project Wizard.
Select Silicon Labs AppBuilder Project and press Next >
Locate the ZCL Application Framework V2 and select it, click Next >
Select EmberZNet 6.7.5.0 GA SOC 6.7.5.0 and click Next >
Select StandardizedRfTesting and click Next >
The Project Configuration page will come up, give your project a name. Leave the location as default. Click Next >
Finally, you will arrive at the Project Setup screen. Here we will select the parts and compiler we are using for this project. They are as follows:
Select Board: EFR32MG12 2.4 Ghz 10dBm Radio Board (BRD4162A Rev A00) and the part number will be selected automatically
Compiler: You can use gcc or IAR ARM to compile this project, for this exercise we use gcc: GNU Arm v7.2.1
Click the Finish button and wait for your project to be generated.
Click the Generate button to generate all of the files for your application.
Once generated, you will see a Generation validation dialog box. Make sure that you don't overwrite callbacks.c file as shown in this image. Click OK.
A Generation successful message should appear next. Click OK.
Click on your StandardizedRfTesting project and build using the hammer icon in the toolbar. Once built successfully, you will see the .s37 binary file in the project.
How it works
One verification test is to flash two WSTK radio boards with the StandardizedRfTesting firmware example as shown above in figure 1. One radio board works as DUT and another one works as Command Module. We can use the Command Module to attempt to communicate over the air with the DUT. This will verify that the DUT will be able to communicate with the test controller via OTA commands. The suggested process for this is:
Flash one WSTK radio board (DUT) with StandardizedRfTesting firmware and appropriate bootloader.
Flash another WSTK radio board (Command Module) with StandardizedRfTesting firmware and appropriate bootloader.
Power on the two radio boards. Connect the Command Module to laptop with USB cable.
Open the console of the Command Module: StandardizedRfTesting> cust find
If Command Module is successfully communicating with the DUT over the air, you will see this on the Command Module console: FIND ACK
If Command Module is no over the air communication, you will see the following on the Command Module console: NO PING ACK
Here is an example to show the CLI commands used during the TIS testing:
The prefix “r” and “l” of the command mean the command impacts on remote device (DUT) or local device (Command Module) respectively. For example:
“cust rsetpower 0x14”, which means set the tx power for remote device.
“cust lsetpower 0x14”, which means set the tx power for local device.
Regarding the four parameters of the rsetchannel/lsetchannel commands, which is the 32 bits channel mask (0xFFFFFFFF) split into 4 bytes. The bit0 is on behalf of channel 0, bit1 is on behalf of channel 1, bit2 is on behalf of channel 2, etc. So the 0x00001000 means channel 12. Here is some more example:
The test result will be reported to Command Module from DUT after typing the command cust rend: StandardizedRfTesting> cust rend
[total]0x00001388 [protocol]0x00001388 [totalLqi]0x00078D98 [totalRssiMgnitude]0x0005B8D8
“total” is the total number of packets received in hex (here 0x1388 = 5000d). “totalRssiMgnitude” is the total RSSI in hex (here 0x5B8D8 = 375000). Avg RSSI can be found by dividing totalRssiMgnitude by total (0x5B8D8/0x1388 = 375000/5000 = -75.00 dBm). totalLqi is also available here, but the RSSI is more useful since it is what is used by the upper level tester to calculate the relative RX antenna pattern.
Note: The RF testing should be operated in shield room.
Conclusion
This KBA introduces how to build the StandardizedRfTesting sample step by step and demonstrates how to use the StandardizedRfTesting firmware for pre-test before sending your product to the test house. More info about the other related CLI commands you can refer to the source code in StandardizedRfTesting_callbacks.c file.
Telegesis Legacy Module Firmware
Telegesis modules are low-power 2.4 GHz ISM band transceivers based on EM35x single chip Zigbee / IEEE 802.15.4 solutions. The unique AT-style command line interface allows developers to quickly integrate meshing radio technology.
On this page you will find the firmware for these transceivers. While the R309 firmware is the latest firmware, you can find versions as far back as the R303 firmware. We also have a change log attached outlining version by version changes.
Information on the Telegesis modules and kits can be found at this link.
Documentation on the Telegesis modules and kits can be found here.
Command-Line PTI Capture Utility
PTI (Packet Trace Interface) Capture is a light-weight command line utility that captures network traffic information via the Packet Trace Interface on Silicon Labs EFR32 and EM3xx devices.
This utility provides the equivalent network capture functionality of Simplicity Studio's Network Analyzer tool without opening the GUI, therefore making it useful for a large capture over a long time with minimal involvement of your computer's resources.
The latest release of the silabs-pti-capture.jar software can be found at:
https://github.com/SiliconLabs/IoT_Utility_Scripts/tree/master/pti_capture
For assistance, please refer to the user guide (README.md).
For more information on the Packet Trace Interface and why you should use it, please refer to this related KBA on Why should I enable the PTI peripheral.
Plugins
Plugins
This is one of the categories in the Zigbee & Thread Knowledge Base Articles List, all the KBAs as follow belong to the 'Plugins' category.
Basic:
Advanced:
Documentation:
RF
RF
This is one of the categories in the Zigbee & Thread Knowledge Base Articles List, all the KBAs as follow belong to the 'RF' category.
Basic:
Advanced:
Documentation:
Zigbee DMP
Zigbee DMP
This is one of the categories in the Zigbee & Thread Knowledge Base Articles List, all the KBAs as follow belong to the 'Zigbee DMP' category.
Basic:
Advanced:
Documentation:
Thread
Thread
This is one of the categories in the Zigbee & Thread Knowledge Base Articles List, all the KBAs as follow belong to the 'Thread' category.
NOTICE:
Silicon Labs Thread is deprecated in favor of OpenThread.
For more information read the full deprecation notice: Deprecation of SL Thread in favor of OpenThread
Basic:
Advanced:
Documentation:
Deprecated SL Thread Documentation: