Thread tools

The tools listed on this page can be helpful when developing your Thread application with the nRF Connect SDK.

nRF Sniffer for 802.15.4 

The nRF Sniffer for 802.15.4 is a tool for learning about and debugging applications that are using protocols based on IEEE 802.15.4, like Thread or Zigbee. It provides a near real-time display of 802.15.4 packets that are sent back and forth between devices, even when the link is encrypted.

See nRF Sniffer for 802.15.4 for documentation.

nRF Thread Topology Monitor 

nRF Thread Topology Monitor is a desktop application that connects to a Thread network through a serial connection to visualize the topology of Thread devices. It allows you to scan for new devices in real time, check their parameters, and inspect network processes through the log.

See nRF Thread Topology Monitor for documentation.

Thread Border Router 

The Thread Border Router is a specific type of Border Router device that provides connectivity from the IEEE 802.15.4 network to adjacent networks on other physical layers (such as Wi-Fi® or Ethernet). Border Routers provide services for devices within the IEEE 802.15.4 network, including routing services for off-network operations.

Typically, a Border Router solution consists of the following parts:

An application based on the Network co-processor (NCP) design or its Radio co-processor (RCP) variant compatible with the IEEE 802.15.4 standard. This application can be implemented, for example, on an nRF52 device.
A host-side application, usually implemented on a more powerful device with an incorporated Linux-based operating system.

The nRF Connect SDK does not provide a complete Thread Border Router solution. For development purposes, you can use the OpenThread Border Router (OTBR) released by Google, an open-source Border Router implementation that you can set up either on your PC using Docker or on a Raspberry Pi.

The OpenThread Border Router is compatible with Nordic Semiconductor devices. It implements a number of features, including:

Bidirectional IP connectivity between Thread and Wi-Fi or Ethernet networks (or both)
Network components that allow Thread nodes to connect to IPv4 networks (NAT64, DNS64)
Bidirectional DNS-based service discovery using mDNS (on Wi-Fi or Ethernet link, or both) and SRP (on Thread network)
External Thread commissioning (for example, using a mobile phone) to authenticate and join a Thread device to a Thread network

You can either install the OpenThread Border Router on a Raspberry Pi or run it using a Docker container, as described in the following sections. In both cases, you must first configure a radio co-processor (RCP), which provides the required radio capability to your Linux device.

Configuring a radio co-processor 

The OpenThread Border Router must have physical access to the IEEE 802.15.4 network that is used by the Thread protocol. As neither the Linux-based PC nor the Raspberry Pi have such radio capability, you must connect an external nRF device that serves as radio co-processor.

To program the nRF device with the RCP application, complete the following steps:

Start the toolchain environment in a terminal window.
Build the Thread: Co-processor sample for the hardware platform and the transport of your choice:
west build -p always -b nrf52840dongle/nrf52840 nrf/samples/openthread/coprocessor/
west build -p always -b nrf52840dk/nrf52840 nrf/samples/openthread/coprocessor/
Depending on the hardware platform, complete the following steps:
This procedure uses the nRF Util tool, which is part of the nRF Connect SDK toolchain bundle and you get it when you Install the nRF Connect SDK code and toolchain.
1. Remove the lock on the nRF Util installation to be able to install other nRF Util commands. See Locking nRF Util home directory in the tool documentation for more information.
2. Install nRF Util’s nrf5sdk-tools command:
  nrfutil install nrf5sdk-tools
  See nrf5sdk-tools command overview for more information.
3. Generate the RCP firmware package:
  nrfutil nrf5sdk-tools pkg generate --hw-version 52 --sd-req=0x00 \ --application build/zephyr/zephyr.hex --application-version 1 build/zephyr/zephyr.zip
4. Connect the nRF52840 Dongle to the USB port.
5. Press the RESET button on the dongle to put it into the DFU mode. The LED on the dongle starts blinking red.
6. Install the RCP firmware package onto the dongle by running the following command, with /dev/ttyACM0 replaced with the device node name of your nRF52840 Dongle:
  nrfutil nrf5sdk-tools dfu usb-serial -pkg build/zephyr/zephyr.zip -p /dev/ttyACM0
1. Program the image using the regular command.
2. Disable the Mass Storage feature on the device, so that it does not interfere with the core RCP functionalities. Also, force Hardware Flow Control to avoid potential race conditions related to the auto-detection:
```
JLinkExe -device NRF52840_XXAA -if SWD -speed 4000 -autoconnect 1 -SelectEmuBySN SEGGER_ID
J-Link>MSDDisable
Probe configured successfully.
J-Link>SetHWFC Force
New configuration applies immediately.
J-Link>exit
```
  Replace SEGGER_ID with the SEGGER ID of your nRF52840 Development Kit. This setting remains valid even if you program another firmware onto the device.
