nRF5 SDK for Thread and Zigbee v1.0.0
Getting Started with Thread

nRF5 SDK for Thread is intended for use with the nRF52840 Development Kit.

The SDK provides precompiled OpenThread libraries for GCC, IAR, and Keil 5. The GCC library was built on Linux with arm-none-eabi-gcc version 4.9.3 with the following parameters:

make -f examples/Makefile-nrf52840 BORDER_ROUTER=1 COAP=1 COMMISSIONER=1 DNS_CLIENT=1 JOINER=1 MAC_FILTER=1 MTD_NETDIAG=1 SERVICE=1 TMF_PROXY=1 USB=1

USB=1 parameter is optional and enables USB CDC support for serial communication.

The IAR libraries were built with IAR Workbench 7.80.4. The Keil 5 libraries were built with Keil µVision V5.18a.

Every Thread example can be built with various toolchains and IDEs. Currently, the following build methods are provided:

Hardware requirements

The following peripherals are owned by the OpenThread stack and cannot be used directly by an application:

Additionally, OpenThread exposes an API to configure the radio frontend module (FEM). In such case, the application must specify two GPIOTE channels.

OpenThread API can be used to access the hardware random number generator and temperature sensor.

If you want to use the logger module, you must utilize the RTT backend or a UART instance other than UART0.

Note
The above hardware resources are reserved for the OpenThread libraries delivered with this SDK. However, you can specify other instances of some peripherals such as Timers, PPIs, SWI, or UART and rebuild libraries. Refer to platform-config.h and nrf_802154_config.h to see the current configuration. You can also disable support for SPI by adding the DISABLE_SPI=1 parameter.

Environment setup

You must install a set of tools to complete the environment setup process.

Linux

Make

First, make sure that you have the make tool installed on your system. To do this, run the following command:

$ which make

If the command does not provide output, you must install the make tool. Refer to the documentation of your Linux distribution for information on how to download and install it.

GNU ARM Embedded Toolchain

To be able to compile projects for the nRF52840 Development Kit, you must install GNU ARM Embedded Toolchain in version 6.3.1. You can download this version from GNU ARM Embedded Toolchain. Make sure to install it in the /usr/local/gcc-arm-none-eabi-6-2017-q2-update folder.

If you already have another version of arm-none-eabi installed, you can modify the default path in the following file: <InstallFolder>/components/toolchain/gcc/Makefile.posix.

SEGGER J-Link

To enable communication between devices, you need the SEGGER J-Link utility. You can download the latest version from the J-Link Download page.

Note
Due to a known issue in Segger’s J-Link firmware, depending on your operating system and version, you might experience data corruption or drops if you use the serial port. You can avoid this issue by disabling the Mass Storage Device:
  1. On Linux or macOS (OS X), open JLinkExe from the terminal. On Microsoft Windows, open the J-Link Commander application.
  2. Run the following command:
    MSDDisable

nrfjprog

You need the nrfjprog tool to program the nRF52840 chips. The latest version of this tool can be found on the nRF52840 product website.

Windows

Make

The make tool, required to build GCC projects, is not natively available on Windows. However, the MinGW package can be used to install it:

  1. Download the MinGW installer. The 32-bit version is recommended.
  2. Run the downloaded binary and select a folder where the MinGW toolchain will be installed. The recommended path is C:\MinGW
  3. When the first part of the installation is finished, the MinGW Installation Manager opens.
    qsg_mingw_intall_manager.png
    MinGW Installation Manager

  4. From the package list, select mingw32-base and msys-base. Then, click Installation -> Apply changes to install the selected items.
  5. Go to the Environment Variables of your system and edit the PATH variable. Append the existing string with the following two paths, each preceded by a semicolon.
    • C:\MinGW\bin
    • C:\MinGW\msys\1.0\bin
      System reboot might be required for the new paths to work properly.
  6. After the installation process finishes, open the command prompt and verify that it succeeded. To do this, check that the Msys environment was set up correctly by running the following command:
    uname -–operating-system
    You should receive the following result:
    qsg_sysinfo.png
    System information
  7. Additionally, check that the make tool was installed correctly by typing make --version and pressing Enter. If there are no errors during installation, the following message is displayed:
    qsg_version_info.png
    Version information
    GNU ARM Embedded Toolchain

To be able to compile projects for the nRF52840 Development Kit, you must install GNU ARM Embedded Toolchain in version 6.3.1. You can download this version from GNU ARM Embedded Toolchain. It is recommended to install it in the default directory: C:\Program Files (x86)\GNU Tools ARM Embedded\6 2017-q2-update.

If you already have another version of arm-none-eabi installed, or have installed it in a different directory, you can modify the default path in the following file: <InstallFolder>\components\toolchain\gcc\Makefile.windows.

nRF5x Command Line Tools

To communicate with and program the nRF52840 Development Kit, you need the SEGGER J-Link and nrfjprog tools. Download and install the latest version of nRF5x Command Line Tools from the nRF52840 product website. This package includes the latest version of SEGGER J-Link and nrfjprog utilities.

After the installation is complete, add nrfjprog installation directory (for example C:\Program Files (x86)\Nordic Semiconductor\nrf5x\bin\) to your system PATH variable.

Note
In case you experience communication issues with the nRF52840 Development Kit, it is recommended to use the latest version of SEGGER J-Link. The installer can be found on the J-Link Download page.

Building examples

Building an example with GCC (6.3 2017-q2-update)

To build an example with GCC, perform the following steps:

  1. Open Windows command line or Linux terminal.
  2. Navigate to the selected example folder, and then to the armgcc project directory, for example: <InstallFolder>/examples/thread/cli/pca10056/blank/armgcc
  3. Run the make command in this folder. If the environment was set up correctly, the build process will start.
  4. The build process produces the HEX file inside the _build folder: <InstallFolder>/examples/thread/cli/pca10056/blank/armgcc/_build/nrf52840_xxaa.hex.
    Note
    If you experience difficulties when running the make command on Windows, make sure that you do not have any other make instances from other toolsets like Cygwin or GnuWin32 in your PATH variable.

Building an example with IAR (7.80.4)

To build an example with IAR, perform the following steps:

  1. Open IAR Embedded Workbench.
  2. Select File->Open->Workspace... and navigate to the selected example folder. Open the selected workspace, for example: <InstallFolder>/examples/thread/cli/thread_cli.eww
  3. Build the example with Project->Make.
  4. You can program the nRF52840 Development Kit directly from IAR Embedded Workspace (Project->Download And Debug), or use nrfjprog as described below.

Building an example with Keil 5 (5.18a)

To build an example with Keil µVision 5, perform the following steps:

  1. Open Keil µVision 5.
  2. Select File->Open, set file type to Project Files, and navigate to the selected example folder. Open the selected project, for example: <InstallFolder>/examples/thread/cli/uart/pca10056/blank/arm5_no_packs/thread_cli_uart_pca10056.uvprojx
  3. Build the example with Project->Build Target.
  4. You can program the nRF52840 Development Kit directly from Keil µVision (Flash->Download), or use nrfjprog as described below.

Building an example with SEGGER Embedded Studio (3.34a)

To build an example with SES, perform the following steps:

  1. Open SEGGER Embedded Studio.
  2. Select File->Open Solution and navigate to the selected example folder. Open the selected project, for example: <InstallFolder>/examples/thread/cli/uart/pca10056/blank/ses/thread_cli_uart_pca10056.emProject
  3. Build the example with Build->Build Solution.
  4. You can program the nRF52840 Development Kit directly from SEGGER Embedded Studio (Target->Download project name), or use nrfjprog as described below.

Running examples

To program the nRF52840 Development Kit, first connect it to your computer with a USB cable. When your board is detected, you can download the example as described below.

Running an example without the SoftDevice

Optionally, when using GCC, you can type the following commands:

nrfjprog -f NRF52 -e
make erase flash

Running an example with the SoftDevice

The SoftDevice is used by the multiprotocol examples.

Optionally, when using GCC, you can type the following commands:

nrfjprog -f NRF52 -e
make erase flash_softdevice flash

You can use RTT Viewer to view the log messages produced by the example.

Building the latest OpenThread libraries

Note
OpenThread is still in prerelease phase and its API changes frequently. Keep in mind that when the API changes, the examples might not compile with the latest OpenThread version right away without fixes.

It is recommended to use the provided, precompiled version of the OpenThread library. However, it is possible to compile the latest version from GitHub. You can build the OpenThread library in POSIX environment on Mac or Linux, or use the provided GCC, IAR, or Keil 5 projects to build the library on Windows.

Building the library with GCC on Linux or Mac (recommended)

Follow these steps to build the library:

  1. Make sure you have GNU Autotools installed on your system. Refer to the documentation of your distribution for information on how to download and install them.
  2. Download or clone the OpenThread stack repository.
  3. Navigate into the repository root folder.
  4. Run the following commands:
    $ ./bootstrap
    $ make –f examples/Makefile-nrf52840 COMMISSIONER=1 JOINER=1 COAP=1 DNS_CLIENT=1 MTD_NETDIAG=1 BORDER_ROUTER=1 MAC_FILTER=1 TMF_PROXY=1
    You can experiment with the build parameters, but make sure you include the parameters presented above. Otherwise, some examples might not compile or work properly. To create libraries suitable for performing Thread certification tests, run make with the following parameters:
    $ make –f examples/Makefile-nrf52840 COMMISSIONER=1 JOINER=1 COAP=1 DNS_CLIENT=1 MTD_NETDIAG=1 BORDER_ROUTER=1 MAC_FILTER=1 TMF_PROXY=1 DHCP6_SERVER=1 DHCP6_CLIENT=1 CERT_LOG=1
  5. If you are going to use USB CDC for serial communication, rebuild the libraries with USB CDC connectivity support:
    $ make –f examples/Makefile-nrf52840 COMMISSIONER=1 JOINER=1 COAP=1 DNS_CLIENT=1 MTD_NETDIAG=1 BORDER_ROUTER=1 MAC_FILTER=1 TMF_PROXY=1 USB=1
    Because the SDK provides libraries with both USB CDC and UART support, you must rename these USB-specific libraries before copying:
    • libopenthread-nrf52840-sdk.a to libopenthread-nrf52840-sdk-usb.a
    • libopenthread-nrf52840-softdevice-sdk.a to libopenthread-nrf52840-sdk-softdevice-usb.a
  6. Copy the libraries from <OpenThreadFolder>/output/lib to the SDK folder: /external/openthread/lib/gcc.
  7. Copy the <OpenThreadFolder>/include folder into the /external/openthread folder.
  8. Now you can recompile the examples with the latest libraries.

Building the library with GCC on Windows

  1. Download or clone the OpenThread stack repository to the <InstallFolder>/external/openthread/project/openthread folder.
  2. Run the build_gcc_libs.bat script to build all of the libraries.
  3. After the libraries are built, use the provided script (<InstallFolder>/external/openthread/project/import_gcc_libs.bat) to copy the compiled libraries to the output folder.
  4. Copy the /external/project/openthread/include folder into the /external/openthread folder.
  5. Now you can recompile the examples with the latest libraries.

Building the library with IAR

Follow these steps to build the library:

  1. Download or clone the OpenThread stack repository to the <InstallFolder>/external/openthread/project/openthread folder.
  2. Open the OpenThread workspace (<InstallFolder>/external/openthread/project/openthread_lib.eww) with IAR Embedded Workbench.
  3. In IAR Embedded Workbench, select all of the projects in the left panel, click right mouse button on any of them and select Make.
  4. After the libraries are built, use the provided script (<InstallFolder>/external/openthread/project/import_iar_libs.bat) to copy the compiled libraries to the output folder.
  5. Copy the /external/project/openthread/include folder into the /external/openthread folder.
  6. Now you can recompile the examples with the latest libraries.

Building the library with Keil 5

Follow these steps to build the library:

  1. Download or clone the OpenThread stack repository to the <InstallFolder>/external/openthread/project/openthread folder.
  2. You must build each of the libraries separately. Open the project of a specific OpenThread library (for example, <InstallFolder>/external/openthread/project/lib/openthread/ftd/arm5_no_packsc/openthread_lib_libopenthread_ftd.uvprojx) with Keil µVision 5.
  3. In Keil µVision 5, select Project->Build Target.
  4. After the libraries are built, use the provided script (<InstallFolder>/external/openthread/project/import_keil_libs.bat) to copy the compiled libraries to the output folder.
  5. Copy the /external/openthread/project/openthread/include folder into the /external/openthread folder.
  6. Now you can recompile the examples with the latest libraries.
Note
OpenThread projects for GCC, IAR, and Keil 5 in this SDK were based on a specific OpenThread commit. Refer to the release notes for the commit ID. Using a more recent commit might require some manual changes in the project to compile libraries without errors. Also, the library configuration must be done manually in case a user wants to build the libraries in other configuration than provided.

OpenThread application development

Note
OpenThread API is not thread-safe.

As an application developer, you must make sure that calls to the OpenThread API are not preempted by other calls to the OpenThread API.

In a bare-metal environment, this is achieved by executing all OpenThread procedures from the main function context. Do not call any OpenThread functions in ISRs or callbacks from ISR context. You can use the app_scheduler module to execute callbacks from the app_timer and the SoftDevice in the main context. Refer to the examples included in this SDK to see how the app_scheduler module should be used with OpenThread.

In an operating system environment, all calls to the OpenThread API must be performed from a single thread. Other threads may call OpenThread functions, but it should be guarded by mutex to make sure one call is not preempted by another one. For a reference, see BLE HRS and Thread CoAP Server with FreeRTOS Example.

More information

See the following topics for further introduction into Nordic Semiconductor's Thread implementation.

OpenThread libraries

Thread Border Router

Thread Sniffer based on nRF52840 with Wireshark

nRF Thread Topology Monitor

Multiprotocol support

OpenThread serialization


Documentation feedback | Developer Zone | Subscribe | Updated