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:

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.

• AN1154: Using Tokens for Non-Volatile Data Storage
• AN703: Using Simulated EEPROM
• AN1135: Using Third Generation NonVolatile Memory (NVM3) Data Storage
• Token Preserver
• Silicon Labs GitHub repository
• Node.js

    当客户或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布局布线图

• 如果以前无线硬件团队在另外的案例入口中评审过相关的设计，则以以前的案例（案例中评审了相同的设计）为父案例来创建新的案例。为了便于追溯，将相似的案例关联在一起是很重要的。

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

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

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

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.

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.