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:

• - 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

1. join to a network manually
2. sleep for 10 seconds
3. measure the ambient light
4. store the measured value into Illuminance Measurement cluster
5. report the value to the Coordinator
6. repeat from 2nd step

HW and SW requirements: 

Software

•  - Simplicity Studio V4
•  - EmberZnet stack version 6.6.x

Hardware

• WSTK  

  •  - BRD4001A   
  •  - For Radio Board (BRD4164A), act as coordinator 

• Radio Board   

  •  - BRD4164A   
  •  - Act as coordinator  

• Thunderboard Sense 2 development board  

  •  - BRD4166A   
  •  - Act as sleepy end device

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

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

• 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.

    • Application note	EFR32xG1x	EFR32xG2x
      Hardware Design Considerations	AN0002.1	AN0002.2
      Oscillator design considerations	AN0016.1	AN0016.2
      EFR32 2.4 GHz Matching Guide	AN930	AN930.2
      EFR32 Sub-GHz Matching Guide	AN923	-
      EFR32 Minimal BOM	AN933.1	AN933.2
      Power Configurations and DC-DC	AN0948	AN0948.2
      Debugging and Programming Interfaces for Custom Designs	AN958

    • 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.
    • AN928.1 for EFR32xG1x
    • AN928.2 for EFR32xG2x
    • Silicon Labs' reference board layout for the part
• 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. 

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:

  • EmberZNet SDK version 6.7.5 or higher

Generate and build the sample

1. Launch Simplicity Studio v4 if you haven’t already and go to the Launcher view to start from the home screen.

2. Click File > New > Project This will launch the New Project Wizard.

3. Select Silicon Labs AppBuilder Project and press Next >

4. Locate the ZCL Application Framework V2 and select it, click Next >

5. Select EmberZNet 6.7.5.0 GA SOC 6.7.5.0 and click Next >

6. Select StandardizedRfTesting and click Next >

7. The Project Configuration page will come up, give your project a name. Leave the location as default. Click Next >

8. 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

9. Click the Finish button and wait for your project to be generated.

10. Click the Generate button to generate all of the files for your application.

11. 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.

12. A Generation successful message should appear next. Click OK.

13. 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:

1. Flash one WSTK radio board (DUT) with StandardizedRfTesting firmware and appropriate bootloader.

2. Flash another WSTK radio board (Command Module) with StandardizedRfTesting firmware and appropriate bootloader.

3. Power on the two radio boards. Connect the Command Module to laptop with USB cable. 

4. 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

5. 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

6. 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.

7. 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:

// channel 12
cust rsetchannel 0x00 0x00 0x10 0x00
// channel 15
cust rsetchannel 0x00 0x00 0x80 0x00
// channel 20
cust rsetchannel 0x00 0x10 0x00 0x00

8. 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.

9. 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:

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

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:

• How to set up reporting functionality in EmberZNet stack, and how to use it?
• Packet Handoff plugin how-to guide

Advanced:

• How does the Concentrator Plugin work?

Documentation:

• ug105-adv-app-programming.pdf                                         
• ug391-zigbee-app-framework-dev-guide.pdf                              

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:

• How does temperature affect radio performance?
• Testing EM3xx Transmit Over Temperature
• What are the valid values for txPower?
• What are minimum crystal tolerances?
• What is the range of our Reference Design?
• Overview of EFR32 series 1 matching networks for 2.4Ghz frequency band
• RF shield vs. RX immunity
• Why does Ember recommend a 3.3K resistor across the 24 MHz crystal?
• Why did my range not improve significantly when I added a PA on one side of the link?
• Where can I obtain source code for the NodeTest (or HALTest or RangeTest) application?
• EM3xx RF Tuning
• EM3xx 24MHz Crystal Tuning
• EM3xx – Prevent Damage to ISA3 When Connecting to Line Powered Targets
• VCO spur radiation issue with Si4x6x RF chips
• Si4x6x reference designs with external power supply
• Si4010 keyfob antenna design and tuning tips
• EM3xx – ETSI EN 300 328 Adaptivity Compliance

Advanced:

• EFR32 sniffer function
• EFR32 2.4GHz discrete RF match
• Turning any EFR32 into a Zigbee or Thread Sniffer
• How can I implement antenna diversity for EFR32MG?
• What do the displayed results in the Nodetest RX command output mean?
• How to Manually Set-up the Arb Waveform Generator for functional test
• My EFR32 is not outputting the power Im expecting for my zigbee (EmberZNet) application. How do I improve it?

Documentation:

• AN700.0: Manufacturing Test Guidelines for the EM35x                
• AN700.1: Manufacturing Test Guidelines for the EFR32                                                                    
• AN709: Adjacent Channel Rejection Measurements for 802.15.4 Radios                                             
• AN718: Manufacturing Test Overview
• AN1019: Using the NodeTest Application
• AN1162: Using the Manufacturing Library for EmberZNet                            
• AN1181: Configuring Antenna Diversity for EmberZNet                                      

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:

• None

Advanced:

• Avoiding shared resources with Zigbee and Micrium.

Documentation:

• an1133-dynamic-multiprotocol-bluetooth-zigbee.pdf                     
• qsg155-dynamic-multiprotocol-demo-quick-start-guide.pdf               
• ug103-16-multiprotocol-fundamentals.pdf                               
• ug305-dynamic-multiprotocol-users-guide.pdf                           

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:

• OpenThread FAQ
• Building a Thread Router Eligible End Device Application (with Silicon Labs Thread 2.7.1) Part 1.
• Building a Thread Router Eligible End Device Application (with Silicon Labs Thread 2.7.1) Part 2.
• Building a Thread Router Eligible End Device Application (with Silicon Labs Thread 2.7.1) Part 3.
• Can CSLIB be used with the Thread SDK?
• How to change the heap size of Thread 2.7.0.0 based applications in Simplicity Studio
• Setting up an OTA Server for Dotdot over Thread
• Thread Commissioners

Advanced:

• Building a Thread Router Eligible End Device Application Part 1.
• Building a Thread Router Eligible End Device Application Part 2.
• Building a Thread Router Eligible End Device Application Part 3.
• Building Silicon Labs Thread Sample Applications
• HAL Configurator Reference ZNet 6.0 Thread 2.4
• Migrating your Thread project to a new stack version
• Thread Leader Router
• What are the differences of  IPv6 address in Thread network?

Documentation:

• Silicon Labs Open Thread

Deprecated SL Thread Documentation:

• https://www.silabs.com/documents/public/user-guides/ug103-11-fundamentals-thread.pdf
• If you have SL Thread installed you can find more under <GeckoSDKFolder>/protocol/thread/documentation