203 lines
8.3 KiB
ReStructuredText
203 lines
8.3 KiB
ReStructuredText
.. _ot_coprocessor_sample:
|
|
|
|
Thread: Co-processor
|
|
####################
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 2
|
|
|
|
The :ref:`Thread <ug_thread>` Co-processor sample demonstrates how to implement OpenThread's :ref:`thread_architectures_designs_cp` inside the Zephyr environment.
|
|
The sample uses the :ref:`thread_architectures_designs_cp_rcp` architecture.
|
|
|
|
The sample is based on Zephyr's :zephyr:code-sample:`openthread-coprocessor` sample.
|
|
However, it customizes Zephyr's sample to fulfill the |NCS| 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 :ref:`logging extension <ot_coprocessor_sample_logging>`, which can be turned on or off independently.
|
|
To enable logging extension, use the ``ot-debug`` snippet.
|
|
|
|
.. _ot_coprocessor_sample_requirements:
|
|
|
|
Requirements
|
|
************
|
|
|
|
The sample supports the following development kits for testing the network status:
|
|
|
|
.. table-from-sample-yaml::
|
|
|
|
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 :ref:`RCP set of OpenThread functionalities <thread_ug_feature_sets>` enabled (:kconfig:option:`CONFIG_OPENTHREAD_NORDIC_LIBRARY_RCP`).
|
|
|
|
Application architecture options
|
|
================================
|
|
|
|
.. include:: ../cli/README.rst
|
|
:start-after: ot_cli_sample_architecture_options_start
|
|
:end-before: ot_cli_sample_architecture_options_end
|
|
|
|
.. _ot_coprocessor_sample_logging:
|
|
|
|
Logging extension
|
|
=================
|
|
|
|
By default, this sample uses :ref:`Spinel logging backend <ug_logging_backends_spinel>` 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 :kconfig:option:`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:
|
|
|
|
.. code-block:: none
|
|
|
|
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 :ref:`ug_thread_tools_ot_apps` for more information.
|
|
|
|
You can also use your own application, provided that it supports the Spinel communication protocol.
|
|
|
|
.. note::
|
|
|thread_hwfc_enabled|
|
|
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 :ref:`ot_cli_sample_diag_module` section of the :ref:`ot_cli_sample` sample documentation.
|
|
However, the Co-processor and CLI samples use different commands for the module, as described in the :ref:`ot_coprocessor_testing` 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 :ref:`ot_cli_sample_bootloader` section of the :ref:`ot_cli_sample` sample documentation.
|
|
However, the Co-processor and CLI samples use different commands, as described in the :ref:`ot_coprocessor_testing` section.
|
|
Additionally, the :ref:`ug_thread_tools_ot_apps` should be built with ``-DOT_PLATFORM_BOOTLOADER_MODE=ON`` option.
|
|
|
|
Configuration
|
|
*************
|
|
|
|
|config|
|
|
|
|
Check and configure the following library option that is used by the sample:
|
|
|
|
* :kconfig:option:`CONFIG_OPENTHREAD_COPROCESSOR_RCP` - Selects the RCP architecture for the sample.
|
|
|
|
|
|
.. include:: /includes/sample_fem_support.txt
|
|
|
|
Building and running
|
|
********************
|
|
|
|
.. |sample path| replace:: :file:`samples/openthread/coprocessor`
|
|
|
|
|enable_thread_before_testing|
|
|
|
|
.. include:: /includes/build_and_run.txt
|
|
|
|
.. _ot_coprocessor_testing:
|
|
|
|
HCI support
|
|
===========
|
|
|
|
The sample supports Bluetooth® Low Energy (LE) Controller functionality using HCI over UART.
|
|
To enable HCI support, complete the following steps:
|
|
|
|
.. tabs::
|
|
|
|
.. tab:: nRF54L15, nRF54L10, and nRF54L05 DKs
|
|
|
|
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:
|
|
|
|
.. parsed-literal::
|
|
:class: highlight
|
|
|
|
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
|
|
|
|
.. tab:: Other supported boards
|
|
|
|
For a list of supported boards, see the :ref:`ot_coprocessor_sample_requirements` section.
|
|
|
|
HCI communication is handled over a USB CDC ACM interface.
|
|
After connecting the board using the nRF USB port, two serial ports will be created.
|
|
Usually, the first port is used for HCI and the second for the Thread co-processor.
|
|
|
|
To enable HCI support, run the following command:
|
|
|
|
.. parsed-literal::
|
|
:class: highlight
|
|
|
|
west build -b *board_target* -p -- -DEXTRA_CONF_FILE=extra_conf/rcp_hci.conf -DEXTRA_DTC_OVERLAY_FILE=extra_conf/rcp_hci.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 :kconfig:option:`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:
|
|
|
|
.. parsed-literal::
|
|
:class: highlight
|
|
|
|
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.
|
|
#. Get the kit's serial port name (for example, :file:`/dev/ttyACM0`).
|
|
#. Run and configure ot-cli as described in :ref:`ug_thread_tools_ot_apps`.
|
|
#. From this point, you can follow the :ref:`ot_cli_sample_testing` instructions in the CLI sample by removing the `ot` prefix for each command.
|
|
If you are using HCI, follow the instructions for the :zephyr:code-sample:`bluetooth_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:
|
|
|
|
* :ref:`zephyr:kernel_api`:
|
|
|
|
* ``include/kernel.h``
|
|
|
|
* :ref:`zephyr:thread_protocol_interface`
|
|
|
|
* :ref:`zephyr:logging_api`:
|
|
|
|
* ``include/logging/log.h``
|
|
|
|
* :ref:`zephyr:bluetooth-hci`
|