Zigbee and Thread Wireless Knowledge Base

Zigbee & Thread Knowledge Base

Publish

What are the valid values for txPower in EFR32 devices?

Verthika Varati | 11/329/2020 | 06:39 PM
The EFR32 families of chips each come equipped with multiple Power Amplifiers (PAs):
- EFR32xG1x
  
  A high-power * 2.4 GHz PA (for power 20 dBm and lower)**
  
  A low-power 2.4 GHz PA (for power 0 dBm and lower)
  
  A Sub-GHz PA**
- EFR32xG21
  
  A high-power 2.4 GHz PA (for power 20 dBm and lower)**
  
  A medium-power 2.4 GHz PA (for power 10 dBm and lower)
  
  A low-power 2.4 GHz PA (for power 0 dBm and lower)
- EFR32xG22
  
  A high-power 2.4 GHz PA (for power 6 dBm and lower)**
  
  A low-power 2.4 GHz PA (for power 0 dBm and lower)
Each of these PAs has a unique number of discrete “power levels”, which are simply abstractions of the different register settings that control the active PA. For each PA, the following power levels are available:
- EFR32xG1x
  
  High-power 2.4 Ghz: 0-252**
  
  Low-power 2.4 Ghz: 1-7
  
  Sub-GHz: 0-248
- EFR32xG21
  
  High-power 2.4 Ghz: 1-180**
  
  Medium-power 2.4 Ghz: 1-90
  
  Low-power 2.4 Ghz: 1-64
- EFR32xG22
  
  High-power 2.4 Ghz: 0-128**
  
  Low-power 2.4 Ghz: 0-15
*Note that the use of 'high', 'medium', and 'low' in the names of these PAs refers to power consumption, not power output. It is possible, for instance, to configure the high-power PA to transmit at a lower dBm output than the low-power PA.

**Maximum power/use of these PAs may be restricted by your specific OPN. Please see the data sheet for more details regarding your particular part.

For more details and to set custom power curves for your design, refer AN1127: Power Amplifier Power Conversion Functions in RAIL 2.x
Master Wireless Hardware KBA list for EFR32 Series 1 SoCs and Wireless Modules

SunnyA | 10/304/2020 | 04:08 PM
This Knowledge Base Article (KBA) aims to organize all Wireless Hardware related technical documents and related individual KBAs for EFR32 Series 1 SoCs and Wireless modules together in one place.

The KBA organizes all technical documents into categories for a better and convenient way to refer to the contents while designing a custom application based on these parts. The categorized RF hardware contents are as follows:-

[A] EFR32 Series 1 Wireless Modules:

Application Notes:
- AN1048: Regulatory RF Module Certifications
- AN1223: LGA Manufacturing Guidance
- AN928.1: EFR32 Series 1 Layout Design Guide
- AN958: Debugging and Programming Interfaces for Custom Designs
- AN0016.1: Oscillator Design Considerations
- AN1088: Designing with an Inverted-F 2.4 GHz PCB Antenna
- AN1128: Bluetooth® Coexistence with Wi-Fi®
- AN1017: Zigbee® and Silicon Labs® Thread Coexistence with Wi-Fi®
- INS12840: Case study for Z-Wave usage in the presence of LTE
Knowledge Base Articles:
[B] EFR32 Series 1 Wireless SOCs:

[1] Matching Networks

Application Notes:
- AN930.1: EFR32 Series 1 2.4 GHz Matching Guide
- AN923: EFR32 sub-GHz Matching Guide
- AN1180: EFR32 Series 1 sub-GHz Discrete Matching Solutions
- AN1081: Integrated Passive Devices for EFR32 Series 1 Sub-GHz RF Matching
Knowledge Base Articles:
[2] RF

Application Notes:
- AN928.1: EFR32 Series 1 Layout Design Guide
- AN933.1: EFR32 Series 1 Minimal BOM
Knowledge Base Articles:
[3] Antenna

Application Notes:
- AN1088: Designing with an Inverted-F 2.4 GHz PCB Antenna
- AN853: SINGLE-ENDED ANTENNA MATRIX DESIGN GUIDE
Knowledge Base Articles:
[4] MCU, Power Supply and Peripherals

