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:
- initial configuration of the network – forming a network as a coordinator, adding devices to the network with the install codes, setting the extended PAN ID;
- troubleshooting the running network – reading and writing attributes, subscribing to the reports of the parameters;
- benchmarking – measuring time needed for message to travel from one node to another.
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:
- 115200 bit/s,
- 8-bit-long word,
- no parity,
- 1-bit stop.
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 SystemThe 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:
- Flash the board with the compiled binaries.
- Connect to the CLI with one of the following:
- J-Link UART Virtual Port (not available when using the nRF52840 Dongle (PCA10059))
- USB CDC Port (the other USB port on the DK)
- 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:
- Run the following command: The CLI Agent joins the network.
- Check the network short address: The command returns the acquired short address of the CLI node.
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:
- Build the CLI example and flash it into the two boards.
- 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 a Zigbee Coordinator from the Zigbee Light Control example and flash it on a third board (see also the note following this procedure).
- Connect to the CLI on both boards that have the CLI example flashed on by using the connection appropriate for you.
- On both CLIs, issue:
- Check that the devices have commissioned by issuing the following command: The command must return the received short address of the board.
- Check the EUI64 addresses of both boards by issuing:
- 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.
- Note
- 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:
- Set CLI device to work as a coordinator:
- Issue the following command on the CLI coordinator node to start a new Zigbee network:
- Now you can proceed with testing the Zigbee ping functionality.
For a full list of CLI commands, see Zigbee CLI Reference.
Using CLI to control lighting devices
The CLI example can be used to control Zigbee lighting devices, such as Philips Hue or IKEA TRÅDFRI bulbs.
- 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 your lighting devices are pre Zigbee 3.0 and do not support BDB TC Link Key Exchange. Such devices will be removed from the network if 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.
- Discover the devices which have joined the network using the
zdo match_desc
command. Use Zigbee Light Link (0xc05e) or 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
- Look up the device EUI64 address using its network address:
> zdo ieee_addr 0x29d5
> 000b57fffebb86b8
Done
- 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
In the above example, the device supports, among others, On/Off Cluster (0x0006), Level Control Cluster (0x0008), and Color Control (0x0300). You can interact with these clusters using zcl cmd
, as shown below:
Set level:
zcl cmd 000b57fffebb86b8 1 0x0008 -p 0x0104 0x00 -l 0affff
Toggle:
zcl cmd 000b57fffebb86b8 1 0x0006 -p 0x0104 0x02
Set color temperature to 4000 k:
zcl cmd 000b57fffebb86b8 1 0x0300 -p 0x0104 0x0a -l af000000
Set color temperature to 2200k:
zcl cmd 000b57fffebb86b8 1 0x0300 -p 0x0104 0x0a -l c2010000
For details, refer to Zigbee Cluster Library specification.