Migration of Legacy ZigBee Profiles to zigbee 3.0

by <a href="http://community.silabs.com/t5/Welcome-and-Announcements/Community-Ranking-System-and-Recognition-Program/m-p/140490#U140490"><font color="#000000"><font size="2">Hero Employee</font></font> </a> RonB on ‎06-12-2017 11:00 AM - edited on ‎10-05-2017 12:42 PM by <a href="http://community.silabs.com/t5/Welcome-and-Announcements/Community-Ranking-System-and-Recognition-Program/m-p/140490#U140490"><font color="#000000"><font size="2">Hero Employee</font></font> </a> kpszupin

Migrating devices from older ZigBee pro profiles to zigbee 3.0 can seem confusing.  However with the right steps, it can be a lot more understandable.  This KBA will help to demonstrate the steps for how to move App Builder projects from legacy ZigBee Pro profiles to full zigbee 3.0.  The initial focus will be on HA device, but it will soon include ZLL devices as well.

 

For this guide, we are going to be looking at the various tabs in App Builder and the change that need to be made in each section.

 

ZCL Clusters

 

This is where the initial changes between older HA and ZigBee 3.0 will  be found.  Where an HA router application will normally have a single endpoint, a ZigBee 3.0 application will have multiple endpoints.  See the pictures below.

 

 zclprofile.png

Figure 1. The ZCL configuration of an HA profile

 

zclprofile2.png

Figure 2. The ZCL configuration of a zigbee 3.0 profile

 

In the HA profile, there is a single endpoint called primary.  In the zigbee 3.0 profile there will be multiple endpoints.  All of profile IDs will be HA, but their device ID will be different.  The GreenPower profile (ID 0x0066) is required by the zigbee 3.0 specification.  Touchlink (ID 0x0200) is not, but including it will give you the most flexibility and compatibility within the zigbee 3.0 network.

 

In terms of clusters, these should be the same for your device from HA to zigbee 3.0.

 

Znet stack

 

Because zigbee 3.0 uses a new security model, there is another change that will need to be made from application to application.  HA had a single security model, zigbee 3.0 Security includes all of the security models needed for new zigbee 3.0 devices.

 

Plugins

 

This is where you will see major changes between the two application profiles.  First we will breakdown the plugins which you will find removed from your HA device profile.  Then we will breakdown and explain the new zigbee 3.0 plugins, many of which are new to the EmberZnet stack.

 

Plugins removed in the transition from your HA device:

  • Identify Feedback
  • EZ-Mode Commissioning
  • Network Find
  • Idle/Sleep (unchecked for sample apps as default)

The plugins you removed in the previous section are replaced by new plugins that are zigbee 3.0 compatible.  Along with this  there are many more plugins which need to be added to support newer zigbee 3.0 features.  All of them are as follows:

  • Green Power Library - The Green Power library provides functionality for Green Power infrastructure devices.
  • Install Code Library - The Install code library provides an initial link key based upon an install code manufacturing token in the device. The key is hashed according to the ZigBee spec and can be used by applications running Smart Energy 1.x profile or Home Automation 1.2 profile.  However, note that for zigbee 3.0 the install code length must be 16 bytes (plus LSB CRC16), as opposed to the variable lengths used by Smart Energy 1.x.
  • ZigBee Light Link Library (optional) - The ZLL library provides support for an application running the ZLL profile by generating and processing ZLL touchlink messages.
  • Green Power Client - A plugin implementing the client-side functionality of the Green Power cluster.
  • Green Power Common - A plugin that provides common functionalities between client and server sides of the Green Power plugins.
  • Green Power Server - A plugin implementing the server-side functionality of the Green Power cluster.
  • Scan Dispatch - This plugin allows there to be multiple consumers of the stack 802.15.4 scan results.
  • AES-CMAC (optional) - Ember implementation of AES-CMAC.
  • Counters - This plugin provides support for reading and manipulating counters that record different events in the stack.
  • Interpan - A plugin to handle sending and receiving interpan messages, messages that are sent by unjoined devices 1-hop away.
  • Find and Bind Target - This plugin provides the functionality for a target device to start identifying on user defined endpoints. The target device can then act as a target for a finding and binding initiator.
  • Network Creator - This plugin will perform the necessary steps to create a network according to the Base Device Behavior specification. The ZigBee specification on which this is based is still in development, and thus the functionality and implementation contained in this plugin may be subject to change until the specification is completed.
  • Network Creator Security - This plugin will perform the necessary security initialization to form a ZigBee 3.0 compliant network.
  • Network Steering - This plugin will perform the necesary steps to join the network of any ZigBee Profile. It tries first to perform a join using an install code using the Primary Channel Mask, and then the secondary channel mask.  If that does not work it then tries to use the default well-known link key (ZigBeeAlliance09) to join on the primary channel maks, and then the secondary channel mask. The ZigBee specification on which this is based is still in development, and thus the functionality and implementation contained in this plugin may be subject to change until the specification is completed.
  • Update TC Link Key - This plugin provides the functionality to update the trust center link key of a device on an ZigBee R21 network.
  • ZLL Commissioning (optional) - Ember implementation of the commissioning mechanism used by the ZigBee Light Link profile.
  • ZLL Utility Server Cluster (optional) - Ember implementation of ZLL Utility server cluster.

 

Callbacks

 

If required for the Network Creation and Steering plugin, you will need to make sure to include these callbacks with your project:

emberAfPluginNetworkCreatorCompleteCallback

emberAfPluginNetworkSteeringCompleteCallback

 

Generation and rebuilding

 

Once you have completed moving your project over to zigbee 3.0 compliant settings, you should be able to generate and compile your project.  There may be other steps required for full project migration.  Manually rebuilding your project callbacks file might be necessary as well as modification of any custom code. Ideally with this KBA this process is much simpler.

Comments
by AP
on ‎07-17-2017 02:54 AM

Hello, 

 

thanks for good article,

 

as a note, to work the profileID indicated for endpoint 242 (GreenPower Endpoint) need to be change from "Home automation ..." to "0xA1E0":

 

SimplicityStudio_ZCLclusterTab_endptConfig.PNG

 

Best regards

by adde
on ‎10-04-2017 04:42 AM

If the Idle/Sleep plugin is removed the halSleep function isn't call and the device will not enter power save mode. Tested on EFR32 platform