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 simple gateway application on the NCP host processor.

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

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp

To test this sample, you also need the following:

  • ZBOSS NCP Host tool, which is based on the ZBOSS stack and requires a PC with an operating system compatible with the 64-bit Ubuntu 18.04 Linux. The tool is available for download as a standalone zip package using the following link:

    For more information, see also the NCP Host documentation.

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

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

Zigbee NCP sample setup overview

Zigbee NCP sample setup overview

Overview

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

The sample uses the CONFIG_ZIGBEE_LIBRARY_NCP_DEV Kconfig option, which is available as part of the ZBOSS library configuration. 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 that controls the ZBOSS and commissioning logic.

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 and building in the nRF Connect SDK documentation 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 API. The serial device is selected in devicetree like this:

chosen {
    ncs,zigbee-uart = &uart20;
};

By default, Zephyr’s logger uses uart20 and the NCP sample communicates through the UART serialization using uart21. The DTS overlay file configures uart21 to be connected to the on-board J-Link instead of uart20. As the result, Zephyr’s logger uart20 is available only through GPIO pins (P1.08 and P1.09).

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

Vendor-specific commands

You can extend the NCP sample with support for vendor-specific commands to implement new features, such as controlling LEDs. These commands let you request custom actions over the ZBOSS NCP protocol.

Vendor-specific commands are sent over the NCP protocol using the following types of packets:

  • Request

    These can be sent only by the host. The nRF SoC must respond to all of them.

  • Response

    These can be sent only by the nRF SoC. The nRF SoC can send them only when requested by the host. This limitation can be bypassed by indications.

  • Indication

    These can be sent only by the nRF SoC. The indications are sent on demand from the nRF SoC to the host, for example to inform the host about polling avoidance or sudden or rare events, such as pressing the button. Indications are neither responded to nor acknowledged.

By default, the NCP sample already supports the vendor-specific commands for controlling a LED.

Implementing vendor-specific commands

Note

The steps in this section describe the process of implementing the vendor-specific commands in the NCP sample. Documentation for the implementation steps for the host side is not yet available.

To implement custom vendor-specific commands, you need to modify the NCP sample as follows:

  1. Implement a callback for handling custom commands requests.

    The function must follow the zb_ncp_custom_request_cb_t declaration. For an example, see ncp_vendor_specific_req_handler() in the sample. This function parses the command payload, validates it, performs required action on LED 1, and sends a response.

  2. Register the handler function using zb_ncp_custom_register_request_cb(), as implemented in the sample.

    Once the callback is registered, it is called for every custom command request received from the host.

  3. At the end of the custom request callback, implement the response to the request using one of the following options:

    • Implement an immediate response that is sent just after the request is received and parsed. For this option, make sure that the length of the response is returned from the custom command callback (implemented in step 1) and zb_ncp_custom_response() is called with a buffer that contains both the response payload and the parameters encapsulated in ncp_hl_custom_resp_t.

    • Implement a delayed response that can be useful for example to implement commands that require more time to complete. For this option, make sure that NCP_RET_LATER is returned from the custom command callback (implemented in step 1) and zb_ncp_custom_response() is called after this callback.

    If the function fails, it must return an error code, while a response is automatically generated by the stack. See ncp_vendor_specific_req_handler() for an example of the immediate response.

  4. Implement custom indications by using zb_ncp_custom_indication() to send an indication to the host.

    The NCP sample demonstrates the indication usage to inform the host about the index of the LED that is controlled by custom requests. The indication is sent three seconds after start-up. See custom_indication() in the sample to see how to pass the data to the indication’s payload.

Once you complete these steps and configure the vendor-specific commands on the host, you can call these commands from the host to use the extended functionalities in the NCP sample.

User interface

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

Building and running

Make sure to configure the Zigbee stack before building and testing this sample. See Configuring Zigbee add-on for more information.

This sample can be found under samples/ncp in the Zigbee add-on folder structure.

To build the sample, follow the instructions in Building an application in the nRF Connect SDK documentation 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 Zigbee add-on which is an SDK repository, 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

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

  1. Download and extract the ZBOSS NCP Host package.

    Note

    If you are using a Linux distribution different than the 64-bit Ubuntu 22.04, make sure to rebuild the package libraries and applications. Follow the instructions in the Rebuilding the ZBOSS libraries for host section in the NCP Host documentation.

  2. Get the kit’s serial port name (for example, /dev/ttyACM0).

  3. Turn on the development kit that runs the Light bulb sample.

  4. To start the simple gateway application, run 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/simple_gw/simple_gw

The simple gateway device forms the Zigbee network and opens the network for 180 seconds for new devices to join. When the light bulb joins the network, the LED 2 on the light bulb device turns on to indicate that it is connected to the simple gateway. The gateway then starts discovering the On/Off cluster. When it is found, the simple gateway configures bindings and reporting for the device. It then starts sending On/Off toggle commands with a 15-second interval that toggle the LED 1 on the light bulb on and off.

Dependencies

This sample uses the following nRF Connect SDK libraries:

  • Zigbee subsystem:

    • zb_nrf_platform.h

It uses the ZBOSS stack:

In addition, it uses the following Zephyr libraries: