diff --git a/site/en/codelabs/openthread-network-simulator/img/00_otns_web.png b/site/en/codelabs/openthread-network-simulator/img/00_otns_web.png new file mode 100644 index 00000000..25397941 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/00_otns_web.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/00b_otns_web_elements.png b/site/en/codelabs/openthread-network-simulator/img/00b_otns_web_elements.png new file mode 100644 index 00000000..59e76880 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/00b_otns_web_elements.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/01_leader_1n.png b/site/en/codelabs/openthread-network-simulator/img/01_leader_1n.png new file mode 100644 index 00000000..7459eb43 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/01_leader_1n.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/02_4n.png b/site/en/codelabs/openthread-network-simulator/img/02_4n.png new file mode 100644 index 00000000..ce1f7e59 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/02_4n.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/03_4n_select1.png b/site/en/codelabs/openthread-network-simulator/img/03_4n_select1.png new file mode 100644 index 00000000..59874c00 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/03_4n_select1.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/04_5n_add_router.png b/site/en/codelabs/openthread-network-simulator/img/04_5n_add_router.png new file mode 100644 index 00000000..a6f6c492 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/04_5n_add_router.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/05_9n_add_multiple.png b/site/en/codelabs/openthread-network-simulator/img/05_9n_add_multiple.png new file mode 100644 index 00000000..e1e39fe0 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/05_9n_add_multiple.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/06_9n_select1.png b/site/en/codelabs/openthread-network-simulator/img/06_9n_select1.png new file mode 100644 index 00000000..39266b3d Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/06_9n_select1.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/07_9n_radio_off_1.png b/site/en/codelabs/openthread-network-simulator/img/07_9n_radio_off_1.png new file mode 100644 index 00000000..08b56d8c Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/07_9n_radio_off_1.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/08_9n_new_partition.png b/site/en/codelabs/openthread-network-simulator/img/08_9n_new_partition.png new file mode 100644 index 00000000..bc4d51a0 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/08_9n_new_partition.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/09_9n_radio_on_1.png b/site/en/codelabs/openthread-network-simulator/img/09_9n_radio_on_1.png new file mode 100644 index 00000000..16896d5e Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/09_9n_radio_on_1.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/10_9n_move_router_away.png b/site/en/codelabs/openthread-network-simulator/img/10_9n_move_router_away.png new file mode 100644 index 00000000..3d68ca2e Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/10_9n_move_router_away.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/11_8n_del_router.png b/site/en/codelabs/openthread-network-simulator/img/11_8n_del_router.png new file mode 100644 index 00000000..c50ac024 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/11_8n_del_router.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/12_7n_del_br.png b/site/en/codelabs/openthread-network-simulator/img/12_7n_del_br.png new file mode 100644 index 00000000..eebb6cf9 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/12_7n_del_br.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/13_wireshark.png b/site/en/codelabs/openthread-network-simulator/img/13_wireshark.png new file mode 100644 index 00000000..4f3ff890 Binary files /dev/null and b/site/en/codelabs/openthread-network-simulator/img/13_wireshark.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/18156770d9f8bf83.png b/site/en/codelabs/openthread-network-simulator/img/18156770d9f8bf83.png deleted file mode 100644 index 9e56be09..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/18156770d9f8bf83.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/2d9cecb8612b42aa.png b/site/en/codelabs/openthread-network-simulator/img/2d9cecb8612b42aa.png index fa34ab93..37664726 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/2d9cecb8612b42aa.png and b/site/en/codelabs/openthread-network-simulator/img/2d9cecb8612b42aa.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/31cca8d5b52fa900.png b/site/en/codelabs/openthread-network-simulator/img/31cca8d5b52fa900.png index fa3c81ee..d276a7be 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/31cca8d5b52fa900.png and b/site/en/codelabs/openthread-network-simulator/img/31cca8d5b52fa900.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/39b88331779277ad.png b/site/en/codelabs/openthread-network-simulator/img/39b88331779277ad.png index 820ea3ab..c1c651b9 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/39b88331779277ad.png and b/site/en/codelabs/openthread-network-simulator/img/39b88331779277ad.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/3ee67903c01aa612.png b/site/en/codelabs/openthread-network-simulator/img/3ee67903c01aa612.png deleted file mode 100644 index 8fcfd727..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/3ee67903c01aa612.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/420258bb92561146.png b/site/en/codelabs/openthread-network-simulator/img/420258bb92561146.png deleted file mode 100644 index 082afe24..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/420258bb92561146.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/46cc2088c9aa7ab6.png b/site/en/codelabs/openthread-network-simulator/img/46cc2088c9aa7ab6.png index e4829a66..7dc93aa2 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/46cc2088c9aa7ab6.png and b/site/en/codelabs/openthread-network-simulator/img/46cc2088c9aa7ab6.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/4c5b43509a2ca0d0.png b/site/en/codelabs/openthread-network-simulator/img/4c5b43509a2ca0d0.png deleted file mode 100644 index 85addd28..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/4c5b43509a2ca0d0.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/6ca8c2e63ed9818d.png b/site/en/codelabs/openthread-network-simulator/img/6ca8c2e63ed9818d.png deleted file mode 100644 index 52b28728..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/6ca8c2e63ed9818d.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/7370a7841861aa3a.png b/site/en/codelabs/openthread-network-simulator/img/7370a7841861aa3a.png deleted file mode 100644 index 5c5a24a2..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/7370a7841861aa3a.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/7ca085f470491dd4.png b/site/en/codelabs/openthread-network-simulator/img/7ca085f470491dd4.png index c9760a04..c772242b 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/7ca085f470491dd4.png and b/site/en/codelabs/openthread-network-simulator/img/7ca085f470491dd4.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/7ff6afd565f4eafc.png b/site/en/codelabs/openthread-network-simulator/img/7ff6afd565f4eafc.png index 06d7a728..8280fc4b 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/7ff6afd565f4eafc.png and b/site/en/codelabs/openthread-network-simulator/img/7ff6afd565f4eafc.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/89618191721e79a0.png b/site/en/codelabs/openthread-network-simulator/img/89618191721e79a0.png index 2775aab8..37d31981 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/89618191721e79a0.png and b/site/en/codelabs/openthread-network-simulator/img/89618191721e79a0.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/8c6a2e191cdae0c7.png b/site/en/codelabs/openthread-network-simulator/img/8c6a2e191cdae0c7.png deleted file mode 100644 index 3f58c00c..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/8c6a2e191cdae0c7.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/9329157c1bd12672.png b/site/en/codelabs/openthread-network-simulator/img/9329157c1bd12672.png index c499ca1d..9968a904 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/9329157c1bd12672.png and b/site/en/codelabs/openthread-network-simulator/img/9329157c1bd12672.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/9ba305c4c5a5f892.png b/site/en/codelabs/openthread-network-simulator/img/9ba305c4c5a5f892.png deleted file mode 100644 index af450497..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/9ba305c4c5a5f892.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/a0e05178d66929b1.png b/site/en/codelabs/openthread-network-simulator/img/a0e05178d66929b1.png deleted file mode 100644 index e49061e1..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/a0e05178d66929b1.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/a3bf58d9d125f95f.png b/site/en/codelabs/openthread-network-simulator/img/a3bf58d9d125f95f.png deleted file mode 100644 index 6de48886..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/a3bf58d9d125f95f.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/c06b4d0a4f183299.png b/site/en/codelabs/openthread-network-simulator/img/c06b4d0a4f183299.png deleted file mode 100644 index 30c78489..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/c06b4d0a4f183299.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/ce25eda3496ffcd4.png b/site/en/codelabs/openthread-network-simulator/img/ce25eda3496ffcd4.png index 3367ffae..de80505d 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/ce25eda3496ffcd4.png and b/site/en/codelabs/openthread-network-simulator/img/ce25eda3496ffcd4.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/d4079cceea0105f0.png b/site/en/codelabs/openthread-network-simulator/img/d4079cceea0105f0.png deleted file mode 100644 index e1bc79b5..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/d4079cceea0105f0.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/e3d32f85c4a1b990.png b/site/en/codelabs/openthread-network-simulator/img/e3d32f85c4a1b990.png deleted file mode 100644 index 9436eae4..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/e3d32f85c4a1b990.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/img/f5f460b2586d299b.png b/site/en/codelabs/openthread-network-simulator/img/f5f460b2586d299b.png index c67c995d..670f374b 100644 Binary files a/site/en/codelabs/openthread-network-simulator/img/f5f460b2586d299b.png and b/site/en/codelabs/openthread-network-simulator/img/f5f460b2586d299b.png differ diff --git a/site/en/codelabs/openthread-network-simulator/img/fe15d6f9726a099e.png b/site/en/codelabs/openthread-network-simulator/img/fe15d6f9726a099e.png deleted file mode 100644 index aeba34a3..00000000 Binary files a/site/en/codelabs/openthread-network-simulator/img/fe15d6f9726a099e.png and /dev/null differ diff --git a/site/en/codelabs/openthread-network-simulator/index.lab.md b/site/en/codelabs/openthread-network-simulator/index.lab.md index 6c650647..0d7f0d3a 100644 --- a/site/en/codelabs/openthread-network-simulator/index.lab.md +++ b/site/en/codelabs/openthread-network-simulator/index.lab.md @@ -2,7 +2,7 @@ id: openthread-network-simulator summary: In this codelab, you'll use the OTNS CLI and web visualization to add/move/delete nodes in a simulated Thread network and observe how the network adapts to topology changes. status: [final] -authors: Simon Lin, Colin Tan +authors: Simon Lin, Colin Tan, Esko Dijk categories: Nest tags: web layout: scrolling @@ -21,13 +21,13 @@ book: /_book.yaml -5abd22afa2f2ee9a.png +Impression of a Thread mesh network topology ### 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. +adapt to topology changes to avoid a single point of failure. > aside positive > @@ -42,44 +42,39 @@ OpenThread supports all features defined in the [OpenThread Network Simulator (OTNS)](http://github.com/openthread/ot-ns) 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. +and operating simulated Thread networks. Scripted simulations (with Python) is +also possible. ### 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 +* Get to know the basics of the OTNS-CLI +* How to add/move/delete OpenThread nodes in OTNS-Web +* Use OTNS-Web's other useful features to control the network simulation * Verify OpenThread's no-single-point-of-failure +* See the data traffic between OpenThread nodes in Wireshark -This codelab is focused on OTNS-CLI and OTNS-Web. OTNS's other features, such as -Python scripting, are not covered. +This codelab is focused on OTNS-CLI and OTNS-Web for interactive use. OTNS's +other features, such as Python scripting, are not covered. ### What you'll need -* Linux x86_64 or Mac OS. +* Preferably Linux x86_64, or Mac OS with [Homebrew](https://brew.sh/). Ubuntu 22/24 in Windows + [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) should also work but may require some manual + tweaking of settings. * [Git](https://git-scm.com/downloads). -* [Go 1.13+](https://golang.org/dl/). -* Web browser. OTNS-Web uses a web browser for displaying simulations. +* Web browser. OTNS-Web uses a web browser for displaying simulations. * [Thread Primer](https://openthread.io/guides/thread-primer). You will need to know the basic concepts of Thread to understand what is taught in this Codelab. +### Terminology -## Installation -Duration: 05:00 - - -### Install Go - -OTNS requires Go 1.13+ to build. +The term "Router" is used as the technical term for the Thread Mesh Extender, which was initially called a +Thread Router. "Node" refers to any simulated OpenThread device in an OTNS simulation. -1. Install Go from [https://golang.org/dl/](https://golang.org/dl/) -2. Add `$(go env GOPATH)/bin` (normally `$HOME/go/bin`) to `$PATH`: - -```console -$ export PATH=$PATH:$(go env GOPATH)/bin -``` +## Installation +Duration: 10:00 ### Get OTNS code @@ -88,79 +83,57 @@ $ git clone https://github.com/openthread/ot-ns.git ./otns $ cd otns ``` -### Install Dependencies - -```console -$ ./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`: - -```console -$ ./script/install -otns installed: /usr/local/google/home/simonlin/go/bin/otns -``` - -#### Let's check if `otns` is properly installed +All subsequent console commands in this Codelab are run from the `otns` directory. -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.` +### Bootstrap and install - -## Build OpenThread for OTNS -Duration: 05:00 - - -### Get OpenThread code from GitHub +The `bootstrap` script will install dependencies (including Python3 and Go/Golang, if needed) and install OTNS. +It also builds the various OT node types that can be used directly in a simulation, and it performs some basic tests. +Due to the node builds, it can take several minutes. ```console -$ mkdir -p ~/src -$ git clone https://github.com/openthread/openthread ~/src/openthread +$ ./script/bootstrap +.... +.... +OTNS installed - use 'otns' to start it. +$ ``` -### Build OpenThread with `OTNS=1` +You might be asked to input a password for `sudo`. -```console -$ 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 -``` +### If `otns` is not properly installed -You can find the OpenThread executables in the `build` directory: +The script may report an error like: ```console -$ ls ~/src/openthread/build/simulation/examples/apps/cli/ -ot-cli-ftd ot-cli-mtd ot-cli-radio +.... +OTNS installed - please add ~/go/bin to your PATH variable first, to use it. +$ ``` -Now it's time to run OTNS... +In this case, you need to add `$(go env GOPATH)/bin` to your `$PATH.` +In case of other errors, a [GitHub issue](https://github.com/openthread/ot-ns/issues) can be created. -## Run OTNS +## Run OTNS for the first time Duration: 01:00 Run `otns`: ```console -$ cd ~/src/openthread/build/simulation/examples/apps/cli $ otns -> ← OTNS-CLI prompt +>_ ← 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 +OTNS-Web window at start **If you can only see a blank page for OTNS-Web, chances are WebGL is not -enabled in your browser. Please refer to** -[**https://superuser.com/a/836833**](https://superuser.com/a/836833) **on how to +enabled in your browser. Please refer to +[**https://superuser.com/a/836833**](https://superuser.com/a/836833) on how to enable WebGL.** In the following sections, you are going to learn to manage OTNS simulations @@ -173,12 +146,11 @@ Duration: 02:00 ### OTNS-CLI -`OTNS-CLI` provides a Command Line Interface (CLI) for managing OTNS simulations. +`OTNS-CLI` is the Command Line Interface (CLI) for managing OTNS simulations. ```console -$ cd ~/src/openthread/build/simulation/examples/apps/cli $ otns -> ← OTNS-CLI prompt +>_ ← OTNS-CLI prompt ``` You can type in commands through `OTNS-CLI`. Refer to the @@ -186,13 +158,37 @@ You can type in commands through `OTNS-CLI`. Refer to the for a full list of commands. Don't worry, you are only going to use a few of these commands in this Codelab. +Type the `help` command for an overview of CLI commands. This list is identical to the CLI reference. + +```console +> help +add Add a node to the simulation and get the node ID. +.... +.... +Done +> +``` + +To get more help on a specific command, use the command's name, for example: + +```console +> help add +add + Add a node to the simulation and get the node ID. + +Definition: +.... +.... +> +``` + ### 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 +OTNS-Web elements explained ## Add Nodes @@ -201,10 +197,10 @@ Duration: 05:00 ### Add nodes through OTNS-CLI -Add a Router at position (300, 100) +Add a Thread Router into the simulation: ```console -> add router x 300 y 100 +> add router 1 Done ``` @@ -212,7 +208,10 @@ 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 +One node in the Leader role + +To make it easy to start simulations interactively, each new OpenThread node is by default commissioned with a +standard set of network parameters. > aside positive > @@ -220,51 +219,58 @@ becomes a Leader in a few seconds: ### Add more nodes through `OTNS-CLI` +Now we will add some nodes of different types. + ```console -> add fed x 200 y 100 +> add fed 2 Done -> add med x 400 y 100 +> add med 3 Done -> add sed x 300 y 200 +> add sed 4 Done ``` Wait a few seconds for nodes to merge into one partition. You should see the -nodes in `OTNS-WEB`: +nodes in `OTNS-Web`: -3ee67903c01aa612.png +Thread Network with 4 nodes > aside positive > > **Tip:** The green line between nodes indicates that the nodes are linked and -the Leader is the parent of FED, MED, and SED. +the Leader is the parent of the FED, MED, and SED. + +Also in `OTNS-Web`, it's possible to select any of the nodes to get a panel with more information about the node. +For example, in the below figure node 1 is selected. The "Role" entry in the panel confirms that it is a Leader. + +Thread Network with 4 nodes, node 1 is selected > aside positive > -> **Tip:** The last added node is selected by default and highlighted using a -green dashed square. +> **Tip:** The selected node is highlighted using a green dashed square and green circle. ### 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: +`Action Bar`. You should see a node being created to the right of the selected node. +The new router should join the existing Thread partition: + +A Router is added, total 5 nodes -420258bb92561146.png +Also click the FED, MED, SSED, and BR buttons on the Action Bar to create these other types +of nodes. There should now be 9 nodes in total. +If you want, drag some nodes around to other positions, to create a different physical network topology. -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: +Multiple new nodes added, total 9 nodes -fe15d6f9726a099e.png > aside positive > -> **Tip:** The blue line between Leader and Router indicates that they're linked. +> **Tip:** A blue line between Leader, Router and FEDs indicates that they're linked. +> Blue indicates it is not a Parent/Child link, but something else, such as a Router-to-Router link. 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 @@ -324,36 +330,36 @@ Setting simulating speed to a value larger than `0` resumes the simulation. #### Speed control buttons -Find the speed control buttons 9329157c1bd12672.png +Find the speed control buttons Speed control buttons 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 +Increase-speed button button until the speed reaches -`MAX`: f5f460b2586d299b.png. +`MAX`: MAX simulation speed indicator. #### Slow down simulation You can slow down the simulation by clicking the -31cca8d5b52fa900.png +Decrease-speed button button. #### Pause simulation -Click the 46cc2088c9aa7ab6.png +Click the Pause button button to pause the simulation when it's running. The button will be changed to -ce25eda3496ffcd4.png. +Play button. #### Resume simulation Click the -ce25eda3496ffcd4.png +Play button button to resume the simulation when it's paused. The button will be changed back to -46cc2088c9aa7ab6.png. +Pause button. ### Set simulating speed to `10X` @@ -371,30 +377,23 @@ Done Duration: 01:00 -Now, the simulation should contain 2 Routers (hexagon shape) and many children, +Now, the simulation should contain at least 2 Routers (hexagon shape), possibly a Border Router (square 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 - -> aside positive -> -> **Tip:** The current selected node is highlighted using a green dashed square. +Thread Network with Leader node 1 selected ### Turn off radio -Click the 7ca085f470491dd4.png -button on the Action Bar to turn off the radio of the Leader node: - -a3bf58d9d125f95f.png - +Click the Radio Off button +button on the Action Bar to turn off the radio of the Leader node. 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 +Wait for about 12s (120s in simulating time) for the other Router or Border Router to become the new Leader: -e3d32f85c4a1b990.png +New partition is formed with node 9 as the new Leader 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. @@ -402,10 +401,10 @@ 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 +Radio on button button on `Action Bar` to restore radio connectivity: -7370a7841861aa3a.png +Node 1 joins the partition after its radio is on again The Leader should reattach to the network after radio connectivity is restored. @@ -418,30 +417,25 @@ 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 the Border Router node 9 to a new location: ```console -> move 5 600 300 +> move 9 50 50 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 - -> aside positive -> -> **Tip:** Nodes have limited radio transmission range in OTNS simulation. - ### Move node through OTNS-Web -Move node 5 back to the original location by dragging. The two partitions should -merge back into one partition: +Move node 5 all the way to the bottom right, by dragging. Because node 5 is now out of radio coverage of +the other Routers, it forms its own partition with a new Partition ID. The Partition IDs can be checked +on the node information panel by clicking the nodes. -9ba305c4c5a5f892.png +Node 5 is moved away from the other nodes and forms a new partition +Note that a single green line is still drawn between node 5 and node 9. This is often due to stale information about a +child, which is still kept in the child table of a former parent. Or it could be stale information about the former +router-to-router link between node 9 and node 5. (Or possibly, in this case, even a rendering bug.) +Eventually, stale information is cleaned up on the nodes after the appropriate timeout. ## Delete Nodes Duration: 01:00 @@ -449,39 +443,27 @@ Duration: 01:00 ### Delete nodes through `OTNS-CLI` -Delete node 8: +Delete node 5: ```console -> del 8 +> del 5 Done ``` -Node 8 should disappear from the simulation: +Node 5 should disappear from the simulation: -18156770d9f8bf83.png +Node 5 is deleted from the simulation ### Delete nodes through `OTNS-Web` -Select node 5 and click the -7ff6afd565f4eafc.png -button on the `Action Bar` to delete node 5: +Select the Border Router node 9 and click the +Delete button +button on the `Action Bar` to delete node 9: -d4079cceea0105f0.png +Border Router node 9 is deleted -`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. +`Node 1` should become Leader of a new partition and all remaining nodes will attach as a Child +to node 1. ## OTNS-CLI Node Context @@ -489,7 +471,7 @@ Duration: 02:00 `OTNS-CLI` provides node context mode for easy interaction with nodes to help -developers diagnose a node's status. +developers diagnose a node's status. Also node actions can be initiated from this mode. ### Enter node context mode @@ -519,13 +501,14 @@ node 1> panid 0xface Done node 1> networkname -OpenThread +otns 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 +fdde:ad00:beef:0:0:ff:fe00:b400 +fd00:f00d:cafe:0:2505:8719:3685:ebfb +fdde:ad00:beef:0:4fd9:b9ba:44e0:96cb +fe80:0:0:0:e86a:e07:ec97:777 Done ``` @@ -545,6 +528,67 @@ Done > ``` +An alternative way to exit node context is the `node 0` command. + +## Viewing node logs and packet captures +Duration: 05:00 + +### OpenThread node logs + +By default, OTNS generates detailed log files for all simulated OpenThread nodes. These can be viewed in the `./tmp` +directory. The filename is `0_.log`. For example, a log file excerpt is shown below: + +```log +7616488 00:00:06.326 [I] MeshForwarder-: Received IPv6 UDP msg, len:90, chksum:5915, ecn:no, from:ca72650db7b856af, sec:no, prio:net, rss:-58.0 +7616488 00:00:06.326 [I] MeshForwarder-: src:[fe80:0:0:0:c872:650d:b7b8:56af]:19788 +7616488 00:00:06.326 [I] MeshForwarder-: dst:[ff02:0:0:0:0:0:0:1]:19788 +7616488 00:00:06.326 [D] Mle-----------: Receive MLE message +7616488 00:00:06.326 [D] Mac-----------: Idle mode: Radio receiving on channel 11 +7657544 00:00:06.367 [D] Mac-----------: ==============================[RX len=063]============================== +7657544 00:00:06.367 [D] Mac-----------: | 41 D8 7F CE FA FF FF 46 | 74 5A 33 9E 76 51 4E 7F | A......FtZ3.vQN. | +7657544 00:00:06.367 [D] Mac-----------: | 3B 02 F0 4D 4C 4D 4C 81 | E6 00 15 03 00 00 00 00 | ;..MLML......... | +7657544 00:00:06.367 [D] Mac-----------: | 00 00 00 01 46 86 7D FE | 06 CC DB 94 86 9C 88 0B | ....F.}......... | +7657544 00:00:06.367 [D] Mac-----------: | 1C 1E 26 9B 8D 21 2E 65 | 53 5A 43 4E A2 59 D6 | ..&..!.eSZCN.Y. | +7657544 00:00:06.367 [D] Mac-----------: ------------------------------------------------------------------------ +7657544 00:00:06.367 [I] MeshForwarder-: Received IPv6 UDP msg, len:84, chksum:81e6, ecn:no, from:4e51769e335a7446, sec:no, prio:net, rss:-48.0 +7657544 00:00:06.367 [I] MeshForwarder-: src:[fe80:0:0:0:4c51:769e:335a:7446]:19788 +7657544 00:00:06.367 [I] MeshForwarder-: dst:[ff02:0:0:0:0:0:0:2]:19788 +7657544 00:00:06.367 [D] Mac-----------: Idle mode: Radio receiving on channel 11 +7833912 00:00:06.543 [I] Mle-----------: AttachState ParentReq -> Idle +7833912 00:00:06.543 [N] RouterTable---: Allocate router id 12 +7833912 00:00:06.543 [N] Mle-----------: RLOC16 fffe -> 3000 +7833912 set node RLOC16: fffe -> 3000 +7833912 00:00:06.543 [D] SubMac--------: RadioShortAddress: 0x3000 +7833912 00:00:06.543 [N] Mle-----------: Role detached -> leader +7833912 00:00:06.543 [N] Mle-----------: Partition ID 0x24c35f10 +7833912 00:00:06.543 [I] RouterTable---: Route table +7833912 00:00:06.543 [I] RouterTable---: 12 0x3000 - me - leader +``` + +The absolute simulation time in microseconds is shown on the left. The `hh:mm:ss` timestamp shows the OpenThread node's +own log timestamp, which may differ from the absolute simulation time. + +### Wireshark packet captures + +By default, all transmitted IEEE 802.15.4 frames are captures in the PCAP file `current.pcap`. This file can be read +by [Wireshark](https://www.wireshark.org/) during or after the simulation. Due to the link-layer encryption of +Thread, a one-time configuration action in Wireshark is needed to set the decryption key for OTNS properly. By +default, one well-known Network Key is used so that frame decryption by Wireshark is made easy. + +See the below screenshot for an example of OpenThread packet inspection in Wireshark. + +Screenshot of OpenThread packet analysis in Wireshark + +To configure the decryption key, select in the menu **Edit -> Preferences**. Then in the preferences window, select +**Protocols -> IEEE 802.15.4**. Click the **Edit...** button next to "Decryption Keys". Click **+** to create a new entry +and enter the key `00112233445566778899aabbccddeeff` (32 characters) and select "Thread hash" in the "Key hash" field. +The "Decryption key index" can be left to `0`. Then click **OK**, and **OK** again. Now the OTNS PCAP file should +properly decrypt when loaded. + +The timestamps shown in the "Time" column (in seconds) correspond to the absolute simulation time values shown in the +OpenThread node logs. This makes it easier to correlate log messages with transmitted or received radio frames. +However, the values are typically not identical up to single microsecond precision: the simulated IEEE 802.15.4 +radio hardware may add some additional delay, after a radio frame is requested to be sent by the OpenThread stack. ## Congratulations @@ -552,9 +596,8 @@ Done Congratulations, you've successfully executed your first OTNS simulation! -You've learned how to install OTNS and its dependencies. You built -[OpenThread](https://github.com/openthread/openthread) for OTNS and started OTNS -simulation with OpenThread simulation instances. You've learned how to +You've learned how to install OTNS and its dependencies. You started an OTNS +simulation with OpenThread simulated nodes. 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 @@ -576,7 +619,7 @@ Check out some of these codelabs... ## License -Copyright (c) 2021-2022, The OpenThread Authors. +Copyright (c) 2021-2024, The OpenThread Authors. All rights reserved. Redistribution and use in source and binary forms, with or without