Communications

Project Overview | Previous Step | Next Step

Now that we have formed a network, it’s time to verify that we can successfully send messages between our light and switch. To do this will be using simple ZCL commands to start and 

First click on the serial console of the switch. At the prompt enter:

zcl on-off toggle

This builds a Zigbee Clusters Library command frame. You can tell it was constructed correctly because of the output:

Msg: clus 0x0006, cmd 0x02, len 3
buffer: 01 00 02

Cluster 0x0006 corresponds to the on-off cluster.

Command 0x02 is the toggle command and length 3 corresponds to the length of the command buffer.

The buffer is 01 for the frame control, 00 for the sequence number and 02 for the command id for toggle.

Now we want to send this command to our light. Because our light is the coordinator, we know it’s Zigbee node ID is 0x0000. Because we want to send these commands from end point 1 on the switch and to endpoint 1 on the light our command to send this would be:

send 0 1 1 

Hitting enter you will see on the light that it received a message for it’s 0x0006 cluster with command 02.

T00000000:RX len 3, ep 01, clus 0x0006 (On/off) FC 01 seq 00 cmd 02 payload[]

On the switch, you will see  it received a message as well.

T00000000:RX len 5, ep 01, clus 0x0006 (On/off) FC 08 seq 05 cmd 0B payload[02 00 ]

This is a default response as it is sent back from the light to the switch.

If we look at App Builder, you can see these messages sent in the transaction view, a ZCL: Toggle followed by a ZCL: DefaultResponse. You can look at details of each message as they are sent on the side panel. For example, if you look within the event details of the the DefaultResponse, you can see that the response is Status: SUCCESS, meaning that the message was sent and properly handled.

Because our light is our network coordinator, we know that it’s address is 0x0000. However, most of the time we can’t trust that this will be the case. We need some sort of functionality to get our switch to look for and find our light and then join with the light so that it can easily send messages to the light instead of needing to know the address of the light. Additionally, the switch and light need some means of discovering if they share common clusters, like the off-off cluster. To assist with this, Zigbee provides finding & binding as a standard means of performing just this action.

If you remember back when we created our light and switch, we added a Find and Bind plugin to each device. The Light utilized the Find and Bind Target plugin while the Switch utilized the Find and Bind Initiator plugin. With these plugins, it makes finding and binding easy. Instead of having our light looking for ZCL messages doing endpoint discovery and having to manually construct a full set of ZCL messages to be sent across our network, asking for nodes to identify themselves as well as their endpoints and clusters and then binding like clusters, the plugins will take care of it all for us.

What we will first do is make the light a find and bind target for its endpoints. This will make it monitor network traffic and look for devices which are doing Find and Bind Initiation. To do this we will enter the following command:

plugin find-and-bind target 1

This tells endpoint 1 to act as an endpoint target. You will know the command works because you will see:

Find and Bind Target: Start target: 0x00

Now on the switch we must start it as an initiator. This is a similar function, but instead of target, we use:

plugin find-and-bind initiator 1

When you enter on this, you will see traffic in both the serial window as well as the network capture window as well. The process will be complete when you see 

Find and Bind Initiator: Complete: 0x00

In the serial console. 

Looking at the network traffic, you can see:

1. Our switch sends out a broadcast ZCL: IdentifyQuery. This is responded to by our light.

2. Then the switch asks the light for its full EUI64 address, the light responds to this with its EUI64.

3. Then finally the switch sends a simple descriptor request to get cluster information from the light. The light responds with 5 clusters which it is server: 0, 3, 4, 5 and 6 and no clusters which it is a client.

From this information our switch with then creates binding with clusters that it matches. For the 5 server clusters on the light, it looks to see if it is a client cluster on any of those, for the switch those are clusters 3 (identify) and 6 (on-off). So if you go to the CLI of the switch and print the binding table, you will see these new bindings, which are bound to the EUI64, not just the short ID. To print the binding table, use the following command:

option binding-table print

The output will look like this:

#  type   nwk  loc   rem   clus   node   eui
0: UNICA  0    0x01  0x01  0x0003 0x0000 (>)000B57FFFEDEA263
1: UNICA  0    0x01  0x01  0x0006 0x0000 (>)000B57FFFEDEA263

With these bindings we can then use a bsend command to tell our device to send commands to a binding for a particular endpoint.

zcl on-off toggle
bsend 1

This sends a command to our bindings on endpoint 1.

With this information, we can get to the step of making our light and switch act like a light and switch. The light will turn on or off LEDs based on attribute state, while our switch will respond to a button press instead of sending commands due to CLI entries.

Project Overview

Previous Step
Next Step

Preparing for this lab

Project Overview | Next Step

First dock the Mini-Simplicity connectors onto your WSTKs are shown here:

Also connect your ribbon cable as shown. Then connect your Thunderboards on their corresponding 10 pin header. If your mini simplicity connectors do not have keyed headers, make sure to match your pin 1s of both 10 pin headers.

Since we are using Thurnderboards connected externally to our WSTKs, we must make sure our WSTKs are set to debug mode OUT. This can be done via commander. For each WSTK run the following command

commander adapter dbgmode OUT -s XXXXXXX

where XXXXXXX is the serial number of your WSTK.

This can also be performed within Studio from the Launcher perspective. Under the Debug Adapters pane near the top left, you should see the two boards/adapters show up as “J-Link Silicon Labs (4400xxxxx). Highlight each adapter and change the Debug Mode to “OUT”. If you are prompted to update the board firmware, please proceed with the update. Note that when the Debug Mode is OUT, Simplicity Studio does not know about the Thunderboard Sense 2 board anymore and this is expected. (WSTK main board is still recognized.)

Creating bootloaders

Because neither of our applications will run without a bootloader, we want to create a bootloader for each. Fortunately, a default Gecko application bootloader will work for each board in this example.

