Simulate Thread Networks using OTNS

1. Introduction

5abd22afa2f2ee9a.png

What is Thread & OTNS

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.

What you'll learn

  • Install OTNS and its dependencies
  • Build OpenThread for OTNS
  • How to add/move/delete nodes in OTNS-Web
  • Use OTNS-Web's other useful features to operate the network simulation
  • Verify OpenThread's no-single-point-of-failure

This codelab is focused on OTNS-CLI and OTNS-Web. OTNS's other features, such as Python scripting, are not covered.

What you'll need

  • Linux x86_64 or Mac OS.
  • Git.
  • Go 1.13+.
  • Web browser. OTNS-Web uses a web browser for displaying simulations.
  • Thread Primer. You will need to know the basic concepts of Thread to understand what is taught in this Codelab.

2. Installation

Install Go

OTNS requires Go 1.13+ to build.

  1. Install Go from https://golang.org/dl/
  2. Add $(go env GOPATH)/bin (normally $HOME/go/bin) to $PATH:
$ export PATH=$PATH:$(go env GOPATH)/bin

Get OTNS code

$ git clone https://github.com/openthread/ot-ns.git ./otns
$ cd otns

Install Dependencies

$ ./script/install-deps
grpcwebproxy installed: /usr/local/google/home/simonlin/go/bin/grpcwebproxy

You might be asked to input a password for sudo.

Install otns

Install otns to $GOPATH/bin:

$ ./script/install
otns installed: /usr/local/google/home/simonlin/go/bin/otns

Let's check if otns is properly installed

  1. Run which otns to check if the otns executable is searchable in $PATH.
  2. If the otns command is not found, verify that you have added $(go env GOPATH)/bin to $PATH.

3. Build OpenThread for OTNS

Get OpenThread code from GitHub

$ mkdir -p ~/src
$ git clone https://github.com/openthread/openthread ~/src/openthread

Build OpenThread with OTNS=1

$ cd ~/src/openthread
$ ./script/cmake-build simulation -DOT_OTNS=ON -DOT_SIMULATION_VIRTUAL_TIME=ON -DOT_SIMULATION_VIRTUAL_TIME_UART=ON -DOT_SIMULATION_MAX_NETWORK_SIZE=999

You can find the OpenThread executables in the build directory:

$ ls ~/src/openthread/build/simulation/examples/apps/cli/
ot-cli-ftd        ot-cli-mtd        ot-cli-radio

Now it's time to run OTNS...

4. Run OTNS

Run otns:

$ cd ~/src/openthread/build/simulation/examples/apps/cli
$ otns
> ← OTNS-CLI prompt

When successfully started, OTNS will enter a CLI console (OTNS-CLI) and launch a web browser for network visualization and management (OTNS-Web):

a0e05178d66929b1.png

If you can only see a blank page for OTNS-Web, chances are WebGL is not enabled in your browser. Please refer tohttps://superuser.com/a/836833 on how to enable WebGL.

In the following sections, you are going to learn to manage OTNS simulations through OTNS-CLI and OTNS-Web.

5. Get to Know OTNS-CLI & OTNS-Web

OTNS-CLI

OTNS-CLI provides a Command Line Interface (CLI) for managing OTNS simulations.

$ cd ~/src/openthread/build/simulation/examples/apps/cli
$ otns
> ← OTNS-CLI prompt

You can type in commands through OTNS-CLI. Refer to the OTNS CLI reference for a full list of commands. Don't worry, you are only going to use a few of these commands in this Codelab.

OTNS-Web

OTNS-Web is OTNS's network visualization and management tool. It provides a visual representation of the nodes, messages, and links of the simulated Thread network. Note the various elements of OTNS-Web:

4c5b43509a2ca0d0.png

6. Add Nodes

Add nodes through OTNS-CLI

Add a Router at position (300, 100)

> add router x 300 y 100
1
Done

You should see a node created in OTNS-Web. The node starts as a Router and becomes a Leader in a few seconds:

6ca8c2e63ed9818d.png

Add more nodes through OTNS-CLI

> add fed x 200 y 100
2
Done
> add med x 400 y 100
3
Done
> add sed x 300 y 200
4
Done

Wait a few seconds for nodes to merge into one partition. You should see the nodes in OTNS-WEB:

3ee67903c01aa612.png

Add nodes by OTNS-Web

You can also add nodes through OTNS-Web. Click the New Router button of the Action Bar. You should see a node being created right above the New Router button. Drag the node to be near the Leader you created through OTNS-CLI. All the nodes should eventually merge into one partition:

420258bb92561146.png

Also click the FED, MED, and SED buttons on the Action Bar to create other types of nodes. Drag them to positions near existing nodes to attach them to that Thread network:

fe15d6f9726a099e.png

Now you have created a Thread network of one partition that contains many nodes. In the next section, we are going to adjust the simulating speed to make the simulation run faster.

7. Adjust Speed

Currently, the simulation should be running at 1X speed, meaning that the simulating time elapsed so far is the same as the actual time since we created the first node.

