Example: Joining a Z3 Light to a Z3 Gateway Using an Installation Code-Derived Link Key#

This example uses command line options to join a Z3 Light to a Z3 Gateway using an installation code-derived link key. Before starting the exercise, you should have already built an SoC-based Z3 Light application with default configurations and a Z3 Gateway application using an NCP+Host setup. For SDK 6.6.x or lower, make sure the Link Key Table size is at least one entry because the following commands populate the Link Key Table. The key table size can be configured under the NCP Configuration plugin on the host side. For SDK 6.7.x or higher, the following instruction populates the Transient Key Table which is already sized appropriately. If you are not familiar with building sample applications, see the applicable quick-start guide for the SDK version you are using.

Note: Zigbee EmberZNet SDK 7.0 introduced a new component-based architecture, along with a Project Configurator and other tools to replace AppBuilder and plugin configuration. In general, the new software components are comparable to the plugins. In this chapter, instructions for both version 7.0 and higher and 6.10.x and lower are provided. For more information, see AN1301: Transitioning from Zigbee EmberZNet SDK 6.x to SDK 7.x.

Using SDK Version 7.0 and Higher#

  1. Make sure the Z3 Light is not on any network. If it is issue network leave.

  2. Follow the instructions in section Programming the Installation Code on a Zigbee Device to create an installation code text file, and program the installation code onto the Z3 Light device.

  3. On the Z3 Gateway, form a centralized network with Zigbee 3.0 security using this command in the Network Creator component's CLI:

    plugin network-creator start 1

  4. To derive a link key from the installation code and store that into the key table on the Z3 Gateway, which acts as the Trust Center for the centralized network, enter:

    option install-code <link key table index> {<Joining Node’s EUI64>} {<installation code + 2-byte CRC>}

    For example:

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

    • This command populates the Link Key Table if the gateway is a Smart Energy device and the TransientKey Table, necessary for Z3 joining, if the gateway is a Z3 device.

    • The first argument is the Link Key Table index. This argument matters only when populating the Link Key Table, as is the case with SDK 6.6.x or earlier. For SDK 6.7.x or higher, the argument has no effect.

    • The next argument is the EUI64 of the joining node (in this example, Z3 Light).

    Tip: You can find this information by running the CLI info command on the joining node. Look for a string similar to node [>)000B57FFFE07A9E3].

    You can also find the EUI64 from the output of the tokendump command but note that it is printed in little endian format. You will need to reverse the bytes to get the proper output.

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

    Tip: You can calculate the CRC yourself, or you can run the Simplicity Commander tokendump command:

    $ commander tokendump --tokengroup znet

    The CRC is displayed just below the install code and is printed in little endian format. Reverse the bytes to big endian before using as an argument with the option install-code CLI. Because the white spaces inside the curly brackets are not mandatory, you can do a straight copy/paste without the spaces. The spaces are included to help better view the data.

  5. To see if the link key is added successfully, enter the keys print CLI on the Z3 Gateway to see it in the Link Key Table or Transient Key Table. This shows both the link key derived from the installation code, and the network key.

  6. (Optional but highly recommended, so that you see the joining device join the network as described in step 7.) At this point, you have all the information the Network Analyzer needs to decrypt future transactions between the Z3 Gateway and Z3 Light. In File >Preferences > Network Analyzer > Decoding > Security Keys, add both the network key and the link key to the list of security key. See the relevant quick-start guide for more information. Start a new network capture from the Z3 Light and/or Z3 Gateway.

    Tip: If you are in a "noisy" environment, you may choose to only capture on the specific PAN.

  7. Finally, on the joining device enter this CLI to join the network:

    plugin network-steering start 0

    The joining device should join the network with the transient link key. If you have started a network capture in step 6, you should see the full transactions live. The Z3 Light is initially allowed on the network using the transient link key. The trust center 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 trust center transports that link key in a "Transport Key (Link)" frame.