Application Notes:
- AN0002.1: EFM32 and EFR32 Wireless Gecko Series 1 Hardware Design Considerations
- AN0948: EFM32 and EFR32 Series 1 Power Configurations and DC-DC
- AN0016.1: Oscillator Design Considerations
- AN958: Debugging and Programming Interfaces for Custom Designs
Knowledge Base Articles:
[6] Antenna Diversity

Knowledge Base Articles:
- Recommended distance between antennas in an antenna diversity application
- How can I implement antenna diversity for EFR32MG?
[7] General

Application Notes:
- AN1128: Bluetooth® Coexistence with Wi-Fi®
- AN1017: Zigbee® and Silicon Labs® Thread Coexistence with Wi-Fi®
- AN700.1: Manufacturing Test Guidelines for the EFR32
- AN1162: Using the Manufacturing Library for EmberZNet
- AN972: EFR32 RF Evaluation Guide
- APL10045: Antennas for Short Range Devices
- INS14284: Prepare for Z-Wave Certification Tests
Knowledge Base Articles:
Green Power Device Energy profiling on MG22

Attila Banszki | 07/213/2020 | 09:57 AM
Description

This article shows how to configure the Green Power On/Off Switch sample application to be a (more) energy-optimized project and then demonstrates the energy profiling with it on EFR32MG22. Stack version used: 6.7.6

Preparing the project

First, you have to configure the Green Power On/Off Switch sample application. This means you have to disable the onboard LEDs, Serial ports, the CLI, and reduce GPD BiDirectional Rx Window.

1. Create a Green Power On/Off Switch sample application as a Silicon Labs Appbuilder Project
- When creating the project, make sure you select your EFR32xG22 board.
2. Configure the .isc file
- Open the Plugins tab and make the following changes:
  
  In the GPD App Configuration plugin change the GPD BiDirectional Rx Window to 8-10 msec. It will reduce energy consumption during BiDirectional communication. It has no impact on sleep mode current draws.
  
  Disable LED, GPD CLI, and the Command Interpreter plugins.
  
  In the Serial plugin, make sure all the 3 Peripherals are disabled. Unfortunately, you cannot turn off all the I/O plugins, because the HAL library requires them. To disable their effect, you have to add some macros in step 5.
- In the CLI tab, disable Command line interface.
3. Generate the project

4. Modify the hwconf file

Open the hwconf file of your project in Hardware Configurator. Switch to DefaultMode Peripherals view then disable Virtual COM Port. Since serial communication is disabled, there is no point in keeping the VCOMPort enabled and it would just increase the power consumption. After the modification, save the file.

5. Modify the callbacks file
- Open gpd-switch-callbacks.c file and add the following #undef macros after this code section:
  
  #if defined(EMBER_AF_PLUGIN_SERIAL) #include EMBER_AF_API_SERIAL #endif #undef EMBER_AF_PLUGIN_EMBER_MINIMAL_PRINTF #undef EMBER_AF_PLUGIN_SERIAL
  
  With these lines added, we disabled the effects of the I/O plugins that were mentioned in step 2.
- To prevent further compile errors, you have to add a type definition and implement the following function as a dummy function:
  typedef uint32_t Ecode_t; Ecode_t COM_ForceWriteData(COM_Port_t port, uint8_t *data, uint8_t length ) {}
  
  You can add these lines after the #undefs.
6. Modify hal-config.c file

For correct EM2 current, MG22 boards require the following macros to be added to the hal-config.c file:
```
#define HAL_EMU_ENABLE (1)
#define HAL_EMU_EM23_VSCALE HAL_EMU_EM23_VSCALE_LOWPOWER
#define _EMU_DCDCCTRL_MASK (1)
```
7. Compile and flash the program to your board

If you successfully programmed your board, you can start the energy profiling. You can measure the current draw in different Energy Modes and measure different commands' power consumption. The device first goes to Energy Mode 2 (EM2) then after the 10-sec timer expires it goes to EM4. This 10 second can be changed in the callback file. Waking up from EM4 is only possible with the toggle button (PB1).

Note: The MG22 board has an MX25 series SPI serial flash on it. If it is not configured properly, your current consumption can be greater with 7-8 μA than in the following pictures (both in EM2 and EM4). The chip can be put into Deep Power Down (DPD) mode, in which its current draw is around 100 nA. To do it, SPI communication is required thus the serial ports are also required, which would increase the current draw. A solution is to first upload an application that has SPI interface enabled (in Hardware Configurator) and issues the chip to DPD as described here. It is also possible to physically remove the chip from the radio module.

Without the MX25 chip, EM2 current should be around 1.8 μA while EM4 current should be around 300 nA.

Commission with reduced BiDirectional Rx Window

Since we reduced the BiDirectional Rx Window, we cannot commission the device with a Z3LightGPCombo. The reason is that the window of receive time is too short for the proxy's debug prints. To solve this issue, you have to disable the CLI on your Z3LightGPCombo. You can put the sink into commissioning mode by pressing PB0.

Measuring power consumption with Simplicity Studio Energy Profiler

Simplicity Studio offers a very convenient, but not the most accurate method for measuring power consumption. This document helps you to get started with Simplicity Studio Energy Profiler.

Note: Energy Profiler's “scope” capabilities and measurement accuracy (1 μA) are limited by the 10 kHz maximum sampling rate of the AEM circuitry on the WSTK. In the picture below, you can see some command's current draw spike and EM2-EM4 currents.

Measuring power consumption with lab instruments

A more precise way to make the energy profile is to use a DC Power Analyzer. These devices usually provide the possibility of measuring with 4-wire sensing technique.

A detailed description of the measurements with lab instruments can be found here in section 2-3.

Measurements with a digital multimeter

Profiling different commands' energy consumption

GP message frames may contain different payloads alongside with the command ID. You can read more about command payloads in the Zigbee Green Power Specification. These payload lengths affect the energy consumed by sending the command.

With the project you made before, you can measure the power consumption of different commands. (For this, your device is not required to be commissioned.)

In gpd-switch-callbacks.c, find the sendToggle function. The Toggle command is a payloadless command, so there is only one byte in the command array (the command ID). You can add more bytes (payloads) to this array and observe how the energy consumption changes with PB1 presses. A noticeable change can be seen if you start increasing the payload length by i.e. 5 bytes.

In the pictures below you can see the difference of the power consumption between a payloadless and 32 bytes length payload command:
How do I maintain application tokens when OTA updating devices?

RonB | 06/170/2020 | 09:52 PM
Application "tokens" are bits of data stored in Non-Volatile Memory (NVM). They are created with a Token Key so that the information stored can be easily retrieved by the application layer without knowing the absolute memory address (note: more details about tokens can be found in AN1154: Using Tokens for Non-Volatile Data Storage and about NVM storage in either AN703: Using Simulated EEPROM or AN1135: Using Third Generation NonVolatile Memory (NVM3) Data Storage).

Simplicity Studio's AppBuilder currently (as of SV4.x.x) creates the token file and allocates token keys to these tokens every time an application is generated or regenerated. For Zigbee projects you can find the application tokens that will be stored in NVM in file <project_name>_tokens.h

However, AppBuilder has no knowledge of token keys that were used previously for the same the token data. If new tokens are created during the generation, for example we want to store additional cluster attributes to NVM, then the new token keys could conflict with the existing token keys.

This has limited impact during development but could be a problem when OTA updating deployed devices.

If the means to access the tokens that were used previously (in the previous version of an application) are not preserved, then the new application can produce indeterminate results when it is run. The new token key may have been used for a different token in the previous version of the firmware. So, the token that used to represent the binding of the application might now map to the space for the setting of the light color, etc... As some application settings are stored in NVM, this could result for example, in a light that was warm white now turning cool white after the OTA upgrade, or that was OFF to now be ON.

This is undesired and you want the light to come back online exactly as it was before the OTA upgrade without the need for a reset to factory defaults. In order to ensure this behavior, the layout of the token address space must be preserved across application upgrades.

