From 86ac0865a38e53cabe115ca5e1980901427788aa Mon Sep 17 00:00:00 2001 From: Jonathan Hui Date: Tue, 21 May 2019 09:02:07 -0700 Subject: [PATCH] [docs] update quick start guides to use dataset method (#3834) --- examples/apps/cli/README.md | 55 +++++---- examples/platforms/efr32/README.md | 152 ++++++++++++++----------- examples/platforms/emsk/README.md | 119 +++++++++++--------- examples/platforms/kw41z/README.md | 89 +++++++++------ examples/platforms/nrf52811/README.md | 57 ++++++---- examples/platforms/nrf52840/README.md | 39 +++++-- examples/platforms/samr21/README.md | 153 +++++++++++++++----------- 7 files changed, 396 insertions(+), 268 deletions(-) diff --git a/examples/apps/cli/README.md b/examples/apps/cli/README.md index 9dd19befc..fc1ea1a88 100644 --- a/examples/apps/cli/README.md +++ b/examples/apps/cli/README.md @@ -1,10 +1,6 @@ # OpenThread CLI Example -This example application demonstrates a minimal OpenThread application -that exposes the OpenThread configuration and management interfaces -via a basic command-line interface. The steps below take you through -the minimal steps required to ping one emulated Thread device from -another emulated Thread device. +This example application exposes OpenThread configuration and management APIs via a simple command-line interface. The steps below take you through the minimal steps required to ping one emulated Thread device from another emulated Thread device. ## 1. Build @@ -23,10 +19,25 @@ $ cd /output//bin $ ./ot-cli-ftd 1 ``` -Set the PAN ID: +Generate, view, and commit a new Active Operational Dataset: ```bash -> panid 0x1234 +> dataset init new +Done +> dataset +Active Timestamp: 1 +Channel: 13 +Channel Mask: 07fff800 +Ext PAN ID: d63e8e3e495ebbc3 +Mesh Local Prefix: fd3d:b50b:f96d:722d/64 +Master Key: dfd34f0f05cad978ec4e32b0413038ff +Network Name: OpenThread-8f28 +PAN ID: 0x8f28 +PSKc: c23a76e98f1a6483639b1ac1271e2e27 +Security Policy: 0, onrcb +Done +> dataset commit active +Done ``` Bring up the IPv6 interface: @@ -55,9 +66,10 @@ View IPv6 addresses assigned to Node 1's Thread interface: ```bash > ipaddr -fdde:ad00:beef:0:0:ff:fe00:0 -fdde:ad00:beef:0:558:f56b:d688:799 -fe80:0:0:0:f3d9:2a82:c8d8:fe43 +fd3d:b50b:f96d:722d:0:ff:fe00:fc00 +fd3d:b50b:f96d:722d:0:ff:fe00:c00 +fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 +fe80:0:0:0:6c41:9001:f3d6:4148 Done ``` @@ -70,10 +82,15 @@ $ cd /output//bin $ ./ot-cli-ftd 2 ``` -Set the PAN ID: +Configure Thread Master Key and PAN ID from Node 1's Active Operational Dataset: ```bash -> panid 0x1234 +> dataset masterkey dfd34f0f05cad978ec4e32b0413038ff +Done +> dataset panid 0x8f28 +Done +> dataset commit active +Done ``` Bring up the IPv6 interface: @@ -90,23 +107,21 @@ Start Thread protocol operation: Done ``` -Wait a few seconds and verify that the device has become a Thread Router: +Wait a few seconds and verify that the device has become a Thread Child or Router: ```bash > state -router +child Done ``` ## 3. Ping Node 1 from Node 2 ```bash -> ping fdde:ad00:beef:0:558:f56b:d688:799 -16 bytes from fdde:ad00:beef:0:558:f56b:d688:799: icmp_seq=1 hlim=64 +> ping fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 +16 bytes from fd3d:b50b:f96d:722d:558:f56b:d688:799: icmp_seq=1 hlim=64 time=24ms ``` -## 4. Want more? +## 4. Explore More -You may note that the example above did not include any network parameter configuration, such as the IEEE 802.15.4 PAN ID or the Thread Master Key. OpenThread currently implements default values for network parameters, however, you may use the CLI to change network parameters, other configurations, and perform other operations. - -See the [OpenThread CLI Reference README.md](../../../src/cli/README.md) to explore more. +See the [OpenThread CLI Reference README.md](../../../src/cli/README.md) to explore more. \ No newline at end of file diff --git a/examples/platforms/efr32/README.md b/examples/platforms/efr32/README.md index 26a946f67..3d26c5a8f 100644 --- a/examples/platforms/efr32/README.md +++ b/examples/platforms/efr32/README.md @@ -142,90 +142,108 @@ Click the Flash button located under the Browse... button. 2. Open terminal to first device `/dev/ttyACM0` (serial port settings: 115200 8-N-1). Type `help` for a list of commands. -```bash -> help -help -channel -childtimeout -contextreusedelay -extaddr -extpanid -ipaddr -keysequence -leaderweight -masterkey -mode -netdataregister -networkidtimeout -networkname -panid -ping -prefix -releaserouterid -rloc16 -route -routerupgradethreshold -scan -start -state -stop -whitelist -``` + ```bash + > help + help + channel + childtimeout + contextreusedelay + extaddr + extpanid + ipaddr + keysequence + leaderweight + masterkey + mode + netdataregister + networkidtimeout + networkname + panid + ping + prefix + releaserouterid + rloc16 + route + routerupgradethreshold + scan + start + state + stop + whitelist + ``` 3. Start a Thread network as Leader. -```bash -> panid 0xface -Done -> ifconfig up -Done -> thread start -Done + ```bash + > dataset init new + Done + > dataset + Active Timestamp: 1 + Channel: 13 + Channel Mask: 07fff800 + Ext PAN ID: d63e8e3e495ebbc3 + Mesh Local Prefix: fd3d:b50b:f96d:722d/64 + Master Key: dfd34f0f05cad978ec4e32b0413038ff + Network Name: OpenThread-8f28 + PAN ID: 0x8f28 + PSKc: c23a76e98f1a6483639b1ac1271e2e27 + Security Policy: 0, onrcb + Done + > dataset commit active + Done + > ifconfig up + Done + > thread start + Done -wait a couple of seconds... + wait a couple of seconds... -> state -leader -Done -``` + > state + leader + Done + ``` 4. Open terminal to second device `/dev/ttyACM1` (serial port settings: 115200 8-N-1) and attach it to the Thread network as a Router. -```bash -> panid 0xface -Done -> routerselectionjitter 1 -Done -> ifconfig up -Done -> thread start -Done + ```bash + > dataset masterkey dfd34f0f05cad978ec4e32b0413038ff + Done + > dataset panid 0x8f28 + Done + > dataset commit active + Done + > routerselectionjitter 1 + Done + > ifconfig up + Done + > thread start + Done -wait a couple of seconds... + wait a couple of seconds... -> state -router -Done -``` + > state + router + Done + ``` 5. List all IPv6 addresses of Leader. -```bash -> ipaddr -fdde:ad00:beef:0:0:ff:fe00:fc00 -fdde:ad00:beef:0:0:ff:fe00:800 -fdde:ad00:beef:0:5b:3bcd:deff:7786 -fe80:0:0:0:6447:6e10:cf7:ee29 -Done -``` + ```bash + > ipaddr + fd3d:b50b:f96d:722d:0:ff:fe00:fc00 + fd3d:b50b:f96d:722d:0:ff:fe00:c00 + fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + fe80:0:0:0:6c41:9001:f3d6:4148 + Done + ``` 6. Send an ICMPv6 ping to Leader's Mesh-EID IPv6 address. -```bash -> ping fdde:ad00:beef:0:5b:3bcd:deff:7786 -8 bytes from fdde:ad00:beef:0:5b:3bcd:deff:7786: icmp_seq=1 hlim=64 time=24ms -``` + ```bash + > ping fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + 16 bytes from fd3d:b50b:f96d:722d:558:f56b:d688:799: icmp_seq=1 hlim=64 time=24ms + ``` The above example demonstrates basic OpenThread capabilities. Enable more features/roles (e.g. commissioner, joiner, DHCPv6 Server/Client, etc.) by assigning compile-options before compiling. diff --git a/examples/platforms/emsk/README.md b/examples/platforms/emsk/README.md index de9ae9351..9f383a76f 100644 --- a/examples/platforms/emsk/README.md +++ b/examples/platforms/emsk/README.md @@ -67,80 +67,99 @@ Modify the file name `arc-elf32-ot-cli-ftd.bin` to `boot.bin`. Copy `boot.bin` t 3. Open a terminal connection on the first board. The `boot.bin` in the SD card will be loaded to the EMSK after a few seconds. - ```bash - MRF24J40 Init started. - MRF24J40 Init finished. - Node No. : - ``` + ```bash + MRF24J40 Init started. + MRF24J40 Init finished. + Node No. : + ``` 4. Set the node number manually. Input `1` and press the `Enter` key in the terminal emulator. - ```bash - Node No. :1 - OpenThread Init Finished - ``` + ```bash + Node No. :1 + OpenThread Init Finished +``` 4. Start a new Thread network. - ```bash - > panid 0x1234 - Done - > ifconfig up - Done - > thread start - Done - ``` + ```bash + > dataset init new + Done + > dataset + Active Timestamp: 1 + Channel: 13 + Channel Mask: 07fff800 + Ext PAN ID: d63e8e3e495ebbc3 + Mesh Local Prefix: fd3d:b50b:f96d:722d/64 + Master Key: dfd34f0f05cad978ec4e32b0413038ff + Network Name: OpenThread-8f28 + PAN ID: 0x8f28 + PSKc: c23a76e98f1a6483639b1ac1271e2e27 + Security Policy: 0, onrcb + Done + > dataset commit active + Done + > ifconfig up + Done + > thread start + Done + ``` 4. After a couple of seconds the node will become a Leader of the network. - ```bash - > state - Leader - ``` + ```bash + > state + leader + ``` 5. Open a terminal connection and reset the second board. After a few seconds, input `2` and press the `Enter` key in the terminal emulator. - ```bash - MRF24J40 Init started. - MRF24J40 Init finished. - Node No. :2 - OpenThread Init Finished - ``` + ```bash + MRF24J40 Init started. + MRF24J40 Init finished. + Node No. :2 + OpenThread Init Finished + ``` 6. Attach the second node to the network. - ```bash - > panid 0x1234 - Done - > ifconfig up - Done - > thread start - Done - ``` + ```bash + > dataset masterkey dfd34f0f05cad978ec4e32b0413038ff + Done + > dataset panid 0x8f28 + Done + > dataset commit active + Done + > ifconfig up + Done + > thread start + Done + ``` 6. After a couple of seconds the second node will attach and become a Child. - ```bash - > state - Child - ``` + ```bash + > state + child + ``` 7. List all IPv6 addresses of the first board. - ```bash - > ipaddr - fdde:ad00:beef:0:0:ff:fe00:fc00 - fdde:ad00:beef:0:0:ff:fe00:ec00 - fdde:ad00:beef:0:4f6e:7e53:67c8:f5b0 - fe80:0:0:0:c462:f165:44eb:ef9f - ``` + ```bash + > ipaddr + fd3d:b50b:f96d:722d:0:ff:fe00:fc00 + fd3d:b50b:f96d:722d:0:ff:fe00:c00 + fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + fe80:0:0:0:6c41:9001:f3d6:4148 + Done + ``` 8. Choose one of them and send an ICMPv6 ping from the second board. - ```bash - > ping fdde:ad00:beef:0:0:ff:fe00:ec00 - 8 bytes from fdde:ad00:beef:0:0:ff:fe00:ec00: icmp_seq=1 hlim=64 time=30ms - ``` + ```bash + > ping fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + 16 bytes from fd3d:b50b:f96d:722d:558:f56b:d688:799: icmp_seq=1 hlim=64 time=24ms + ``` For a list of all available commands, visit [OpenThread CLI Reference README.md][CLI]. diff --git a/examples/platforms/kw41z/README.md b/examples/platforms/kw41z/README.md index 184c16731..e9d225ad2 100644 --- a/examples/platforms/kw41z/README.md +++ b/examples/platforms/kw41z/README.md @@ -62,56 +62,75 @@ The [NXP(Freescale) Test Tool][test-tool] provides a convenient method for flash 3. Open a terminal connection on the first board and start a new Thread network. - ```bash - > panid 0xabcd - Done - > ifconfig up - Done - > thread start - Done - ``` + ```bash + > dataset init new + Done + > dataset + Active Timestamp: 1 + Channel: 13 + Channel Mask: 07fff800 + Ext PAN ID: d63e8e3e495ebbc3 + Mesh Local Prefix: fd3d:b50b:f96d:722d/64 + Master Key: dfd34f0f05cad978ec4e32b0413038ff + Network Name: OpenThread-8f28 + PAN ID: 0x8f28 + PSKc: c23a76e98f1a6483639b1ac1271e2e27 + Security Policy: 0, onrcb + Done + > dataset commit active + Done + > ifconfig up + Done + > thread start + Done + ``` 4. After a couple of seconds the node will become a Leader of the network. - ```bash - > state - Leader - ``` + ```bash + > state + leader + ``` 5. Open a terminal connection on the second board and attach a node to the network. - ```bash - > panid 0xabcd - Done - > ifconfig up - Done - > thread start - Done - ``` + ```bash + > dataset masterkey dfd34f0f05cad978ec4e32b0413038ff + Done + > dataset panid 0x8f28 + Done + > dataset commit active + Done + > ifconfig up + Done + > thread start + Done + ``` 6. After a couple of seconds the second node will attach and become a Child. - ```bash - > state - Child - ``` + ```bash + > state + child + ``` 7. List all IPv6 addresses of the first board. - ```bash - > ipaddr - fdde:ad00:beef:0:0:ff:fe00:fc00 - fdde:ad00:beef:0:0:ff:fe00:9c00 - fdde:ad00:beef:0:4bcb:73a5:7c28:318e - fe80:0:0:0:5c91:c61:b67c:271c - ``` + ```bash + > ipaddr + fd3d:b50b:f96d:722d:0:ff:fe00:fc00 + fd3d:b50b:f96d:722d:0:ff:fe00:c00 + fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + fe80:0:0:0:6c41:9001:f3d6:4148 + Done + ``` 8. Choose one of them and send an ICMPv6 ping from the second board. - ```bash - > ping fdde:ad00:beef:0:0:ff:fe00:fc00 - 16 bytes from fdde:ad00:beef:0:0:ff:fe00:fc00: icmp_seq=1 hlim=64 time=8ms - ``` + ```bash + > ping fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + 16 bytes from fd3d:b50b:f96d:722d:558:f56b:d688:799: icmp_seq=1 hlim=64 time=24ms + ``` For a list of all available commands, visit [OpenThread CLI Reference README.md][CLI]. diff --git a/examples/platforms/nrf52811/README.md b/examples/platforms/nrf52811/README.md index 1a87b7ad5..72007e46f 100644 --- a/examples/platforms/nrf52811/README.md +++ b/examples/platforms/nrf52811/README.md @@ -150,20 +150,34 @@ To test the example: 6. Use the following commands to form a network: ```bash - > panid 0xabcd - Done - > ifconfig up - Done - > thread start - Done + > dataset init new + Done + > dataset + Active Timestamp: 1 + Channel: 13 + Channel Mask: 07fff800 + Ext PAN ID: d63e8e3e495ebbc3 + Mesh Local Prefix: fd3d:b50b:f96d:722d/64 + Master Key: dfd34f0f05cad978ec4e32b0413038ff + Network Name: OpenThread-8f28 + PAN ID: 0x8f28 + PSKc: c23a76e98f1a6483639b1ac1271e2e27 + Security Policy: 0, onrcb + Done + > dataset commit active + Done + > ifconfig up + Done + > thread start + Done ``` - + After a couple of seconds the node will become a Leader of the network. - ```bash - > state - Leader - ``` + ```bash + > state + leader + ``` 7. Open a terminal connection on the second board and attach a node to the network: @@ -189,7 +203,11 @@ To test the example: 8. Use the following commands to attach to the network on the second board: ```bash - > panid 0xabcd + > dataset masterkey dfd34f0f05cad978ec4e32b0413038ff + Done + > dataset panid 0x8f28 + Done + > dataset commit active Done > ifconfig up Done @@ -201,24 +219,25 @@ To test the example: ```bash > state - Child + child ``` 9. List all IPv6 addresses of the first board. ```bash > ipaddr - fdde:ad00:beef:0:0:ff:fe00:fc00 - fdde:ad00:beef:0:0:ff:fe00:9c00 - fdde:ad00:beef:0:4bcb:73a5:7c28:318e - fe80:0:0:0:5c91:c61:b67c:271c + fd3d:b50b:f96d:722d:0:ff:fe00:fc00 + fd3d:b50b:f96d:722d:0:ff:fe00:c00 + fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + fe80:0:0:0:6c41:9001:f3d6:4148 + Done ``` 10. Choose one of them and send an ICMPv6 ping from the second board. ```bash - > ping fdde:ad00:beef:0:0:ff:fe00:fc00 - 16 bytes from fdde:ad00:beef:0:0:ff:fe00:fc00: icmp_seq=1 hlim=64 time=8ms + > ping fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + 16 bytes from fd3d:b50b:f96d:722d:558:f56b:d688:799: icmp_seq=1 hlim=64 time=24ms ``` For a list of all available commands, visit [OpenThread CLI Reference README.md][CLI]. diff --git a/examples/platforms/nrf52840/README.md b/examples/platforms/nrf52840/README.md index c166a8953..65367675c 100644 --- a/examples/platforms/nrf52840/README.md +++ b/examples/platforms/nrf52840/README.md @@ -201,7 +201,21 @@ To test the example: 3. Use the following commands to form a network on the first board. ```bash - > panid 0xabcd + > dataset init new + Done + > dataset + Active Timestamp: 1 + Channel: 13 + Channel Mask: 07fff800 + Ext PAN ID: d63e8e3e495ebbc3 + Mesh Local Prefix: fd3d:b50b:f96d:722d/64 + Master Key: dfd34f0f05cad978ec4e32b0413038ff + Network Name: OpenThread-8f28 + PAN ID: 0x8f28 + PSKc: c23a76e98f1a6483639b1ac1271e2e27 + Security Policy: 0, onrcb + Done + > dataset commit active Done > ifconfig up Done @@ -213,13 +227,17 @@ To test the example: ```bash > state - Leader + leader ``` 4. Use the following commands to attach to the network on the second board. ```bash - > panid 0xabcd + > dataset masterkey dfd34f0f05cad978ec4e32b0413038ff + Done + > dataset panid 0x8f28 + Done + > dataset commit active Done > ifconfig up Done @@ -231,24 +249,25 @@ To test the example: ```bash > state - Child + child ``` 5. List all IPv6 addresses of the first board. ```bash > ipaddr - fdde:ad00:beef:0:0:ff:fe00:fc00 - fdde:ad00:beef:0:0:ff:fe00:9c00 - fdde:ad00:beef:0:4bcb:73a5:7c28:318e - fe80:0:0:0:5c91:c61:b67c:271c + fd3d:b50b:f96d:722d:0:ff:fe00:fc00 + fd3d:b50b:f96d:722d:0:ff:fe00:c00 + fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + fe80:0:0:0:6c41:9001:f3d6:4148 + Done ``` 6. Choose one of them and send an ICMPv6 ping from the second board. ```bash - > ping fdde:ad00:beef:0:0:ff:fe00:fc00 - 16 bytes from fdde:ad00:beef:0:0:ff:fe00:fc00: icmp_seq=1 hlim=64 time=8ms + > ping fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + 16 bytes from fd3d:b50b:f96d:722d:558:f56b:d688:799: icmp_seq=1 hlim=64 time=24ms ``` For a list of all available commands, visit [OpenThread CLI Reference README.md][CLI]. diff --git a/examples/platforms/samr21/README.md b/examples/platforms/samr21/README.md index a85518a36..b715131f3 100644 --- a/examples/platforms/samr21/README.md +++ b/examples/platforms/samr21/README.md @@ -90,90 +90,109 @@ $ (gdb) c 2. Open terminal to first device `/dev/ttyACM0` (serial port settings: 115200 8-N-1). Type `help` for a list of commands. -```bash -> help -help -channel -childtimeout -contextreusedelay -extaddr -extpanid -ipaddr -keysequence -leaderweight -masterkey -mode -netdataregister -networkidtimeout -networkname -panid -ping -prefix -releaserouterid -rloc16 -route -routerupgradethreshold -scan -start -state -stop -whitelist -``` + ```bash + > help + help + channel + childtimeout + contextreusedelay + extaddr + extpanid + ipaddr + keysequence + leaderweight + masterkey + mode + netdataregister + networkidtimeout + networkname + panid + ping + prefix + releaserouterid + rloc16 + route + routerupgradethreshold + scan + start + state + stop + whitelist + ``` 3. Start a Thread network as Leader. -```bash -> panid 0xface -Done -> ifconfig up -Done -> thread start -Done + ```bash + > dataset init new + Done + > dataset + Active Timestamp: 1 + Channel: 13 + Channel Mask: 07fff800 + Ext PAN ID: d63e8e3e495ebbc3 + Mesh Local Prefix: fd3d:b50b:f96d:722d/64 + Master Key: dfd34f0f05cad978ec4e32b0413038ff + Network Name: OpenThread-8f28 + PAN ID: 0x8f28 + PSKc: c23a76e98f1a6483639b1ac1271e2e27 + Security Policy: 0, onrcb + Done + > dataset commit active + Done + > ifconfig up + Done + > thread start + Done + ``` -wait a couple of seconds... + wait a couple of seconds... -> state -leader -Done -``` + > state + leader + Done + ``` 4. Open terminal to second device `/dev/ttyACM1` (serial port settings: 115200 8-N-1) and attach it to the Thread network as a Router. -```bash -> panid 0xface -Done -> routerselectionjitter 1 -Done -> ifconfig up -Done -> thread start -Done + ```bash + > dataset masterkey dfd34f0f05cad978ec4e32b0413038ff + Done + > dataset panid 0x8f28 + Done + > dataset commit active + Done + > routerselectionjitter 1 + Done + > ifconfig up + Done + > thread start + Done -wait a couple of seconds... + wait a couple of seconds... -> state -router -Done -``` + > state + router + Done + ``` 5. List all IPv6 addresses of Leader. -```bash -> ipaddr -fdde:ad00:beef:0:0:ff:fe00:fc00 -fdde:ad00:beef:0:0:ff:fe00:800 -fdde:ad00:beef:0:5b:3bcd:deff:7786 -fe80:0:0:0:6447:6e10:cf7:ee29 -Done -``` + ```bash + > ipaddr + fd3d:b50b:f96d:722d:0:ff:fe00:fc00 + fd3d:b50b:f96d:722d:0:ff:fe00:c00 + fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + fe80:0:0:0:6c41:9001:f3d6:4148 + Done + ``` 6. Send an ICMPv6 ping to Leader's Mesh-EID IPv6 address. -```bash -> ping fdde:ad00:beef:0:5b:3bcd:deff:7786 -8 bytes from fdde:ad00:beef:0:5b:3bcd:deff:7786: icmp_seq=1 hlim=64 time=24ms -``` + ```bash + > ping fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 + 16 bytes from fd3d:b50b:f96d:722d:558:f56b:d688:799: icmp_seq=1 hlim=64 time=24ms + ``` The above example demonstrates basic OpenThread capabilities. Enable more features/roles (e.g. commissioner, joiner, DHCPv6 Server/Client, etc.) by assigning compile-options before compiling.