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

To use the Thread protocol in the nRF Connect SDK, set the following Kconfig options:

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.

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:

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.

Note

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

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, or the Thread 1.3 Specification. You can change the stack version by using the following Kconfig options:

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

For a list of all supported features in the nRF Connect SDK, see the Feature sets. For more information about Thread 1.2 features, see the Thread 1.2 Base Features document.

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:

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 CONFIG_IEEE802154_VENDOR_OUI_ENABLE to replace Nordic Semiconductor’s company ID with your own company ID. Specify your company ID in CONFIG_IEEE802154_VENDOR_OUI.

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_ENABLE and set CONFIG_IEEE802154_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 an nRF52840 device:

  1. Enable CONFIG_IEEE802154_NRF5_UICR_EUI64_ENABLE.

  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 (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):

     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
8877665544332211
Done

Cryptography options

By default, the OpenThread stack uses the nRF Security (nrf_security) for cryptographic operations. The module provides hardware-accelerated cryptographic functionality on selected Nordic Semiconductor SoCs as well as alternate software-based implementations of the Mbed TLS APIs To use Mbed TLS, modify the OPENTHREAD_MBEDTLS_CHOICE Kconfig option.

For more information about the configuration and usage of the nRF Security, see the Configuration page. For more information about the open source Mbed TLS implementation in the nRF Connect SDK, see the sdk-mbedtls repository.

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:

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:

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

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:

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:

Zephyr L2 logging options

If you want to get logging output related to Zephyr’s L2 layer, enable one of the following Kconfig options:

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:

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

To configure your Thread application on the nRF5340 DK to run with Trusted Firmware-M, use the nrf5340dk/nrf5340/cpuapp/ns board target and enable the following Kconfig options:

In the nRF Connect SDK, these options are enabled by default for the application core of the Thread samples that can be programmed with the nrf5340dk/nrf5340/cpuapp/ns board target.

For more Trusted Firmware-M documentation, see Running applications with Trusted Firmware-M and the official TF-M documentation.