Using SDK Version 6.x and Lower#

  1. Make sure the Z3 Light is not on any network. If it is issue network leave.

  2. Follow the instructions in section Programming the Installation Code on a Zigbee Device to create an installation code text file, and program the installation code onto the Z3 Light device.

  3. On the Z3 Gateway, form a centralized network with Zigbee 3.0 security using this command in the Network Creator plugin's CLI:

    plugin network-creator start 1

  4. To derive a link key from the installation code and store that into the key table on the Z3 Gateway, which acts as the Trust Center for the centralized network, enter:

    option install-code <link key table index> {<Joining Node’s EUI64>} {<installation code + 2-byte CRC>}

    For example:

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

    • Starting with GSDK 2.7, this command adds the key entry into the Transient Key Table which is necessary for Z3 joining. For GSDK 2.6 or earlier, this command populates the Link Key Table. Step 7 shows how to move the key entry from the Link Key Table to the Transient Key Table.

    • For GSDK 2.7 or higher, this command populates the Link Key Table if the gateway is a Smart Energy device and the Transient Key Table if the gateway is a Z3 device.

    • The first argument is the Link Key Table index. This argument matters only when populating the Link Key Table, as is the case with GSDK 2.6 or earlier. For GSDK 2.7 or higher, the argument has no effect.

    • The next argument is the EUI64 of the joining node (in this example, Z3 Light).

    Tip: You can find this information by running the CLI info command on the joining node. Look for a string similar to node [>)000B57FFFE07A9E3].

    You can also find the EUI64 from the output of the tokendump command, but note that it is printed in little endian format. You will need to reverse the bytes to get the proper output.

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

    Tip: You can calculate the CRC yourself, or you can simply find out from running the Simplicity Commander tokendump command:

    $ commander tokendump --tokengroup znet

    The CRC is displayed just below the install code and is printed in little endian format. Reverse the bytes to big endian before using as an argument with the option install-code CLI. Because the white spaces inside the curly brackets are not mandatory, you can do a straight copy/paste without the spaces. The spaces are included to help better view the data.

  5. To see if the link key is added successfully, enter the keys print CLI on the Z3 Gateway to see it in the Link Key Table or Transient Key Table. This shows both the link key derived from the installation code, and the network key. Note: In GSDK 2.6 or earlier, the fact that the option install-code CLI copies the link key to the Link Key Table may not be desirable in practice. To avoid populating the permanent Link Key Table completely, instead of using the option install-code CLI call the API emAfInstallCodeToKey() to calculate the joining link key from the install code and keep this link key value ready for steps 6 and 7 below. Alternatively, leave the entry in the Link Key Table and reuse it later in step 7, where the entry is moved to the Transient Key Table.

  6. (Optional but highly recommended, so that you see the joining device join the network as described in step 8.) At this point, you have all the information the Network Analyzer needs to decrypt future transactions between the Z3 Gateway and Z3 Light. In File > Preferences > Network Analyzer > Decoding > Security Keys, add both the network key and the link key to the list of security key. See QSG106: Zigbee EmberZNet PRO Quick Start Guide for more information. Start a new network capture from the Z3 Light and/or Z3 Gateway. Tip: If you are in a "noisy" environment, you may choose to only capture on the specific PAN.

  7. Complete this step only for GSDK 2.6 or earlier: Set the transient link key (the same link key that you derived from the install code) on the Trust Center and open the network for joining with the joining device’s EUI64:

    plugin network-creator-security open-with-key {eui64} {linkkey}

    For example:

    plugin network-creator-security open-with-key {00 0B 57 FF FE 07 A9 E3} {FA 80 81 CA AA 41 D5 AD E9 B5 65 87 99 26 8B 88}

    Once a transient link key exists for the device about to join, remove the unnecessary Link Key Table entry by issuing this command:

    keys delete {index}

    where {index} refers to the Link Key Table index as shown in the output to keys print.

  8. Finally, on the joining device enter this CLI to use the Network Steering plugin to join the network:

    plugin network-steering start 0

    The joining device should join the network with the transient link key. If you have started a network capture in step 6, you should see the full transactions live. The Z3 Light is initially allowed on the network using the transient link key. The trust center 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 trust center transports that link key in a "Transport Key (Link)" frame.

Transferring Installation Codes to the Trust Center#

In this example, the installation codes were entered manually, but in practice it may not be practical to connect to the Trust Center in this way. Customers are responsible for implementing installation codes, and should consider a number of details:

  • Will the commissioning be done all at the same time (perhaps for a large industrial lighting application), or piece-by-piece in a home automation setting?

  • Will there be an Internet-connected gateway?

  • Can the installation codes be written during manufacturing for a pre-commissioned bundle?

  • Will initial commissioning differ from later commissioning for added devices or in the case of leaving the network and then re-joining?

  • How might the network accommodate a commissioner that would leave and return to a network in a switched multiprotocol scenario?

Here are some methods we envision being used:

  • Bluetooth commissioning using our Dynamic Multiprotocol (DMP) feature and a Bluetooth phone app for commissioning. See UG305: Dynamic Multiprotocol User’s Guide for more information.

  • Pre-commissioning at the factory: install codes entered at manufacturing time for trust center and joining devices.

  • Bluetooth-based commissioning with Switched Multiprotocol (SMP) on the trust center and a Bluetooth phone app for entering install codes. See UG267: Switched Multiprotocol User's Guide for more information.

  • Using QR codes on joining devices, and using an app to send the install code via WiFi to an internet-enabled NCP gateway.

  • Barcode/QR code scanning capability on the trust center.