To generate this bootloader:

• Make sure your Simplicity Studio is in either the Launcher view or the Simplicity IDE view.
• Then select File > New > Project. This will bring up the New Project Wizard.
• On the first screen you want to select Silicon Labs AppBuilder Project and select Next.
• Then select Gecko Bootloader and select Next.
• When the Select Application screen comes up find the bootloader template titled “SPI Flash Storage Bootloader (single image)”. Select it and hit Next.
• Give your Project a name, such as “TB-app-BL” and hit Next.
• Finally, you will be asked for your Board, Part and Configuration. Make sure to specify the board as “Thunderboard Sense 2 (BRD4166A)”, this will populate the part field automatically (EFR32MG12P332F1024GL125) then specify your toolchain (GNU ARM 7.2.1 or IAR ARM 8.30.1) and hit Finish.

Once your App Builder project opens, click the generate button to generate your project without any changes. Once the Generation successful window appears, you are done.  Then use the Hammer icon on the toolbar to invoke your compiler and build your project. This will give you the binaries to flash onto your board. You will need to locate the file named -combined.s37, it should be located in your projects binary folder.

You should flash this application to each of your Thunderboards, making sure to erase each board as you do this. Because you are flashing an external part, it will ask you to use the device option (-d) to identify the part connected to your board, using EFR32 will be enough to proceed.

commander flash TB-app-BL-combined.s37 --masserase -s XXXXXXX -d EFR32

Once you have completed this, you will be ready to begin creating your projects.

Project Overview

Next Step

In this tutorial we are going to be demonstrating how to build two simple Zigbee 3.0 applications for a light and a switch using Simplicity Studio on the Thunderboard Sense 2. 

This project will start by building up a basic set of applications using AppBuilder which will start out as the framework for our light and switch. Then we will add some custom hardware definitions as well as some custom code and expand the base projects provided to tie the software in with the hardware.

When you are finished you will have a light application that controls the states of LEDs based on software attributes and you will have a switch which reacts to a button to send ZCL messages over the air to update the attributes of the light. Below you will find some basic instructions which walk you along the next few lessons as well as code examples and hardware configuration files to get you started.

Some prerequisites you will need for this tutorial:

NOTE:  Version 2.6 of the Gecko SDK introduced EmberZNet 6.6.0. This version of the SDK made fundamental changes in the looks and behaviour of the Application Framework. This Tutorial has been updated to accommodate these changes. The new default wording of the tutorial represents the state of EmberZnet 6.6.0 but for users of the older versions the previous instructions were left in with the following note: "Pre Znet 6.6.0:" 

Simplicity Studio 4 with the latest updates
EmberZNet 6.6.3 or later

Pre Znet 6.6.0: EmberZnet 6.4.0 or later (earlier than 6.6.0)
Two Thunderboard Sense 2 boards (BRD4166A)
Two WSTKs (BRD4001A)
Two Mini-Simplicity connectors (BRD8010A) and the included 10 pin ribbon cable

You will also need easy access to Simplicity Commander's CLI interface. While it isn't the only way to program your chips, there are a few steps, like token programming, that require Commander.

Tutorial Steps

ZigBee 3.0 Tutorial - Step 0: Preparation and bootloaders

ZigBee 3.0 Tutorial - Step 1: Creating the projects

ZigBee 3.0 Tutorial - Step 2: Configuring the projects

ZigBee 3.0 Tutorial - Step 3: Flashing and testing our application

ZigBee 3.0 Tutorial - Step 4: Forming and joining the network

ZigBee 3.0 Tutorial - Step 5: Communications

ZigBee 3.0 Tutorial - Step 6: Physical interface - light

ZigBee 3.0 Tutorial - Step 7: Physical interface - switch

Older Tutorial

The videos that went with the older lesson can be found here:

ZigBee Home Automation Developer Tutorial: Light and Switch Overview
ZigBee Home Automation - Light and Switch - part 1
ZigBee Home Automation - Light and Switch - part 2
ZigBee Home Automation - Light and Switch - part 3
ZigBee Home Automation - Light and Switch - part 4
ZigBee Home Automation - Light and Switch - part 5
ZigBee Home Automation - Light and Switch - part 6
ZigBee Home Automation - Light and Switch - part 7
ZigBee Home Automation - Light and Switch - part 8
ZigBee Home Automation - Light and Switch - part 9
ZigBee Home Automation - Light and Switch - part 10
ZigBee Home Automation - Light and Switch - part 11
ZigBee Home Automation - Light and Switch - part 12
 

Creating the projects

Project Overview | Previous Step | Next Step

Now it is time to build our projects for our light and switch. We will be modifying them over the course of a few steps to give them the features they require.

Our first step will be to create two blank projects, from these blank templates, we will start to add the pieces which are required for building a full Zigbee light and switch.

So, let’s get started:

• Make sure your Simplicity Studio is in either the Launcher view or the Simplicity IDE view. 
• Then select File > New > Project. This will bring up the New Project Wizard.
• On the first screen you want to select Silicon Labs AppBuilder Project and select Next.
• When you are asked for the application type, select “Silicon Labs Zigbee” and press Next.
  • Pre Znet 6.6.0: Select “ZCL Application Framework V2” and press Next.
• Then you will pick your stack version and application type, for this example we will pick EmberZNet 6.6.3.0 GA SOC and press Next.
  • Pre Znet 6.6.0: Select EmberZnet 6.4.0.0 GA SOC.
• You will then be asked to pick a sample application to start with, since we are building this project from scratch select the ZigbeeMinimal Sample application.
  • Pre Znet 6.6.0: check the box near the bottom of the window that says “Start with a blank application” and hit Next.
