Testing a Thread Network with Visualization

1. Introduction

What is Thread, OpenThread, OTNS, and Silk?

Thread is an IP-based low-power wireless mesh networking protocol that enables secure device-to-device and device-to-cloud communications. Thread networks can adapt to topology changes to avoid single point of failure.

OpenThread released by Google is an open-source implementation of Thread. Despite its small code size and memory footprint, OpenThread supports all features defined in the Thread Specification.

OpenThread Network Simulator (OTNS) can be used to simulate Thread networks by running simulated OpenThread nodes on posix platforms. OTNS provides an easy-to-use Web interface (OTNS-Web) for visualizing and operating simulated Thread networks.

Silk is a fully automated test platform for validating OpenThread function, feature, and system performance with real devices.

What you'll learn

OpenThread's functionality verification framework: Silk
Build OpenThread for real devices with the OTNS feature enabled
Use OTNS-Web interface to monitor the status of the Thread network formed by running Silk test cases

This codelab is focused on using Silk with OTNS. Other features of Silk and OTNS are not covered.

What you'll need

Hardware:

6 Nordic Semiconductor nRF52840 dev boards
6 USB to Micro-USB cables to connect the boards
USB hub

Software:

Linux x86_64.
Git.
Go 1.11+.
Web browser. OTNS-Web uses a web browser for displaying simulations.

Prerequisites:

2. Prerequisites

Complete prior basic Codelabs

Thread Primer. You will need to know the basic concepts of Thread to understand what is taught in this Codelab.
Build a Thread network with nRF52840 boards and OpenThread. This Codelab assumes that you have successfully built a Thread network.
Simulate Thread Networks using OTNS. This Codelab assumes that you have successfully run the OTNS tool.

Checking package prerequisites

Let's make sure all the prerequisites are met.

Run which otns to check if the otns executable is searchable in $PATH.
Run which wpantund to make sure wpantund is available.
Make sure ARM GNU toolchain, J-Link, and nrfjprog packages are all available.

Note: Please refer to the linked documentations for set up guidance. Prerequisite #1 is from Simulate Thread Networks using OTNS and others are from Build a Thread network with nRF52840 boards and OpenThread.

3. Silk setup

To clone Silk and set up the environment, run the following commands under your source directory:

$ git clone https://github.com/openthread/silk.git
$ cd silk
$ ./bootstrap.sh
$ sudo make install-cluster

Define hardware configuration file

To allow Silk to gather the available test hardware resources connected to your machine, define a hwconfig.ini file in the following format:

[DEFAULT]
ClusterID: 0
LayoutCenter: 300, 300
LayoutRadius: 100

[Dev-8A7D]
HwModel: Nrf52840
HwRev: 1.0
InterfaceSerialNumber: E1A5012E8A7D
USBInterfaceNumber: 1
DutSerial: 683536778

A tool called usbinfo is installed as part of Silk which can be used to find out the Interface Serial Number and USB Interface Number. DutSerial is the SN number printed on the chip or displayed by usbinfo for J-Link products.

The LayoutCenter and LayoutRadius fields in the [DEFAULT] section defines the shape of the layout when the devices are visualized on the web UI. Setting them to the values presented here can be a good starting point.

Following that, it defines a section for each test device and supplies the relevant hardware information.

4. Compile OpenThread with OTNS enabled

Building image and flashing

By default, OpenThread devices do not emit OTNS related messages. To allow the dev boards to emit status messages to log interfaces that are essential to OTNS visualization, run the following command under the OpenThread source directory to build an FTD image, and convert it to hex format.

$ git clone https://github.com/openthread/ot-nrf528xx.git --recursive
$ cd ot-nrf528xx
$ ./script/bootstrap
$ ./script/build nrf52840 USB_trans -DOT_COMMISSIONER=ON -DOT_JOINER=ON -DOT_OTNS=ON
$ cd ./build/bin
$ arm-none-eabi-objcopy -O ihex ot-ncp-ftd ot-ncp-ftd.hex

To flash the boards, follow the instructions in step 4 of the Build a Thread network Codelab to use nrfjprog. After that, connect all the boards via the nRF USB port to the host machine. The same set of USB to Micro-USB cables can be disconnected from the J-Link ports and connected to the nRF USB ports of the nRF52840 dev boards. Thus with just these 6 cables test execution can be carried out. To avoid the hassle, use 12 cables and connect to both ports.

5. Running OTNS server with real mode

Running OTNS with default parameters allows the user to simulate a Thread network. To use it as a visualization tool for an actual physical network, run it with:

otns -raw -real -ot-cli otns-silk-proxy

These arguments tell OTNS to expect gRPC and UDP messages that describe how the Thread network should be visualized, instead of running multiple ot-cli processes to simulate the network. Your browser should automatically open the visualization page with an empty canvas.

6. Running Silk test cases with OTNS support

Silk is a fully automated test platform for validating OpenThread function, feature, and system performance with real devices. The instructions in the project README covers how to use it.

The silk_run_test.py file located at silk/unit_tests gives you a headstart. Silk provides OTNS support when running a test case. Since the OTNS real mode service is already running locally, we simply need to modify the silk_run_test.py file with the desired locations for an output log file, input test scripts, and hwconfig.ini file. The -s localhost argument tells Silk to send OTNS messages to localhost.

For example, one can run the test named ot_test_form_network.py using the following modifications to silk_run_test.py file. /opt/openthread_test/ is the default path Silk uses for log output and config file, but you can use any path.

silk_run_test.py

import datetime
import os

from silk.tests import silk_run

RESULT_LOG_PATH = '/opt/openthread_test/results/' + 'silk_run_' + \
                  datetime.datetime.today().strftime('%m-%d') + '/'
CONFIG_PATH = '/opt/openthread_test/'

os.chdir('~/src/silk/silk/tests/')

timestamp = datetime.datetime.today().strftime('%m-%d-%H:%M')

run_log_path = RESULT_LOG_PATH + 'test_run_on_' + timestamp + '/'

argv = [
    'tests/silk_run.py',
    '-v2',
    '-c', CONFIG_PATH + 'hwconfig.ini',
    '-d', run_log_path,
    '-s', 'localhost',
    'ot_test_form_network.py'
]

silk_run.SilkRunner(argv=argv)

The topology visualization of the formed network will show up on the OTNS web UI.

The top left corner shows visualization stats, OT version and test title. The bottom left corner has controls of the log window, which is shown on the right. Initially, nodes are added but no network is formed. As the test progresses, the modes and roles of each node change, and links are formed.

7. Congratulations

Congratulations, you've successfully run a Silk test on physical Thread devices and visualized it using OTNS!

You executed a Silk test using development boards that are flashed with firmwares that have OTNS support. The boards report their status to a Silk server, which monitors and aggregates all of them, and sends them to the OTNS service along with other test information. OTNS running in real mode visualizes the Thread network on the web interface.

What's next?

Try running other OpenThread test cases included in the Silk package.