Note that this relates to application tokens and not to stack tokens. The token keys for stack tokens are fixed/preserved so that after an OTA update the device can rejoin the network that it belongs to without user intervention. A factory reset would clear these tokens resulting in the device being removed from the network. The stack tokens can be found in file <SDK_install_directory>/stack/config/token-stack.h

The Silicon Labs team is working on a long-term solution for this but until one is available inside Simplicity Studio we’ve created a script that provides a workaround for the problem.

It does this by first reading the 'old' token header file and then reading the 'new' token header file. From these two files it 'writes' a 3rd token header file which preserves the token key values of the 'old' file while at the same time assigning unused token key values for the 'new' tokens. This ensures that any new tokens will be initialized to their default values and preserves the values of the previously defined tokens.

So, an application token for light temperature will continue to use the same token key after the OTA upgrade of the device. The light that was warm white prior to OTA upgrade will continue to be warm white after the OTA upgrade.

This script is written in Node.js and you need to make sure you have the node engine on your workstation. It can be downloaded from the official Node.js site.

The “Token Preserver” script can be found on Silicon Labs GitHub repository.

With the node engine installed you run: 'node token_preserver.js' in your shell and it will print out the usage information.

An example to demonstrate this uses two header files, 1-old.h (used with the original application) and 1-new.h (generated by the updated application) resulting in an updated 1-mod.h below.

We can see that in the original application the following token keys:
```
CREATOR_START_UP_ON_OFF_1, CREATOR_CURRENT_LEVEL_1, CREATOR_OPTIONS_1 and CREATOR_START_UP_COLOR_TEMPERATURE_MIREDS_1
```
didn’t exist. These have been created by app builder when generating the new project but need their token key values to be renumbered by the script. Note that “creator code” is the same as token key (see AN1154 section 3.2.1 for details).

Several of the other token keys in 1-new.h though did already exist, but with different token keys in 1-old.h. If the newly created token keys do not match those of the original application, then the data fetched by the application will represent something else.

For example; in the 1-new.h file the token key 0xB004 is used for the CREATOR_CURRENT_LEVEL_1 token whereas in the devices memory, which uses token keys specified in 1-old.h, that key is used with token CREATOR_COLOR_CONTROL_CURRENT_X_1. The script changes the token key value for the updated application to match the original.

The final step is to replace the 1-new.h file that was generated when creating the new project with the 1-mod.h file that has been created using the token-preserver script. Then rebuild the project.
提交基于EFR32MGxx硬件设计评审的预期事项

JunFan | 06/170/2020 | 07:43 AM
当客户或FAE想要在Salesforce中创建一个硬件设计评审服务的案例时，他或她须检查以下能对无线SOC和模块进行彻底有效评审的预期事项，这是非常重要的。
- 提供产品用例的简短描述。
- 提交原理图评审的检查清单
  
  原理图应以可搜索的PDF格式提供，因为这将允许评审人在多张页面的原理图中搜索指定的网络或器件。
  
  最好提供整个设计原理图，但是，如果因保密要求而无法提供整个原理图，那就在案例说明中提供所用电源、主机MCU型号和其他无线器件型号（如有）的详细信息，以便彻底评审。例如，如果设计中有WiFi部分，而在提供的原理图中看不到，那么我们提供的评审反馈就不那么完整，因为在单个PCB上临近位置的多个无线电需要额外的软件和硬件更改来改善无线电之间的共存。
  
  在原理图中未提及的情况下，提供连接到EFR32的所有元器件的型号，因为元器件特性可能因尺寸不同而不同，就可能影响预期的性能，例如，由于匹配网络的失调而影响的射频性能。另外，请提供HFXO和LFXO（如有）晶体的规格书，因为晶体可能有多种变量，如果没有提供完整的型号，找到正确的规格书将会令人困惑。
  
  除了规格书的建议外，还应参考以下文件，并尽可能遵循原理图设计指导，以达到最佳性能。
  
  芯科实验室的相关器件参考板的原理图。选择参考设计中的满足规格书要求的元器件值。
