Thread: Co-processor

The Thread Co-processor sample demonstrates how to implement OpenThread’s Co-processor designs inside the Zephyr environment. The sample uses the Radio co-processor (RCP) architecture.

The sample is based on Zephyr’s OpenThread co-processor sample. However, it customizes Zephyr’s sample to fulfill the nRF Connect SDK requirements (for example, by increasing the stack size dedicated for the user application), and also extends it with features such as:

  • Increased Mbed TLS heap size.

  • Lowered main stack size to increase user application space.

  • No obsolete configuration options.

  • Vendor hooks for co-processor architecture allowing users to extend handled properties by their own, customized functionalities.

  • Thread 1.4 features, including support for Thread 1.3 and Thread 1.2.

This sample supports optional logging extension, which can be turned on or off independently. To enable logging extension, use the ot-debug snippet.

Requirements

The sample supports the following development kits for testing the network status:

Hardware platforms

PCA

Board name

Board target

nRF54LM20 DK

PCA10184

nrf54lm20dk

nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp

nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp/ns nrf54l15dk/nrf54l15/cpuapp

nRF54L15 DK (emulating nRF54L10)

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l10/cpuapp

nRF54L15 DK (emulating nRF54L05)

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l05/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

To test the sample, you need at least one development kit. You can use additional development kits programmed with the Co-processor sample for testing network joining.

Moreover, the sample requires a Userspace higher layer process running on your device to communicate with the MCU co-processor part. This sample uses ot-cli as reference.

Overview

The sample demonstrates using a co-processor target on the MCU to communicate with ot-cli on Unix-like operating system. According to the co-processor architecture, the MCU part must cooperate with user higher layer process to establish the complete full stack application. The sample shows how to set up the connection between the co-processor and the host.

By default, this sample comes with the RCP set of OpenThread functionalities enabled (CONFIG_OPENTHREAD_NORDIC_LIBRARY_RCP).

Application architecture options

The sample supports two application architecture options depending on if you are using the Zephyr networking layer.

  • Direct IEEE 802.15.4 radio integration with OpenThread Stack (default)

  • Integration with Zephyr networking layer

To learn more about the differences between the two architectures, see the OpenThread stack architecture page. To learn how to switch between the two architectures, see the Enable OpenThread in the nRF Connect SDK user guide.

Additionally, you can use the ot-zephyr-l2 snippet to switch between the two architectures. See the Snippets section for details.

Logging extension

By default, this sample uses Spinel logging backend for sending log messages to the host device using the Spinel protocol. This is a useful feature, because it does not require separate interfaces to communicate with the co-processor through the Spinel protocol and collect log messages. Moreover, using the Spinel logging backend (by setting CONFIG_LOG_BACKEND_SPINEL) does not exclude using another backend like UART or RTT at the same time.

By default, the log levels for all modules are set to critical to not engage the microprocessor in unnecessary activities. To make the solution flexible, you can change independently the log levels for your modules, for the whole Zephyr system, and for OpenThread. Use the ot-debug snippet as reference for this purpose.

For example:

west build -b nrf54l15dk_nrf54l15_cpuapp -p -- -Dcoprocessor_SNIPPET=ot-debug

User interface

All the interactions with the application are handled using serial communication.

You can interact with the sample through ot-daemon or ot-cli with commands listed in OpenThread CLI Reference. See OpenThread POSIX applications for more information.

You can also use your own application, provided that it supports the Spinel communication protocol.

Note

This sample has Hardware Flow Control mechanism enabled by default in serial communication. When enabled, it allows devices to manage transmission by informing each other about their current state, and ensures more reliable connection in high-speed communication scenarios. In addition, the Co-processor sample reconfigures the baud rate to 1000000 bit/s by default.

Diagnostic module

The Co-processor sample enables a diagnostic module in a similar way as described in the Diagnostic module section of the Thread: CLI sample documentation. However, the Co-processor and CLI samples use different commands for the module, as described in the HCI support section.

Rebooting to bootloader

The Co-processor sample enables rebooting to bootloader for the nrf52840dongle/nrf52840 board target, similar to what is described in the Rebooting to bootloader section of the Thread: CLI sample documentation. However, the Co-processor and CLI samples use different commands, as described in the HCI support section. Additionally, the OpenThread POSIX applications should be built with -DOT_PLATFORM_BOOTLOADER_MODE=ON option.

Configuration

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

Check and configure the following library option that is used by the sample:

You can add support for the nRF21540 front-end module to this sample by using one of the following options, depending on your hardware:

  • Build the sample for one board that contains the nRF21540 FEM, such as nRF21540 DK.

  • Manually create a devicetree overlay file that describes how the nRF21540 FEM is connected to the SoC. See Configuring devicetree for different ways of adding the overlay file.

  • Provide nRF21540 FEM capabilities by using a shield, for example the nRF21540 EK shield that is available in the nRF Connect SDK. In this case, build the project for a board connected to the shield you are using with an appropriate variable included in the build command, for example -DSHIELD=nrf21540ek. This variable instructs the build system to append the appropriate devicetree overlay file.

    To build the sample in nRF Connect for VS Code for an nRF52840 DK with the nRF21540 EK attached, add the shield variable in the build configuration’s Extra CMake arguments and rebuild the build configuration. For example: -DSHIELD=nrf21540ek.

    See How to work with build configurations in the nRF Connect for VS Code documentation for more information.

    See Programming nRF21540 EK for information about how to program when you are using a board with a network core, for example the nRF5340 DK.

Each of these options adds the description of the nRF21540 FEM to the devicetree. See Developing with Front-End Modules for more information about FEM in the nRF Connect SDK.

To add support for other front-end modules, add the respective devicetree file entries to the board devicetree file or the devicetree overlay file.

Building and running

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

This sample can be found under samples/openthread/coprocessor 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.

HCI support

The sample supports Bluetooth® Low Energy (LE) Controller functionality using HCI over UART. To enable HCI support, complete the following steps:

HCI communication is handled over a dedicated UART peripheral on the nRF54L Series System-on-Chip (SoC). After connecting the board using the SEGGER J-Link USB port, two serial ports will be created. The first port is used for HCI and the second for the Thread co-processor (Spinel).

To enable HCI support, run the following command:

west build -b board_target -p -- -DEXTRA_CONF_FILE=extra_conf/rcp_hci_nrf54l_05_10_15.conf -DEXTRA_DTC_OVERLAY_FILE=extra_conf/rcp_hci_nrf54l_05_10_15.overlay

Vendor hooks

The sample supports vendor hooks for co-processor architecture allowing you to extend handled properties by your own, customized functionalities.

To enable vendor hooks, set the CONFIG_OPENTHREAD_COPROCESSOR_VENDOR_HOOK_SOURCE Kconfig option to the path of the vendor hook source file and run the following command with board_target replaced with the board target name:

west build -b board_target -p -- -DCONFIG_OPENTHREAD_COPROCESSOR_VENDOR_HOOK_SOURCE="/src/user_vendor_hook.cpp"

Testing

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

  1. Connect the development kit’s SEGGER J-Link USB port to the PC USB port with a USB cable. If you are using HCI for boards other than nRF54L15, nRF54L10, and nRF54L05 DKs, connect the kit’s nRF USB port to the PC USB port instead.

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

  3. Run and configure ot-cli as described in OpenThread POSIX applications.

  4. From this point, you can follow the Testing instructions in the CLI sample by removing the ot prefix for each command. If you are using HCI, follow the instructions for the HCI UART sample in the Zephyr documentation. You can follow these instead of or in addition to the CLI sample instructions.

Dependencies

This sample uses the following Zephyr libraries: