Configuring Thread in nRF Connect SDK¶
This page describes what is needed to start working with Thread in nRF Connect SDK.
Required modules¶
Thread requires the following Zephyr’s modules to properly operate in nRF Connect SDK:
IEEE 802.15.4 radio driver - This library is automatically enabled when working with OpenThread on Nordic Semiconductor’s Development Kits.
Settings subsystem - This is required to allow Thread to store settings in the non-volatile memory.
Enabling OpenThread in nRF Connect SDK¶
To use the Thread protocol in nRF Connect SDK, set the following Kconfig options:
CONFIG_NETWORKING
- This option enables the generic link layer and the IP networking support.CONFIG_NET_L2_OPENTHREAD
- This option enables the OpenThread stack required for the correct operation of the Thread protocol and allows you to use them.CONFIG_MPSL
- - This options enables the Nordic Multi Protocol Service Layer (MPSL) implementation, which provides services for single-protocol and multi-protocol implementations.
Selecting building options¶
After enabling OpenThread in nRF Connect SDK, you can either:
- Configure OpenThread to build from source
This option allows you to define additional configuration options one by one. It is enabled by default and can be set with the
CONFIG_OPENTHREAD_SOURCES
Kconfig option. With this option selected, the feature set option is by default set to custom (CONFIG_OPENTHREAD_USER_CUSTOM_LIBRARY
), which allows you to create your own OpenThread stack configuration for compilation. Moreover, selecting this option allows you to update pre-built OpenThread libraries.
- Configure OpenThread to use pre-built libraries
This option disables building OpenThread from source files and links pre-built libraries instead, which for example can be useful for certification purposes. Set the
CONFIG_OPENTHREAD_LIBRARY_1_1
Kconfig option to start using pre-built Nordic library feature sets.
Additional configuration options¶
Depending on your configuration needs, you can also set the following options:
CONFIG_NET_SOCKETS
- This option enables API similar to BSD Sockets on top of the native Zephyr networking API. This configuration is needed for managing networking protocols.CONFIG_NET_SHELL
- This option enables Zephyr’s Network Shell. This configuration is needed for managing the network, based on Zephyr’s IP stack, from the command line.CONFIG_OPENTHREAD_SHELL
- This option enables OpenThread CLI (see OpenThread CLI Reference).CONFIG_COAP
- This option enables Zephyr’s CoAP support.CONFIG_COAP_UTILS
- This option enables the CoAP utils library.CONFIG_OPENTHREAD_COAP
- This option enables OpenThread’s native CoAP API.
You can also change the default values in menuconfig for the options listed in the following files:
subsys/net/l2/openthread/Kconfig.features
- OpenThread stack features.subsys/net/l2/openthread/Kconfig.thread
- Thread network configuration options.
This includes the following options:
CONFIG_OPENTHREAD_CHANNEL
- By default set to11
. You can set any value ranging from11
to26
.CONFIG_OPENTHREAD_PANID
- By default set to43981
. You can set any value ranging from0
to65535
.
- Default configuration reference
The default configuration for all Thread samples is defined in
nrf/samples/openthread/common/overlay-ot-defaults.conf
.
For other optional configuration options, see the following sections.
Hardware-accelerated cryptography¶
You can enable hardware-accelerated cryptography by using the Nordic Security Module. To do this, modify the setting of the following Kconfig option:
CONFIG_OPENTHREAD_MBEDTLS
- Disable this option to disable the default mbedTLS configuration for OpenThread. The nrf_security module is enabled by default when mbedTLS for OpenThread is disabled.
For more configuration options, read the module documentation.
Thread Specification v1.2 options¶
The OpenThread stack can be configured to operate in compliance with either Thread Specification v1.1 or Thread Specification v1.2. You can change the stack version by using the following Kconfig options:
CONFIG_OPENTHREAD_THREAD_VERSION_1_1
- Selects the Thread stack version that is compliant with Thread Specification v1.1. This option is enabled by default if no other option is selected.CONFIG_OPENTHREAD_THREAD_VERSION_1_2
- Selects the Thread stack version that is compliant with Thread Specification v1.2.
By selecting support for the v1.2, you enable the following features in addition to the v1.1 features:
Enhanced Frame Pending
Enhanced Keep Alive
Thread Domain Name
Moreover, the v1.2 also comes with the following features supported in experimental status:
CONFIG_OPENTHREAD_DUA
- Enable Domain Unicast Addresses.CONFIG_OPENTHREAD_MLR
- Enable Multicast Listener Registration.CONFIG_OPENTHREAD_BACKBONE_ROUTER
- Enable Backbone Router.
Note
To test Thread Specification v1.2 options, you can use the Thread CLI sample with the experimental v1.2 extension.
Thread commissioning¶
Thread commissioning is the process of adding new Thread devices to the network. It involves two devices: a Commissioner that is already in the Thread network and a Joiner that wants to become a member of the network.
Configuring this process is optional, because the Thread samples in nRF Connect SDK use hardcoded network information.
If you want to manually enable the Thread network Commissioner role on a device, set the following Kconfig option to the provided value:
To enable the Thread network Joiner role on a device, set the following Kconfig option to the provided value:
CONFIG_OPENTHREAD_JOINER
toy
.
You can also configure how the commissioning process is to be started:
Automatically after Joiner’s power up with the
CONFIG_OPENTHREAD_JOINER_AUTOSTART
option, configured for the Joiner device.Started from the application.
Triggered by Command Line Interface commands. In this case, the shell stack size must be increased to at least 3 KB by setting the following option:
CONFIG_SHELL_STACK_SIZE
to3072
.
For more details about the commissioning process, see Thread Commissioning on OpenThread portal.
OpenThread stack logging options¶
You can enable the OpenThread stack logging for your project with the following options:
CONFIG_LOG
- This option enables Zephyr’s Logging.CONFIG_OPENTHREAD_DEBUG
- This option enables logging for the OpenThread stack.
Both options must be enabled to allow logging.
After setting these options, you can choose one of several logging backends available in Zephyr and supported in nRF Connect SDK.
Note
If you are working with Thread samples, enabling logging and logging backend is optional.
By default, all Thread samples have logging enabled in the overlay-ot-defaults.conf
file, and are set to provide output at the informational level (CONFIG_OPENTHREAD_LOG_LEVEL_INFO
).
Logging levels¶
You can set one of the following logging levels to customize the logging output:
CONFIG_OPENTHREAD_LOG_LEVEL_CRIT
- This option enables critical error logging only.CONFIG_OPENTHREAD_LOG_LEVEL_WARN
- This option enables warning logging in addition to critical errors.CONFIG_OPENTHREAD_LOG_LEVEL_NOTE
- This option additionally enables notice logging.CONFIG_OPENTHREAD_LOG_LEVEL_INFO
- This option additionally enables informational logging.CONFIG_OPENTHREAD_LOG_LEVEL_DEBG
- This option additionally enables debug logging.
The more detailed logging level you select, the more logging buffers you need to be able to see all messages, and the buffer size also needs to be increased. Use the following Kconfig options for this purpose:
CONFIG_LOG_STRDUP_BUF_COUNT
- This option specifies the number of logging buffers.CONFIG_LOG_STRDUP_MAX_STRING
- This option specifies the size of logging buffers.
Zephyr L2 logging options¶
If you want to get logging output related to the Zephyr’s L2 layer, enable one of the following Kconfig options:
CONFIG_OPENTHREAD_L2_LOG_LEVEL_ERR
- Enables logging only for errors.CONFIG_OPENTHREAD_L2_LOG_LEVEL_WRN
- Enables logging for errors and warnings.CONFIG_OPENTHREAD_L2_LOG_LEVEL_INF
- Enables logging for informational messages, errors, and warnings.CONFIG_OPENTHREAD_L2_LOG_LEVEL_DBG
- Enables logging for debug messages, informational messages, errors, and warnings.
Choosing one of these options will enable writing the appropriate information in the L2 debug log.
Additionally, enabling CONFIG_OPENTHREAD_L2_LOG_LEVEL_DBG
allows you to set the CONFIG_OPENTHREAD_L2_DEBUG
option, which in turn has the following settings:
These options enable dumping 802.15.4 or IPv6 frames (or both) in the debug log output.
You can disable writing to log with the CONFIG_OPENTHREAD_L2_LOG_LEVEL_OFF
option.
Switching device type¶
An OpenThread device can be configured to run as one of the following device types, which serve different roles in the Thread network:
- Full Thread Device (FTD)
In this configuration, the device can be both Router and End Device. To enable this device type thread, set the following Kconfig option:
This is the default configuration if none is selected.
- Minimal Thread Device (MTD)
In this configuration, the device can only be an End Device. To enable this device type thread, set the following Kconfig option:
By default, when a Thread device is configured as MTD, it operates as Minimal End Device (MED). You can choose to make it operate as Sleepy End Device (SED) by enabling the
CONFIG_OPENTHREAD_MTD_SED
option.
For more information, see Device Types on OpenThread portal.
Nordic library feature sets¶
OpenThread pre-built libraries available in nrfxlib provide features and optional functionalities from the OpenThread stack.
These features and functionalities are available in nRF Connect SDK as Nordic library feature sets.
You can use these sets for building application with complete Thread specification support when you configure OpenThread to use pre-built libraries (with the CONFIG_OPENTHREAD_LIBRARY_1_1
Kconfig option).
The following feature sets are available for selection:
CONFIG_OPENTHREAD_NORDIC_LIBRARY_MASTER
- Enable the complete set of OpenThread features.CONFIG_OPENTHREAD_NORDIC_LIBRARY_FTD
- Enable optimized OpenThread features for FTD.CONFIG_OPENTHREAD_NORDIC_LIBRARY_MTD
- Enable optimized OpenThread features for MTD.CONFIG_OPENTHREAD_USER_CUSTOM_LIBRARY
- Enabled by default. Allows you to create a custom feature set for compilation when building using OpenThread sources. If you selectCONFIG_OPENTHREAD_LIBRARY_1_1
, choose a different feature set.Note
When building OpenThread from source, you can still select other feature sets, but the user configuration takes precedence over them.
Selecting these sets is not related to Switching device type.
The following table lists the supported features for each of these sets.
Note
No tick means missing support for the given feature in the related configuration, while the tick is equal to =1
value.
OpenThread feature |
Master |
Optimized_FTD |
Optimized_MTD |
Custom |
---|---|---|---|---|
BORDER_AGENT |
✔ |
|||
BORDER_ROUTER |
✔ |
|||
CHILD_SUPERVISION |
✔ |
✔ |
✔ |
|
COAP |
✔ |
✔ |
✔ |
|
COAPS |
✔ |
✔ |
✔ |
|
COMMISSIONER |
✔ |
|||
DIAGNOSTIC |
✔ |
|||
DNS_CLIENT |
✔ |
✔ |
✔ |
|
DHCP6_SERVER |
✔ |
|||
DHCP6_CLIENT |
✔ |
✔ |
✔ |
|
ECDSA |
✔ |
✔ |
✔ |
|
IP6_FRAGM |
✔ |
✔ |
✔ |
|
JAM_DETECTION |
✔ |
✔ |
✔ |
|
JOINER |
✔ |
✔ |
✔ |
|
LINK_RAW |
✔ |
|||
MAC_FILTER |
✔ |
✔ |
✔ |
|
MTD_NETDIAG |
✔ |
|||
SERVICE |
✔ |
✔ |
||
SLAAC |
✔ |
✔ |
✔ |
|
SNTP_CLIENT |
✔ |
✔ |
✔ |
|
UDP_FORWARD |
✔ |
✔ |
Updating pre-built OpenThread libraries¶
You can update nrfxlib’s OpenThread pre-built libraries when using any Thread sample if you configure the sample to build OpenThread stack from source with CONFIG_OPENTHREAD_SOURCES
.
Use this functionality for example for certification of your configuration of OpenThread libraries.
Note
The libraries destination directory can differ.
When you selected CONFIG_OPENTHREAD_USER_CUSTOM_LIBRARY
, the location depends the chosen nrf_security backend, either CONFIG_CC3XX_BACKEND
or CONFIG_OBERON_BACKEND
.
Updating libraries without debug symbols¶
You can install the release version of the latest nrfxlib libraries without the debug symbols.
This is handled with the CONFIG_OPENTHREAD_BUILD_OUTPUT_STRIPPED
Kconfig option.
This option is disabled by default.
Run the following command to update the nrfxlib libraries:
west build -b nrf52840dk_nrf52840 -t install_openthread_libraries -- -DOPENTHREAD_BUILD_OUTPUT_STRIPPED=y
This command builds two versions of the libraries, with and without debug symbols, and installs only the version without debug symbols.
This command also builds the sample on the specified board.
Make sure that the board you mention is compatible with the chosen sample.
The CONFIG_OPENTHREAD_BUILD_OUTPUT_STRIPPED
Kconfig option will be disabled again after this command completes.
Updating libraries to debug version¶
You can also install only the debug version of the current OpenThread libraries (from Zephyr). This can be useful when debugging, but will take a significant amount of memory of the PC storage - it should be taken into account if one intends to commit those libraries to the repository.
To update the nrfxlib libraries with debug symbols, run the following command:
west build -b nrf52840dk_nrf52840 -t install_openthread_libraries
UART recommendations for NCP¶
Use the following recommended default UART settings for configuration based on Network Co-Processor (NCP) architecture:
Bit rate: 1000000
Start bits: 1
Data bits: 8
Stop bits: 1
No parity
Flow Control: Hardware
Flow control¶
UART Hardware Flow Control is recommended in the Nordic solution. Using Software Flow Control is neither recommended nor implemented.
Hardware reset¶
Use the Arduino-style hardware reset, where the DTR signal is coupled to the RES pin through a 0.01[micro]F capacitor. This causes the NCP to automatically reset whenever the serial port is opened.
Note
This hardware reset method is not used in Nordic’s solution. It is recommended to dedicate one of your host pins to control the RES pin on the NCP, so that you can easily perform a hardware reset if necessary.
Recommended UART signals¶
The following UART signals are used in the Nordic solution:
RX
TX
CTS
RTS
DTS (optional, not used)
RES