• Next you will be asked to give your project a name, fill in the blank with your project name, such as "MyLight" or "MySwitch", and press Next.
  Note - these are the names we are going to assume you have used, so anytime a filename will include a project name, this is what you will see.
• Finally, you will be asked for your Board, Part and Configuration. These are the same settings are the bootloader, so specify the board as “Thunderboard Sense 2 (BRD4166A)”, this will populate the part field automatically (EFR32MG12P332F1024GL125) then specify your toolchain (GNU ARM 7.2.1 or IAR ARM 8.30.1) and hit Finish.

After some time, Studio will display your newly created .ISC file, this will mean your project is ready for editing. Don't forget you need to create two projects, one for the light and one for the switch, so make sure to have both before you move on.

Unlike our bootloader, we will need to make some modifications to this application to build it, so let’s do this for our next step, starting with the light.

Project Overview

Previous Step
Next Step

Physical interface - Light

Project Overview | Previous Step | Next Step

So now it’s time to make the physical interface for our light and switch. While being able to send and see messages go across the network is fun, since we are making a light and a switch, we should expect them to act like a light, turning a light source on and off and a switch, taking an input from a button press or similar signal.

First let’s turn our attention to the light, since a light turning on and off is an easier goal to observe. As we have noticed on our last step, we have been toggling one of our cluster attributes, specifically an on-off attribute. What we want is to have our device change based on this attribute’s value. One mechanism that we can use to handle this is through a callback.

A callback is a way that EmberZNet handles events throughout the stack code and application layer as well. If you click on the callbacks tab, you will see a number of calls that can be used throughout your code. These are generally broken down into application callbacks, plugin callbacks, stack callbacks, API callback and cluster callbacks. An in depth look at the callbacks is beyond the scope of this lesson.

For our light code, we are going to need to handle two events. First, at startup we need to enable our lights and configure them. Once that’s done we need to handle the toggling of the light based on the On/Off attribute. 

To setup our light, we need to look at the section called “Non-cluster related.” All of these callbacks are in order. As you look down the list you will come across two callbacks Main Init and Main Start, both of these callbacks run at the start of our main() function. Main Init runs right after main executes, but before the network is setup, while Main Start runs right before our main loop executes, after the HAL is done configuring the hardware. In most cases it won’t matter where we set up our LED interface, so for this we will use Main Start, check the box for it.

Next, we need to figure out how to toggle our light on and off. Because this is tied to the on/off cluster, you want to go to the On/Off cluster under the General. Looking through the list, we can find the Server Attribute Changed callback. Since we are operating on the attribute value setting, this is perfect for our needs, check its box as well.

Before we leave this page, make sure at the bottom of your callbacks page you have the “Generate project-specific callbacks file” box checked. This will ensure your new callbacks file is generated for your application.

Before we click generate, we also need to configure all of our GPIOs to work as LEDs. The Thunderboard has 1 green LED, 1 red LED and 4 full color LEDs, for this project we are going to use the full color LEDs. If you read UG309 section 3.4.8, you will see all of the pin definitions, as well as an explanation of how the LEDs are setup.

Next, we need to launch Hardware Configurator (HWConf for short). If you look in your light project, you should see a file named brd4166a_efr32mg12p332f1024gl125.hwconf, this is your header file for your project. Double click on it and it should open in HWConf in the DefaultMode Port I/O. If it isn’t in that format, click that tab at the bottom of the DefaultMode Peripherals window. This view brings us to a graphical representation of the pins, it is where we will set our GPIOs to be available to us within our software.

Setting the GPIOs from within HWConf is fairly straight forward. First you need to go to the Outline view on the top right corner of Studio and open the Port I/O tree. Then click on the Port (A-K) you want to set, this will make those GPIOs become active on the graphical pin grid. Locate the pin you want to setup on the grid (be careful, the pin letters are easy to get confused with their grid identifiers) and click on them. You will then see the Properties of this pin on the middle right of Studio. If you click on the value area within Custom pin name, you will be able to give the pins a name, this will be how you identify the pin in your program.

For example: PJ14 is RGB_LED_ENABLE (note this is configured by default)

• Outline view: click on PortJ
• DefaultMode Port I/O: Click on PJ14 (located in row B, column 6)
• Properties view: name it RGB_LED_ENABLE

Do the same for the following pins – locations provided for easy locating:

• PD11 (M10) – LEDS_RED
• PD12 (N11) – LEDS_GREEN
• PD13 (M11) – LEDS_BLUE
• PI0 (G13) – LED0
• PI1 (G12) – LED1
• PI2 (G11) – LED2
• PI3 (F13) – LED3

Remember all of the names you give these pins.

Once this is done, save your HWConf file, this might take some time as it will generate some new hardware configurations. Then return to Simplicity IDE view and click on your MyLight.isc file. Click the Generate button. After some time you will get a validation window to appear. Make sure that all files on this window are checked, Studio will many times leave the *_callbacks.c file unchecked to not overwrite this. Once all the boxes are checked, click OK to continue.

Finally, it is time to put in some code to make our lights turn on and off. First, locate the callbacks file in your project list. It will be called PROJECTNAME_callbacks.c, in our case, this will be MyLight_callbacks.c, double click on it and the code in this file will appear. You will note that you should have 2 additional functions in the project: emberAfMainStartCallback and emberAfOnOffClusterServerAttributeChangedCallback.

First let's enable our lights. Since we need to enable our LEDs as our code starts, we will focus our attention to the emberAfMainStartCallback() function. As noted, this function is called right before our program initiates it's loop while it is running. 

Now we will need a fuction to initialize our GPIOs, configuring them as output pins. You can look through docs.silabs.com and find the EMLIB section to discover a function to run this setup. To save you some time, the function you are looking for is:

void GPIO_PinModeSet (GPIO_Port_TypeDef port, unsigned int pin, GPIO_Mode_TypeDef mode, unsigned int out)