Adjust speed through OTNS-CLI

You can adjust the simulating speed through OTNS-CLI.

Set simulating speed to 100X

> speed 100
Done

You should see the nodes send messages much more frequently than before.

Set simulating speed to MAX

> speed max
Done

Now, OTNS is trying it's best to simulate as fast as it can, so you should see nodes sending a great number of messages.

Pause simulation

> speed 0
Done

Setting simulating speed to 0 pauses the simulation.

Restore simulation at normal speed

> speed 1
Done

Setting simulating speed to a value larger than 0 resumes the simulation.

Adjust speed through OTNS-Web

Speed control buttons

Find the speed control buttons 9329157c1bd12672.png on the Action Bar. The buttons show the current simulating speed and can be used to adjust simulating speed and pause/resume the simulation.

Speed up simulation

You can speed up the simulation by clicking the 39b88331779277ad.png button until the speed reaches MAX: f5f460b2586d299b.png.

Slow down simulation

You can slow down the simulation by clicking the 31cca8d5b52fa900.png button.

Pause simulation

Click the 46cc2088c9aa7ab6.png button to pause the simulation when it's running. The button will be changed to ce25eda3496ffcd4.png.

Resume simulation

Click the ce25eda3496ffcd4.png button to resume the simulation when it's paused. The button will be changed back to 46cc2088c9aa7ab6.png.

Set simulating speed to 10X

In order to save time, use

OTNS-CLI to adjust the simulating speed to

10X so that we can observe topology changes in the network much faster.

> speed 10
Done

8. Turn On/Off Radio

Now, the simulation should contain 2 Routers (hexagon shape) and many children, and runs at 10X speed.

Find the current Leader (red border) of the 2 Routers, single click to select it:

8c6a2e191cdae0c7.png

Turn off radio

Click the 7ca085f470491dd4.png button on the Action Bar to turn off the radio of the Leader node:

a3bf58d9d125f95f.png

The Leader won't be able to send or receive messages with the radio off.

Wait for about 12s (120s in simulating time) for the other Router to become the new Leader:

e3d32f85c4a1b990.png

The Thread network recovers from Leader failure automatically by forming a new partition with a new Leader. The new partition also has a new partition color.

Turn on radio

Select the Leader whose radio was turned off. Click the 2d9cecb8612b42aa.png button on Action Bar to restore radio connectivity:

7370a7841861aa3a.png

The Leader should reattach to the network after radio connectivity is restored.

9. Move Nodes

OTNS enables users to move nodes easily through OTNS-CLI or OTNS-Web.

Move node through OTNS-CLI

Move node 5 to a new location:

> move 5 600 300
Done

Since now node 5 is far from the other Router, they should lose connectivity to each other, and after about 12s (120s in simulating time) both become Leaders of their own partition:

c06b4d0a4f183299.png

Move node through OTNS-Web

Move node 5 back to the original location by dragging. The two partitions should merge back into one partition:

9ba305c4c5a5f892.png

10. Delete Nodes

Delete nodes through OTNS-CLI

Delete node 8:

> del 8
Done

Node 8 should disappear from the simulation:

18156770d9f8bf83.png

Delete nodes through OTNS-Web

Select node 5 and click the 7ff6afd565f4eafc.png button on the Action Bar to delete node 5:

d4079cceea0105f0.png

Node 1 should become Leader and Node 7 should detach since it can not reach any Router.

Clear simulation (delete all nodes)

You can clear the simulation by deleting all nodes through OTNS-Web.

Click 89618191721e79a0.png button on Action Bar. All nodes will disappear at once.

Before continuing...

Add some nodes to the simulation by yourself so that you can continue in this tutorial.

11. OTNS-CLI Node Context

OTNS-CLI provides node context mode for easy interaction with nodes to help developers diagnose a node's status.

Enter node context mode

Enter the node context of node 1:

> node 1
Done
node 1>

The CLI prompt changed to node 1> , indicating the current node context. You can type in OpenThread CLI commands to be executed on the node as if you are interacting with the node directly.

Execute commands in node context

node 1> state
leader
Done
node 1> channel
11
Done
node 1> panid
0xface
Done
node 1> networkname
OpenThread
Done
node 1> ipaddr
fdde:ad00:beef:0:0:ff:fe00:fc00
fdde:ad00:beef:0:0:ff:fe00:d800
fdde:ad00:beef:0:2175:8a67:1000:6352
fe80:0:0:0:2075:82c2:e9e9:781d
Done

Switch to another node context

node 1> node 2
Done
node 2> 

Exit node context

node 1> exit
Done
>

12. Congratulations

Congratulations, you've successfully executed your first OTNS simulation!

You've learned how to install OTNS and its dependencies. You built OpenThread for OTNS and started OTNS simulation with OpenThread simulation instances. You've learned how to manipulate the simulation in various ways through both OTNS-CLI and OTNS-Web.

You now know what OTNS is and how you can use OTNS to simulate OpenThread networks.

What's next?

Check out some of these codelabs...

Reference docs