- 提交PCB布局布线评审的检查清单
  
  PCB布局布线应以Gerber文件格式提供所有层，包括焊接掩模、锡膏和钻孔文件。一般来说，Gerber文件是提供给PCB制造商的，因此重要的是评审最终设计文件，而不是CAD文件本身，以便检查可能导致制造或性能问题的任何异常。
  
  除了规格书建议外，还应参考以下文件，并尽可能遵循PCB布局布线指导，以实现最佳性能，尤其是射频性能。
  
  AN928.1 for EFR32xG1x
  
  AN928.2 for EFR32xG2x
  
  芯科实验室的相关器件参考板的PCB布局布线图
- 如果以前无线硬件团队在另外的案例入口中评审过相关的设计，则以以前的案例（案例中评审了相同的设计）为父案例来创建新的案例。为了便于追溯，将相似的案例关联在一起是很重要的。
Illuminance measuring with Thunderboard Sense 2 - Testing

Tibor Bakos | 06/164/2020 | 11:57 AM
Previous step | Project Overview

Firmware update and creation of a network

Flashing the firmware

To test our sleepy end device, it has to join to a centralized network, so firstly we have to create a network. All necessary files are attached to this description, but you can create them if you prefer.

The following firmware's for this documentation:
- Bootloader for BRD4164A
  
  see: attachments, BRD4164A_MG12_bootloader-storage-internal-single-combined.s37
- Firmware for Coordinator
  
  Z3Light Coordinator FW for BRD4164A
  
  see: attachments, BRD4164A_MG12_Z3LightSoc_663.s37
- Bootloader for Thunderboard Sense 2
  
  see: attachments, BRD4166A_TB2_bootloader-storage-internal-single-combined.s37
- Firmware for Sleepy End Device
  
  Occupancy Sensor related firmware
  
  JUST USE AS REFERENCE POINT, the output of the previous chapter should be this firmware
  
  see: attachments, BRD4166A_TB2_SED_FW_665.s37
Firstly, flash the bootloaders for both devices, secondly, upload the Coordinator related FW to the BRD4164A radio and finally, upload the previous chapter relating generated *.s37 file to the TB2. (Or as described, as a reference point you can flash the attached BRD4166A_TB2_SED_FW_665.s37 file to the Thunderboard Sense 2 development board.)

Connect the devices

Launch both devices related consoles and issue the following commands:
- 1.) send to both devices the following command: "network leave". This command will cause that the device will leave any network if it was part of a network. If the devices were not part of any network, generally nothing happens.
- 2.) send to the Coordinator: "plugin network-creator start 1" then "plugin network-creator-security open-network". The first command will create a network, the second one opens it, so other devices can connect to the network for a while.
- 3.) send to the SED: "plugin network-steering start 0". This command will cause the SED search for other networks, and if SED finds an open network, it will connect to them.
Creation of a network -> Done

Now, our Zigbee network is up, the SED should send data with a regular base and we are ready to examine it.

Figure 5. - Response messages

Examination with Network Analyzer and Energy Profile

The Network Analyzer and Energy Profiler tools provide testing possibilities to check the reporting, sleeping, timing parameters to fulfill the requirements.

Figure 6. - Network Analyzer

Figure 7. - Energy Profiler

It can be observed on the Energy Profiler figure how the device wakes up and poll its parent. The 1st waking up consumes more current due to the I2C communication and the building up of the reporting package. At the 2nd time, the APS Ack is transmitted as a reply for the ZCL Default response. The remaining two polls don't require as much effort as before, since the data request message doesn't affect the upper layer than the MAC.

To minimize the current consumption, the EM4 plugin can be used, but then it causes negligible current decreasing compared to the sensors' consumption.

This concludes this tutorial, if you are interested in learning more feel free to check out the provided material on the project overview page.

Previous step | Project Overview
Illuminance measuring with Thunderboard Sense 2 - Driver integration and code implementation

Tibor Bakos | 06/164/2020 | 11:56 AM
Previous step | Project Overview | Next step

Project customization

The driver of the light sensor is placed in the folder of si1133_driver. It should be simply copied into the project via Simplicity Studio, like File->New File .... It's important to insert in this way, otherwise the project settings won't be applied to these files, so compillation error will happen.

