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:

Selecting building options

After enabling OpenThread in nRF Connect SDK, you can either:

Additional configuration options

Depending on your configuration needs, you can also set the following options:

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:

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.

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

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:

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:

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:

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

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:

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:

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:

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.