Getting Started with Thread and Zigbee

This page contains all the information required to start working with the nRF5 SDK for Thread and Zigbee: from the supported boards to the procedures for building and running. Most of the sections are common to both Thread and Zigbee protocols.

Hardware support and requirements

This section describes hardware elements supported or required by the nRF5 SDK for Thread and Zigbee.

Supported boards for Thread and Zigbee

The nRF5 SDK for both Thread and Zigbee is compatible with the configurations mentioned in the following table.

Note

You can use PCA10112 to evaluate the Front End Module support for Thread and Zigbee examples. See the PA/LNA module (FEM support) page for more information. nRF21540 on PCA10112 is not supported by SoftDevice, and for this reason PCA10112 does not support multiprotocol examples.

Thread nRF52811 support

The Thread protocol supports the nRF52811 SoC.

Because of the memory constraints, multiprotocol features are not supported when using nRF52811. For this reason, the SoftDevice is not used. Moreover, the support for Joiner and Commissioner in nRF52811 is not available through the regular SoC architecture, but it is possible in the RCP mode.

Peripheral requirements

See the tables in this section for the overview of peripherals used by the nRF5 SDK for Thread and Zigbee. These peripherals cannot be used directly by an application.

The peripherals for the 802.15.4 Radio Driver are always used, regardless of the protocol and the SoftDevice. The SoftDevice peripherals are used in the multiprotocol solutions (for details, see S140 SoftDevice hardware peripherals usage).

Thread peripheral requirements

Thread peripheral requirements are almost identical for nRF52840 and nRF52833, and different for nRF52811.

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

To use the logger module, use the RTT backend. Depending on the OpenThread platform library, UART0 or USB might be reserved by the Thread stack. Do not use the logger backend using those peripherals.

Note

The resources mentioned in the tables in this section are reserved by all the OpenThread libraries delivered with this SDK, unless marked as optional. The optional serial transport peripherals are reserved by the corrensponding library variants. You can specify other instances of some peripherals such as Timers, PPIs, SWI, UART, SPI, or USB, and then rebuild the libraries. Refer to platform-config.h (in the related board directory) and nrf_802154_config.h to view the current configuration.

Thread nRF52840 peripheral requirements

The following table shows the hardware requirements of the OpenThread stack for nRF52840. SoftDevice usage is provided for the multiprotocol features.

Thread nRF52833 peripheral requirements

The hardware requirements of the OpenThread stack for nRF52833 are identical to Thread nRF52840 peripheral requirements , with the following exception:

• CRYPTOCELL is not available for nRF52833.

SoftDevice usage is provided for the multiprotocol features.

Thread nRF52811 peripheral requirements

The following table shows the hardware requirements of the OpenThread stack for nRF52811, in simulated and standard versions. Only OpenThread MTD and radio-only variants are available for this chip. Due to insufficient memory resources, multiprotocol features are not supported, and SoftDevice is not used.

Zigbee peripheral requirements

Zigbee peripheral requirements are almost identical for nRF52840 and nRF52833.

For information about the Zigbee stack memory layout and requirements, see Zigbee memory layout and requirements.

Zigbee nRF52840 peripheral requirements

See the following table for the peripheral requirements for the Zigbee protocol running on the nRF52840 SoC. SoftDevice usage is provided for the multiprotocol features.

Zigbee nRF52833 peripheral requirements

The peripheral requirements for the Zigbee protocol running on the nRF52833 SoC are identical to Zigbee nRF52840 peripheral requirements , with the following exception:

• CRYPTOCELL is not available for nRF52833.

SoftDevice usage is provided for the multiprotocol features.

Running precompiled examples

The only thing you need to run precompiled examples are nRF5x Command Line Tools.

You do not need to install the full toolchain. Additionally, if you want to test the precompiled version of Thread CLI Example and Thread NCP/RCP Example with the Thread protocol, or Zigbee CLI Agent example with the Zigbee protocol, you do not have to disable the Mass Storage Device (see Configuring SEGGER J-Link software) before testing these examples.

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.

To program a precompiled example:

