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 and building for instructions on how to update the configuration for your application, permanently or temporarily.

Required configuration

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.

Enable Zephyr modules

Thread requires the following Zephyr modules to properly operate in the 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 subsystem is required to allow Thread to store settings in the non-volatile memory.

Enable OpenThread in the nRF Connect SDK

You can enable the Thread protocol in the nRF Connect SDK by using the Zephyr networking layer or by passing Thread frames directly to the nRF 802.15.4 radio driver.

• To use the Thread protocol with Zephyr networking layer, enable the following Kconfig options:

  • CONFIG_NETWORKING - This option enables a generic link layer and the IP networking support.

  • CONFIG_NET_L2_OPENTHREAD - This option enables the OpenThread stack required for operating the Thread protocol effectively.

• To use the Thread protocol and nRF 802.15.4 radio directly, disable the previous Kconfig options and enable the CONFIG_OPENTHREAD option. This enables the OpenThread stack, allowing for direct use of the nRF 802.15.4 radio.

To learn more about available architectures, see the OpenThread stack architecture user guide.

Additionally, you can set the CONFIG_MPSL Kconfig option. It enables the Multiprotocol Service Layer (MPSL) implementation, which provides services for both single-protocol and multi-protocol implementations. This is automatically set for all nRF Connect SDK samples that use the IEEE 802.15.4 radio driver.

Select OpenThread libraries

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.

  You must select one of the Feature sets by enabling CONFIG_OPENTHREAD_NORDIC_LIBRARY_MASTER, CONFIG_OPENTHREAD_NORDIC_LIBRARY_FTD, CONFIG_OPENTHREAD_NORDIC_LIBRARY_MTD, or CONFIG_OPENTHREAD_NORDIC_LIBRARY_RCP.

  This disables building OpenThread from source files and links pre-built libraries instead.

Additional configuration options

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 an API similar to BSD Sockets on top of the native Zephyr networking API. This configuration is needed for managing networking protocols. This configuration is available only if Zephyr networking layer is enabled.

• 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.

• CONFIG_OPENTHREAD_CHANNEL - By default set to 11. You can set any value ranging from 11 to 26.

• CONFIG_OPENTHREAD_PANID - By default set to 43981. You can set any value ranging from 0 to 65535.

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.

• nrf/modules/openthread/Kconfig.features.nrf - Thread network configuration dedicated to nRF Connect purposes.

Note

You can find the default configuration for all Thread samples in the nrf/subsys/net/openthread/Kconfig.defconfig file.

Message pool configuration

OpenThread uses a message pool to manage memory for message buffers. Memory for the message pool can be statically allocated by the OpenThread stack or managed by the platform. You can use the CONFIG_OPENTHREAD_PLATFORM_MESSAGE_MANAGEMENT Kconfig option to enable platform message management.

Message buffer size and number of message buffers in the pool can be configured with the CONFIG_OPENTHREAD_MESSAGE_BUFFER_SIZE and CONFIG_OPENTHREAD_NUM_MESSAGE_BUFFERS Kconfig options, respectively. By default, the message buffer size is set to 128, and the number of message buffers is set to 96 for a Full Thread Device and 64 for a Minimal Thread Device.

Note

When using Pre-built libraries, changing the CONFIG_OPENTHREAD_PLATFORM_MESSAGE_MANAGEMENT Kconfig option will have no effect. Additionally, the CONFIG_OPENTHREAD_MESSAGE_BUFFER_SIZE Kconfig option has to be set to the same value that is used in the pre-built library.

Thread Specification options

The OpenThread stack can be configured to operate in compliance with either the Thread 1.1 Specification, the Thread 1.2 Specification, the Thread 1.3 Specification, or the Thread 1.4 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.

• CONFIG_OPENTHREAD_THREAD_VERSION_1_4 - Selects the Thread stack version that is compliant with the Thread 1.4 Specification. This option is enabled by default if no other option is selected.

By selecting 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 Thread 1.3 features in addition to the Thread 1.2 features:

• Service Registration Protocol (SRP) client

By selecting support for Thread 1.4, you enable the following Thread 1.4 features in addition to the Thread 1.3 features and Thread 1.2 features:

• Enhanced Internet Connectivity

• Enhanced Network Diagnostics

For a list of all supported features in the nRF Connect SDK, see the Feature sets.

IEEE 802.15.4 EUI-64 configuration options

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 depending on chosen architecture:

Zephyr networking layer enabledZephyr networking layer disabled

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