3. Power-cycle the device to apply the changes.

Installing OTBR manually (Raspberry Pi)

The recommended option is to build and configure the OpenThread Border Router on a Raspberry Pi 3 Model B or newer. This option provides most of the functionalities available in the OpenThread Border Router, such as border routing capabilities needed for establishing Thread communication with a mobile phone on a Wi-Fi network. However, this approach requires you to download the OpenThread Border Router repository and install the Border Router manually on the Raspberry Pi.

To set up and configure the OpenThread Border Router, follow the official OpenThread Border Router Codelab tutorial on the OpenThread documentation portal with the below modifications:

After cloning the repository in the Get OTBR code section, make sure to check out the compatible commit id:
cd ot-br-posix git pull --unshallow git checkout fbde28a
After the Build and install OTBR section, configure RCP device’s UART baud rate in otbr-agent. Modify the /etc/default/otbr-agent configuration file with default RCP baud rate:
```
spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=1000000
```
Omit the Build and flash RCP firmware section, because that section duplicates the steps already performed in the Configuring a radio co-processor section of this guide.

Running OTBR using Docker 

For development purposes, you can run the OpenThread Border Router on any Linux-based system using a Docker container that already has the Border Router installed. This solution can be used when you are only interested in direct communication between your Border Router and the Thread network. For example, you can use the Docker container when you want to establish IP communication between an application running on Linux (such as the CHIP Tool Matter controller) and an application running on a Thread node.

To install and configure the OpenThread Border Router using the Docker container on an Ubuntu operating system, complete the following steps:

Install the Docker daemon:

sudo apt update && sudo apt install docker.io

Start the Docker daemon:
```
sudo systemctl start docker
```

Create an IPv6 network for the OpenThread Border Router container in Docker:

sudo docker network create --ipv6 --subnet fd11:db8:1::/64 -o com.docker.network.bridge.name=otbr0 otbr

Download the compatible version of the OpenThread Border Router docker image by running the following command:
```
docker pull nrfconnect/otbr:fbde28a
```
Connect the radio co-processor that you configured in Configuring a radio co-processor to the Border Router device.

Start the OpenThread Border Router container using the following commands:

sudo modprobe ip6table_filter
sudo docker run -it --rm --privileged --name otbr --network otbr -p 8080:80 \
--sysctl "net.ipv6.conf.all.disable_ipv6=0 net.ipv4.conf.all.forwarding=1 net.ipv6.conf.all.forwarding=1" \
--volume /dev/ttyACM0:/dev/radio nrfconnect/otbr:fbde28a --radio-url spinel+hdlc+uart:///dev/radio?uart-baudrate=1000000

Replace /dev/ttyACM0 with the device node name of the OpenThread radio co-processor.

Form the Thread network using one of the following options:
- Follow the instruction in the OpenThread Border Router Codelab tutorial step 3.
- Open the http://localhost:8080/ address in a web browser and choose Form from the menu.
  
  Note
  
  If you are using a Raspberry Pi without a screen, but you have a different device in the same network, you can start a web browser on that device and use the address of the Raspberry Pi instead of localhost.
Note down the selected On-Mesh Prefix value. For example, fd11:22::/64.
Make sure that packets addressed to devices in the Thread network are routed through the OpenThread Border Router container in Docker. To do this, run the following command that uses the On-Mesh Prefix that you configured in the previous step (in this case, fd11:22::/64):
```
sudo ip -6 route add fd11:22::/64 dev otbr0 via fd11:db8:1::2
```
Check the status of the OpenThread Border Router by executing the following command:
```
sudo docker exec -it otbr sh -c "sudo service otbr-agent status"
```
Check the status of the Thread node running inside the Docker:
```
sudo docker exec -it otbr sh -c "sudo ot-ctl state"
```

Note

OTBR on the Docker has got disabled DNS64 service by default.

OpenThread POSIX applications 

OpenThread POSIX applications allow to communicate with a radio co-processor (RCP) in a comfortable way.

OpenThread provides the following applications:

ot-cli - Works like the Thread: CLI sample for the RCP architecture.
ot-daemon and ot-ctl - Provides the same functionality as ot-cli, but keeps the daemon running in the background all the time. See OpenThread Daemon for more information.

When working with Thread, you can use these tools to interact with the following sample:

