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

Question:

What is the default power setting for the devices in the EmberZnet stack? How can I change it? Can I set a power level for each channel? 

Answer: 

Stack version used: EmberZnet 6.4.1.0

The default power setting of the device in the EmberZnet stack is defined based on the device hardware.
If it is a EM3xx series device the default power setting is +3dBm.
If it is a EFR32 series device the default power setting is +20dBm. This setting will default to the maximum value available on the part that is being used. 

There are two ways to do change this setting relating to the AppBuilder tool. 

1. You can change the Radio output power setting (default +3dBm) of the Network Steering plugin in AppBuilder.
2. You can enable the Get radio output power from callback option of the Network Steering plugin and set your power level in your projects _callbacks.c file. In the generated callback. This callback takes the current channel as an argument and returns with the desired power level. 

This example uses that generated callback and sets the power to +10dBm if the channel number is greater than 18 otherwise it sets the power to the value described in the Network Steering plugin.

int8_t emberAfPluginNetworkSteeringGetPowerForRadioChannelCallback(uint8_t channel)
{
	int8_t power;
		if(channel > 18){
			power = 10;
		} else {
			power = emberAfMaxPowerLevel();
		}
  return power;
}

In the example the board configured is a BRD4162A board with a blank application based end device. Where the modifications were the following: 

• The code above was added
• Custom commands for checking radio power and channel. 

The result can be seen below. The project used for this test can be found attached to this article. 

NWK Steering: Start: 0x00
RadioPowerTest>Starting scan on channel 14
Starting scan on channel 15
Starting scan on channel 19
Starting scan on channel 20
Starting scan on channel 24
Starting scan on channel 25
NWK Steering State: Scan Secondary Channels and Use Centralized Key
Starting scan on channel 18
Starting scan on channel 19
Starting scan on channel 20
Starting scan on channel 21
NWK Steering joining 0x25D5
EMBER_NETWORK_UP 0x4F02
NWK Steering network joined.
Update TC Link Key: Starting update trust center link key process: 0x00
Update TC Link Key: Requesting link key from R21 trust center: 0x00
Update TC Link Key: New key established: 0x03
Partner: 8B 9F DE FE FF 57 0B 00 
NWK Steering: Trust center link key update status: 0x03
Update TC Link Key: New key established: 0x65
Partner: 8B 9F DE FE FF 57 0B 00 
NWK Steering: Trust center link key update status: 0x65
pJoin for 180 sec: 0x00
NWK Steering: Broadcasting permit join: 0x00
NWK Steering Stop.  Cleaning up.
Network Steering Completed: Join Success (0x00)
Finishing state: 0x06
Beacons heard: 1
Join Attempts: 1
RadioPowerTest>getPower returned: 10
RadioPowerTest>getChannel returned: 21
RadioPowerTest>

As you can see the device I joined was on channel 21 thus the power setting is +10dBm.

It is important to Note that currently the default power setting of +20dBm will be used during the initial network scan that happens every time a network join is initiated in ZigBee 3.0 if the device in question is an EFR32 series device (+3dBm will be used for EM3xx series). This means that the methods mentioned above are only suitable for changing the radio power level settings during joining a network and for the communications that are taking place after the network was joined.  

This also means that these setting do not affect the power setting before the network is joined. If you want to change the default power level you can use the emberSetRadioPower(int8_t); callback to override the power setting from the default +20dBm.

The following example shows how to use this callback by calling it in emberAfMainInit after the device has been initalized to set the power to 0dBm. 

void emberAfMainInitCallback(void)
{
	int8_t power = 0;
	EmberStatus status;
	status = emberSetRadioPower(power);
	emberAfCorePrintln(" SetRadioPower status: 0x%x",status);
}

Note: In Zigbee R22 there is a similar callback to emberAfPluginNetworkSteeringGetPowerForRadioChannelCallback for the Network Find plugin which can be used to set the power level for different channels. 

Question: What can I do to get around the post build batch file invocation failures with Ember ZNet 5.7.2  on Simplicity Studio 4?

Answer: 

The post build batch file takes the *.out file from the build and generates 32 bit *.s37 file and *.ebl file. 

There are 2 problems that occur with the post build batch file invocation:

1. The path of the batch file is incorrect after generation and therefore the post build process does not get executed. To fix this, edit SiliconLabs\SimplicityStudio\v4\developer\stacks\znet\v5.7.2.0\tool\appbuilder\addition.slsproj and add single quotes around the .bat path like so - 

  $-studioCmdLaunchCommand$ '$genDir$/app/builder/$deviceName$/$deviceName-$.bat' ${BuildArtifactFileBaseName} ..

Since this is a change in the SDK, you will need to close and reopen Studio and refresh the SDK (Window -> Preferences -> Simplicity Studio -> SDK's -> Select only the SDK 5.7.2  – If not, this operation will take a long time as all installed SDK's will be refreshed > Press ctrl + shift + F5 to refresh. 

2. The path to the em3xx_convert.exe file is not reachable. To fix this, add windows environment variable to define ISA3_UTILS DIR to wherever your em3xx_convert.exe file is. Example : _

Silicon Labs recently released an update that included ZNet 6.4.1. The update was to correct an issue in RAIL, modifying the Gecko SDK to 2.4.1, RAIL_LIB 2.5.1.0 and Bluetooth SDK 2.10.1.

The update contains no bug fixes for Zigbee, and updating has no effect on your ZNet stack or applications. Both 6.4.0 and 6.4.1 will be Zigbee certified.

If you are doing any Dynamic Multiprotocol (DMP) with BLE, we do recommend installing the updates. Please see the Bluetooth release notes if this may apply to you.

This KBA deals with locating and downloading the wireless mesh stacks. If you are looking for information on getting access to the stacks, go here.

Once you have registered and gotten access to our wireless mesh stacks, you can download the stacks in one of two places. First is Simplicity Studio v4 the second is the support portal. The stack version you are looking will make a difference on your download method.

If you are looking for earlier stacks, prior to and including EmberZNet 5.7.1 use the support portal to download them.

If you are looking for the latest stacks, specifically stacks from EmberZNet 5.7.2 and later, use Simplicity Studio v4.

Simplicity Studio

Simplicity Studio v4 allows for easy integration of the stacks within the development tools. Using the easy to use Package Manager, you can quickly download stacks and have them ready to use within just a few minutes.

To download the stacks, you first need to go to the Launcher perspective of Studio and click on the Update Software button which can be found in the tool bar.

The stacks appear in the SDK Tab of the package manager (you might need to click through the Installation Manager windows to get to this page).

Within this tab you can find all of the available stacks for you. They are sorted by categories. The view allows you to see all categories or just narrow down to a single category, like EmberZNet or Thread. You can also choose which versions you want, looking at just the latest, all available versions or the ones you have installed. You can also look at the versions which match a version of the Gecko Suite, so you will have the matched versions of different stacks.

If you have access to unreleased stack versions, certain beta stacks can be found within the Early Access tab.

Be mindful that not every stack is available through Simplicity Studio, only stacks from around mid-2016. Most components like ECC Libraries are also not found within Studio either. For these you will need to locate them within the support portal. 

Support Portal

If you want to install the stacks separately from Studio or are looking to locate for packages that are not available within Studio, you can locate them within the support portal.  This includes older software like the ISA3 Utilities and Ember Desktop.

To locate these, you will need to log into your portal account and click on the Software Releases tab within your account. From there you can use the pulldown menu to change display options, the All Software tab shows everything if you are looking for that.

Contact support with any questions or problems.

Under most circumstances you will want to build a Z3 Coordinator with our Z3Gateway sample application. However, this requires building an NCP and a host app and utilizing a PC or Raspberry Pi. However, you can also build a much simpler Coordinator with our Z3Light sample application. It requires a few changes to the Z3 Light application.

1. On the ZNet stack tab of the application, Change device type to Coordinator or Router
2. On the Plugins Tab:
   1. Include Network Creator plugin
   2. Include Network Creator Security plugin
   3. Within the Network Creator Security plugin you will also need to enable Trust Center Support

Once this is done, you can then generate your application and build it.

Once you have built and loaded your application from the CLI you can start a centralized network with the following command:

plugin network-creator start 1

How to form Zigbee 3.0 network with EmberZnet stack?

Background:

As you know, currently the Zigbee Alliance only certificates the Zigbee 3.0 devices, some customers are familiar with HA1.2 network, but for Z3.0 network, there are many differences. This article is talking about how to form Z3.0 network with EmberZnet stack. Hope it is helpful for some junior Zigbee engineers who develop the Z3.0 devices.

Before we talk about the Z3.0 network, let's review the HA1.2 network quickly. It is easy to setup HA1.2 network, especially, Silicon labs provide lots of CLI commands which can be used conveniently. Here are the examples:

1. For HA1.2 network

• On coordinator, if you want to form the network on the given channel, power and Pan Id, you can use below CLI command:

// Form HA1.2 network on coordinator
>> network form [channel:1] [power:1] [panId:2]
eg: 
>> network form 12 3 0x1234

If you want to search for an unused Channel and Pan Id, and automatic form a network on the first unused Channel and Pan Id it finds, you can use below CLI command.

// Form HA1.2 network
>> network find unused

Permit joining after the network is formed.

// Permit joining
>> network pjoin [time:1]
eg:
>> network pjoin 200

• On router or end device, if you want to join the network, you can use below CLI command.

// Joining a network
>> network join [channel:1] [power:1] [panId:2]
eg:
>> network join 12 3 0x1234

2. For Z3.0 network

The Zigbee Alliance specifies the details of Z3.0 network in docs-13-0402-13-00zi-Base-Device-Behavior-Specification.pdf, any customers can download this file on Zigbee website if they are members of Zigbee Alliance.

First, you should know the difference between the Centralized and Distributed network in Z3.0 network.

Centralized security network:

A centralized security network is a ZigBee network formed by a ZigBee coordinator with the functionality of a Trust Center. Each node that joins such a network is authenticated with the Trust Center before it can operate on the network.

Distributed security network:

A distributed security network is a ZigBee network formed by a ZigBee router and which does not have a Trust Center. Each node that joins such a network is authenticated by its parent before it can operate on the network.

Then, let's use CLI commands to form the Z3.0 network. If you want to form Z3.0 network, you can use below CLI command:

// Form Z3.0 network.
>> plugin network-creator form [centralized:1] [panId:1] [radioTxPower:1] [channel:1]

//Form centralized network.
>> plugin network-creator form 1 0x1234 3 12

//Form distributed network.
>> plugin network-creator form 0 0x1234 3 12

If you want to search for an unused Channel and Pan Id, and automatic form a network on the best unused Channel and Pan Id it finds, you can use below CLI command.

// Form Z3.0 network.
>>plugin network-creator start [useCentralizedSecurity:1]

//Form centralized network.
>> plugin network-creator start 1

//Form distributed network.
>> plugin network-creator start 0

Open network after the network formed. If you go through the detailed implementation of this CLI command, it sets the TC policy and opens the network, but additionally puts the well known key into the transient key table.

// open network
>> plugin network-creator-security open-network

If you want to join the network for routers or end devices, you can use below CLI command:

//option = 0 means the device will update TCLK after joining centralized network succeed,
//otherwise it won’t.
>> plugin network-steering start [options:1]

// Update TCLK after joining network succeed.
>> plugin network-steering start 0

Please note that, for router devices, it will form distributed network once it fails to join centralized network.

In conclusion, you can use above CLI commands to setup Z3.0 network, meanwhile, we have Z3Gateway/Z3LightSoc/Z3SwitchSoc samples in stack, you can build these samples to do testing quickly. If you want to get more details about the implementation of the CLI commands, please refer to the source code in plugins (Network Creator/Network Creator Security/Network Steering/Update TC Link Key).

The Simulated EEPROM v1 and v2 libraries responsible for abstracting non-volatile data storage ("tokens") across the underlying flash wear-leveling medium are designed to accommodate changes in token definitions between the in-memory data on the chip and the compile-time parameters used by the currently running application.  This is done at SimEEPROM initialization time by examining the token metadata at the top of each SimEEPROM virtual page (see AN703 for background), which records the size in bytes and creator ID (a unique 16-bit value defined in the token header) of each token, and comparing this with the running application's token definitions.

In general, the result of the token comparison will be as follows:

• If the size of a Basic or Counter token or per-element size of an Indexed token has changed, the token is assumed to be different/incompatible and will be re-initialized at startup to its compile-time default value.
• Regarding Indexed (array) tokens: If an array size is decreased, elements above the new array size will be flagged as out of range and ignored.  If an array size is increased, elements that are not found in flash will be loaded from default values.
• If the token type (Basic/Counter/Indexed) has changed, the token is considered different and will be reinitialized to its default value.

Also note that changes between SimEEPROM versions can impact the tokens:

• If the saved data is in SimEEPROM v1 format and the new firmware uses SimEEPROM v2 Library and does not include upgrade library code (sim-eeprom2-1to2upgrade-stub plugin used), the SimEEPROM code will fail to initialize and will reset with an assert() failure, leaving intact the existing tokens in flash.
• If the saved data is in SimEEPROM v1 format and the new firmware uses SimEEPROM v2 Library and does include upgrade library code (sim-eeprom2-1to2upgrade), the SimEEPROM code will attempt to preserve all tokens in the manner noted earlier in this article and convert them into SimEEPROM v2 format.
• If the saved data is in SimEEPROM v2 format and the new firmware uses SimEEPROM v1 Library and does not include the plugin option for "Destructive downgrade", the SimEEPROM code will fail to initialize and will reset with an assert() failure, leaving intact the existing tokens in flash.
• If the saved data is in SimEEPROM v2 format and the new firmware uses SimEEPROM v1 Library and does include the plugin option for "Destructive downgrade", the SimEEPROM code will remove/reinitialize all token data, setting them to their compile-time default values.
• The process for upgrading from SimEEPROM v2 to NVM3 format requires addition of Creator and Key defines. This is described in AN1135.

For further information about tokens and SimEEPROM, see UG103.7: Non-Volatile Data Storage Fundamentals

Within our EmberZNet and Silicon Labs Thread stacks we provide a number of pre-built NCP images.  However, with the customability EFR32 Mighty Gecko, these NCP images don't always meet every application.  This guide, along with reading AN1010: Building a Customized NCP Application, should give you the tools to build your own xNCP image.

1. Go to File -> New -> Project. This will bring up the New Project Wizard
2. Select “Silicon Labs AppBuilder Project”. Click Next.
3. Select “Customizable network coprocessor (NCP) application”. Click Next.
4. Select the Stack you want to use. Click Next.
5. Select xNCP LED. Click Next.
6. Give your project a name, leave it in the default location. Click Next.
7. On the Project Setup Window remove any boards that are selected in the top section.  In the bottom section select the chip you are using. Hit Finish.
8. Download the board header below for your particular stack and copy it into your project (you can drag and drop it into your Project in Studio, when prompted, make sure to Copy the file into your project).
   EmberZNet 5.9.2 and prior: xNCP_board.h
   EmberZNet 5.10.0 and later: xNCP_board_5.10.x.h
9. On the General Tab
   • Selected Architecture – verify the chip you selected is there
10. On the HAL Tab
    • Change Board Header from Default to Use Custom Board Header
    • Point the Custom Board Header to file you downloaded in step 8 (it should be in your Studio v4 Workspace)
11. On the Plugins Tab
    • In the Core section pick the Plug for either NCP-SPI or NCP-UART for the NCP version you are using
    • If you are building a Smart Energy NCP, you will need to enable the CBKE and ECC plugins required for your build.
12. On the Other Tab
    • • (EmberZNet 5.9.2 and prior only) In the Additional .c and .h files section Add the following directories:

    <PATH_TO_STACK_FOLDER_ROOT>\hardware\kit\EFR32MG1_BRD4151A\config
    <PATH_TO_STACK_FOLDER_ROOT>\hardware\kit\common\bsp

13. Open the board header file from step 8 and make these changes:
    • (EmberZNet 5.9.2 and prior)
      •  Find the #define statements for which build to use

        #define UART_XNCP_BUILD
        #define SPI_XNCP_BUILD

        Comment out the one you aren’t using and make sure the one you need is defined
      • Modify the section to match the interface you have selected.  For UART, setup the Tx, Rx, CTS and RTS pins.  For SPI, setup MOSI, MISO, CS and CLK as well as the nHOST, nWAKE and nSSEL (CS) pins.
        See below for where to find ROUTELOC definitions to match these pins.
    • (EmberZNet 5.10.x)
      • If you are building a UART NCP, edit the section titled /* USART0 */.  Setup Tx, Rx, CTS and RTS pins that you are using for your NCP.
        See below for where to find ROUTELOC definitions to match these pins.
      • If you are building a SPI NCP, edit the section titled /* USART1 */.  Setup the MOSI, MISO, CS and CLK pins.
        Additonally, edit the section titled /* SPINCP */.  You shouldn't have to change the USART port, but match the nHOST and nWAKE pins to your design.
        See below for where to find ROUTELOC definitions to match these pins.
    • You can get the ROUTELOC definitions from the Mighty Gecko datasheet corresponding to your model of Mighty Gecko (MG1, MG12 or MG13).  Links to the datasheets are below.
    • Once the modifications are made, save the file
14. Generate the files for your project
15. Build your project

 Use the following KBA for building a bootloader:

Make customized ZigBee bootloader for the EFR32MG1 QFN32 parts
 

 Additional Information:

AN1010: Building a Customized NCP Application

EFR32MG1 Mighty Gecko ZigBee & Thread SoC Family Data Sheet (Section 6.4)

EFR32MG12 Mighty Gecko Multi-Protocol Wireless SoC Family Data Sheet (Section 6.4)

EFR32MG13 Mighty Gecko Multi-Protocol Wireless SoC Family Data Sheet (Section 6.6)