This driver folder contains header files. These have to be added to the Include path of the compiler.Do this by inserting the *"${workspace_loc:/${ProjName}/si1133_driver}"* to the paths. (Right-click on Project-> C/C++ Build->Settings->Tool Settings tab->GNU ARM C Compiler->Includes)

The device can be powered from battery, hence it's important to reduce the power consumption. The TB2 includes an external SPI flash that is not used in this project. To disable this external memory, the mx25flash_spi.c/h files should be copied to the project as well. The files can be found at "SKD_PATH/v2.6/hardware/kit/common/drivers".

Figure - Neccesarry files

illuminance-si1141-stub.c

It's always a practical solution to separate the functionalities by using different files. The illuminance-si1141-stub/illuminance-si1141-stub.c serves this goal. The "stub" means that this file provides only the frame for the driver without any actual functionality. It's our task to place the driver into this file. (see: attachments of the KBA)
I recommend to copy this file into our project instead of modifying the SDK.
The halIlluminanceStartRead(..) function does the realization of getting data from the light sensor. Firstly the device should be detected by its hardware id ( detectDevice(..) ), then send the start measuring command and read the values ( getSensorData(..) ). The provided data is not in lux dimension, but it can be converted to it ( Si1133_getLuxReading(..) ).
The measured value attribute of the Illuminance Measurement cluster should be updated with the converted data. The halIlluminanceReadingCompleteCallback(data) function freshen the attribute value.

<ProjectName>_callback.c

When the Generate button is pressed in the AppBuilder, this source file might not be overwritten, thus the previously enabled callback functions should be copied manually, namely, the emberAfMainInitCallback() and emberAfPluginIdleSleepWakeUpCallback().

emberAfMainInitCallback( )

This is the appropriate function to initialize the peripherals before any operation would be done with them.
It contains the GPIO settings like disable the power line of other sensors, heartbeat, and enable the light sensor's GPIOs.
A timer should be initialized because the sensor operation requires a delay between the start and read commands (200ms). The TIMER1 is used for this purpose ( Init_TIMER1() ). At this point, it would be important to mention that the EmberZNet stack uses its timer, and it's critical to not change those settings. The used peripherals by the stack can be found -here-.

To minimizing the power consumption, the MX25 SPI flash should be turned off. The MX25_init() and MX25_DP() functions bring the flash into deep power-down mode.

To communicate with the sensor, the I2C has to be configured. The I2CSPM_Init(&i2cInit) function initialize the peripheral.

The Si1133InitUvAls(&sensI2C) function sets all the parameters of the sensor for further operations.

emberAfPluginIdleSleepWakeUpCallback(..)

This function is called after the device comes back from sleep. Its parameter, durationMs, signs how long the device slept.
This variable is used to determine whether the sleep duration was a Long- or Short poll period. The importance of this, to measure and report the light value only after a Long poll period. The ignoration of this would cause an infinite loop, since the reporting would occur at the 1st Short poll, and the Coordinator would send back the 802.14.05 Ack with true Frame Pending due to the ZCL Default Response. The 2nd Short poll would cause a new report which causes a new Frame Pending from the Coordinator and so forth.

The sensor reading and reporting happens after waking up from the Long poll period.
The halIlluminanceStartRead(..) function is defined in the illuminance-si1141-stub.c and does sensor handling as described in some chapters above.

The reporting of the measured value is done at the ReportToZC() function.

Reporting

ReportToZC( )

By taking into account the length of this function, the complete function is not presented here but it can be found among the attached source files.
The reporting is set up manually in this tutorial, but there is a Reporting plugin and a -KBA- how to use that to automate the functionality.

The working of the reporting is presented in reverse order to get a better view of how it looks like, so start with the final step.

