Zigbee Light Control with touchlink commissioning example

The Zigbee light control example with touchlink commissioning is a variation of the Basic Zigbee Light Control example. In this example, the touchlink commissioning procedure is used to create and extend the Zigbee network.

It provides an example implementation of the following devices:

• Touchlink initiator with light switch, which creates new Zigbee network credentials. This commissioning role may be implemented with both ZR and ZED libraries.
• Touchlink target with light bulb, which is commissioned into a network. This role is implemented with ZR library. Current implementation does not support ZED as touchlink target device.

The light switch, working as a touchlink initiator, will generate random network credentials and request network creation on the first connected router (light bulb). Afterwards, it will only provide the network key and request the new device to try the rejoin procedure to join the network established by the first router. On every new device, the switch will read a simple descriptor of the router's endpoint, check if it implements Level Control and On Off clusters, and finally add it into the control group. During normal operation, pressing physical buttons will send messages to the group address, and every commissioned light bulb will respond to that command.

Description

All devices indicate the Zigbee stack state using LEDs, as defined in Thread BSP LED reference. Additionally, BSP_LED_3 on the light bulb imitates dimmable light and BSP_LED_3 on the light switch node informs whether the touchlink commissioning process is in progress. The behavior of BSP_LED_2 on the light switch is also slightly modified, it will toggle on every successfully commissioned light bulb, so connecting the second bulb should turn it off.

Buttons are used only on the light switch node. Pressing BSP_BUTTON_1 after successful commissioning (BSP_LED_2 state) should turn off BSP_LED_3 on the light bulb node. Pressing BSP_BUTTON_0 will turn it back on. Using a long press adjusts the brightness level of the light bulb. BSP_BUTTON_1 decreases the brightness and BSP_BUTTON_0 increases the brightness.

Note

If the user decreases the brightness level to the minimum, the effect of turning on the light bulb might not be noticeable. Additionally, pressing BSP_BUTTON_2 will restart the touchlink commissioning procedure. The light switch does not start this procedure upon start-up, so it has to be restarted in order to join every light bulb, even the first one. If the switch has successfully created the network, it can be restarted. In this case, it will try to rejoin the previous network automatically, indicated by turning on BSP_LED_2.

Touchlink master key

In order to secure the communication between devices, the special network key exchange mechanism was introduced (see Zigbee Cluster Library Specification, section 13.3.4.10.5.2). This exchange uses a touchlink master key, that "is provided to a company as a result of a successful certification of a product" (Base Device Behavior Specification, section 6.3.4). As a result, examples provided with this SDK are not going to work with stock products without modifications (they use developer or certification key by default). In order to do that, the master key has to be specified during the initialization:

/* Set up touchlink master key. */
zb_uint8_t master_key[ZB_CCM_KEY_SIZE] = { place, 128-bit, secret, key, here };
zb_zdo_touchlink_set_master_key(master_key);

Setup

You can find the source code and the makefiles in the following folders:

• <InstallFolder>\examples\zigbee\experimental\touchlink\target
• <InstallFolder>\examples\zigbee\experimental\touchlink\initiator

Testing

1. Build the example according to the instructions in Building examples.
2. Program one board for each example: Touchlink Initiator and Touchlink Target.
3. Turn on the Light switch node. Both BSP_LED_2 and BSP_LED_3 should be turned off.
4. Turn on the Light bulb node.
5. Place the light bulb in close proximity to the light switch (distance between the board's antennas should be less than 50 cm)
6. Press BSP_BUTTON_2 on the light switch to start the touchlink procedure. The BSP_LED_3 on that board should turn on.
7. Wait until BSP_LED_2 on both boards turns on. If that does not happen, and BSP_LED_3 on the switch is turned off, restart the commissioning procedure by pressing BSP_BUTTON_2.
8. After successful commissioning you can control BSP_LED_3 on the light bulb node by pressing BSP_BUTTON_0 and BSP_BUTTON_1 on the light switch node.
9. Pressing BSP_BUTTON_0 or BSP_BUTTON_1 turns the light bulb on or off.
10. Press and hold BSP_BUTTON_0 or BSP_BUTTON_1 to increase or decrease the brightness level of the light bulb.