The function call for this is defined fully here. But we will step you through the function calls for easy reference.

The first two arguments are the port and pin that we want to configure. Because we have defined our pins in HWConf, you can use those names you assigned these pins in the GUI. They will be something like PIN_NAME_PORT and PIN_NAME_PIN, which correspond do the port letter and port number respectively. If you look in your project tree there is a folder called hal-config and in that folder you will find a file hal-config.h, this file contains the names of the ports and pins for easy reference, locate the section

// $[Custom pin names]

The next argument is how the pin is configured. Fortunately all of our GPIOs are set as outputs and our GPIO mode is going to be gpioModePushPull. A full list of pin options can be found here.

Finally because we are using these as output pins, the last argument is the desired initial state of the pin, either 0: off or 1: on.

So to set up RGB_LED_ENABLE, use the following:

GPIO_PinModeSet(RGB_LED_ENABLE_PORT, RGB_LED_ENABLE_PIN, gpioModePushPull, 1);

Do the same for all of your ports and pins. You should certainly make sure that RGB_LED_ENABLE is on at startup. If you want a particular color, the colored LEDs should be enabled as you want for the color you want to output, red, green or blue, or some combination of them all. LEDs 0-3 can be disabled or enabled, they are what we are going to use to turn on the LEDs. 

One final warning the LEDs are quite bright, especially if you turn on all four for white, so be careful when looking at them. After doing so, you might decide you want to start with them off. 

At this point you can re-compile your code and test to see if your lights come on. Once you have verified that your LEDs are working, you can then implement the on/off feature.

So now we will move down to the function emberAfOnOffClusterServerAttributeChangedCallback. This function is called anytime a server sided attribute on the light changes. It has two variables in its definition which are the endpoint that is being operated on by the change and the attribute itself which is being changed. In our case we want to change anytime we are seeing a call on our defined endpoint on the on/off attribute and change to the state which is set in that attribute. Despite only having a single endpoint in our project, you should wrap this call to make sure you are calling it on a particular endpoint, because you can then expand it to work for additional endpoint. Since our light functionality is our primary endpoint, you should compare the endpoint passed to this function against this. EmberZnet provides a means of getting this with the function emberAfPrimaryEndpoint(), this means we know that we are getting this called against the main light endpoint.

if (endpoint == emberAfPrimaryEndpoint())

Once we have done that, we need to make sure we are operating on the on/off attribute. First you should look at the file attribute-id.h. This file lists all of the attributes in your project and sets a number of defines for these attributes, using these your code will be much more readable. If you go to the section with the On/off cluster, you will see the ZCL_ON_OFF_ATTRIBUTE_ID, which matches that attribute ID. You can then do some comparison or switch statement and use that as the entry into your function.

if(attributeId == ZCL_ON_OFF_ATTRIBUTE_ID)

Now, we need a means of reading our attribute and turning the light on or off based on this attribute. Because this callback is made after the attribute has changed, we can read this attribute to get its state. To do this we will need to look through the documentation of EmberZNet. If you go to Docs.silabs.com, you can find the Ember Application framework API

On the left, if you click Ember Application Framework API Reference it will show you the sections of the top-level API. At this point we just want the General Application Framework Interface. When you get this page, you will find the Attribute storage section listed at the very top. We are looking for some function to read an attribute, a little searching will find the function emberAfReadServerAttribute, a function that is doing exactly what we want, reading a server attribute, so copy that whole definition and paste it into your code. 

EmberAfStatus emberAfReadServerAttribute (uint8_t endpoint, EmberAfClusterId cluster, EmberAfAttributeId attributeID, uint8_t *dataPtr, uint8_t readLength)

Because the function returns an EmberAfStatus, create one to catch the return value. We should only change our LED if the read was successful. You can return to the API guide and look up EmberAfStatus, you will find this is EMBER_ZCL_STATUS_SUCCESS.

if(readStatus == EMBER_ZCL_STATUS_SUCCESS)

Finally we need to make sure we properly read our attribute and change our LED, so go back to emberAfReadServerAttribute function call and let’s set it up properly. We know that our endpoint is the endpoint passed to our callback, so make sure this matches. The cluster ID is that for the on/off cluster. If you look at cluster-id.h, you will see that it is enumerated as ZCL_ON_OFF_CLUSTER_ID, so put that as the 2nd variable in the call. The attribute ID is again ZCL_ON_OFF_ATTRIBUTE_ID, so use that. Finally, we need something to catch the value of the data. I created a boolean type named onOff to catch this, the last two variables of the signature are a pointer to this variable and the size of that variable. In the end our full call looks something like this:

boolean onOff;
EmberAfStatus readStatus;
readStatus = emberAfReadServerAttribute(endpoint, 
                                        ZCL_ON_OFF_CLUSTER_ID,
                                        ZCL_ON_OFF_ATTRIBUTE_ID,
                                        &onOff,
                                        sizeof(onOff));

Now we can just use an if-else called against onOff to turn on or turn off our LED. The checking EMLIB again, we see that the function calls for this are:

GPIO_PinOutSet(port, pin); 

GPIO_PinOutClear(port, pin);

Make the appropriate calls to the LEDs you want on and off within your code block, save and recompile your code. You can then reflash it to your “light” Thunderboard and use the switch to toggle it from the CLI. If you are able to turn the lights on and off, it’s time to move on to our switch to get it to toggle from the buttons.

Project Overview

Previous Step
Next Step

Configuring the projects

Project Overview | Previous Step | Next Step

Once you have created your projects, it's time to use App Builder to configure the projects for the types of devices they are going to. As we introduce new parts of app builder, we will do our best to explain to you the pieces which you are using and hopefully educate you on making the best use of app builder. 

For the light