Send the report as a Unicast message. The first two parameters mean it's an outgoing message to the Coordinator. Then the APS-, ZCL frame and ZCL's size must be added.
```
 emberAfSendUnicast(
     EMBER_OUTGOING_DIRECT,       // type
     0x0000,                      // destination
     &apsFrame,                   // aps frame
     ZclBufferLen,                // message length
     ZclBuffer);                  // message
```
To set up the APS frame, the emberAfGetCommandApsFrame() function pointer can be used.
```
 emberAfGetCommandApsFrame()->profileId = emberAfPrimaryProfileId();
 emberAfGetCommandApsFrame()->sourceEndpoint = emberAfPrimaryEndpoint();
 emberAfGetCommandApsFrame()->clusterId=ZCL_ILLUM_MEASUREMENT_CLUSTER_ID;
 emberAfGetCommandApsFrame()->destinationEndpoint = 0x01;
 emberAfGetCommandApsFrame()->options |= EMBER_APS_OPTION_RETRY;
```
After the APS frame is configured, all the elements of the frame structure are stored in a local structure like,
```
 EmberApsFrame apsFrame={
     emberAfGetCommandApsFrame()->profileId,
     emberAfGetCommandApsFrame()->clusterId,
     emberAfGetCommandApsFrame()->sourceEndpoint,
     emberAfGetCommandApsFrame()->destinationEndpoint,
     emberAfGetCommandApsFrame()->options,
     emberAfGetCommandApsFrame()->groupId,
     emberAfGetCommandApsFrame()->sequence,
     emberAfGetCommandApsFrame()->radius
 };
```
At this point the local APS frame is ready to use.
The ZCL frame is similarly stored in a local array. Have a look at the Zigbee Cluster Library Specification how this frame should look like.

Figure - ZCL Frame
```
 uint8_t ZclBuffer[8]={
     frameControl,                                          // Frame control
     SeqNum,                                                // Transaction sequence number
     0x0A,                                                  // Command identifier -> ID of Report attributes
     ZCL_ILLUM_MEASURED_VALUE_ATTRIBUTE_ID,                 // Attribute identifier[0]
     ZCL_ILLUM_MEASURED_VALUE_ATTRIBUTE_ID,                 // Attribute identifier[1]
     AttrType,                                              // Attribute data type
     AttrData[0],                                           // Attribute data[0]
     AttrData[1]};                                          // Attribute data[1]

 ZclBufferLen = sizeof(ZclBuffer);
```
The frame control is filled up like,
```
uint8_t frameControl=(
    ZCL_GLOBAL_COMMAND|
    ZCL_FRAME_CONTROL_SERVER_TO_CLIENT);
```
and the sequence number gets value via the emberAfNextSequence() function.

Here the last-, practically the first thing is to read the previously updated value of the attribute.
```
  static uint8_t AttrData[2];
  static EmberAfAttributeType AttrType;

emberAfReadAttribute(
    1,                                      //endpoint
    ZCL_ILLUM_MEASUREMENT_CLUSTER_ID,       //cluster ID
    ZCL_ILLUM_MEASURED_VALUE_ATTRIBUTE_ID,  //attribute ID
    CLUSTER_MASK_SERVER,                    //Server to Client
    &AttrData,                              //data storage
    sizeof(AttrData),                       //data storage size
    &AttrType);                             //type of the attribute
```
The attribute value is stored in the AttrData array.

Build of the firmware

Now, everything is ready to make the executable file, so we can build it. Let's do it and in the next step we will examine how does it work in practice.

Figure - Build it!

The result of this building will be placed in the project related binaries folder, called *.s37. In the following chapter, we will flash this *.s37 file to the Thunderboard Sense 2.

Previous step | Project Overview | Next step
Illuminance measuring with Thunderboard Sense 2 - Appbuilder

Tibor Bakos | 06/164/2020 | 11:54 AM
Previous step | Project Overview | Next step

Project creation

Select the Zigbee Minimal sample application as the starting point.
From SSv4 -> File -> New -> Project -> Silicon Labs Appbuilder Project -> Silicon Labs Zigbee -> EmberZnet -version- GA SoC -> ZigbeeMinimal

ZCL

AppBuilder provides pre-defined ZCL device types. This project is based on the light sensor, thus its ZCL type should be HA Light Sensor. This option selects all the clusters and attributes required by the Zigbee Alliance specification for a HA light sensor. In case we would like to use additional functionalities, it's possible to choose the Zigbee Custom.. type, and select the HA Light Sensor template from the drop-down menu. It lets us to freely select the needed clusters, and remains the Profile Id and Device Id. As per the ZigBee Lighting & Occupancy Device Specification, the Profile Id should be 0x104 with a Device Id of 0x0106.

