Configuring Thread in nRF Connect SDK

This page describes what is needed to start working with Thread in nRF Connect SDK.

See Configuring your application for instructions on how to update the configuration for your application, permanently or temporarily.

Required modules

Thread requires the following Zephyr 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 subsystem 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:

Selecting OpenThread libraries

After enabling OpenThread in 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.

Configure OpenThread to build from source

Set CONFIG_OPENTHREAD_SOURCES to build the libraries from source. This option is selected by default.

This alternative 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.

Configure OpenThread to use pre-built libraries

Set CONFIG_OPENTHREAD_LIBRARY_1_1 to use pre-built libraries. Select one of the Feature sets by enabling CONFIG_OPENTHREAD_NORDIC_LIBRARY_MASTER, CONFIG_OPENTHREAD_NORDIC_LIBRARY_FTD, or CONFIG_OPENTHREAD_NORDIC_LIBRARY_MTD.

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

Additional configuration options

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/samples/openthread/common/overlay-ot-defaults.conf file.

For other optional configuration options, see the following sections.

IEEE 802.15.4 EUI-64 configuration

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

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 1.2 Specification options

The OpenThread stack can be configured to operate in compliance with either the Thread 1.1 Specification or the Thread 1.2 Specification. You can change the stack version by using the following Kconfig options:

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

  • Enhanced Frame Pending

  • Enhanced Keep Alive

  • Thread Domain Name

  • Coordinated Sampled Listening (CSL) Transmitter (for Full Thread Devices only)

Moreover, Thread 1.2 also comes with the following features that are supported for development, but not production:

Note

The Link Metrics and Coordinated Sampled Listening features are not supported for nRF53 Series devices yet. The Backbone Router feature enables the functionality for the Thread Network side, but not for the Backbone side.

To test Thread 1.2 options, you can use the Thread: CLI sample with the Experimental Thread 1.2 extension.

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 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_AUTOSTART option 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.

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.

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 configured to provide output at the informational level (CONFIG_OPENTHREAD_LOG_LEVEL_INFO).

Logging levels

Select one of the following logging levels to customize the logging output:

The more detailed logging level you select, the more logging buffers you need to be able to see all messages. The buffer size must also be increased. Use the following Kconfig options 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), enabling CONFIG_OPENTHREAD_MTD_SED.

Pre-built libraries

The nRF Connect SDK provides a set of OpenThread pre-built libraries. These pre-built libraries are available in nrfxlib and provide features and optional functionalities from the OpenThread stack. You can use these libraries for building applications with support for the complete Thread 1.1 Specification.

To use a pre-built library, configure OpenThread to use pre-built libraries by setting the CONFIG_OPENTHREAD_LIBRARY_1_1 Kconfig option and select one of the provided Feature sets.

Feature sets

A feature set defines a combination of OpenThread features for a specific use case. These feature sets are mainly used for pre-built libraries, but you can also use them for selecting several configuration options at once when you build your application using OpenThread sources.

The nRF Connect SDK provides the following feature sets:

The following table lists the supported features for each of these sets. No tick indicates that there is no support for the given feature in the related configuration, while the tick signifies that the feature is selected (=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

✔

✔

For the full list of configuration options that were used during compilation, including their default values, see the openthread_lib_configuration.txt file within each library folder in the nrfxlib repository.

Customizing pre-built libraries

Selecting a feature set allows you to use the respective OpenThread features in your application. You might need to customize some configuration options to fit your use case though.

Be aware of the following limitations when customizing the configuration of a pre-built library:

  • You can only update configuration options that are configurable at run time. If you change any options that are compiled into the library, your changes will be ignored.

  • Changes to the configuration might impact the certification status of the pre-built libraries. See Thread certification options for more information.

The following list shows some of the configuration options that you might want to customize:

Updating pre-built OpenThread libraries

You can update the OpenThread pre-built libraries in nrfxlib when using any Thread sample if you configure the sample to build the OpenThread stack from source with CONFIG_OPENTHREAD_SOURCES. Use this functionality for certification of your configuration of the OpenThread libraries, for example.

Note

The libraries destination directory can differ. When you selected CONFIG_OPENTHREAD_USER_CUSTOM_LIBRARY, the location depends on 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 µ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 Semiconductor’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.