nRF5 SDK for Thread and Zigbee v2.0.0
OpenThread libraries

Table of Contents

The nRF5 SDK for Thread contains the pre-built OpenThread stack in the form of binary libraries. 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 binaries can be found in the following folder: <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.

Refer to API for detailed API reference for the libraries.

Mandatory libraries

Optional libraries

FTD MTD Usage
libopenthread-cli-ftd.a libopenthread-cli-mtd.a Command Line Interface (CLI) library for UART or USB CDC transport.
libopenthread-ncp-ftd.a libopenthread-ncp-mtd.a Network Co-Processor (NCP) library for UART or USB CDC transport.
libopenthread-ncp-ftd-spi.a libopenthread-ncp-mtd-spi.a Network Co-Processor (NCP) library for SPI transport.
Optional FTD and MTD libraries

The following optional library is also available:

Limitations

The pre-built OpenThread libraries located in <InstallFolder>\external\openthread\lib do not support DHCPv6 Client/Server.

ARM CryptoCell support

This SDK provides a precompiled version of the hardware-accelerated mbed TLS libary (libmbedcrypto.a) that uses the ARM CryptoCell technology, which can be used with OpenThread. For more information, see CryptoCell library.

The CryptoCell library is used by OpenThread to accelerate cryptographic operations (AES-EBC, ECJ-PAKE, and SHA256) in mbed TLS library. The application can still use it when called from the same context as OpenThread (main context in bare-metal applications, or the same thread in RTOS apllications).

Note
The current version of the CryptoCell library is not thread-safe – do not use it from multiple threads or interrupt service routines.

You can also use a library without hardware acceleration (libmbedcrypto-software.a), but the commissioning procedure will take more time (see the following table). For the best performance, use the library utilizing ARM CryptoCell.

Version Commissioning
(with Network Discovery) 		DTLS Handshake
Without CryptoCell 37,76 s 32,88 s
With CryptoCell 6,31 s 1,51 s
Commissioning with and without hardware acceleration

USB pseudo reset

The USB variant of the nRF52840 platform library uses a feature called pseudo reset.

Pseudo reset causes the reinitialization of the OpenThread stack and certain peripherals. It is invoked instead of triggering a hardware reset when a reset from OpenThread stack is requested. The reason for such behavior is that when native USB CDC connectivity is used, performing a hardware reset would cause the device to reenumerate in the host system. As a result, this would impair the ongoing communication through CLI or Spinel. Any application that uses USB CDC for serial communication must use the pseudo reset feature instead of the hardware reset. Refer to Thread CLI Example or Thread NCP Example for an example implementation of this feature.

Certification

The OpenThread stack has been officially certified on nRF52840 as Thread Group Certified Component.

The included stack was internally tested using Thread V1.1 Test Harness 1.3.2 R48 and the complete Thread Test Bed.

The DUT device has been tested in the following combinations:

All 150 out of 150 tests passed.

The test Router_9_2_10 occasionally fails due to the incorrect test case definition in Thread V1.1 Test Harness 1.3.2 software. In step 7, the test case checks if unicast MLE Data Response sent to SED includes non-stable data. This problem is being processed by Thread Group: https://threadgroup.atlassian.net/browse/TSTBED-96. As a workaround, the incorrect step was removed as suggested.