Znet stack

Moving ahead to the Zigbee Stack tab, change the device to Sleepy End Device with a security type of ZigBee 3.0 Security.

Printing and CLI

The next tab is Printing and CLI. Enabling debug printing is highly recommended. It gives straightforward feedback on what is happening in the software stack. The default setting is enough in most cases, but in case of any issues the additional debug information helps to determine the root cause.

Plugins

Simplicity Studio prepares the essential and most frequently used plugins. To make sure all the necessary components are selected, take a look at the following list:
- Zigbee PRO Leaf Library
  
  End Devices are not required to participate in Network Layer communication. The Zigbee PRO Leaf Library is a subset of the Core Zigbee Pro Library with the unsupported functionalities removed to conserve space. It includes all the required libraries by an End Device.
- Network Steering
  
  It provides a complete solution to find and join the network. The plugin is compliant with Zigbee 3.0 Network Steering.
- End Device Support
  
  This plugin implements the polling mechanism. The poll intervals are configured here, as follows: Short Poll: 1 second, Long-Poll: 10 seconds. The default Wake Timeout value (3 seconds) and bitmask (0x18) means that the device doesn't go back to sleep immediately after waking up, rather it remains in short poll mode for 3 seconds until it receives ZCL or ZDO responses. This setting fits for our application since the device will send reports and it's important to get the APS ACK from the Coordinator. More information about the polling mechanism can be found -here-.
- Idle/Sleep
  
  The plugin provides the possibility of deep sleep for the sleepy end device when there are no tasks to perform. The radio is turned off during this state, therefore it significantly reduces the power consumption. On the other hand, it makes the device to be more unresponsive, thus it's recommended to enable the "Stay awake when NOT joined".
- Serial
  
  A fundamental task to communicate with the device, and the Serial plugin serves this goal. By default, the SERIAL and USART0 should be enabled. Furthermore, the flow control mode should be turned off since TB2 doesn't support flow control.
- Illuminance Measurement Server Cluster
  
  The Illuminance Measurement Server Cluster plugin includes the necessary functions to store the measured value in the correct ZCL attribute.
- Illuminance Si1141 Stub
  
  Although the used sensor is not exactly the Si1141, the plugin is a good starting sample for us to extend with the Si1133 driver.
Callbacks

Two callback functions are used in our application:

The Main init - void emberAfMainInitCallback(void); function, which is called at stack startup. Anything that would be at the top of the main function should be put here. It's the right place to initialize the sensor-related functionalities like GPIOs, the timer, the I2C, and the
sensor itself.

The other used callback is the - void emberAfPluginIdleSleepWakeUpCallback(uint32_t durationMs); callback. This function is called directly after the device wakes up. The illuminance measuring, measured value storing, and reporting are performed in this routine.

Enable both on the Callbacks tab and copy their stubs to the -projectname-_callbacks.c file.

Hardware Configurator

The Hardware Configurator is not part of the above detailed App Builder, but it's also a fundamental tool. As its name suggests, its function is managing the low-level peripheral settings. Use it by opening the -part-.hwconf file and save it to generate the hal-config/hal-config.h file, where the selected settings are represented as #defines that change the behavior of the rest of the source.

By opening this file and switching to "DefaultMode Peripherals" view, the SPI Flash check-box should be picked. It's necessary because the driver of the external flash refers to its #define.

Generate

Now all the necessary components are set up, it's time to Generate the project files. This process will generate all the Zigbee stack related files automatically, some of the files can be tailored according to custom needs. The next step explains customizing the generated files where necessary.

Figure - Generate

Previous step | Project Overview | Next step
Illuminance measuring with Thunderboard Sense 2 - Overview

Tibor Bakos | 06/164/2020 | 11:36 AM
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
FILES.ZIP
Switching antenna path on Series 2 devices (EFR32MG21, MGM210) in EmberZNet stack

Patrik | 05/142/2020 | 10:31 AM
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.