You can enable the CONFIG_IEEE802154_VENDOR_OUI_ENABLE Kconfig option to replace Nordic Semiconductor’s company ID with your own company ID. Specify your company ID with the CONFIG_IEEE802154_VENDOR_OUI option.

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). nRF52 Series devices use the CUSTOMER registers block, while nRF53 Series devices use the OTP registers block

To use the EUI-64 value from the UICR, enable the CONFIG_NRF5_UICR_EUI64_ENABLE Kconfig option and set CONFIG_NRF5_UICR_EUI64_REG to 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 the nRF52840 device:

1. Enable the CONFIG_IEEE802154_NRF5_UICR_EUI64_ENABLE Kconfig option.

2. Specify the offset for the UICR registers in CONFIG_IEEE802154_NRF5_UICR_EUI64_REG. This example uses UICR->CUSTOMER[0] and UICR->CUSTOMER[1], which means that you can keep the default value 0.

3. Build and program your application erasing the whole memory. Make sure to replace serial_number with the serial number of your debugger:

    west build -b nrf52840dk/nrf52840 -p always
    west flash --snr serial_number --erase

4. Program the registers UICR->CUSTOMER[0] and UICR->CUSTOMER[1] with your EUI-64 value (replace serial_number with the serial number of your debugger):

    nrfutil device x-write --serial-number serial_number --address 0x10001080 --value 0x11223344
    nrfutil device x-write --serial-number serial_number --address 0x10001084 --value 0x55667788
    nrfutil device reset --reset-kind=RESET_PIN

   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 the OpenThread CLI as follows:

   uart:~$ ot eui64
   8877665544332211
   Done
   

Cryptographic support

By default, the OpenThread stack uses the PSA Crypto API for cryptographic operations. The support is implemented through the nRF Security library, which provides hardware-accelerated cryptographic functionality on selected Nordic Semiconductor SoCs. For more information, see the Configuring PSA Crypto API page.

Mbed TLS support

By default, the OpenThread stack uses the Mbed TLS library for X.509 certificate manipulation and the SSL protocols. The cryptographic support is handled through PSA Crypto API, as mentioned in Cryptographic support.

The Mbed TLS protocol features can be handled using the OPENTHREAD_MBEDTLS_CHOICE Kconfig option.

Note

The OPENTHREAD_MBEDTLS_CHOICE Kconfig option has not been tested and is not recommended for use with the nRF Connect SDK.

For more information about the open source Mbed TLS implementation in the nRF Connect SDK, see the sdk-mbedtls repository. For more information about the OpenThread security in nRF Connect SDK, see the OpenThread security page.

Thread commissioning options

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:

• CONFIG_OPENTHREAD_COMMISSIONER to y.

To enable the Thread network Joiner role on a device, set the following Kconfig option to the provided value:

• CONFIG_OPENTHREAD_JOINER to y.

  When you set the CONFIG_OPENTHREAD_JOINER Kconfig option, the CONFIG_SHELL_STACK_SIZE Kconfig option is automatically increased to 3168, meaning the shell stack size is set to 3 KB.

You can also configure how the commissioning process is to be started. The following options are available:

• Provisioning starts automatically after the Joiner powers up. To configure this option, configure the CONFIG_OPENTHREAD_JOINER_AUTOSTART option for the Joiner device.

• Provisioning is started when the application makes a call to the OpenThread API.

• Provisioning is started by using Command Line Interface commands.

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. Use the logging snippet to enable both options for the Thread samples in the nRF Connect SDK.

After setting these options, you can choose one of several logging backends available in Zephyr and supported in the nRF Connect SDK. The logging snippet enables RTT as the logging backend by default.

Note

If you are working with Thread samples, enabling logging and logging backend is optional.

Logging levels

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.

Zephyr L2 logging options

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.

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:

• 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 CONFIG_OPENTHREAD_L2_LOG_LEVEL_OFF option.

Device type options

You can configure OpenThread devices to run as a specific device type.

Full Thread Device (FTD)

Set CONFIG_OPENTHREAD_FTD to configure the device as FTD. This is the default configuration.

Minimal Thread Device (MTD)

Set CONFIG_OPENTHREAD_MTD to 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 CONFIG_OPENTHREAD_MTD_SED.

Trusted Firmware-M support options

Thread currently supports Trusted Firmware-M (TF-M) on the nRF54L15 DK.

To configure your Thread application to run with Trusted Firmware-M, use the nrf54l15dk/nrf54l15/cpuapp/ns board target and follow the instructions in Building and configuring TF-M.