From 787184d4bb5bd6390176fe07cad868dfd4e54365 Mon Sep 17 00:00:00 2001 From: Jonathan Hui Date: Tue, 21 May 2019 13:01:01 -0700 Subject: [PATCH] [docs] enhance commissioning docs for CLI (#3862) - Separate into separate README files. - Add quick start guide. --- src/cli/README.md | 141 +---------------------- src/cli/README_COMMISSIONER.md | 198 ++++++++++++++++++++++++++++++++ src/cli/README_COMMISSIONING.md | 129 +++++++++++++++++++++ src/cli/README_JOINER.md | 68 +++++++++++ 4 files changed, 397 insertions(+), 139 deletions(-) create mode 100644 src/cli/README_COMMISSIONER.md create mode 100644 src/cli/README_COMMISSIONING.md create mode 100644 src/cli/README_JOINER.md diff --git a/src/cli/README.md b/src/cli/README.md index cfeb3da95..b9f0c62c6 100644 --- a/src/cli/README.md +++ b/src/cli/README.md @@ -16,7 +16,7 @@ OpenThread test scripts use the CLI to execute test cases. * [childtimeout](#childtimeout) * [coap](README_COAP.md) * [coaps](README_COAPS.md) -* [commissioner](#commissioner-start-provisioningurl) +* [commissioner](README_COMMISSIONER.md) * [contextreusedelay](#contextreusedelay) * [counters](#counters) * [dataset](README_DATASET.md) @@ -31,8 +31,7 @@ OpenThread test scripts use the CLI to execute test cases. * [ifconfig](#ifconfig) * [ipaddr](#ipaddr) * [ipmaddr](#ipmaddr) -* [joiner](#joiner-start-pskd-provisioningurl) -* [joinerid](#joinerid) +* [joiner](README_JOINER.md) * [joinerport](#joinerport-port) * [keysequence](#keysequence-counter) * [leaderdata](#leaderdata) @@ -232,108 +231,6 @@ Set the Thread Child Timeout value. Done ``` -### commissioner start \ - -Start the Commissioner role. - -* provisioningUrl: Provisioning URL for the Joiner (optional). - -This command will cause the device to send LEAD_PET and LEAD_KA messages. - -```bash -> commissioner start -Done -``` - -### commissioner stop - -Stop the Commissioner role. - -This command will cause the device to send LEAD_KA[Reject] messages. - -```bash -> commissioner stop -Done -``` - -### commissioner joiner add \ \ - -Add a Joiner entry. - -* eui64: The IEEE EUI-64 of the Joiner or '*' to match any Joiner. -* pskd: Pre-Shared Key for the Joiner. - -```bash -> commissioner joiner add d45e64fa83f81cf7 PSK -Done -``` - -### commissioner joiner remove \ - -Remove a Joiner entry. - -* eui64: The IEEE EUI-64 of the Joiner or '*' to match any Joiner. - -```bash -> commissioner joiner remove d45e64fa83f81cf7 -Done -``` - -### commissioner provisioningurl \ - -Set the Provisioning URL. - -```bash -> commissioner provisioningurl http://github.com/openthread/openthread -Done -``` - -### commissioner energy \ \ \ \ \ - -Send a MGMT_ED_SCAN message. - -* mask: Bitmask identifying channsl to perform IEEE 802.15.4 ED Scans. -* count: Number of IEEE 802.15.4 ED Scans per channel. -* period: Period between successive IEEE 802.15.4 ED Scans (milliseconds). -* scanDuration: IEEE 802.15.4 ScanDuration to use when performing an IEEE 802.15.4 ED Scan (milliseconds). -* destination: IPv6 destination for the message (may be multicast). - -The contents of MGMT_ED_REPORT messages (i.e. Channel Mask and Energy -List) are printed as they are received. - -```bash -> commissioner energy 0x00050000 2 32 1000 fdde:ad00:beef:0:0:ff:fe00:c00 -Done -Energy: 00050000 0 0 0 0 -``` - -### commissioner panid \ \ \ - -Send a MGMT_PANID_QUERY message. - -* panid: PAN ID to check for conflicts. -* mask: Bitmask identifying channels to perform IEEE 802.15.4 Active Scans. -* destination: IPv6 destination for the message (may be multicast). - -The contents of MGMT_PANID_CONFLICT messages (i.e. PAN ID and Channel -Mask) are printed as they are received. - -```bash -> commissioner panid 0xdead 0x7fff800 fdde:ad00:beef:0:0:ff:fe00:c00 -Done -Conflict: dead, 00000800 -``` - -### commissioner sessionid - -Get current commissioner session id. - -```bash -> commissioner sessionid -0 -Done -``` - ### contextreusedelay Get the CONTEXT_ID_REUSE_DELAY value. @@ -667,40 +564,6 @@ Disable multicast promiscuous mode. Done ``` -### joiner start \ \ - -Start the Joiner role. - -* pskd: Pre-Shared Key for the Joiner. -* provisioningUrl: Provisioning URL for the Joiner (optional). - -This command will cause the device to perform an MLE Discovery and -initiate the Thread Commissioning process. - -```bash -> joiner start PSK -Done -``` - -### joiner stop - -Stop the Joiner role. - -```bash -> joiner stop -Done -``` - -### joinerid - -Get the Joiner ID. - -```bash -> joinerid -e0b220eb7d8dda7e -Done -``` - ### joinerport \ Set the Joiner port. diff --git a/src/cli/README_COMMISSIONER.md b/src/cli/README_COMMISSIONER.md new file mode 100644 index 000000000..59ccbd153 --- /dev/null +++ b/src/cli/README_COMMISSIONER.md @@ -0,0 +1,198 @@ +# OpenThread CLI - Commissioner + +## Quick Start + +See [README_COMMISSIONING.md](README_COMMISSIONING.md). + +## Command List + +- [help](#help) +- [announce](#announce) +- [energy](#energy) +- [joiner add](#joiner-add) +- [joiner remove](#joiner-remove) +- [mgmtget](#mgmtget) +- [mgmtset](#mgmtset) +- [panid](#panid) +- [provisioningurl](#provisioningurl) +- [sessionid](#sessionid) +- [start](#start) +- [stop](#stop) + +## Command Details + +### help + +Usage: `commissioner help` + +Print commissioner help menu. + +```bash +> commissioner help +help +announce +energy +joiner +mgmtget +mgmtset +panid +provisioningurl +sessionid +start +stop +Done +``` + +### announce + +Usage: `commissioner announce ` + +Send a `MGMT_ANNOUNCE_BEGIN` message. + +- mask: Bitmask identifying channels to send MLE Announce messages. +- count: Number of MLE Announce transmissions per channel. +- period: Period between successive MLE Announce transmissions (milliseconds). +- destination: IPv6 destination for the message (may be multicast). + +```bash +> commissioner announce 0x00050000 2 32 fdde:ad00:beef:0:0:ff:fe00:c00 +Done +``` + +### energy + +Usage: `commissioner energy ` + +Send a `MGMT_ED_SCAN` message. + +- mask: Bitmask identifying channels to perform IEEE 802.15.4 ED Scans. +- count: Number of IEEE 802.15.4 ED Scans per channel. +- period: Period between successive IEEE 802.15.4 ED Scans (milliseconds). +- scanDuration: IEEE 802.15.4 ScanDuration to use when performing an IEEE 802.15.4 ED Scan (milliseconds). +- destination: IPv6 destination for the message (may be multicast). + +The contents of `MGMT_ED_REPORT` messages (i.e. Channel Mask and Energy List) are printed as they are received. + +```bash +> commissioner energy 0x00050000 2 32 1000 fdde:ad00:beef:0:0:ff:fe00:c00 +Done +Energy: 00050000 0 0 0 0 +``` + +### joiner add + +Usage: `commissioner joiner add ` + +Add a Joiner entry. + +- eui64: The IEEE EUI-64 of the Joiner or '*' to match any Joiner. +- pskd: Pre-Shared Key for the Joiner. + +```bash +> commissioner joiner add d45e64fa83f81cf7 J01NME +Done +``` + +### joiner remove + +Usage: `commissioner joiner remove ` + +Remove a Joiner entry. + +- eui64: The IEEE EUI-64 of the Joiner or '*' to match any Joiner. + +```bash +> commissioner joiner remove d45e64fa83f81cf7 +Done +``` + +### mgmtget + +Usage: `commissioner mgmtget [locator] [sessionid] [steeringdata] [joinerudpport] [binary ]` + +Send a `MGMT_GET` message to the Leader. + +```bash +> commissioner mgmtget locator sessionid +Done +``` + +### mgmtset + +Usage: `commissioner mgmtset [locator ] [sessionid ] [steeringdata ] [joinerudpport ] [binary ]` + +Send a `MGMT_SET` message to the Leader. + +```bash +> commissioner mgmtset joinerudpport 9988 +Done +``` + +### panid + +Usage: `commissioner panid ` + +Send a `MGMT_PANID_QUERY` message. + +- panid: PAN ID to check for conflicts. +- mask: Bitmask identifying channels to perform IEEE 802.15.4 Active Scans. +- destination: IPv6 destination for the message (may be multicast). + +The contents of `MGMT_PANID_CONFLICT` messages (i.e. PAN ID and Channel Mask) are printed as they are received. + +```bash +> commissioner panid 0xdead 0x7fff800 fdde:ad00:beef:0:0:ff:fe00:c00 +Done +Conflict: dead, 00000800 +``` + +### provisioningurl + +Usage: `commissioner provisioningurl ` + +Set the Provisioning URL. + +```bash +> commissioner provisioningurl http://github.com/openthread/openthread +Done +``` + +### sessionid + +Usage: `commissioner sessionid` + +Get current commissioner session id. + +```bash +> commissioner sessionid +0 +Done +``` + +### start + +Usage: `commissioner start` + +Start the Commissioner role. + +This command will cause the device to send `LEAD_PET` and `LEAD_KA` messages. + +```bash +> commissioner start +Commissioner: petitioning +Done +Commissioner: active +``` + +### stop + +Usage: `commissioner stop` + +Stop the Commissioner role. + +This command will cause the device to send `LEAD_KA[Reject]` messages. + +```bash +> commissioner stop +Done +``` diff --git a/src/cli/README_COMMISSIONING.md b/src/cli/README_COMMISSIONING.md new file mode 100644 index 000000000..b61d7bd79 --- /dev/null +++ b/src/cli/README_COMMISSIONING.md @@ -0,0 +1,129 @@ +# OpenThread CLI - Commissioning + +## Quick Start + +### Build with Joiner support + +Use the `JOINER=1` build switch to enable Joiner support. + +```bash +> ./bootstrap +> make -f examples/Makefile-posix JOINER=1 +``` + +### Build with Commissioner support + +Use the `COMMISSIONER=1` build switch to enable Commissioner support. + +```bash +> ./bootstrap +> make -f examples/Makefile-posix COMMISSIONER=1 +``` + +### Form Network + +Form a network with the device that has Commissioner support. + +1. Generate and view new network configuration. + + ```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 + ``` + +2. Commit new dataset to the Active Operational Dataset in non-volatile storage. + + ```bash + dataset commit active + Done + ``` + +3. Enable Thread interface + + ```bash + > ifconfig up + Done + > thread start + Done + ``` + +### Obtain Joiner IEEE EUI-64 + +1. Start the Joiner node and obtain the Joiner's IEEE EUI-64. + + ```bash + > eui64 + 18b4300000000002 + Done + ``` + +### Start Commissioner + +1. Start the Commissioner Role + + ```bash + > commissioner start + Commissioner: petitioning + Done + Commissioner: active + ``` + +2. Add the Joiner with the device-specific pre-shared key (PSKd) + + ```bash + > commissioner joiner add 18b4300000000002 J01NME + Done + ``` + +### Start Joiner + +1. Start the Joiner process. + + ```bash + > ifconfig up + Done + > joiner start J01NME + Done + Join success + ``` + +2. Attach to Thread network + + ```bash + > thread start + Done + ``` + +3. After successful attach, validate the device has the same Active Operational Dataset as above. + + ```bash + > dataset active + 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 + ``` + +## CLI Reference + +- [Commissioner CLI Reference](README_COMMISSIONER.md) +- [Joiner CLI Reference](README_JOINER.md) diff --git a/src/cli/README_JOINER.md b/src/cli/README_JOINER.md new file mode 100644 index 000000000..8422dab43 --- /dev/null +++ b/src/cli/README_JOINER.md @@ -0,0 +1,68 @@ +# OpenThread CLI - Joiner + +## Quick Start + +See [README_COMMISSIONING.md](README_COMMISSIONING.md). + +## Command List + +* [help](#help) +* [id](#id) +* [start](#start) +* [stop](#stop) + +## Command Details + +### help + +Usage: `joiner help` + +Print dataset help menu. + +```bash +> joiner help +help +id +start +stop +Done +``` + +### id + +Usage: `joiner id` + +Print the Joiner ID. + +```bash +> joiner id +d65e64fa83f81cf7 +Done +``` + +### start + +Usage: `joiner start [provisioning-url]` + +Start the Joiner role. + +* pskd: Pre-Shared Key for the Joiner. +* provisioning-url: Provisioning URL for the Joiner (optional). + +This command will cause the device to start the Joiner process. + +```bash +> joiner start J01NM3 +Done +``` + +### stop + +Usage: `joiner stop` + +Stop the Joiner role. + +```bash +> joiner stop +Done +```