Let's take a look at the MyLight.isc file.

By default you should be on the General tab of your project. It consist of the Application configuration panel and the Information configuration panel. The application configuration panel gives you information about location of the project and the name of the device. This panel also allows you the view the Board, chip and compiler and configure them with the Edit Architecture button.

Pre 6.6.0: By default you should be on the General tab of your project. This gives some basic settings for your project, such as board, chip, and compiler. Below this is the Application configuration, which outlines the version of EmberZNet you are using and the location of the project. If you had an example project from the stack, this would give you a description of the operation of the application. And directly underneath this is multi-network configuration. This isn't something we will use today, but if you are looking for details, AN724 will outline multi-networking.

Pre 6.6.0: The next tab is the ZCL global tab. This is identification and versioning information for your part. You don't want to make any changes here for this project.

After this is the ZCL clusters tab, here is where we will make our first changes. On this tab you configure the ZCL elements of your device, namely your endpoints, the clusters which are enabled on your endpoints, and the attributes and commands that are supported by these clusters. After version 6.6.0 the Manufacturer ID and Default response policy can be changed on this tab as well as the ZCL global tab has been removed.  

For our light device we only need a single endpoint, which is the default, but we need to pick a device type that will work for our needs. While you can build custom devices with whatever clusters and attributes you want supported, AppBuilder includes a number of ZCL device types which contain the preconfigured clusters and attributes which are normal for a particular device type. Since we are building a light, we can use a default device included with the stack, for this project find the LO On/Off Light Switch  under the LO devices. This light definition has a number of default clusters for you, such as Basic, Identify, Groups, Scenes and On/Off. For this project we are going to focus on the On/Off cluster. But after you are done you can explore the other settings or even extend this light to be dimmable or color control, to add more functionality.

Moving to the Zigbee stack tab (Pre 6.6.0: Znet stack tab) we will configure the Zigbee device and security level. This tab is where many of the Zigbee options are set. For the light, it will be a Coordinator/Router and utilize Zigbee 3.0 Security. These should be the default settings for this device, but if these settings aren’t correct they can be changed here. There are also some settings here for Radio configugration, ZDO and Inter-PAN settings, but they are beyond the scope of this project. After 6.6.0 you can also configure multi-networking related features on this tab and add custom ZCL additions. 

Proceeding to the Printing and CLI tab we find the configuration of Debug printing as well as the setup of the CLI. Debug printing allows you to add additional printing options beyond the ones that are supported by a standard application. The Cluster debugging includes print statements that are specific to the clusters enabled for your device. The General-purpose debug printing gives you additional printing within different aspects of your application, such as security or service discovery. You can even created your own custom messaging within this block.  Along the bottom you will settings for customizing your CLI. In this section you can enable different CLI commands for your device beyond the standard ones which are included.  For our needs, we are going to enable the On/Off cluster printing can be found in the Debug Configuration panel under Application specific debug printing (Pre 6.6.0: On/off cluster printing can be found along the top), so check box boxes next to this so that these print statements are compiled in and enabled at startup. But the normal CLI as it's built will be fine for our needs, so there are no changes needed for the bottom section.

The next tab is the HAL configuration tab. As noted, this is where some hardware settings are made. You want to be sure that your device is setup for the Application bootloader,  any other changes, we will make in a future step. This is also one of the places where you can access Hardware Configurator which we will use in a later step. 

Finally, we need to configure the required plugins, which can be found on the corresponding tab. Plugins are the EmberZNet method to quickly enable or disable functionality supported by our application layer with a simple click of the button. For plugins, you should use all of the plugins which are included by default with the project and add the following:

• Network Creator
• Network Creator Security
• Find and Bind Target (all under ZigBee 3.0)
• Security Link Keys Library (Stack Libraries).
• On/Off Server cluster plugin
• Identify plugin

Just to be safe, save your project to prevent anything from being lost. We aren't quite done yet, so don't hit the generate button just yet.

For the switch

Now, let's open up MySwitch.isc and configure the Switch similar to the light. Since you know where to find these settings, they should be much easier to set up.

Like the light, your device will have 1 endpoint. But the ZCL device type will be an LO On/Off Light Switch.

It will utilize Zigbee 3.0 Security but will be an End Device. Don't make it a sleepy end device, you won't be able to get as much response from the CLI, and we need to be able to interact with the device as we make our settings.

For plugins, you should use all of the plugins which are included by default with the project and add the following:

• Find and Bind Initiator (ZigBee 3.0)
• Button Interface (HAL).
• Install code library

Because the switch is an end device you can exchange the Zigbee PRO Stack Library Plugin for the Zigbee Pro Leaf Library. This is an optional step, but the leaf library removes many of the additional stack libraries which are only needed for routers and coordinators. The result is a smaller library which consumes less power. While we aren't using the sleepy end device, this would help you achieve a much lower current draw when your device sleeps.

Finally, located the Binding Table Library plugin. It has one option to configure – the size of the binding table, we need to make sure our table has at least 6 entries. We probably won't need this many entries, but we want to make sure we have them, just in case. 

For both devices

There is one final setting you need to make to both devices to make sure you can run the CLI. This involves making sure that the serial port is configured correctly.

On both mySwitch and myLight go back to the plugins tab and you want to make sure that the Serial plugin is enabled. From within the Serial plugin you need to ensure both SERIAL and USART0 are enabled (select each in the peripheral box). Finally, because the Thunderboard doesn’t support hardware flow control, we need to change the flow control type within the USART0 peripheral (in the serial plugin), make sure that Flow Control mode is set to Xon-Xoff.

Once you have configured both applications, you want to save each project.

Next, click the Generate button on each project. Just like our bootloader this will create or link to all of the files necessary to build the project. It shouldn't take too long, but you will have a few moments of waiting until the Generation successful window appears. Once you get that, click OK.