Thread: Co-processor

See OpenThread POSIX app for more information.

Building the OpenThread POSIX applications 

Build the OpenThread POSIX applications by performing the following steps:

Enter the openthread directory:
```
cd modules/lib/openthread
```
Install the OpenThread dependencies:
```
./script/bootstrap
```
Build the applications with the required options. For example, to build the ot-cli application, run the following command:
```
./script/cmake-build posix
```
Alternatively, to build the ot-daemon and ot-ctl applications, run the following command:
```
./script/cmake-build posix -DOT_DAEMON=ON
```

You can find the generated applications in ./build/posix/src/posix/.

Running the OpenThread POSIX applications 

Use the following radio URL parameter to connect to an RCP node.

'spinel+hdlc+uart://\ *ncp_uart_device*\ ?uart-baudrate=\ *baud_rate*' -B *backbone_link*

Replace the following parameters:

ncp_uart_device - Specifies the location of the device, for example: /dev/ttyACM0.

baud_rate - Specifies the baud rate to use. The Thread Co-Processor sample supports baud rate 1000000.

backbone_link - Specifies Backbone link for communication with external network. This parameter can be omitted.

For example, to use ot-daemon, enter the following command:

sudo ./build/posix/src/posix/ot-daemon 'spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=1000000' --verbose -B eth0

And on a separate terminal window:

sudo ./build/posix/src/posix/ot-ctl

To use ot-cli, enter the following command instead:

sudo ./build/posix/src/posix/ot-cli 'spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=1000000' --verbose -B eth0

OpenThread performance measurement 

When measuring network performance, it is important to select the appropriate tool. The available tools are IPerf, zperf, and otperf, each serving slightly different use cases:

IPerf: IPerf is a widely used, general-purpose tool for benchmarking the throughput of IP-based networks. It offers a wide range of advanced functionalities, many of which go beyond the requirements of typical Thread devices. You can use this tool on a powerful device, such as a border router.
zperf: Zperf an implementation of IPerf protocol using Zephyr’s L2 (data link) layer. Use zperf if your Thread implementation uses the Zephyr network stack.
otperf: Otperf is a lightweight implementation of IPerf protocol that uses OpenThread stack directly (bypassing the Zephyr L2 layer, as is the case for the default Thread implementation in nRF Connect SDK). Use otperf when your device runs OpenThread directly (without Zephyr L2 integration).

Because otperf, zperf, and IPerf v2.0.10 and newer are protocol-compatible, clients and servers can be mixed across these tools, allowing flexible test scenarios (for example, otperf server and zperf client). The following section describes the usage of otperf. For the other tools, consult the proper documentation.

Configuration 

You can enable and configure otperf using the following Kconfig options:

CONFIG_OTPERF - Enables the otperf tool.

CONFIG_OTPERF_SHELL (enabled by default) - Allows otperf to be used through the shell (requires CONFIG_SHELL).

CONFIG_OTPERF_SERVER (enabled by default) - Enables the otperf udp download (server) command.

CONFIG_OTPERF_MAX_PACKET_SIZE - Specifies the maximum data packet size (default: 1232 bytes).

CONFIG_OTPERF_MAX_SESSIONS - Sets the maximum number of handled connections.

CONFIG_OTPERF_UDP_REPORT_RETRANSMISSION_COUNT - Defines how many times the client will attempt to request a UDP report.

CONFIG_OTPERF_DEFAULT_PORT, CONFIG_OTPERF_DEFAULT_DURATION_S, CONFIG_OTPERF_DEFAULT_PACKET_SIZE, CONFIG_OTPERF_DEFAULT_RATE_KBPS - Default values applied when not overridden by the user.

Usage 

Before starting measurements, ensure that two Thread devices are connected to the same network.

To enable the server on one device, run the following command:

otperf udp download <port>

You should see a message similar to this:

UDP server started on port 5001

On the other device, initiate a test session using the following command:

otperf udp upload <ipv6> <port> <duration> <packet size> <rate>

You can use K (kilobits) and M (megabits) as units for the rate. For example, to send data at 200 kbps, use the following parameters:

otperf udp upload fe80:0:0:0:fcfb:7a67:4a05:ba27 5001 10 1064 200K

After a successful upload, both devices should display results similar to this (server will not display client statistics, while client will display both):

Statistics:             server  (client)
Duration:               10.72 s (10.06 s)
Num packets:            121     (241)
Num packets out order:  0
Num packets lost:       118
Jitter:                 8.78 ms
Rate:                   96 Kbps (203 Kbps)