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.
The OpenThread libraries for Nordic devices are related to both stack variant and configuration sets.
The stack variants are based on the Thread specification. The following stack variants are available:
See the following table for an overview of the variant support per device.
| Device | FTD | MTD | RCP |
|---|---|---|---|
| nRF52840 | | | |
| nRF52833 | | | |
| nRF52811 | | ✔* | |
✔*: nRF52811 can act as MTD, but the following functionalities are not supported: BORDER_AGENT, COMMISSIONER, JOINER, SERVICE, UDP_FORWARD, ECDSA, SNTP_CLIENT, COAPS.
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:
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.
| OpenThread feature | Master | Optimized_FTD | Optimized_MTD | Default nRF52811 configuration |
|---|---|---|---|---|
| BORDER_AGENT | | |||
| BORDER_ROUTER | | | ||
| COMMISSIONER | | |||
| JOINER | | | | |
| DNS_CLIENT | | | | |
| DHCP6_SERVER | | |||
| DHCP6_CLIENT | | | | |
| COAP | | | | |
| COAPS | | | | |
| DIAGNOSTIC | | | ||
| LINK_RAW | | | ||
| MAC_FILTER | | | | |
| MTD_NETDIAG | | | ||
| SERVICE | | | ||
| UDP_FORWARD | | | ||
| ECDSA | | | | |
| SNTP_CLIENT | | | | |
| CHILD_SUPERVISION | | | | |
| JAM_DETECTION | | | |
Mandatory OpenThread libraries for nRF52840 and nRF52833 are different than the libraries for nRF52811.
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 :
The following table lists the FTD libraries for the Master (full configuration) and the Optimized_FTD configuration set.
| Master (full configuration) | Optimized_FTD configuration set | Description |
|---|---|---|
libopenthread-ftd.a | libopenthread-ftd-optimized-ftd.a | OpenThread’s Thread stack implementation of the Full Thread Device (FTD). |
- libopenthread-nrf52xxx-sdk.a - libopenthread-nrf52xxx-softdevice-sdk.a | - libopenthread-nrf52xxx-sdk-nodiag.a - libopenthread-nrf52xxx-softdevice-sdk-nodiag.a | OpenThread’s platform implementation library for single PHY or multiprotocol operation. Multiprotocol support is indicated by softdevice in the name. |
libopenthread-platform-utils.a | libopenthread-platform-utils-optimized-ftd.a | OpenThread’s platform util that contains the flash manager library. |
- libnordicsemi-nrf52xxx-radio-driver.a - libnordicsemi-nrf52xxx-radio-driver-softdevice.a | - libnordicsemi-nrf52xxx-radio-driver.a - libnordicsemi-nrf52xxx-radio-driver-softdevice.a | OpenThread's IEEE802.15.4 radio driver library for single PHY or multiprotocol operation. Multiprotocol support is indicated by softdevice in the name. |
| Mandatory Mbed TLS library files | Mandatory Mbed TLS library files | See Mandatory Mbed TLS library for more information. |
The following table lists the MTD libraries for the Master (full configuration) and the Optimized_MTD configuration set.
| Master (full configuration) | Optimized_MTD configuration set | Description |
|---|---|---|
libopenthread-mtd.a | libopenthread-ftd-optimized-mtd.a | OpenThread’s Thread stack implementation of the Minimal Thread Device (MTD). |
- libopenthread-nrf52xxx-sdk.a - libopenthread-nrf52xxx-softdevice-sdk.a | - libopenthread-nrf52xxx-sdk-nodiag.a - libopenthread-nrf52xxx-softdevice-sdk-nodiag.a | OpenThread’s platform implementation library for single PHY or multiprotocol operation. Multiprotocol support is indicated by softdevice in the name. |
libopenthread-platform-utils.a | libopenthread-platform-utils-optimized-mtd.a | OpenThread’s platform util that contains the flash manager library. |
- libnordicsemi-nrf52xxx-radio-driver.a - libnordicsemi-nrf52xxx-radio-driver-softdevice.a | - libnordicsemi-nrf52xxx-radio-driver.a - libnordicsemi-nrf52xxx-radio-driver-softdevice.a | OpenThread's IEEE802.15.4 radio driver library for single PHY or multiprotocol operation. Multiprotocol support is indicated by softdevice in the name. |
| Mandatory Mbed TLS library files | Mandatory Mbed TLS library files | See Mandatory Mbed TLS library for more information. |
The following table lists the RCP libraries for the Master (full configuration).
| Master (full configuration) | Description |
|---|---|
libopenthread-radio.a | OpenThread’s Thread stack implementation of the radio-only (RCP) library. |
- libopenthread-nrf52xxx-sdk.a - libopenthread-nrf52xxx-softdevice-sdk.a | OpenThread’s platform implementation library for single PHY or multiprotocol operation. Multiprotocol support is indicated by softdevice in the name. |
libopenthread-platform-utils.a | OpenThread’s platform util that contains the flash manager library. |
- libnordicsemi-nrf52xxx-radio-driver.a - libnordicsemi-nrf52xxx-radio-driver-softdevice.a | OpenThread's IEEE802.15.4 radio driver library for single PHY or multiprotocol operation. Multiprotocol support is indicated by softdevice in the name. |
| Mandatory Mbed TLS library files | See Mandatory Mbed TLS library for more information. |
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:
The following table lists the MTD libraries for nRF52811.
| Name | Description |
|---|---|
libopenthread-mtd.a | OpenThread’s Thread stack implementation of the Minimal Thread Device (MTD) library. |
libopenthread-nrf52811-sdk.a | OpenThread’s platform implementation library. |
libopenthread-platform-utils.a | OpenThread’s platform util that contains the flash manager library. |
libnordicsemi-nrf52811-radio-driver.a | OpenThread's IEEE802.15.4 radio driver library for single PHY operation. |
| Mandatory Mbed TLS library files | See Mandatory Mbed TLS library for more information. |
The following table lists the RCP libraries for nRF52811.
| Name | Description |
|---|---|
libopenthread-radio.a | OpenThread’s Thread stack implementation of the radio-only (RCP) library. |
libopenthread-nrf52811-sdk.a | OpenThread’s platform implementation library. |
libopenthread-platform-utils.a | OpenThread’s platform util that contains the flash manager library. |
libnordicsemi-nrf52811-radio-driver.a | OpenThread's IEEE802.15.4 radio driver library for single PHY operation. |
| Mandatory Mbed TLS library files | See Mandatory Mbed TLS library for more information. |
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:
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.
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:
<InstallFolder>/external/nrf_security/liblibmbedcrypto_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 <InstallFolder>/external/nrf_security/liblibmbedcrypto_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:
MBEDTLS_CONFIG_FILE set to nrf-config.h MBEDTLS_USER_CONFIG_FILE set to nrf52840-mbedtls-config.h <InstallFolder>/external/nrf_security/include/mbedtlsThis 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:
nrf52833/gcc/libmbedcrypto.a nrf52833/iar/libmbedcrypto.a nrf52840/keil/libmbedcrypto.lib nrf52833/gcc/libmbedcrypto.a nrf52833/iar/libmbedcrypto.a nrf52833/keil/libmbedcrypto.lib nrf52811/gcc/libmbedcrypto.a nrf52811/iar/libmbedcrypto.a 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):
MBEDTLS_CONFIG_FILE set to mbedtls-config.h MBEDTLS_USER_CONFIG_FILE set to nrf528xx-mbedtls-config.h <InstallFolder>/external/openthread/mbedtls/mbedtls/repo/include<InstallFolder>/external/nrf_security/include/software-only-threadingThere are two available sets of OpenThread optional libraries, which are different for nRF52840 and nRF52833 compared with the libraries for nRF52811:
You can include the chosen set in your application.
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.
The following table lists the FTD libraries for the Master (full configuration) and the Optimized_FTD configuration set.
| Master (full configuration) | Optimized_FTD configuration | Description |
|---|---|---|
libopenthread-cli-ftd.a | libopenthread-cli-ftd-optimized-ftd.a | Command Line Interface (CLI). Requires UART or USB CDC transport library. |
| Transport library files | Transport library files | See Transport libraries for more information. |
The following table lists the MTD libraries for the Master (full configuration) and the Optimized_MTD configuration set.
| Master (full configuration) | Optimized_MTD configuration | Description |
|---|---|---|
libopenthread-cli-mtd.a | libopenthread-cli-mtd-optimized-mtd.a | Command Line Interface (CLI). Requires UART or USB CDC transport library. |
| Transport library files | Transport library files | See Transport libraries for more information. |
The optional CLI OpenThread libraries (for nRF52811) are available for MTD stack variant in default configuration. See the following tables for more information.
| MTD | Description |
|---|---|
libopenthread-cli-mtd.a | Command Line Interface (CLI). Requires UART or USB CDC transport library. |
| Transport library files | See Transport libraries for more information. |
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.
The following table lists the FTD libraries for the Master (full configuration).
| UART or USB CDC transport | SPI transport | Description |
|---|---|---|
libopenthread-ncp-ftd.a | libopenthread-ncp-ftd-spi.a | Network Co-Processor (NCP) library. |
libopenthread-hdlc.a | openthread-hdlc.a | HDLC-lite encoder and decoder. |
libopenthread-spinel-ncp.a | libopenthread-spinel-ncp.a | Host-controller protocol (Spinel) definitions. |
| Transport library files | Transport library files | See Transport libraries for more information. |
The following table lists the MTD libraries for the Master (full configuration).
| UART or USB CDC transport | SPI transport | Description |
|---|---|---|
libopenthread-ncp-mtd.a | libopenthread-ncp-mtd-spi.a | Network Co-Processor (NCP) library. |
libopenthread-hdlc.a | openthread-hdlc.a | HDLC-lite encoder and decoder. |
libopenthread-spinel-ncp.a | libopenthread-spinel-ncp.a | Host-controller protocol (Spinel) definitions. |
| Transport library files | Transport library files | See Transport libraries for more information. |
The following table lists the RCP libraries for the Master (full configuration).
| UART or USB CDC transport | SPI transport | Description |
|---|---|---|
libopenthread-rcp.a | libopenthread-rcp-spi.a | Network Co-Processor (NCP) library. |
libopenthread-hdlc.a | openthread-hdlc.a | HDLC-lite encoder and decoder. |
libopenthread-spinel-rcp.a | libopenthread-spinel-rcp.a | Host-controller protocol (Spinel) definitions. |
| Transport library files | Transport library files | See Transport libraries for more information. |
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.
| UART or USB CDC transport | SPI transport | Description |
|---|---|---|
libopenthread-rcp.a | libopenthread-rcp-spi.a | Network Co-Processor (NCP) library. |
libopenthread-hdlc.a | openthread-hdlc.a | HDLC-lite encoder and decoder. |
libopenthread-spinel-rcp.a | libopenthread-spinel-rcp.a | Host-controller protocol (Spinel) definitions. |
| Transport library files | Transport library files | See Transport libraries for more information. |
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.
| Device | UART | USB | SPI |
|---|---|---|---|
| nRF52840 | | | |
| nRF52833 | | | |
| nRF52811 | | | |
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.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:
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.