1. Download and install the latest version of nRF5x Command Line Tools.
2. Download the latest nRF5-SDK-for-Thread-and-Zigbee repository file in zip format from the SDK download page.
3. Extract the zip file to the directory that you want to use to work with the SDK.
4. Depending on the board you are using:
   • PCA10056 or PCA10068:
     1. Connect the board to your computer using the J2 USB port on the board (on the side of the coin cell battery). The computer recognizes it as a standard USB drive.

        Note

        If the computer does not recognize the board as a USB drive, the Mass Storage Device might have been already disabled on the board and needs to be enabled. See Configuring SEGGER J-Link software for more information.

     2. 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/ftd/uart/hex.
        • For the Zigbee CLI Agent example, navigate to examples/zigbee/experimental/cli/cli_agent_router/hex.
     3. Select the hex file that corresponds to your development board and copy it to the board J-Link USB drive.
   • PCA10059:
     • Flash the dongle as described in the Building examples section.

To test the example, follow the testing instructions in the example documentation (Thread and Thread+BLE examples or Zigbee and Zigbee+BLE examples, respectively), with the following exceptions:

• Do not disable the Mass Storage Device in SEGGER J-Link (if listed as one of the prerequisites in the example). You still need to force Hardware Flow Control.
• Skip the initial steps that refer to building examples and programming development kits.

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 the native USB, SPI, or a phone app.

Installing the toolchain

You must install a set of tools to set up the build environment. The setup process depends on your preferred toolchain and operating system.

See the following table for the toolchains and IDEs supported by both protocols, and the following sections for detailed installation instructions.

Precompiled libraries
The nRF5 SDK for Thread and Zigbee includes the following precompiled libraries for GCC, IAR, and Keil 5:

• Thread: precompiled OpenThread libraries.
• Zigbee: precompiled ZBOSS libraries.

In both cases, the SEGGER Embedded Studio project uses the libraries built with GCC.

Build environment based on GCC

The GCC ARM Embedded Toolchain is supported for both Windows and Linux.

Installing GCC on Linux

See the following table for the list of software required for setting up the build environment based on GCC ARM Embedded Toolchain on Linux.

$ which make 

Installing GCC on Windows

See the following table for the list of software required for setting up the build environment based on GCC ARM Embedded Toolchain on Windows.

Installing make on Windows

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. Run the downloaded MinGW binary and select a folder where the MinGW toolchain is to be installed. The recommended path is C:/MinGW. When the first part of the installation is finished, the MinGW Installation Manager opens.
   
   

   MinGW Installation Manager
   
   
2. From the package list, select mingw32-base and msys-base.
3. Click Installation -> Apply changes to install the selected items.
4. 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.
5. 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:
   

   System information
6. 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:
   

   Version information
   If you experience issues 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.

Build environment based on IAR

See the following table for the list of software required for setting up the build environment based on IAR Embedded Workbench on Windows.

Build environment based on Keil 5

See the following table for the list of software required for setting up the build environment based on Keil µVision 5 MDK on Windows.

Build environment based on SEGGER Embedded Studio

SEGGER Embedded Studio (SES) is available for both Windows and Linux. However, by default the nRF5 SDK for Thread and Zigbee refers to the SES build environment on Windows.

See the following table for the list of software required for setting up the build environment based on SES on Windows.

Required additional software for Thread protocol

You might also need to install the following tools when using the Thread protocol:

• Thread Border Router for Thread NCP/RCP Example.
• nRF Thread Topology Monitor for visualizing the Thread network.

Configuring SEGGER J-Link software

If you plan to use Thread CLI Example, Thread NCP/RCP Example with the Thread protocol, or Zigbee CLI Agent example with the Zigbee protocol, make sure you configure SEGGER J-Link by completing the following procedures:

• Disable Mass Storage Device – to avoid data corruption or data drops when you use the serial port; the Mass Storage Device is enabled by default on new development kits.
  • This is required due to a known issue in SEGGER's J-Link firmware, though this depends on the software version.
• Force Hardware Flow Control – to avoid potential race conditions related to the auto-detection.
  • By default, SEGGER J-Link automatically detects at runtime whether the target is using Hardware Flow Control (HWFC). The automatic HWFC detection is done by driving P0.07 (Clear to Send - CTS) from the interface MCU and evaluating the state of P0.05 (Request to Send - RTS) when the first data is sent or received. If the state of P0.05 (RTS) is high, it is assumed that HWFC is not used.

Configuring SEGGER J-Link software on Windows

To disable the MSD and force the HWFC on Windows:

1. Connect the board to your machine with a USB cable.
2. Run J-Link Commander. The configuration window appears.
3. From the Specify Target Device dropdown menu, select NRF52810_XXAA, NRF52833_XXAA, or NRF52840_XXAA, depending on your board.
4. From the Target Interface & Speed dropdown menu, select SWD.
5. Run the following commands:
   • To disable the MSD:

     MSDDisable

   • To force the HWFC:

     SetHWFC Force

6. Power cycle the board using the on/off Power switch.

To enable the MSD, you can repeat the first four steps above and then run the following command: MSDEnable.

Configuring SEGGER J-Link software on Linux

To either disable the MSD or force the HWFC on Windows, or do both:

1. Connect the NRF52810_XXAA, NRF52833_XXAA, or NRF52840_XXAA board to your machine with a USB cable.
2. Run JLinkExe to connect to the target. For example, for NRF52810_XXAA:

   JLinkExe -device NRF52810_XXAA -if SWD -speed 4000 -autoconnect 1 -SelectEmuBySN [SEGGER_ID]

3. Run the following commands:
   • To disable the MSD:

     MSDDisable

   • To force the HWFC:

     SetHWFC Force

4. Power cycle the board using the on/off Power switch.

To enable the MSD, you can repeat the first four steps above and then run the following command: MSDEnable.

Building examples

The procedure for building examples depends on the toolchain you are using:

• Building examples with GCC
• Building examples with IAR
• Building examples with Keil 5
• Building examples with SEGGER Embedded Studio

Building examples with GCC

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

1. Open Windows command line or Linux terminal.
2. Navigate to the selected example directory, and then to the armgcc project directory, for example:
   • Thread: <InstallFolder>/examples/thread/cli/ftd/pca10056/blank/armgcc
   • Zigbee: <InstallFolder>/examples/zigbee/light_control/light_bulb/pca10056/blank/armgcc
3. Run the make command in this directory. If the environment is set up correctly, the build process starts.

The build process produces the hex file inside the _build directory, for example:

• Thread: <InstallFolder>/examples/thread/cli/ftd/pca10056/blank/armgcc/_build/nrf52840_xxaa.hex
• Zigbee: <InstallFolder>/examples/zigbee/light_control/light_bulb/pca10056/blank/armgcc/_build/nrf52840_xxaa.hex

Building examples with IAR

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

1. Open IAR Embedded Workbench.
2. Select File->Open->Workspace... and navigate to the selected example directory.
3. Open the selected workspace, for example:
   • Thread: <InstallFolder>/examples/thread/cli/ftd/thread_cli.eww
   • Zigbee: <InstallFolder>/examples/zigbee/light_control/light_bulb/zigbee_light_bulb.eww
4. Build the example with Project->Make.

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

Building examples with Keil 5

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

1. Open Keil µVision 5.
2. Select File->Open, set file type to Project Files, and navigate to the selected example directory.
3. Open the selected project, for example:
   • Thread: <InstallFolder>/examples/thread/cli/ftd/uart/pca10056/blank/arm5_no_packs/thread_cli_uart_pca10056.uvprojx
   • Zigbee: <InstallFolder>/examples/zigbee/light_control/light_bulb/pca10056/blank/arm5_no_packs/zigbee_light_bulb.uvprojx
4. Build the example with Project->Build Target.

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

Building examples with SEGGER Embedded Studio

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

1. Open SEGGER Embedded Studio.
2. Select File->Open Solution and navigate to the selected example directory.
3. Open the selected project, for example:
   • Thread: <InstallFolder>/examples/thread/cli/ftd/uart/pca10056/blank/ses/thread_cli_uart_pca10056.emProject
   • Zigbee: <InstallFolder>/examples/zigbee/light_control/light_bulb/pca10056/blank/ses/zigbee_light_bulb.emProject
4. Build the example with Build->Build Solution.

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

Running examples

To program the nRF52840 or the nRF52833 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.

Then, you can program the example either:

• without the SoftDevice
• with the SoftDevice

Running examples without the SoftDevice

To program the device, run:

nrfjprog -f NRF52 --chiperase --program <path to the hex file> --reset

To list the available nrfjprog commands, run:

nrfjprog --help

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

make erase flash

Running examples 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_7.0.1_softdevice.hex

To write an application to the device, run:

nrfjprog -f NRF52 --sectorerase --program <path to the hex file> --reset

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

make erase flash_softdevice flash