Zigbee: Shell

Note

Support for Zigbee R22 has been deprecated in nRF Connect SDK v2.8.0 and it will be removed in one of the future releases, following the deprecation policy. As a result, the nRF52833, nRF52840 and nRF5340 SoCs are not recommended for new Zigbee designs. Experimental support for Zigbee R23 is available for the nRF54L Series as an nRF Connect SDK Add-on.

This Zigbee Shell sample demonstrates a Zigbee router (with the possibility of being a coordinator) that uses the Zigbee shell library for interaction.

You can use this sample for several purposes, including:

Initial configuration of the network - forming a network as coordinator, adding devices to the network with the install codes, setting the extended PAN ID.
Benchmarking - measuring time needed for a message to travel from one node to another.

Requirements 

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF5340 DK	PCA10095	nrf5340dk	`nrf5340dk/nrf5340/cpuapp`
nRF52840 Dongle	PCA10059	nrf52840dongle	`nrf52840dongle/nrf52840`
nRF52840 DK	PCA10056	nrf52840dk	`nrf52840dk/nrf52840`
nRF52833 DK	PCA10100	nrf52833dk	`nrf52833dk/nrf52833`
nRF21540 DK	PCA10112	nrf21540dk	`nrf21540dk/nrf52840`

You can use one or more of the development kits listed above and mix different development kits.

To test this sample you also need to program the following samples:

The Zigbee Network coordinator sample on one separate device or using a second Zigbee Shell sample.

Additionally, you can use this sample with any other Zigbee sample application for testing the communication or other sample-specific functionalities.

Overview 

The Zigbee Shell sample takes the Zigbee Router role and implements two clusters: Basic and Identify. The Basic cluster provides attributes and commands for determining basic information about the node. The Identify cluster allows to put the device into the identification mode, which provides a way to locate the device. The device also includes all Zigbee shell commands that allow for discovering, controlling and testing other Zigbee devices.

Sample logging 

The Zigbee Shell sample does not use the default logging settings for the nRF Connect SDK samples. Unlike the default sample logging in the nRF Connect SDK, the Zigbee Shell sample’s logger is configured to also log module name and timestamps for every message. The sample has log shell commands enabled for configuring logging, for example the logging level for each log module.

The Zigbee shell library also enables the Zigbee endpoint logger library by default. This library will log information about every ZCL packet received, which can be useful for debugging. You can enable or disable logging from the endpoint logger module by using the commands described in the Enabling and disabling endpoint logging.

Available shell interfaces 

You can run the Zigbee shell commands after connecting and configuring any of the supported backends for testing. These interfaces are completely independent one from another and can be used simultaneously or exclusively. For information about setup, see Testing and optimization.

The Zigbee Shell sample uses UART as the default shell backend. To change the shell backend from the default UART to the nRF USB CDC ACM, use the prj_usb.conf configuration file and add the -DFILE_SUFFIX=usb flag when building the sample. With such configuration, Zephyr logs are printed only to the backend that the shell is using. You can enable the UART backend for the logger, so that Zephyr logs are printed to both the shell backend and the UART. To do this, enable the CONFIG_LOG_BACKEND_UART Kconfig option. If the sample is built for nRF52840 Dongle, the nRF USB CDC ACM is the default backend for shell.

User interface 

LED 1 (nRF52 Dongle):: Blinks green to indicate that the identification mode is on.
LED 3:: Turns on when the device joins the network.
LED 4 (supported DKs):: Blinks to indicate that the identification mode is on.
Button 1 (nRF52 Dongle):: Starts or cancels the Identify mode.
Button 4 (supported DKs):: Starts or cancels the Identify mode.

All other interactions with the application can be handled using serial communication. See Zigbee shell command list for available serial commands.

Configuration 

See Configuring and building for information about how to permanently or temporarily change the configuration.

Enabling and disabling endpoint logging 

Zigbee Shell sample has Zigbee endpoint logger library enabled by default and will log every ZCL packet received.

You can enable and disable logs from endpoint logger using the log enable and log disable shell commands with the appropriate log module instance name, respectively:

To disable the logs from Zigbee endpoint logger, use the following command:
```
log disable zigbee.eprxzcl
```
To enable logs from Zigbee endpoint logger and set its logging to the info level (inf), use the following command:
```
log enable inf zigbee.eprxzcl
```
You can also use the following command to see other available logging levels:
```
log enable --help
```

Building and running 

Make sure to configure the Zigbee stack before building and testing this sample. See Configuring Zigbee in nRF Connect SDK for more information.

This sample can be found under samples/zigbee/shell in the nRF Connect SDK folder structure.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Testing 

In this testing procedure, both of the development kits are programmed with the Zigbee Shell sample. One of these samples acts as Zigbee Coordinator, the other one as Zigbee Router.

After building the sample and programming it to your development kits, complete the following steps to test it:

Turn on the development kits.
Set up the serial connection with the development kits using one of the Available shell interfaces.
To set one shell device to work as coordinator, run the following shell command:
```
bdb role zc
```
This shell device is now the shell coordinator node.
Run the following command on the shell coordinator node to start a new Zigbee network:
```
bdb start
```
Run the following command on the second board programmed with the Shell sample:
```
bdb start
```
The shell device joins the network.
To check that the shell device has commissioned, run the following command:
```
zdo short
```
The command returns the acquired short address of the shell device.

To check the communication between the nodes, issue a ping request with the acquired short address value and the payload size:

zcl ping zdo_short_address payload_size

For example:

zcl ping 0x2485 10

The ping time response is returned when the ping is successful, followed by the additional information from the endpoint logger. For example:

Ping time: 20 ms
Done
[00:00:21.261,810] <inf> zigbee.eprxzcl: Received ZCL command (0): src_addr=0x2485(short) src_ep=64 dst_ep=64 cluster_id=0xbeef
profile_id=0x0104 cmd_dir=0 common_cmd=0 cmd_id=0x01 cmd_seq=0 disable_def_resp=1 manuf_code=void payload=[cdcdcdcdcdcdcdcdcdcd] (0)

Disable the endpoint logger:
```
log disable zigbee.eprxzcl
```
Issue another ping request:
```
zcl ping 0x2485 10
```
The result does not include the endpoint logger information anymore. For example:
```
Ping time: 20 ms
Done
```

Dependencies 

This sample uses the following nRF Connect SDK libraries:

It uses the following sdk-nrfxlib libraries:

ZBOSS Zigbee stack 3.11.5.0 (API documentation)

In addition, it uses the following Zephyr libraries:

include/zephyr.h
include/device.h
Logging