Documentation library

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

The 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 UDP_PROXY=1 USB=1 BORDER_AGENT=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.

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

  • GCC Makefile (uses OpenThread libraries built with GCC)
  • IAR Embedded Workbench project (uses OpenThread libraries built with IAR)
  • Keil µVision 5 project (uses OpenThread libraries built with Keil 5)
  • SEGGER Embedded Studio project (uses OpenThread libraries built with GCC)

Hardware requirements

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

  • RADIO
  • RNG
  • SWI3 - EGU15
  • SWI3 - EGU0, EGU1, EGU2 (only used for dynamic multiprotocol)
  • PPI (channels 6-12)
  • RTC2
  • TIMER1
  • TEMP
  • UART0 (only when OpenThread CLI or OpenThread NCP modules are used)
  • USB (only if USB CDC is used for serial communication)
  • SPIS0 (only when OpenThread NCP in SPI variant is used)

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 (either on Linux or Windows).

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. Depending on your operating system:
    • 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, you can use the MinGW package 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. When the first part of the installation is finished, the MinGW Installation Manager opens.
    qsg_mingw_intall_manager.png
    MinGW Installation Manager

  3. From the package list, select mingw32-base and msys-base.
  4. 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 will 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.
  3. Open the selected workspace, for example: <InstallFolder>/examples/thread/cli/thread_cli.eww.
  4. Build the example with Project->Make.

You can program the nRF52840 Development Kit directly from IAR Embedded Workspace (Project->Download And Debug), or use nrfjprog as described in Running an example without the SoftDevice (for standard examples) or Running an example with the SoftDevice (for multiprotocol examples).

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.
  3. Open the selected project, for example: <InstallFolder>/examples/thread/cli/uart/pca10056/blank/arm5_no_packs/thread_cli_uart_pca10056.uvprojx.
  4. Build the example with Project->Build Target.

You can program the nRF52840 Development Kit directly from Keil µVision (Flash->Download), or use nrfjprog as described in Running an example without the SoftDevice (for standard examples) or Running an example with the SoftDevice (for multiprotocol examples).

Building an example with SEGGER Embedded Studio (3.40)

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.
  3. Open the selected project, for example: <InstallFolder>/examples/thread/cli/uart/pca10056/blank/ses/thread_cli_uart_pca10056.emProject.
  4. Build the example with Build->Build Solution.

You can program the nRF52840 Development Kit directly from SEGGER Embedded Studio (Target->Download project name), or use nrfjprog as described in Running an example without the SoftDevice (for standard examples) or Running an example with the SoftDevice (for multiprotocol examples).

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 with the appropriate nrfjprog command, depending on the example.

Running an example without the SoftDevice

  • To program the device, run:
    nrfjprog -f NRF52 --chiperase --program _build/nrf52840_xxaa.hex
  • To reset the device, run:
    nrfjprog -f NRF52 -r
  • To list available nrfjprog commands, run:
    nrfjprog --help

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.

  • To write SoftDevice to the device, run:
    nrfjprog -f NRF52 --chiperase --program <InstallFolder>\components\softdevice\s140\hex\s140_nrf52_6.1.0_softdevice.hex
  • To write an application to the device, run:
    nrfjprog -f NRF52 --sectorerase --program _build/nrf52840_xxaa.hex
  • To reset the device, run:
    nrfjprog -f NRF52 -r

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.

Running precompiled Thread examples

To quickly test an example without having to install the full toolchain, program a precompiled example application to your development board.

The zip version of the SDK provides precompiled hex files for most of the supplied examples. For examples that require a SoftDevice, the SoftDevice must be flashed separately.

Perform the following steps to program a precompiled example:

  1. Download the latest nRF5-SDK-for-Thread-and-Zigbee repository file in zip format from the SDK download page.
  2. Extract the zip file to the directory that you want to use to work with the SDK.
  3. Connect the J-Link USB of the board to your computer with a USB cable. The computer will recognize it as a standard USB drive.
  4. In the SDK directory, navigate to the example that you want to test and open the hex subdirectory. For example, for the Thread CLI Example, navigate to examples\thread\cli\uart\hex.
  5. Select the hex file that corresponds to your development board and copy it to the board J-Link USB drive.

To test the example, follow the testing instructions in the Thread examples documentation. Depending on the example that you programmed, it might be sufficient to observe the LEDs on the board. Other examples require you to connect to the board through native USB, SPI, or a phone app.

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

  • build the OpenThread library in POSIX environment on Mac or Linux;
  • 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 UDP_PROXY=1 BORDER_AGENT=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 UDP_PROXY=1 DHCP6_SERVER=1 DHCP6_CLIENT=1 CERT_LOG=1 BORDER_AGENT=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 UDP_PROXY=1 USB=1 BORDER_AGENT=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 – rename to libopenthread-nrf52840-sdk-usb.a
    • libopenthread-nrf52840-softdevice-sdk.a – rename 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 to the /external/openthread folder.
  8. Copy the nRF52840-specific platform-fem.h and platform-softdevice.h files from /external/project/openthread/examples/platforms/nrf52840 to the /external/openthread/include/platform folder.
  9. Copy openthread-system.h file from /external/project/openthread/examples/platforms to the /external/openthread/include/platform folder.

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 to the /external/openthread folder.
  5. Copy the nRF52840-specific platform-fem.h and platform-softdevice.h files from /external/project/openthread/examples/platforms/nrf52840 to the /external/openthread/include/platform folder.
  6. Copy openthread-system.h file from /external/project/openthread/examples/platforms to the /external/openthread/include/platform folder.

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:
    1. Select all of the projects in the left panel.
    2. Right-click 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 to the /external/openthread folder.
  6. Copy the nRF52840-specific platform-fem.h and platform-softdevice.h files from /external/project/openthread/examples/platforms/nrf52840 to the /external/openthread/include/platform folder.
  7. Copy openthread-system.h file from /external/project/openthread/examples/platforms to the /external/openthread/include/platform folder.

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 to the /external/openthread folder.
  6. Copy the nRF52840-specific platform-fem.h and platform-softdevice.h files from /external/project/openthread/examples/platforms/nrf52840 to the /external/openthread/include/platform folder.
  7. Copy openthread-system.h file from /external/project/openthread/examples/platforms to the /external/openthread/include/platform folder.

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 the function call must 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

Multiprotocol support

OpenThread serialization