Finally, you can click the hammer icon on the toolbar

(or any other command that will begin building your application) and build your application. This will take a minute or two, depending on the speed of your computer. You can follow the progress in your Console window at the bottom. Once the files are compiled and linked, some post build scripts will run. If these run correctly you will get the following message:

Image-builder not invoked since "OTA Bootload Cluster Policy plugin" is not enabled

16:55:26 Build Finished (took 48s.142ms)

The key is the Image-builder message. Image-builder is run after your project compiles correctly. Once you see that, you know that your project has compiled successfully. Next we need to flash it to our device and test it.

If you get some sort of error during your build, return to your project .ISC file and check your work setting on your device and see if you missed any steps or have an incorrect setting.

Project Overview

Previous Step
Next Step

Forming and joining the network

Project Overview | Previous Step | Next Step

Now we will form our network with the light and use a Zigbee installation code to join the switch to the network. This will be handled via the CLI, so we will need to connect to the CLI on both devices, this can be done just like in the prior step, right clicking on each WSTK in the Debug Adapter View and select “Launch Console.”

Setting up the network

First, we will form the network on the Light. Go to the CLI for the light and enter the command:

plugin network-creator start 1

This tells the light to invoke the network-creator plugin to start network formation. The 1 option tells the plugin to form the network centralized, this makes the light a trust center as well as a router.

You should see output similar to the following:

NWK Creator: Form: 0x00
NWK Creator Security: Start: 0x00
EMBER_NETWORK_UP 0x0000
NWK Creator: Form. Channel: 25. Status: 0x00
NWK Creator: Stop. Status: 0x00. State: 0x00

If you see the EMBER_NETWORK_UP, you can check the network settings with the command:

info

This will output network information. They key thing is that your device should have a panID and its nodeID should be 0x0000.

panID [0x06BA] nodeID [0x0000] xpan [0x(>)1989C1541BB9E874]

If this is all set, we can move over to the switch.

Putting the install code on the switch

As noted before, for the switch we are going to use an installation code (also known as an install code) to join our switch to our network. An install code is a means for a device to join a Zigbee network in a reasonably secure fashion. For a complete description of install codes, read AN1089.

The install code itself is a random value installed on the joining device at manufacturing time and is used to encrypt the initial network key transport from the coordinator to the joining device, via a unique link key. To emulate this, we are going to use commander to flash the install code onto our Thunderboard. We have included a file install.txt on this page to give you an install code to work with for this example. While you can use any code you want, this code matches the commands you will see in this example and will allow you to easily follow along with our example. To install this via commander, use this command:

commander flash --tokengroup znet --tokenfile install.txt --device efr32mg12p

Make sure to flash this onto your Thunderboard that is acting as your switch, it won’t hurt to have the install code on the light, but it has to be on the switch for this join process to work.

The output from commander will look very similar to when you flashed your application to the Thunderboard, but shorter. If you don’t see this output, make sure your Thunderboard is attached to your WSTK and that your WSTK is attached to your computer correctly. Once you have flashed the install code, you can check that it was stored correctly with the following command:

commander tokendump –-tokengroup znet –-device efr32mg12p

What you are looking for are two sections, at the top that you can see your EUI 64 and near the bottom, that the install code is stored on your device:

# MFG_EMBER_EUI_64     : C3A4DEFEFF570B00
…
#’MFG_INSTALLATION_CODE (Smart Energy Install Code)' token group
# Install Code Flags : 0x0002
Install Code       : 3141592653589793
# CRC                : 0xCE31

If you see this, the install code was correctly installed. You should run this command on your part as you will need your EUI64 for the next steps. NOTE: using the command, the EUI64 and CRC you see there are both in little endian format. Looking at this, the EUI64 is actually: 000B57FFFEDEA4C3 and our CRC is 0x31CE.

Joining the switch to the network

With this information, we will now return to our light. Our light is acting as the coordinator for our network, so It will need to know this information from our joining device. Specifically, it needs to the link key of the joining device. We are going to do a two-step process to get the link key and they move this key to the transient link key table of the light so that the information is changed after the switch joins.

From the light’s CLI, we are going to tell the light the EUI64, the install code and the CRC of the switch, from this information it will hash out the switch’s link key. To do this, enter the following on the light’s CLI:
Let’s look at this command a little closer, because there are a few things to note:

option install-code 0 {00 0B 57 FF FE DE A4 C3} {31 41 59 26 53 58 97 93 31 CE}

option install-code – this is simply the command which we are running, telling the coordinator we are adding an install-code based link key.

0 – This is the key table entry to add the entry to

{00 0B 57 FF FE DE A4 C3} – this is the EUI64 of the joining device. It is in big endian format. Note, this is the EUI64 of my joining device, you want to make sure to put your EUI64 here.

{31 41 59 26 53 58 97 93 31 CE} – this is our install code (the first 8 bytes) and the CRC (last 4 bytes) we are using. Note that our CRC is in big endian format.

If this command works correctly, you should see the following:

Success: add link key

From this we will then get our new link key from the key table. This is done from the CLI entering:

keys print

This command displays most of the security information for our network. What you are looking for on this display is the key table, which should display information like this:

Link Key Table
0     (>)000B57FFFEDEA4C3  00000000  L     y     FE 2A 47 BE 40 CC AE B2 DC 54 0E 0A EA DB 82 A1 
1/6 entries used.

This is the link key that was derived from the install code. Take note of this new link key, we are going to use it in a future step. With this, you want to delete the key from the permanent key table. To do this enter:

keys delete 0

Which tells the coordinator to delete our 0th entry from the key table.

