Configuring Thread in the nRF Connect SDK
This page describes the configuration you need to start working with Thread in the nRF Connect SDK.
The page also lists additional options you can use to configure your Thread application. See Configuring your application for instructions on how to update the configuration for your application, permanently or temporarily.
Thread requires the following configuration when working in the nRF Connect SDK. All Thread samples in the nRF Connect SDK have these set by default.
Thread requires the following Zephyr modules to properly operate in the nRF Connect SDK:
To use the Thread protocol in the 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 it.
CONFIG_MPSL- This option enables the Multiprotocol Service Layer (MPSL) implementation, which provides services for both single-protocol and multi-protocol implementations. This is automatically set for all samples in the nRF Connect SDK that use the IEEE 802.15.4 radio driver.
After enabling OpenThread in the nRF Connect SDK, you must choose which OpenThread libraries to use. You can choose to either build the libraries from source or use pre-built variants of the libraries.
Building the OpenThread libraries from source gives you full flexibility in configuration. Using pre-built variants can be useful for certification purposes.
CONFIG_OPENTHREAD_SOURCES- This option enables building the OpenThread libraries from source. This option is selected by default.
Building from source allows you to define Additional configuration options one by one. By default, the Feature sets option is set to custom (
CONFIG_OPENTHREAD_USER_CUSTOM_LIBRARY), which allows you to create your own OpenThread stack configuration. However, you can select other feature sets as a basis.
When building the OpenThread libraries from source, you can also update the pre-built OpenThread libraries.
CONFIG_OPENTHREAD_LIBRARY- This option enables OpenThread to use pre-built libraries.
This disables building OpenThread from source files and links pre-built libraries instead.
In addition to the required configuration, you can configure other features such as which Thread Specification to use and whether to enable hardware-accelerated cryptography.
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_OPENTHREAD_COAP- This option enables OpenThread’s native CoAP API.
CONFIG_OPENTHREAD_CHANNEL- By default set to
11. You can set any value ranging from
CONFIG_OPENTHREAD_PANID- By default set to
43981. You can set any value ranging from
See the following files for more options that you might want to change:
zephyr/subsys/net/l2/openthread/Kconfig.features- OpenThread stack features.
zephyr/subsys/net/l2/openthread/Kconfig.thread- Thread network configuration options.
You can find the default configuration for all Thread samples in the
The OpenThread stack can be configured to operate in compliance with either the Thread 1.1 Specification, the Thread 1.2 Specification, or the Thread 1.3 Specification. 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 the Thread 1.1 Specification.
CONFIG_OPENTHREAD_THREAD_VERSION_1_2- Selects the Thread stack version that is compliant with the Thread 1.2 Specification.
CONFIG_OPENTHREAD_THREAD_VERSION_1_3- Selects the Thread stack version that is compliant with the Thread 1.3 Specification. This option is enabled by default if no other option is selected.
By enabling support for Thread 1.2, you enable the following Thread 1.2 features in addition to the Thread 1.1 features:
Coordinated Sampled Listening (CSL)
Link Metrics Probing
Multicast across Thread networks
Thread Domain unicast addressing
Enhanced Frame Pending
Enhanced Keep Alive
By selecting support for Thread 1.3, you enable the following features in addition to the Thread 1.2 features:
Service Registration Protocol (SRP) client
An IEEE EUI-64 address consists of two parts:
Company ID - a 24-bit MA-L (MAC Address Block Large), formerly called OUI (Organizationally Unique Identifier)
Extension identifier - a 40-bit device unique identifier
You can configure the EUI-64 for a device in the following ways:
- Use the default
By default, the company ID is set to Nordic Semiconductor’s MA-L (
f4-ce-36). The extension identifier is set to the DEVICEID from the factory information configuration registers (FICR).
- Replace the company ID
The extension identifier is set to the default, namely the DEVICEID from FICR.
- Replace the full EUI-64
You can provide the full EUI-64 value by programming certain user information configuration registers (UICR). For nRF52 Series devices, the CUSTOMER registers block is used. For nRF53 Series devices, the OTP registers block is used.
To use the EUI-64 value from the UICR, enable
CONFIG_IEEE802154_NRF5_UICR_EUI64_REGto the base of the two consecutive registers that contain your EUI-64 value.
The following example shows how to replace the full EUI-64 on an nRF52840 device:
Specify the offset for the UICR registers in
CONFIG_IEEE802154_NRF5_UICR_EUI64_REG. This example uses UICR->CUSTOMER and UICR->CUSTOMER, which means that you can keep the default value
Build and program your application erasing the whole memory (replace serial_number with the serial number of your debugger):
west build -b nrf52840dk_nrf52840 -p always west flash --snr serial_number --erase
Program the registers UICR->CUSTOMER and UICR->CUSTOMER with your EUI-64 value (replace serial_number with the serial number of your debugger):
nrfjprog --snr serial_number --memwr 0x10001080 --val 0x11223344 nrfjprog --snr serial_number --memwr 0x10001084 --val 0x55667788 nrfjprog --snr serial_number --reset
If you used a different value for
CONFIG_IEEE802154_NRF5_UICR_EUI64_REG, you must use different register addresses.
At the end of the configuration process, you can check the EUI-64 value using OpenThread CLI:
uart:~$ ot eui64
You can enable hardware-accelerated cryptography by using the Nordic Security Module (nrf_security). To do this, modify the setting of the following Kconfig option:
CONFIG_OPENTHREAD_MBEDTLS- Disable this option to disable the default Mbed TLS configuration for OpenThread. The nrf_security module is enabled by default when Mbed TLS for OpenThread is disabled.
For more configuration options, read the module documentation.
Thread commissioning is the process of adding new Thread devices to the network. See OpenThread commissioning for more information.
Configuring this process is optional, because the Thread samples in the 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:
You can also configure how the commissioning process is to be started. The following options are available:
Start automatically after the Joiner powers up. To configure this option, configure the
CONFIG_OPENTHREAD_JOINER_AUTOSTARToption for the Joiner device.
Start from the application.
Trigger 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:
For more details about the commissioning process, see Thread Commissioning on OpenThread portal.
You can enable the OpenThread stack logging for your project with the following options:
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 the nRF Connect SDK.
If you are working with Thread samples, enabling logging and logging backend is optional.
Select 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 bigger logging buffer you need to have to see all messages. Use the following Kconfig option for this purpose:
CONFIG_LOG_BUFFER_SIZE- This option specifies the number of bytes dedicated to the logger internal buffer.
If you want to get logging output related to 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 enables writing the appropriate information in the L2 debug log.
CONFIG_OPENTHREAD_L2_DEBUG_DUMP_15_4- Enables dumping 802.15.4 frames in the debug log output.
CONFIG_OPENTHREAD_L2_DEBUG_DUMP_IPV6- Enables dumping IPv6 frames in the debug log output.
You can disable writing to log with the
You can configure OpenThread devices to run as a specific device type.
- Full Thread Device (FTD)
CONFIG_OPENTHREAD_FTDto configure the device as FTD. This is the default configuration.
- Minimal Thread Device (MTD)
CONFIG_OPENTHREAD_MTDto configure the device as MTD.
By default, the MTD operates as Minimal End Device (MED). To make it operate as Sleepy End Device (SED), set
To configure your Thread application on the nRF5340 DK to run with Trusted Firmware-M, use the
nrf5340dk_nrf5340_cpuapp_ns build target and enable the following Kconfig options: