OpenThread libraries

The nRF5 SDK for Thread includes a pre-built OpenThread stack. It is provided as binary libraries in different variants and configurations. These Thread libraries contain numerous features not required by the Thread specification. They are meant to showcase the potential of OpenThread on Nordic's platforms.

If you want to build your own project, you must include all of the mandatory libraries and can add some of the optional libraries. The nRF52840, nRF52833, and nRF52811 devices use different libraries. You can find them at the following path: <InstallFolder>/external/openthread/lib. Currently, libraries for GCC, IAR, and Keil 5 are provided.

Refer to the release notes for the ID of the OpenThread commit that has been used both for generating the pre-built Thread stack libraries and for testing and verification. You can also compile the latest version of the libraries from GitHub on your own. See Building the latest OpenThread libraries for details.

Refer to API for detailed API reference for the libraries.

OpenThread library variants

The OpenThread libraries for Nordic devices are related to both stack variant and configuration sets.

Stack variants

The stack variants are based on the Thread specification. The following stack variants are available:

• FTD - OpenThread’s Thread stack implementation of the Full Thread Device (FTD) library.
• MTD - OpenThread’s Thread stack implementation of the Minimal Thread Device (MTD) library.
• Radio - OpenThread’s Thread stack implementation of the radio-only (RCP) library.

See the following table for an overview of the variant support per device.

Supported stack variants per device

✔*: nRF52811 can act as MTD, but the following functionalities are not supported: BORDER_AGENT, COMMISSIONER, JOINER, SERVICE, UDP_FORWARD, ECDSA, SNTP_CLIENT, COAPS.

Configuration sets

OpenThread libararies can be built for specific configurations, which are based around a set of features and optional functionalities. The following predefined sets of features are included in this SDK:

• Master (full configuration)
• Optimized_FTD
• Optimized_MTD
• Default configuration for nRF52811

See the following table for an overview of supported features in libraries for each of these sets. No tick means no support, and the green tick is equal to =1 value.

Features supported by each configuration set

Mandatory libraries

Mandatory OpenThread libraries for nRF52840 and nRF52833 are different than the libraries for nRF52811.

nRF52840 and nRF52833 mandatory libraries

The following tables list mandatory libraries for nRF52840 and nRF52833. Replace nrf52xxx in the file name with either nRF52840 or nRF52833, based on the device you are using. Where multiple files are mentioned, choose only one, depending on your configuration.

nRF52840 and nRF52833 support the following Stack variants :

• FTD stack variant (nRF52840 and nRF52833)
• MTD stack variant (nRF52840 and nRF52833)
• Radio-only stack variant (nRF52840 and nRF52833)

FTD stack variant (nRF52840 and nRF52833)

The following table lists the FTD libraries for the Master (full configuration) and the Optimized_FTD configuration set.

nRF52840 and nRF52833 mandatory libraries for FTD stack variant

MTD stack variant (nRF52840 and nRF52833)

The following table lists the MTD libraries for the Master (full configuration) and the Optimized_MTD configuration set.

nRF52840 and nRF52833 mandatory libraries for MTD stack variant

Radio-only stack variant (nRF52840 and nRF52833)

The following table lists the RCP libraries for the Master (full configuration).

nRF52840 and nRF52833 mandatory libraries

nRF52811 mandatory libraries

The following tables list mandatory libraries for nRF52811. Where multiple files are mentioned, choose only one.

nRF52811 supports the following Stack variants in Default nRF52811 configuration:

• MTD stack variant (nRF52811)
• Radio-only stack variant (nRF52811)

MTD stack variant (nRF52811)

The following table lists the MTD libraries for nRF52811.

nRF52811 mandatory libraries

Radio-only stack variant (nRF52811)

The following table lists the RCP libraries for nRF52811.

nRF52811 mandatory libraries

Mandatory Mbed TLS library

Mbed TLS is a TLS/SSL library with support for operations used by OpenThread: ECC, SHA-256, and AES ECB. It implements basic cryptographic functions required by OpenThread.

The Mbed TLS library is mandatory for nRF52840, nRF52833, and nRF52811. It comes in the following variants:

• Mbed TLS library with CryptoCell 310 for nRF52840
• Mbed TLS library with software cryptography only for nRF52840, nRF52833, or nRF52811.

The Mbed TLS library for GCC and IAR on nRF52840 comes by default in the variant with the hardware acceleration of cryptographic operations on CryptoCell 310. Keil only provides software only version of the library, without the CryptoCell 310.

Mbed TLS library with CryptoCell 310 for nRF52840

CryptoCell hardware is present only in nRF52840.

The CryptoCell library is used by OpenThread to accelerate cryptographic operations (AES-EBC, ECJ-PAKE, and SHA256) in the Mbed TLS library.

This section lists only libraries required for the CryptoCell support. For more information about how to implement the CryptoCell support in your application, see ARM CryptoCell 310 module variant.

Depending on the compiler, use a different set of precompiled library files:

• GCC:
  • Path: <InstallFolder>/external/nrf_security/lib
  • Files:
    • libmbedcrypto_cc310_backend.a
    • libmbedcrypto_glue.a
    • libmbedcrypto_glue_cc310.a
    • libmbedcrypto_glue_vanilla.a
    • libmbedcrypto_vanilla_backend.a
    • libmbedtls_base_vanilla.a
    • libmbedtls_tls_vanilla.a
    • libmbedtls_x509_vanilla.a
    • libnrf_cc310_platform_0.9.2.a
• IAR:
  • Path: <InstallFolder>/external/nrf_security/lib
  • Files:
    • libmbedcrypto_cc310_backend_short_wchar.a
    • libmbedcrypto_glue_short_wchar.a
    • libmbedcrypto_glue_cc310_short_wchar.a
    • libmbedcrypto_glue_vanilla_short_wchar.a
    • libmbedcrypto_vanilla_backend_short_wchar.a
    • libmbedtls_base_vanilla_short_wchar.a
    • libmbedtls_tls_vanilla_short_wchar.a
    • libmbedtls_x509_vanilla_short_wchar.a
    • libnrf_cc310_platform_0.9.2_short_wchar.a

Make sure to use the correct configuration files and include the required directories for the correct operation of the cryptographic library:

• Defines:
  • MBEDTLS_CONFIG_FILE set to nrf-config.h
  • MBEDTLS_USER_CONFIG_FILE set to nrf52840-mbedtls-config.h
• Directories to include:
  • <InstallFolder>/external/nrf_security/include/mbedtls

Mbed TLS library with software cryptography only

This section lists only library files for software cryptography. For information about how to implement this variant in your application, see Software-only variant.

Depending on your device and compiler, use different precompiled libraries from <InstallFolder>/external/openthread/lib:

• nRF52840:
  • GCC: nrf52833/gcc/libmbedcrypto.a
  • IAR: nrf52833/iar/libmbedcrypto.a
  • Keil: nrf52840/keil/libmbedcrypto.lib
• nRF52833:
  • GCC: nrf52833/gcc/libmbedcrypto.a
  • IAR: nrf52833/iar/libmbedcrypto.a
  • Keil: nrf52833/keil/libmbedcrypto.lib
• nRF52811:
  • GCC: nrf52811/gcc/libmbedcrypto.a
  • IAR: nrf52811/iar/libmbedcrypto.a
  • Keil: nrf52811/keil/libmbedcrypto.lib

Make sure to use the correct configuration files and include the required directories for the correct operation of the cryptographic library (replace the nrf528xx in the file name with the name of the device that you are using):

• Define:
  • MBEDTLS_CONFIG_FILE set to mbedtls-config.h
  • MBEDTLS_USER_CONFIG_FILE set to nrf528xx-mbedtls-config.h
• Directories to include:
  • <InstallFolder>/external/openthread/mbedtls/mbedtls/repo/include
  • <InstallFolder>/external/nrf_security/include/software-only-threading

Optional libraries

There are two available sets of OpenThread optional libraries, which are different for nRF52840 and nRF52833 compared with the libraries for nRF52811:

• CLI
  • CLI optional libraries for nRF52840 and nRF52833
  • CLI optional libraries for nRF52811
• NCP
  • NCP optional libraries for nRF52840 and nRF52833
  • NCP optional libraries for nRF52811

You can include the chosen set in your application.

CLI optional libraries for nRF52840 and nRF52833

The optional CLI OpenThread libraries (for nRF52840 and nRF52833) are available for both FTD and MTD stack variants in Master (full configuration), Optimized_MTD, and Optimized_FTD configuration. See the following tables for more information.

CLI optional libraries for FTD stack variant

The following table lists the FTD libraries for the Master (full configuration) and the Optimized_FTD configuration set.

nRF52840 and nRF52833 optional CLI libraries for FTD stack variant

CLI optional libraries for MTD stack variant

The following table lists the MTD libraries for the Master (full configuration) and the Optimized_MTD configuration set.

nRF52840 and nRF52833 optional CLI libraries for MTD stack variant

CLI optional libraries for nRF52811

The optional CLI OpenThread libraries (for nRF52811) are available for MTD stack variant in default configuration. See the following tables for more information.

nRF52811 optional CLI libraries

NCP optional libraries for nRF52840 and nRF52833

The optional NCP OpenThread libraries (for nRF52840 and nRF52833) are available for FTD, MTD and Radio-only (RCP) stack variants in Master (full configuration). The Network-Co-Processor Library (NCP) that should be used depends on the desired transport. See the following tables for more information.

NCP optional libraries for FTD stack variant

The following table lists the FTD libraries for the Master (full configuration).

nRF52840 and nRF52833 optional NCP libraries for FTD stack variant

NCP optional libraries for MTD stack variant

The following table lists the MTD libraries for the Master (full configuration).

nRF52840 and nRF52833 optional NCP libraries for MTD stack variant

NCP optional libraries for Radio-only (RCP) stack variant

The following table lists the RCP libraries for the Master (full configuration).

nRF52840 and nRF52833 optional NCP libraries for Radio-only (RCP) stack variant

NCP optional libraries for nRF52811

The optional NCP OpenThread libraries for nRF52811 are available for the Radio-only (RCP) stack variant in the default configuration. The Network Co-Processor (NCP) library to be used depends on the desired transport. See the following tables for more information.

nRF52811 optional NCP libraries

Transport libraries

UART, USB CDC, and SPI transport must be defined for CLI and NCP optional library scenarios. The table below shows which transports are supported per device.

Supported transports per device

This SDK provides precompiled libraries with transport definitions for UART, USB CDC, and SPI. Include the chosen library based on the desired transport:

• libopenthread-nrf52xxx-transport.a - definitions for UART transport.
• libopenthread-nrf52xxx-transport-usb.a - definitions for USB CDC transport.
• libopenthread-nrf52xxx-transport-spi.a - definitions for SPI transport.
• libopenthread-nrf52xxx-transport-none.a - use this library only when you want to include empty definitions of transport functions.

IEEE EUI-64 address

When the Thread device is configured to obtain the Thread Network security credentials with either Thread Commissioning or an out-of-band method, the extended MAC address should be constructed out of the globally unique IEEE EUI-64. This must be done before Building the latest OpenThread libraries.

The IEEE EUI-64 address consists of two parts:

• 24 bits of MA-L (MAC Address Block Large), formerly called OUI (Organizationally Unique Identifier)
• 40-bit device unique identifier

By default, the device uses Nordic Semiconductor's MA-L (f4-ce-36). You can modify it by overwriting the OPENTHREAD_CONFIG_STACK_VENDOR_OUI define in openthread-core-nrf52840-config.h or openthread-core-nrf52811-config.h. This value must be publicly registered by the IEEE Registration Authority.

You can also provide the full IEEE EUI-64 address by providing a custom otPlatRadioGetIeeeEui64 function. To do this, define the flag OPENTHREAD_CONFIG_ENABLE_PLATFORM_EUI64_CUSTOM_SOURCE.

After the Thread Network security credentials have been successfully obtained, the device uses randomly generated extended MAC address.