diff --git a/docs/architectures.rst b/docs/architectures.rst index 811966c1..48a9277a 100644 --- a/docs/architectures.rst +++ b/docs/architectures.rst @@ -14,8 +14,6 @@ This page describes the platform designs that are possible with the Zigbee stack The designs are described from the least to the most complex, that is from simple applications that consist of a single chip running single or multiple protocols to scenarios in which the nRF SoC acts as a network co-processor when the application is running on a much more powerful host processor. -.. include:: /includes/coprocessor_note.txt - .. _ug_zigbee_platform_design_soc: System-on-Chip designs @@ -95,8 +93,6 @@ This platform design is suitable for the following development kit: Co-processor designs ******************** -.. include:: /includes/coprocessor_note.txt - In co-processor designs, the application runs on one processor (the host processor) and communicates with another processor that provides the radio interface. In these designs, the more powerful processor (host) interacts with the Zigbee network through a connectivity device, for example a Nordic Semiconductor's device with the Zigbee interface. diff --git a/docs/images/zigbee_platform_design_ncp.svg b/docs/images/zigbee_platform_design_ncp.svg index d5ed05a3..a1b91d92 100644 --- a/docs/images/zigbee_platform_design_ncp.svg +++ b/docs/images/zigbee_platform_design_ncp.svg @@ -70,9 +70,9 @@ Application Sheet.142 - UART/USB + UART - UART/USB + UART Sheet.143 nRF SoC diff --git a/docs/lib/index.rst b/docs/lib/index.rst index 70174ffc..ca8bd950 100644 --- a/docs/lib/index.rst +++ b/docs/lib/index.rst @@ -84,6 +84,7 @@ The following table lists libraries enabled by default for each available Zigbee - :ref:`Light bulb ` - :ref:`Light switch ` - :ref:`Network coordinator ` + - :ref:`NCP ` - :ref:`Shell (sample) ` - :ref:`Template ` * - ZBOSS OSIF @@ -92,28 +93,33 @@ The following table lists libraries enabled by default for each available Zigbee - ✔ - ✔ - ✔ + - ✔ * - Shell (library) - - - + - - ✔ - * - Application utilities (default signal handler) - ✔ - ✔ - ✔ + - - ✔ - ✔ * - Error handler - ✔ - ✔ - ✔ + - - ✔ - ✔ * - Endpoint logger - - - + - - ✔ - * - Scene helper @@ -122,6 +128,7 @@ The following table lists libraries enabled by default for each available Zigbee - - - + - Read the table symbols in the following manner: diff --git a/docs/lib/osif.rst b/docs/lib/osif.rst index 25b1914a..74689177 100644 --- a/docs/lib/osif.rst +++ b/docs/lib/osif.rst @@ -70,23 +70,23 @@ The ZBOSS OSIF serial implements sets of backend functions that are used by the These backend functions serve logging ZBOSS traces that are useful for debugging and are provided in binary format. -.. - These backend functions serve one or both of the following purposes: - * Logging ZBOSS traces - Used for handling stack logs that are useful for debugging and are provided in binary format. - * Handling NCP communication with the host device - Used only for the :ref:`NCP architecture `. +These backend functions serve one or both of the following purposes: + +* Logging ZBOSS traces - Used for handling stack logs that are useful for debugging and are provided in binary format. +* Handling NCP communication with the host device - Used only for the :ref:`NCP architecture `. - The following table shows which sets of functions serve which purpose. +The following table shows which sets of functions serve which purpose. - .. _osif_table: +.. _osif_table: - +----------------------------+---------------+---------------+----------+ - | | Async serial | Serial logger | Logger | - +============================+===============+===============+==========+ - | Logging ZBOSS traces | - | - | - | - +----------------------------+---------------+---------------+----------+ - | Handling NCP communication | - | | | - +----------------------------+---------------+---------------+----------+ ++----------------------------+---------------+---------------+----------+ +| | Async serial | Serial logger | Logger | ++============================+===============+===============+==========+ +| Logging ZBOSS traces | - | - | - | ++----------------------------+---------------+---------------+----------+ +| Handling NCP communication | - | | | ++----------------------------+---------------+---------------+----------+ For more information about configuring ZBOSS stack logs, see :ref:`zigbee_ug_logging_stack_logs`. @@ -116,16 +116,14 @@ To configure this set of functions, use the following Kconfig options: * ``CONFIG_ZIGBEE_HAVE_ASYNC_SERIAL`` - This option enables Zigbee async serial. * ``CONFIG_ZIGBEE_UART_SUPPORTS_FLOW_CONTROL`` - This option should be set if serial device supports flow control. * ``CONFIG_ZIGBEE_UART_RX_BUF_LEN`` - This option enables and configures the size of internal RX and TX buffer. - -.. - * ``CONFIG_ZBOSS_TRACE_BINARY_NCP_TRANSPORT_LOGGING`` - This option enables logging ZBOSS traces in binary format with Zigbee async serial. +* ``CONFIG_ZBOSS_TRACE_BINARY_NCP_TRANSPORT_LOGGING`` - This option enables logging ZBOSS traces in binary format with Zigbee async serial. The Zigbee ZBOSS OSIF layer serial device needs to be provided in devicetree as follows: .. code-block:: devicetree chosen { - ncs,zigbee-uart = &uart0; + ncs,zigbee-uart = &uart20; }; Zigbee serial logger @@ -149,7 +147,7 @@ The ZBOSS tracing serial device needs to be provided in Devicetree like this: .. code-block:: devicetree chosen { - ncs,zboss-trace-uart = &uart1; + ncs,zboss-trace-uart = &uart21; }; Zigbee logger diff --git a/docs/links.txt b/docs/links.txt index 1b3767a6..6e47d248 100644 --- a/docs/links.txt +++ b/docs/links.txt @@ -142,7 +142,7 @@ .. _`ZBOSS stack release notes`: .. _`external ZBOSS development guide and API documentation`: https://nrfconnect.github.io/ncs-zigbee/docs/zboss/4.1.4.2/zigbee_devguide.html .. _`Stack commissioning start sequence`: https://nrfconnect.github.io/ncs-zigbee/docs/zboss/4.1.4.2/using_zigbee__z_c_l.html#stack_start_initiation -.. _`ZBOSS NCP Host`: https://developer.nordicsemi.com/Zigbee/ncp_sdk_for_host/ncp_host_v2.2.3.zip +.. _`ZBOSS NCP Host`: https://github.com/nrfconnect/ncs-zigbee/resources/ncp_host_v3.0.0.zip .. _`NCP Host documentation`: https://nrfconnect.github.io/ncs-zigbee/docs/zboss/4.1.4.2/zboss_ncp_host_intro.html .. _`Rebuilding the ZBOSS libraries for host`: https://nrfconnect.github.io/ncs-zigbee/docs/zboss/4.1.4.2/zboss_ncp_host.html#rebuilding_libs .. _`process the frame`: https://nrfconnect.github.io/ncs-zigbee/docs/zboss/4.1.4.2/using_zigbee__z_c_l.html#process_zcl_cmd diff --git a/docs/memory.rst b/docs/memory.rst index de349223..e40eb1aa 100644 --- a/docs/memory.rst +++ b/docs/memory.rst @@ -17,11 +17,6 @@ Values are provided for :ref:`ZBOSS libraries `. Samples were built using the available :ref:`zigbee_zboss`. Unless stated otherwise, the default :file:`prj.conf` was used. -.. _zigbee_memory_52840: -.. _zigbee_memory_52833: -.. _zigbee_memory_5340: -.. _zigbee_memory_21540: - RAM and flash memory requirements ********************************* @@ -49,6 +44,8 @@ Values are provided in kilobytes (KB). +------------------------------------------------------------------------------------------------------------------------+--------------------------+---------------------------+----------------------------------+-----------------------------+-------------+--------------------------+-------------+ | :ref:`Light switch ` with :ref:`zigbee_light_switch_sample_nus` | 446 | 0 | 32 | 4 | 482 | 72 | 72 | +------------------------------------------------------------------------------------------------------------------------+--------------------------+---------------------------+----------------------------------+-----------------------------+-------------+--------------------------+-------------+ + | :ref:`NCP ` | 0 | 0 | 32 | 4 | 0 | 0 | 0 | + +------------------------------------------------------------------------------------------------------------------------+--------------------------+---------------------------+----------------------------------+-----------------------------+-------------+--------------------------+-------------+ | :ref:`Zigbee application template ` | 392 | 0 | 32 | 4 | 428 | 100 | 100 | +------------------------------------------------------------------------------------------------------------------------+--------------------------+---------------------------+----------------------------------+-----------------------------+-------------+--------------------------+-------------+ | :ref:`Zigbee shell ` | 472 | 0 | 32 | 4 | 508 | 117 | 117 | diff --git a/docs/quick-start.rst b/docs/quick-start.rst index a2023657..8825c789 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -123,11 +123,10 @@ After you complete this quick start guide, we recommend that you get familiar wi * If you want to test a multiprotocol solution, see the :ref:`zigbee_light_switch_sample_nus` section of the light switch sample. -.. - * If you want to start developing for co-processor designs: +* If you want to start developing for co-processor designs: - * :ref:`ug_zigbee_platform_design_ncp` - * `NCP Host documentation`_ + * :ref:`ug_zigbee_platform_design_ncp` + * `NCP Host documentation`_ * If you want to learn more about ZBOSS: diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 7a8e73d2..bc9af434 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -21,11 +21,25 @@ For a full list of |addon|, related |NCS| and ZBOSS stack and NCP host package v +-------------------+------------------+-----------------------+---------------------+ | |addon| version | |NCS| version | ZBOSS stack version | NCP host version | +===================+==================+=======================+=====================+ - | 0.1.0 | 2.8.0 | 4.1.4.2 | N/A | + | 0.2.0 | 2.8.0 | 4.1.4.2 | 3.0.0 | + +-------------------+ + +---------------------+ + | 0.1.0 | | | N/A | +-------------------+------------------+-----------------------+---------------------+ .. _zigbee_release: +|addon| v0.2.0 - 28/11/2024 +*************************** + +This is an experimental release. + +* Added: + + * The :ref:`NCP ` sample. + * The `ZBOSS NCP Host`_ package v\ |zigbee_ncp_package_version|. + +* Updated the documentation with small improvements. + |addon| v0.1.0 - 15/11/2024 *************************** diff --git a/docs/samples/index.rst b/docs/samples/index.rst index 68e09deb..a1b8446f 100644 --- a/docs/samples/index.rst +++ b/docs/samples/index.rst @@ -76,30 +76,35 @@ The following table lists variants and extensions available for each Zigbee samp - Light bulb - Light switch - Network coordinator + - NCP - Shell - Template * - Sleepy End Device behavior - :ref:`*** ` - ✔ - + - - :ref:`** ` - :ref:`** ` * - Multiprotocol Bluetooth LE - `*** `_ - ✔ - `*** `_ + - - `*** `_ - `*** `_ * - Endpoint logger - :ref:`** ` - :ref:`** ` - :ref:`** ` + - - ✔ - :ref:`** ` * - ZCL scene helper - ✔ - :ref:`*** ` - :ref:`*** ` + - - :ref:`*** ` - :ref:`*** ` diff --git a/docs/samples/ncp/README.rst b/docs/samples/ncp/README.rst new file mode 100644 index 00000000..dcabdb75 --- /dev/null +++ b/docs/samples/ncp/README.rst @@ -0,0 +1,7 @@ +.. _zigbee_ncp_sample: + +Zigbee: NCP +########### + +.. include:: ../../../samples/ncp/README.rst + :start-after: ########### diff --git a/docs/shortcuts.txt b/docs/shortcuts.txt index 36188832..4100edc6 100644 --- a/docs/shortcuts.txt +++ b/docs/shortcuts.txt @@ -1,6 +1,6 @@ .. ### Versions -.. |addon_version| replace:: 0.1.0 +.. |addon_version| replace:: 0.2.0 .. |ncs_version| replace:: 2.8.0 .. |zigbee_version| replace:: Zigbee 3.0 .. |zboss_version| replace:: 4.1.4.2 @@ -40,6 +40,6 @@ .. |zigbee_ncp_package| replace:: It contains the full development-ready source code for host and evaluation-ready firmware for the nRF54L15 DK. The package comes with prebuilt libraries compatible with 64-bit Ubuntu 22.04 Linux. .. |zigbee_ncp_package_more_info| replace:: For information about how to recompile the package libraries for a different host architecture or operating system, see the `NCP Host documentation`_. - For information about how to use NCP Host for Zigbee in the |NCS| or build the firmware using the NCP sample, see the :ref:`NCP sample `. + For information about how to use NCP Host with the |addon| for the |NCS| or build the firmware using the NCP sample, see the :ref:`NCP sample `. .. |zigbee_shell_config| replace:: You can add support for Zigbee shell commands to any of the available :ref:`Zigbee samples `. Some of the commands use an endpoint for sending packets, so no endpoint handler is allowed to be registered for this endpoint. diff --git a/docs/tools.rst b/docs/tools.rst index 6bbb8f38..f3bce20d 100644 --- a/docs/tools.rst +++ b/docs/tools.rst @@ -22,20 +22,19 @@ It provides a near real-time display of 802.15.4 packets that are sent back and See `nRF Sniffer for 802.15.4`_ for documentation. -.. - .. _ug_zigbee_tools_ncp_host: +.. _ug_zigbee_tools_ncp_host: - ZBOSS NCP Host - ************** +ZBOSS NCP Host +************** - The NCP Host is a ZBOSS-based tool for running the host side of the :ref:`ug_zigbee_platform_design_ncp_details` design. - |zigbee_ncp_package| +The NCP Host is a ZBOSS-based tool for running the host side of the :ref:`ug_zigbee_platform_design_ncp_details` design. +|zigbee_ncp_package| - The tool is available for download as a standalone :file:`zip` package using the following link: +The tool is available for download as a standalone :file:`zip` package using the following link: - * `ZBOSS NCP Host`_ (|zigbee_ncp_package_version|) +* `ZBOSS NCP Host`_ (|zigbee_ncp_package_version|) - |zigbee_ncp_package_more_info| +|zigbee_ncp_package_more_info| .. _ug_zigbee_tools_logger_endpoint: diff --git a/docs/zboss/changelog.rst b/docs/zboss/changelog.rst index 5e14b854..3f2c550c 100644 --- a/docs/zboss/changelog.rst +++ b/docs/zboss/changelog.rst @@ -12,6 +12,15 @@ ZBOSS stack changelog All notable changes to the ZBOSS stack are documented in ZBOSS documentation. +|addon| v0.2.0 +************** + +ZBOSS 4.1.4.2 + `Documentation `_ | `Release notes `_ + +NCP Host 3.0.0 + `Documentation `_ | `Release notes `_ + |addon| v0.1.0 ************** diff --git a/samples/ncp/README.rst b/samples/ncp/README.rst new file mode 100644 index 00000000..9b14181f --- /dev/null +++ b/samples/ncp/README.rst @@ -0,0 +1,237 @@ +.. _zigbee_ncp_sample: + +Zigbee: NCP +########### + +.. contents:: + :local: + :depth: 2 + +The :ref:`Zigbee ` NCP sample demonstrates the usage of Zigbee's :ref:`ug_zigbee_platform_design_ncp_details` architecture. + +Together with the source code from :ref:`ug_zigbee_tools_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 :ref:`Zigbee Light bulb ` to set up a basic Zigbee network. + +Requirements +************ + +The sample supports the following development kits: + +.. include:: /includes/device_table_nrf54l15.txt + +To test this sample, you also need the following: + +* :ref:`ug_zigbee_tools_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 :file:`zip` package using the following link: + + * `ZBOSS NCP Host`_ (|zigbee_ncp_package_version|) + + For more information, see also the `NCP Host documentation`_. +* The :ref:`zigbee_light_bulb_sample` sample programmed on one separate device. + +This means that you need at least two development kits for testing this sample. + +.. figure:: /images/zigbee_ncp_sample_overview.svg + :alt: 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 :ref:`zboss_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 +************* + +|config| + +See :ref:`ug_zigbee_configuring_eui64` 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: + +.. code-block:: devicetree + + chosen { + ncs,zigbee-uart = &uart20; + }; + +By default, Zephyr's logger uses ``uart20`` and the NCP sample communicates through the UART serialization using ``uart1``. +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 :file:`boards` directory. + +.. + Bootloader support + ================== + + The bootloader support in the NCP sample for the ``nrf54l15dk/nrf54l15/cpuapp`` board target is by default disabled, but you can enable `MCUboot`_. + + MCUboot + ------- + + When you select `Communication through USB`_, MCUboot is built with support for a single application slot, and it uses the USB DFU class driver to allow uploading of the image over USB. + + If you want to use the default UART serial communication channel, set the ``CONFIG_BOOTLOADER_MCUBOOT`` Kconfig option to enable MCUboot. + To use the same MCUboot configuration as in `Communication through USB`_, you need to provide MCUboot with the Kconfig options included in the :file:`sysbuild/mcuboot_usb.conf` file. + See `Image-specific variables`_ in the |NCS| documentations to learn how to set the required options. + + MCUboot with the USB DFU requires a larger partition. + To increase the partition, define the :makevar:`PM_STATIC_YML_FILE` variable that provides the path to the :file:`pm_static__.yml` static configuration file for the board target of your choice. + This is done automatically when building the sample with the ``-DFILE_SUFFIX=`` flag. + + For instructions on how to set these additional options and configuration at build time, see `Providing CMake options`_ and `Configuring and building`_ in the |NCS| documentation. + + See `Using MCUboot in nRF Connect SDK`_ for information about build system 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, you can upload the new image with the `dfu-util tool`_. + See the Testing section of the `USB DFU (Device Firmware Upgrade)`_ Zephyr sample for the list of required dfu-util commands. + + To learn more about configuring bootloader for an application in |NCS|, see the `Secure bootloader chain` page in the |NCS| documentation. + +.. + FEM support + =========== + + .. include:: /includes/sample_fem_support.txt + +.. _zigbee_ncp_vendor_specific_commands: + +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 :c:struct:`zb_ncp_custom_request_cb_t` declaration. + For an example, see :c:func:`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. + +#. Register the handler function using :c:func:`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. + +#. 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 :c:func:`zb_ncp_custom_response` is called with a buffer that contains both the response payload and the parameters encapsulated in :c:struct:`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 :c:macro:`NCP_RET_LATER` is returned from the custom command callback (implemented in step 1) and :c:func:`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 :c:func:`ncp_vendor_specific_req_handler` for an example of the immediate response. +#. Implement custom indications by using :c:func:`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 :c:func:`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. + +.. _zigbee_ncp_user_interface: + +User interface +************** + +All the NCP sample's interactions with the application are automatically handled using serial communication. + +Building and running +******************** + +.. |sample path| replace:: :file:`samples/ncp` + +|enable_zigbee_before_testing| + +.. include:: /includes/build_and_run.txt + +.. _zigbee_ncp_testing: + +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`_. + +#. Get the kit’s serial port name (for example, ``/dev/ttyACM0``). +#. Turn on the development kit that runs the Light bulb sample. +#. 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: + + .. parsed-literal:: + :class: highlight + + 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 |NCS| libraries: + +* Zigbee subsystem: + + * :file:`zb_nrf_platform.h` + +It uses the ZBOSS stack: + +* :ref:`zigbee_zboss` |zboss_version| (`API documentation`_) + +In addition, it uses the following Zephyr libraries: + +* :file:`include/device.h` +* `Logging`_ +* `UART API`_