Now we are going to join the switch to the network. We are also going to watch the process take place on network analyzer, so we can get a graphical representation of the joining process. So first, let’s start our capture. Because we are using an install code, Studio can’t natively see the joining process, so we need to put our install code into Studio. To do this, we need to open Studio’s preference, find the gear icon in Debug Adapter and click it.

This will launch the Preferences window. In the search window enter Security Keys, which should located it under Network Analyzer > Decoding. In that window click New and with the New security Key, enter your link key to allow Studio to be able to decode with it. Hit Apply and then OK to save this information.

Once the link key is added, we can start our capture. From Studio select our two WSTKs again like we did to launch the CLI. We are going to right click on them again, but instead select Start capture (if your environment is particularly noisy, you can select Start capture with options … and only capture off your particular pan ID). This will launch Network Analyzer, Silicon Labs network decryption tool. We won’t dive too deeply into the tool, but we will cover some parts as we work through this example.

At this point you might find it useful to organize Studio to allow you to see more of your windows than you had before. To move around views within Studio, you can drag them around by grabbing their tabs moving them to other areas. When they find a new location, you will see them leave an outline on the window. Since we want to see our network trace as well as both serial windows, you might find an arrangement like this better:

Now we want to return to the CLI of the light. Find the tab that contains the CLI for the light. We are going to open the network for joining and provide the link key of the joining device. We do this with a command from one of our plugins:

plugin network-creator-security open-with-key {00 0B 57 FF FE DE A4 C3} {FE 2A 47 BE 40 CC AE B2 DC 54 0E 0A EA DB 82 A1}

The first set of hex digits is the EUI64 of our joining device, the second is the link key that device will use when joinng. As before, make sure you put your own EUI64 in here. This command will add these keys and open our network for 255 seconds as well.

Now let’s go to the switch CLI. We need to start joining the network. In Zigbee 3.0 this is done by network steering, a plugin we added to our switch. So, in the CLI enter the following:

plugin network-steering start 0

Just like the name says, this starts the network steering process. The 0 option tells the switch to join with no additional options. The primary thing that this does is tell the joining device to change its install code after joining.

If you have arranged your windows as noted, you can watch the process take place in both CLIs and network analyzer. The key step is to watch the transport of the network key. Because have told our device to join with a particular link key, you can watch this key be used to transfer the network key to our device. You can follow other steps graphically, like the device announce of the switch to the network and the request and transport of a new link key.

Now that we have formed our network, it is time for us to start sending communications between our light and switch.

Project Overview

Previous Step
Next Step

Simplicity Studio can be utilized within Mac OSX to develop for Silicon Labs wireless mesh stacks (as well as all other Silicon Labs stacks). This guide will help you set up your development environment.

Download, Install Studio and Setup Studio

A full walk through of a Studio installation is beyond this KBA, this will highlight the primary points.

Studio can be downloaded from here. Once you download the file, you can open the file and then drag the Simplicity Studio application to your Applications folder.

Go to your Application folder and launch your new Simplicity Studio application. Once the application is open, this will start the update process for Studio. Follow the instructions for installing the wireless mesh stacks. If you don’t have access to these stacks, go to this link.

Installing Windows IAR

For compiling with Studio, you can utilize either GCC-ARM or IAR Embedded Workbench. If you want to install IAR (a Windows program), follow these steps:

First you will need to download a copy of IAR (see the above link for a download location). Use this KBA to note the version of IAR you need.

Studio comes with an installation of wine for running Windows applications within the OSX environment. Once Studio has completed installation, you should add the folder with wine to your PATH. This folder is located at:

/Applications/Simplicity Studio.app/Contents/Eclipse/support/common/wine/opt/local/bin/

You can add this to your PATH by editing your .bash_profile file within your user home directory. Using a text editor, add the following line to the file:

export PATH=$PATH:/Applications/Simplicity\ Studio.app/Contents/Eclipse/support/common/wine/opt/local/bin/

The next time you launch your terminal, you can see if this works by trying to run wine:

$ wine
Usage: wine PROGRAM [ARGUMENTS...]   Run the specified program
       wine --help                   Display this help and exit
       wine --version                Output version information and exit

If this works, navigate to the folder you downloaded IAR and run the installer via wine:

$wine EWARM-CD-8301-17148.exe

This will launch IAR in a Windows like environment. Follow the installer as you normally would (depending on version, this could take a while). 

NOTE: In Windows applications, they use the CONTROL key instead of the COMMAND key for many functions. So Cut, Copy and Paste are CTRL-X, CTRL-C and CTRL-V, respectively. This is primarily for adding license information to your IAR installation.

Other useful tools

Once Studio and IAR are installed, there are other useful tools which can be added to your PATH (.bash_profile) for ease of use:

Commander: The Silicon Labs programmer and chip debugger for the EFR32 family of chips

export PATH=$PATH:/Applications/Simplicity\ Studio.app/Contents/Eclipse/developer/adapter_packs/commander/Commander.app/Contents/MacOS

ISA3 Utilities: The Silicon Labs programmer and chip debugger for the EM35x family of chips

export PATH=$PATH:/Applications/Simplicity\ Studio.app/Contents/Eclipse/developer/adapter_packs/em3xx/utils/

Within EmberZNet and Silicon Labs Thread, different sleep modes are supported based on the particular chip you have selected for your product. This KBA will outline the different sleep modes within EM35x and EFR32 chips and how they are used within the stack.

EM35x

When utilizing Silicon Labs wireless mesh stacks, the EM35x supports two different sleep modes: Deep Sleep and Power Down. Both of these modes will get down to under 1 µA of current, with Power Down being able to realize lower current consumption.

Deep Sleep – EM35x SoC and EM35x NCP

This is the primary sleep mode of the EM35x. In this mode the EM35x will go into a lower current sleep mode by halting most peripherals, maintaining the ability to wake due to GPIO interrupts or a wake timer. This means that the EM35x can be woken by an external event, like a button press, or a scheduled event that is pending, such as polling event scheduled at set intervals.

This is the only supported sleep mode of any EM35x SoC design, utilizing the Idle/Sleep plugin, while it is one of two sleep modes that are supported by an EM35x NCP design, utilizing the sleep bits of the Frame Control bytes within the EZSP structure (see UG100: EZSP Reference Guide for full details).

Power Down - EM35x NCP only

This is a secondary sleep mode of the EM35x. In this mode the EM35x will go into a lower current sleep mode by halting most peripherals, including all timers as well. In this state only a GPIO interrupt can wake the EM35x.

This sleep mode is only supported in the EM35x NCP design as timer functionality can be offloaded to the Host processor, which can trigger polling or other scheduled events, utilizing the external interrupt to wake the NCP. This mode can be entered by utilizing the sleep bits of the Frame Control bytes within the EZSP structure (see UG100: EZSP Reference Guide for full details).

EFR32

Within EmberZNet and Silicon Labs Thread, the EFR32 can support two different sleep modes as well.

EM2 Deep Sleep – EFR32 SoC and EFR32 NCP

This is the primary sleep mode utilized by the wireless mesh stacks on the EFR32. In this mode the EFR32 will halt most peripherals and many timers, keeping only system necessary timers running. In this mode, the EFR32 maintains the ability to wake due to all interrupts or a wake timer and will resume operation as normal when waking from sleep.

To utilize this within an SoC design, use of the Idle/Sleep plugin is necessary. EM2 sleep can be utilized on SPI based NCP implementations through the sleep bits of the Frame Control bytes within the EZSP structure (see UG100: EZSP Reference Guide for full details).

EM4 Hibernate – EFR32 SoC only

EM4 is a special use case sleep mode that disables most functionality within the EFR32 and puts it into a hibernation state. In this mode the EFR32 can only be woken via a select GPIO wake mask or a system timer. Wake in this mode is treated like a reset of the processor.

To utilize EM4 sleep, you will need to enable the EM4 plugin with your application. You will need to further enable the emberAfOKToGoToEM4Callback() within your application’s callbacks. Within this function, you will enable the logic for which your application will enter into EM4 sleep.

NOTE: EM4 sleep is highly disruptive within normal operation of the stack. Use of it can result in an application that will have difficulty meeting Zigbee or Thread certification. It should only be utilized when this extremely low power mode is required and a well-defined state machine handling the sleep mode of the stack can be defined to govern the EFR32’s behavior.

Ideally, it is assumed that the source (generator) and load has 50Ω impedance, thus to transmit a signal from source to load without any losses, the transmission medium also must have 50Ω impedance.

Practically, the source / load impedance solely cannot be guaranteed to be 50Ω, hence additional impedance matching network is required in the circuit. Matching the impedance of complete RF path will make sure that there is minimum reflection loss and thus the antenna will resonate all of the incoming energy at its resonant frequency.

The RF path of EFR32 Series 1 can be divided into 3 parts as follows:

a) EFR32 Matching Network:

After performing load pull experiments, the optimum termination impedance of power amplifier was found as:

Case A: [Tx power level < +10dBm] ----> 20+j10Ω

Case B: [+20dBm > Tx power level > +10dBm] ----> 23+j11.5Ω

This impedance at the power amplifier should be matched to 50Ω to achieve the maximum power transfer from EFR to antenna. A low pass filter is used to transform this impedance and reject unwanted signals.

For case A, 2 element ladder LC low pass filter is enough to transform the impedance from 20+j10Ω to 50Ω. As max Tx power is limited to +10dBm, additional filtering is not required.
For case B, At higher Tx power, 2nd and 3rd order harmonics go beyond the allowable limit by the regulatory bodies. Hence suppressing higher order harmonics becomes important. To suppress these harmonics, a 3 element Pi filter is combined with the 2 element LC match which then results in a 4 element LCLC ladder that acts as a matching network and a low pass filter.

(For component values, detailed analysis and other types of EFR matching networks, Please refer AN930 rev 0.4 or later).

Thus the impedance at the end of EFR matching network in either case has been successfully transformed to ~50Ω.

b) Pigtail connection (Optional):

Even though pigtail connection is optional, we always recommend everyone to keep a provision for a U.FL connector and a series zero Ω resistor in their prototype design, this will allow the engineer to perform some RF tests such as measuring reflection loss, perform conducted test and etc.

This section is divided into 2 subsections:

i) U.FL connector:

To perform RF conducted test, a provision for U.FL connector can be helpful in the circuit. For this the series zero Ω resistor (3 - Res) has to be removed and it has to be placed at branched path towards U.FL connector. This will help us to ensure that the signal sent by the EFR RFIC is equal to the received signal at U.FL connector. Conducted test helps the engineer to verify that there are no reflection losses in the RF path between EFR and pigtail connection.

ii) Pigtail connector:

To measure reflection loss between pigtail connection and antenna, a pigtail connector is used. This can be done by removing zero Ω resistor (3 – Res) and soldering a pigtail connector at the second pad of the removed component. Please make sure that the metal jacket of the pigtail connector is properly soldered to ground pour from the pad till the edge of the board. By measuring the reflection coefficient, the antenna can also be matched to 50 Ω impedance.

This pigtail connection does not include any kind of impedance transformation, thus the impedance at the end of this network and before antenna is ~50Ω.

c) Antenna Matching Network:

The impedance of the antenna also solely cannot be guaranteed to be 50Ω, hence an additional matching network is required. We usually recommend a 3 element pi structured filter irrespective of the antenna type. Using a pigtail connector would be the starting stage of the antenna matching exercise. More information on the antenna matching network can be found at this KBA.

Please note that detailed design procedure and antenna tuning information for inverted F PCB antenna is given in AN1088.