Z3 network: join with install-code-derived link key

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> yuxiao on ‎03-10-2017 01:55 PM - edited on ‎08-16-2017 09:53 AM 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> ADKates

In this exercise, you can follow these steps using command line options to join a Z3 Light to a Z3 Gateway using an install-code-derived link key. This exercise is for our sample applications. Please see the end of the exercise for some ways you might load the install code in a real-world implementation.


We assume that you have already built a SoC-based Z3 Light sample app (default configurations), and a Z3 Gateway app on an NCP+Host setup (make sure the link key table size, which can be configured under the "NCP Configuration" plugin on the host side, is at least one entry) based on EmberZNet stack version 5.8.1 or higher. You can use either the EM358x or EFR32MG platform. 


1. First make sure the Z3 Light is not on any network (issue "network leave" if it is).

2. Come up with an install codes of 6, 8, 12 or 16 bytes. In this example, I used 1122334455667788.

Save this into a text file in this format:

Install Code: 1122334455667788

In this example I named the file "inst_001.txt" 

3. Following the instructions in AN714, specifically sections 4 and 5, to program this install code to the Z3 Light device.

On my EFR32MG1 radio module on WSTK with serial # 440030469, the command (run it in a generic Windows command prompt from a directory where your Simplicity Commander is installed) is:

>commander flash –-tokengroup znet –-tokenfile inst_001.txt -–serialno 440030469

You will see the follwoing output:

Writing 2048 bytes starting at address 0x0fe04000
Comparing range 0x0FE04000 - 0x0FE047FF (2 KB)
Erasing range 0x0FE04000 - 0x0FE047FF (1 sector, 2 KB)
Programming range 0x0FE04240 - 0x0FE0435F (288 Bytes)
Programming range 0x0FE04360 - 0x0FE04487 (296 Bytes)
Verifying range 0x0FE04000 - 0x0FE047FF (2 KB)


To verify the install code, run the following: 

>commander tokendump –-tokengroup znet -–serialno 440030469


The output will have the following important sections:

# The token data can be in one of three main forms: byte-array, integer, or string.
# Byte-arrays are a series of hexadecimal numbers of the required length.
# Integers are BIG endian hexadecimal numbers.
# String data is a quoted set of ASCII characters.
# MFG_EMBER_EUI_64 : E3A907FEFF570B00

#'MFG_INSTALLATION_CODE (Smart Energy Install Code)' token group
# Install Code Flags : 0x0000
Install Code : 1122334455667788
# CRC : 0xF74A


4. On the Z3 Gateway, form a centralized network with Z3 security using this command on the CLI:

plugin network-creator start 1


5. Derive a link key from the install code, and store that into the Z3 Gateway which acts as the Trust Center for the centralized network. For example:

option install-code 0 {00 0B 57 FF FE 07 A9 E3} {11 22 33 44 55 66 77 88 4A F7}

The first argument after "option install-code" is the link key table index.


The next argument is the EUI64 of the joining node (i.e. Z3 Light).
Tip: you can find this information by running the "info" command on Z3 Light; note the string "node [(>)000B57FFFE07A9E3]". (Your EUI64 will be different from mine, though!).

You can also get it in the EUI64 from the output of the token dump, but note that it is outputted in little endian format.  You will need to reverse the bytes to get the proper output.


The last argument is the install code with the 2-byte CRC appended at the end.

Tip: if you don't want to calculate the CRC yourself, you can simply find out from running the "tokendump" command in step 3 above. Note the CRC displayed just below the install code is outputted in little endian format and reverse the bytes to big-endian when you feed it to the "option install-code ..." CLI. BTW, the white spaces inside the curly brackets are not mandatory and you can do a straight copy/paste without the spaces; they just help to view the data a little better.

If the link key is added successfully, you can type the "keys print" CLI to see it. Your link key table should look something like this:

Now you see what the actual link key is that you derived from the install code. You will also see the network key displayed.


6. Optional step which I highly recommend: at this point, you have all the information the Network Analyzer would need to decrypt future transactions between the Z3 Gateway and Z3 Light. Enter both the network key and the link key to the list of security keys under Network Analyzer decoding preferences. Start a new network capture from the Z3 Light and/or Z3 Gateway. If you are in a "noisy" environment, you may choose to only capture on the specific PAN.

7. Now set the transient link key (the same link key that you derived from the install code) on the Trust Center:

plugin network-creator-security set-joining-link-key {eui64} {linkkey}

For example:

plugin network-creator-security set-joining-link-key {00 0B 57 FF FE 07 A9 E3} {41 61 8F C0 C8 3B 0E 14 A5 89 95 4B 16 E3 14 66}

8. Open the Gateway network for joining:

plugin network-creator-security open-network

9. Then on the joining device enter this CLI to use the Network Steering plugin to join the network:

plugin network-steering start 0

With the transient link key being used, it should join the network. If you have started a network capture in step 6, now you should see the full transactions live, and see the Z3 Light is initially let on the network using the transient link key. The TC transports the network key encrypted with the transient link key in a "Transport Key (NWK)" frame. Subsequently, the Z3 Light requests a new link key, and the TC transports the link key in a "Transport Key (Link)" frame.

Some Possible Ways Install Codes Can Be Transferred to TC

In this example, the install codes were entered manually, but in the real world, it may not be practical to connect to the Trust Center in this way. The implementation of install codes is a customer responsibility and there are details which must be taken into consideration, like: if the commissioning is going to be done all at the same time, (perhaps for a large industrial lighting application), if it will be piece-by-piece in a home automation setting, will there be an internet-connected gateway, or if the install codes can be written during manufacturing for a precommssioned bundle. Others questions might be how inital commissioning might differ from later commissioning for added devices or in the case of leaving the network and joining again, and how the network might accommodate a commissioner which would leave and return to a network in a switched multiprotocol scenario.


Here are some methods we envision being used:


  • Bluetooth commissioning using Dynamic Multiprotocol (DMP). This is likely to be the most ideal method, using our DMP feature to be released in the future.
  • Precommissioning at the factory: install codes entered at manufacturing time for TC and joining devices
  • Bluetooth-based commissioning with Switched Multiprotocol (SMP) on the TC and a Bluetooth phone app for entering install codes (Please see our UG267 for an example of passing data between BLE and Zigbee in a multiprotocol example)
  • Using QR codes on joining devices, and using an app to send the install code via WiFi to an internet-enabled NCP gateway
  • Using a temporary ZLL-based connection to send an install code to the TC, along with information proving the device's identity (perhaps an encoded EUI64), and then reconnecting using the install code
  • Barcode/QR code scanning capability on the TC

The method for transferring the install code, and the ease of doing so, is likely to provide a major opportunity for product design differentiation.