nRF5 SDK for Thread and Zigbee v4.1.0
Zigbee CLI Agent example

Table of Contents

This information applies to the following SoCs: nRF52833 and nRF52840.

The Zigbee Command Line Interface Agent example demonstrates a Zigbee router (with the possibility of being a coordinator) that interacts with the user by employing the Command Line Interface. This CLI Agent is a tool can be used for several purposes, including:

Available CLI interfaces

The CLI can be accessed by using the following interfaces:

These interfaces are completely independent one from another and can be used simultaneously or exclusively.

Both interfaces use the following speed and parity settings:

The CLI uses its own dedicated library. See the Zigbee CLI library for more details.

The Command Line Interface consists of several commands. See the Zigbee CLI Reference page for details.

You can use a Python CLI wrapper library to control Zigbee network and devices using Python language.


Driver installation on host

The CLI example requires for the host PC to be able to connect to it. Some PC USB drivers might be needed. The driver installation depends on the host operating system.

Operating System Installation procedure
Windows XP or 7 If the native USB CDC connectivity is used, manually install the nordic_cdc_acm.inf driver.
The file that is located at <InstallFolder>\examples\usb_drivers
Windows 8 and later Hosts pick the correct usbser.sys driver file automatically.
Most of modern Linux and MacOS Hosts handle the driver installation automatically.
Driver installation per Operating System

The CLI application starts in the disconnected state and remains in this state until the appropriate commands are issued by the user. These commands can be issued by using a serial line connection with a terminal application like PuTTy.


Setup

You can find the source code and the makefiles in the following folder: <InstallFolder>\examples\zigbee\experimental\cli\cli_agent_router

To set up the example:

  1. Flash the board with the compiled binaries.
  2. Connect to the CLI using one of the following ports:
    • J2 USB port (on the side of the coin cell battery; not available when using the nRF52840 Dongle (PCA10059))
    • J3 nRF USB CDC Port (the USB port next to the buttons on the DK)
  3. By default, the CLI Agent implements the Zigbee Router functionality. If you have a coordinator nearby that is listening on the channel 16, run the following command:
    bdb channel 16
  4. Run the following command:
    bdb start
    The CLI Agent joins the network.
  5. Check the network short address:
    zdo short
    The command returns the acquired short address of the CLI node.

CLI device as Zigbee Coordinator

If you do not have access to the coordinator (standalone or on a third board), you can have one of the CLIs to act as a coordinator. To do so:

  1. Set CLI device to work as a coordinator:
    bdb role zc
  2. Issue the following command on the CLI coordinator node to start a new Zigbee network:
    bdb start
  3. Now you can proceed with testing the Zigbee ping functionality.

Testing

Precondition
  • To test the CLI Agent example, prepare two boards and a Zigbee Coordinator or a third board.
  • Make sure you disabled the Mass Storage Device and forced Hardware Flow Control in SEGGER J-Link. See Configuring SEGGER J-Link software for details.

To test the example:

  1. Build the CLI example and flash it into the two boards.
  2. Do one of the following:
    • If you have a standalone Zigbee Coordinator, make sure it is able to accept new nodes.
    • If you do not have a standalone Zigbee Coordinator, use one of the following solutions:
  3. Connect to the CLI on both boards that have the CLI example flashed on by using the connection appropriate for you.
  4. On both CLIs, issue:
    bdb start
  5. Check that the devices have commissioned by issuing the following command:
    zdo short
    The command must return the received short address of the board.
  6. Check the EUI64 addresses of both boards by issuing:
    zdo eui64
  7. On one board, issue:
    zcl ping <eui64 address of the other board> 30

The board pings the other board with 30 bytes of payload data and prints the time passed between sending a request and receiving a reply.

For a full list of CLI commands, see Zigbee CLI Reference.


Using CLI to control lighting devices

You can use the CLI example to control Zigbee lighting devices, such as Philips Hue or IKEA TRÅDFRI bulbs. Complete the following steps:

  1. Establish a Zigbee network and allow the devices to join:
    > bdb role zc
    Coordinator set
    Done
    > bdb start
    Started coordinator
    Done
    > bdb legacy enable
    Done
    Note
    The last command is mandatory if the firmware of your lighting devices is before Zigbee 3.0 and does not support BDB TC Link Key Exchange. Such devices will be removed from the network if the legacy mode is not enabled. Uncommissioned devices will join the network using Network Steering. A device which was previously commissioned to another network will require a factory reset. Refer to your device's manual for instructions on how to do that.
  2. Discover the devices that have joined the network using the zdo match_desc command. Use the Zigbee Light Link (0xc05e) or the Home Automation (0x0104) profile, depending on the type of devices you have in the network.
    > zdo match_desc 0xfffd 0xfffd 0xc05e 1 0 0
    Sending broadcast request.
    > src_addr=29D5 ep=1
    Done
  3. Search for the device EUI64 address using its network address:
    > zdo ieee_addr 0x29d5
    > 000b57fffebb86b8
    Done
  4. You can discover clusters, thus features supported by a given device, using the zdo simple_desc_req command:
    > zdo simple_desc_req 0x29d5 1
    > src_addr=0x29D5 ep=0x49246 profile_id=0x220 app_dev_id=0x2 app_dev_ver=0x0 in_clusters 0x0 0x3 0x4 0x5 0x6 0x8 0x300 0xB05 0x1000 out_clusters 0x5 0x19 0x20 0x1000
    Done

Interacting with clusters

In this example, the device supports several clusters, including the following ones:

You can interact with these clusters using zcl cmd:

For details about interacting with the clusters using the CLI commands, refer to Zigbee Cluster Library specification.

Adding light switch from other examples

You can also use zcl cmd to add and use a light switch from one of the following light control examples:

This enables you to control bulbs that do not feature an identify button in their production version and cannot respond to the Finding and Binding process of the light switch.

To add the light switch support:

  1. Build and program the light switch according to the instructions in the light control example of your choice.
  2. Turn on the light switch.
  3. Establishing the network and allowing the light switch to join the network:
    > bdb start
    Done
  4. Use the following command to put the bulb in the identify mode:
    zcl cmd 0x29d5 1 0x0003 0x00 -l 0x3c
  5. While the bulb is in the identify mode (check the bulb documentation to see how it indicates this state – for example, it can be blinking), press the Finding & Binding button on the light switch.

Once the light switch establishes connection with the light bulb, you will be able to control the light bulb both as described in the light control example of your choice, and with the CLI commands from Interacting with clusters.


Documentation feedback | Developer Zone | Subscribe | Updated