Zigbee: NCP

The Zigbee NCP sample demonstrates the usage of Zigbee’s Network Co-Processor (NCP) architecture.

Together with the source code from ZBOSS NCP Host, you can use this sample to create a complete and functional Zigbee device. For example, as shown in the Testing scenario, you can program a development kit with the NCP sample and bundle it with the light control application on the NCP host processor.

You can then use this sample together with the Zigbee network coordinator and the Zigbee light bulb to set up a basic Zigbee network.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Build target
nRF52840 DK	PCA10056	nrf52840dk_nrf52840	nrf52840dk_nrf52840
nRF52840 Dongle	PCA10059	nrf52840dongle_nrf52840	nrf52840dongle_nrf52840
nRF52833 DK	PCA10010	nrf52833dk_nrf52833	nrf52833dk_nrf52833
nRF21540 DK	PCA10112	nrf21540dk_nrf52840	nrf21540dk_nrf52840

You can use any of the development kits listed above.

Note

The nRF52840 Dongle uses a different bootloader than other development kits.

For this sample to work, you also need the following:

• ZBOSS NCP Host tool, which is based on the ZBOSS stack and available for download as a standalone zip package as one of Zigbee tools. It contains the source code for all parts of the ZBOSS library for the NCP host. This allows you to recompile the library for the designated hardware platform. Running the ZBOSS NCP Host requires a PC with an operating system compatible with the 64-bit Ubuntu 18.04 Linux.

• The Zigbee network coordinator sample programmed on one separate device.

• The Zigbee: Light bulb sample programmed on one separate device.

This means that you need at least three development kits for testing this sample.

Zigbee NCP sample setup overview

Overview

The sample demonstrates using a Nordic Semiconductor’s Development Kit as Zigbee Network Co-Processor.

The sample uses the CONFIG_ZIGBEE_LIBRARY_NCP_DEV Kconfig option, which is available in the development version of the ZBOSS stack libraries (managed by the CONFIG_ZIGBEE_LIBRARY_DEVELOPMENT Kconfig option, also enabled by default). The NCP Kconfig option extends the compilation process with an implementation of the ZBOSS API serialization through NCP commands. It also implements the ZBOSS default signal handler function, which controls the ZBOSS and commissioning logic.

The sample is built to work with bootloader. See Bootloader support for more information.

The NCP application creates and starts a ZBOSS thread as well as the communication channel for NCP commands that are exchanged between the connectivity device and the host processor.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

See IEEE 802.15.4 EUI-64 configuration for information about how to configure the IEEE address for this sample.

Serial communication setup

The communication channel uses Zephyr’s UART API. This serial device is selected with CONFIG_ZIGBEE_UART_DEVICE_NAME.

By default, the NCP sample communicates through the UART serialization (UART0). As a result, Zephyr’s logger is configured to use UART1, which is available through GPIO pins (P1.00 and P1.01).

The UART0 pins are configured by Devicetree overlay files for each supported development kit in the boards directory.

Communication through USB

You can change the communication channel from the default UART to nRF USB by using the prj_usb.conf configuration file. This configuration file is not applied automatically and can be passed into CMake by using the -- separator when building the sample. For example:

west build samples/zigbee/ncp -b nrf52840dk_nrf52840 -- -DCONF_FILE='prj_usb.conf'

The USB device VID and PID are configured by the sample’s Kconfig file.

Note

If you want to use the USB as the NCP communication channel when using the nRF52840 Dongle, building the sample with the prj_usb.conf configuration file is mandatory.

Bootloader support

The bootloader support in the NCP sample depends on the development kit, its respective build target, and Serial communication setup:

• For the nrf52840dongle_nrf52840 build target, nRF5 SDK Bootloader is used by default because the dongle comes with this bootloader preinstalled.

• For the nrf52840dk_nrf52840, nrf52833dk_nrf52833, and nrf21540dk_nrf52840 build targets, the following scenarios are possible when building for these build targets:

  • If the Communication through USB is selected, MCUboot is enabled by default.

  • If the default UART serial communication channel is used, the bootloader support is not enabled, but MCUboot can be enabled by the user.

MCUboot

When the Communication through USB is selected, MCUboot in this sample is built with support for single application slot, and uses the USB DFU class driver to allow uploading image over USB.

If you want to use the default UART serial communication channel, you can enable MCUboot by setting the CONFIG_BOOTLOADER_MCUBOOT Kconfig option. To use the same MCUboot configuration as in Communication through USB, you need to provide MCUboot with the Kconfig options included in the child_image/mcuboot_usb.conf file. See Image-specific variables for how to set the required options.

MCUboot with the USB DFU requires a larger partition. To increase the partition, define the PM_STATIC_YML_FILE variable that provides the path to the pm_static.yml static configuration file in the configuration directory for the build target of your choice. These additional options and configuration file can be passed into CMake by using the -- separator when building the sample. For example:

