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 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
- 6 Nordic Semiconductor nRF52840 dev boards
- 6 USB to Micro-USB cables to connect the boards
- USB hub
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.
which otnsto check if the
otnsexecutable is searchable in
which wpantundto make sure
- Make sure ARM GNU toolchain, J-Link, and
nrfjprogpackages are all available.
- Make sure an OpenThread binary can be made, running
make -f examples/Makefile-nrf52840under the
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.
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.
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
For example, one can run the test named
ot_test_form_network.py using the following modifications to
/opt/openthread_test/ is the default path Silk uses for log output and config file, but you can use any path.
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.
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.
Try running other OpenThread test cases included in the Silk package.