Due to Thread Harness issue and non-compliant implementation of Golden Devices in the Thread Test Bed, several certification tests fail (https://threadgroup.atlassian.net/browse/TESTPLAN-380) with default topology config file. For seven test cases, 5.6.4, 5.6.6, 5.6.9, 7.1.3, 7.1.5, 9.2.6, 9.2.18, an OpenThread device is used as a SED Golden Device. The modified topology config is available in the release zip. Thread Certification Laboratories also use OpenThread devices as SED devices in those test cases. The modified topology configuration is available in the directory \external\openthread\thread_harness\config. This modification is acceptable by Thread Certification Laboratories until Thread Harness and Golden Device vendors fix the non-compliance issue.

Internal testing has been done on the CLI application and OpenThread libraries compiled with GCC and IAR. The libraries can be found in the following folders:

How to run certification tests on nRF52840 dev-kits
To certify a Thread product, all certification test cases must be run on the Thread Test Harness software.

A detailed description on how to assemble and configure Thread Test Bed and run Thread Test Harness can be found on Thread Group's Confluence wiki page.

  1. Copy the OpenThread THCI nRF52840.py file to C:\GRL\Thread1.1\Thread_Harness\THCI. The proper works with the Thread stack, and is included in nRF5 SDK for Thread and Zigbee in the directory <InstallFolder>\external\openthread\thread_harness\THCI.
  2. Copy the nRF52840.jpg file to the folder C:\GRL\Thread1.1\Web\images.
  3. Append the following section in the DEVICE_FIELDS section inside the C:\GRL\Thread1.1\Web\data\deviceInputFields.xml.
    <DEVICE name="nRF52840" thumbnail="nRF52840.jpg" description = "Nordic Semiconductor: nRF52840 (OpenThread)" THCI="nRF52840">
    <ITEM label="Serial Line"
    type="text"
    forParam="SerialPort"
    validation="COM"
    hint="eg: COM1">COM
    </ITEM>
    <ITEM label="Speed"
    type="text"
    forParam="SerialBaudRate"
    validation="baud-rate"
    hint="eg: 115200">115200
    </ITEM>
    </DEVICE>

Note for Thread Test Harness software
The procedure of running the Thread Test Harness software on Nordic Semiconductor's nRF52840 SoC (on the PCA10056 Development Kit) must be adjusted in the following way.

Thread Test Harness does not correctly identify the PCA10056 Development Kit out-of-the-box. Due to a collision of USB PID:VID with another vendor (this is valid only for Nordic Semiconductor development kits with J-Link virtual COM port), Nordic devices are not automatically added to the device list.

To add an nRF52840 device, drag the nRF52840 device and drop it on the configuration page. After that, the devices are configured and proper baud rate (115200) and COM port is set.

Useful links

Flash/RAM requirements

The following tables list flash memory and RAM requirements for the applications compiled with the chosen options using the GCC compiler with size optimization. RAM memory requirements can be adjusted, for example to support different number of children, buffers, or registered addresses. The default configuration for nRF52840 platform is defined in two files:

Note
The presented memory requirements do not include 16 KB of flash memory used for settings storage.

CLI application memory requirements

Minimal configuration

Role App Multiprotocol Crypto Flash [KB] (OpenThread stack + app) Persistent Data [KB] RAM [KB] (OpenThread stack + app) Flash [KB] (BLE stack) RAM [KB] (BLE stack) Total ROM [KB] Total RAM [KB]
Router cli yes CC310 202 16 41 152 6 370 47
End Device cli yes CC310 148 16 37 152 6 316 43
Router cli yes Software 203 16 35 152 6 371 41
End Device cli yes Software 150 16 31 152 6 318 37
Router cli no CC310 179 16 39 0 0 195 39
End Device cli no CC310 126 16 35 0 0 142 35
Router cli no Software 181 16 33 0 0 197 33
End Device cli no Software 127 16 29 0 0 143 29

No additional options are used in this configuration.

Full-featured configuration

Role App Multiprotocol Crypto Flash [KB] (OpenThread stack + app) Persistent Data [KB] RAM [KB] (OpenThread stack + app) Flash [KB] (BLE stack) RAM [KB] (BLE stack) Total ROM [KB] Total RAM [KB]
Router cli yes CC310 308 16 58 152 6 476 64
End Device cli yes CC310 250 16 54 152 6 418 60
Router cli yes Software 288 16 52 152 6 456 58
End Device cli yes Software 230 16 48 152 6 398 54
Router cli no CC310 285 16 56 0 0 301 56
End Device cli no CC310 227 16 52 0 0 243 52
Router cli no Software 265 16 50 0 0 281 50
End Device cli no Software 207 16 46 0 0 223 46

Additional options used in this configuration:

COMMISSIONER=1 JOINER=1 DHCP6_SERVER=1 DHCP6_CLIENT=1 CERT_LOG=1 DEFAULT_LOGGING=1 COAP=1 DNS_CLIENT=1 UDP_PROXY=1 BORDER_AGENT=1 BORDER_ROUTER=1 MAC_FILTER=1 MTD_NETDIAG=1

Auto-DUT certification mode

Role App Multiprotocol Crypto Flash [KB] (OpenThread stack + app) Persistent Data [KB] RAM [KB] (OpenThread stack + app) Flash [KB] (BLE stack) RAM [KB] (BLE stack) Total ROM [KB] Total RAM [KB]
Router cli yes CC310 302 16 57 152 6 470 63
End Device cli yes CC310 244 16 53 152 6 412 59
Router cli yes Software 282 16 51 152 6 450 57
End Device cli yes Software 224 16 47 152 6 392 53
Router cli no CC310 280 16 55 0 0 296 55
End Device cli no CC310 222 16 51 0 0 238 51
Router cli no Software 260 16 49 0 0 276 49
End Device cli no Software 202 16 45 0 0 218 45

Additional options used in this configuration:

COMMISSIONER=1 JOINER=1 COAP=1 DNS_CLIENT=1 MTD_NETDIAG=1 BORDER_ROUTER=1 DHCP6_SERVER=1 DHCP6_CLIENT=1 CERT_LOG=1

Typical device

Role App Multiprotocol Crypto Flash [KB] (OpenThread stack + app) Persistent Data [KB] RAM [KB] (OpenThread stack + app) Flash [KB] (BLE stack) RAM [KB] (BLE stack) Total ROM [KB] Total RAM [KB]
Router cli yes CC310 287 16 57 152 6 455 63
End Device cli yes CC310 233 16 53 152 6 401 59
Router cli yes Software 267 16 50 152 6 435 56
End Device cli yes Software 213 16 46 152 6 381 52
Router cli no CC310 264 16 55 0 0 280 55
End Device cli no CC310 211 16 51 0 0 227 51
Router cli no Software 244 16 49 0 0 260 49
End Device cli no Software 191 16 45 0 0 207 45

Additional options used in this configuration:

JOINER=1 DHCP_CLIENT=1 DNS_CLIENT=1 COAP=1

Typical Border Router

Role App Multiprotocol Crypto Flash [KB] (OpenThread stack + app) Persistent Data [KB] RAM [KB] (OpenThread stack + app) Flash [KB] (BLE stack) RAM [KB] (BLE stack) Total ROM [KB] Total RAM [KB]
Router cli yes CC310 293 16 57 152 6 461 63
End Device cli yes CC310 242 16 53 152 6 410 59
Router cli yes Software 273 16 51 152 6 441 57
End Device cli yes Software 222 16 47 152 6 390 53
Router cli no CC310 271 16 56 0 0 287 56
End Device cli no CC310 220 16 52 0 0 236 52
Router cli no Software 250 16 49 0 0 266 49
End Device cli no Software 200 16 46 0 0 216 46

Additional options used in this configuration:

JOINER=1 DHCP_SERVER=1 DHCP_CLIENT=1 COAP=1 DNS_CLIENT=1 BORDER_ROUTER=1 BORDER_AGENT=1 MTD_NETDIAG=1 UDP_PROXY=1
Documentation feedback | Developer Zone | Subscribe | Updated