west build samples/zigbee/ncp -b nrf52840dk_nrf52840 -- -DCONFIG_BOOTLOADER_MCUBOOT=y  -Dmcuboot_CONFIG_MULTITHREADING=y -Dmcuboot_CONFIG_BOOT_WAIT_FOR_USB_DFU=y -Dmcuboot_CONFIG_SINGLE_APPLICATION_SLOT=y -DPM_STATIC_YML_FILE=samples/zigbee/ncp/configuration/nrf52840dk_nrf52840/pm_static.yml

When building the sample, the build system also generates the signed app_update.bin image file in the build directory. This file can be used to upgrade a device. See Using MCUboot in nRF Connect SDK for more information about this and other automatically generated files.

After every reset, the sample first boots to MCUboot and then, after a couple of seconds, the NCP sample is booted. When booted to MCUboot, the new image can be uploaded with the dfu-util tool. See USB DFU sample documentation for a reference.

To learn more about configuring bootloader for an application in nRF Connect SDK, see the Secure bootloader chain page.

nRF5 SDK Bootloader

When the sample is built for nrf52840dongle_nrf52840, the build system does not produce an upgrade image. You can use the nRF Connect Programmer application (part of nRF Connect for Desktop) to generate and upload a new application image to the dongle. For more details, see Programming the nRF52840 Dongle in the nRF Connect Programmer user guide.

To boot to the bootloader on the dongle, an additional action is required. For example, you can trigger the pin reset procedure to reboot the device to the bootloader DFU mode, in which the new application image can be uploaded. See nRF5 Bootloader DFU Mode for the list of possible conditions for activating the DFU mode.

FEM support

Note

Software FEM support is not present on nRF53 Series devices yet. For now, it also cannot be combined with multiprotocol operation.

You can add support for the nRF21540 front-end module to the sample. See Radio front-end module (FEM) support for more information.

To add support for the nRF21540 FEM, add the provided dts-nrf21540-fem.overlay devicetree overlay file when building. The file is located in the samples/zigbee/common folder. Make sure that the GPIOs in the file correspond to those in which your front-end module is connected.

Note

You must add the provided overlay file if you use the nRF21540 EK. If you use the nRF21540 DK, build your application for the nrf21540dk_nrf52840 board. The devicetree for the nRF21540 DK already contains the required FEM configuration, so you do not need to add the overlay file.

See Set devicetree overlays for different ways of adding the overlay file.

The easiest way to add the file when building is to set it in the DTC_OVERLAY_FILE variable. However, doing so will override the default settings. For some boards, this sample requires additional overlay files, which are automatically included when building with the default settings. When you set the DTC_OVERLAY_FILE variable, you must specify all overlay files that are needed for building. Check the boards folder to see the additional overlay files.

Follow the instructions in Providing CMake options to specify the DTC_OVERLAY_FILE variable. For example, to build the sample from the command line for an nRF52833 DK with an attached nRF21540 EK, invoke the following command within the sample directory:

west build -b nrf52833dk_nrf52833 -- -DDTC_OVERLAY_FILE="boards/nrf52833dk_nrf52833.overlay;../common/dts-nrf21540-fem.overlay"

Alternatively, you can copy the contents of dts-nrf21540-fem.overlay to the board’s overlay file.

To add support for other front-end modules, add the respective overlay files in the same way.

User interface

All the NCP sample’s interactions with the application are automatically handled using serial or USB communication.

Building and running

Make sure to enable the Zigbee stack before building and testing this sample. See Zigbee for more information.

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

See Building and programming a sample application for information about how to build and program the application.

Testing

After building the sample and programming it to your development kit, test it by performing the following steps:

1. Download and extract the ZBOSS NCP Host package.

   Note

   If you are using an Linux distribution different than the 64-bit Ubuntu 18.04, make sure to rebuild the package libraries and applications by following the instructions described in the README.rst file in the ZBOSS NCP Host package.

2. If you are using Communication through USB, connect the nRF USB port of the NCP sample’s development kit to the PC USB port with an USB cable.

3. Get the kit’s serial port name (for example, /dev/ttyACM0). If you are communicating through the nRF USB, get the nRF USB serial port name.

4. Turn on the development kit that runs the network coordinator sample. When LED 3 turns on, this development kit has become the Coordinator of the Zigbee network.

5. Turn on the development kit that runs the light bulb sample. When LED 3 turns on, the light bulb has become a Router inside the network.

   Tip

   If LED 3 does not turn on, press Button 1 on the Coordinator to reopen the network.

6. Start the light control application by running the following command with serial_port_name replaced with the serial port name used for communication with the NCP sample:

   NCP_SLAVE_PTY=*serial_port_name* ./application/light_sample/light_control/light_control
   

The light control device joins the Zigbee network, searches for a light bulb to control, and starts sending On/Off commands with a 15-sec period that toggle the LED 4 on the light bulb on and off.

Dependencies

This sample uses the following nRF Connect SDK libraries:

• Zigbee subsystem:

  • zb_nrf_platform.h

This sample uses the following sdk-nrfxlib libraries:

• ZBOSS Zigbee stack (development version)

In addition, it uses the following Zephyr libraries:

• include/device.h

• USB device stack

• Logging

• UART