Prepare the Thread Network and Joiner Device

View source on GitHub

In this guide, learn how to use OTBR Web GUI to form the Thread Network. Then, choose a supported platform and build a Joiner device.

To set up a Border Router, refer to OpenThread Border Router Build and Configuration.

Form the Thread network

Web GUI

The recommended way to form a Thread network is via the OTBR Web GUI. When doing so, change all the default values on the Form menu option, except for the On-Mesh Prefix.

Make note of the Passphrase used. This passphrase is the Commissioner Credential and is used (along with the Extended PAN ID and Network Name) to generate the Pre-Shared Key for the Commissioner (PSKc). The PSKc is needed to authenticate the Thread Commissioner (the external device) to the network.

Manual

The Thread network can also be formed manually on the command line of OpenThread POSIX, using ot-ctl.

Initialize a new operational dataset:
```
sudo ot-ctl dataset init new
Done
```

Set the network credentials:

sudo ot-ctl dataset panid 0xdead
Done

sudo ot-ctl dataset extpanid dead1111dead2222
Done

sudo ot-ctl dataset networkname OpenThreadGuide
Done

sudo ot-ctl dataset networkkey 11112233445566778899DEAD1111DEAD
Done

Generate a hex-encoded PSKc by using a Passphrase (Commissioner Credential), the Extended PAN ID, and the Network Name with the PSKc Generator tool on the OTBR. Make sure to use the same Extended PAN ID and Network Name that was used in the operational dataset:
```
cd ~/ot-br-posix/build/otbr/tools
./pskc j01Nme DEAD1111DEAD2222 OpenThreadGuide
198886f519a8fd7c981fee95d72f4ba7
```

Set the PSKc:

sudo ot-ctl dataset pskc 198886f519a8fd7c981fee95d72f4ba7
Done

Commit the active dataset, set the on-mesh prefix, and form the Thread network:

sudo ot-ctl dataset commit active
Done

sudo ot-ctl prefix add fd11:22::/64 pasor
Done

sudo ot-ctl ifconfig up
Done

sudo ot-ctl thread start
Done

sudo ot-ctl netdata register
Done

Confirm the network configuration:

sudo ot-ctl state
leader
Done

sudo ot-ctl pskc
198886f519a8fd7c981fee95d72f4ba7
Done

Prepare the Joiner device

Build and flash a device with OpenThread, to function as the Joiner. For an overview of building OpenThread, see the Building Guide.

Use the -DOT_JOINER=ON build option to enable the Joiner role.

Specific instructions on building supported platforms with GNU Autotools can be found in each example's platform folder.

When commissioning a Joiner, it's important to understand the following terms and concepts:

Joining Device Credential: You'll need to provide a Passphrase to commission a device, for example J01NU5. This Passphrase is separate from the Commissioner Credential you created when forming your Thread network, and has different requirements:
- Must be a string of all uppercase alphanumeric characters (0-9 and A-Y, excluding I, O, Q, and Z for readability), with a length between 6 and 32 characters.
The Joining Device Credential might also be referred to as Join Passphrase, Joiner Password, or PSKd. This Passphrase is used to authenticate a device during Thread Commissioning. You can also use it with a device's EUI64 value to generate a unique QR Code.
PSKd: Pre-Shared Key for the Joiner. The PSKd is the Joining Device Credential when it's specifically encoded in binary form.
EUI-64: 64-bit Extended Unique Identifier, for example 0000b57fffe15d68. This is a Joiner device's factory-assigned IEEE EUI-64, used to generate a QR code and uniquely identify a device.

Once the Joiner device is ready, obtain its factory-assigned IEEE EUI-64. Use the eui64 command in the OpenThread CLI:

eui64
0000b57fffe15d68
Done

Select Commissioner type

The OpenThread Commissioner provides the OT Commissioner CLI to externally commission a device.

The OT Commissioner CLI runs on the same host machine as OTBR. In the next guide, learn how to use the OT Commissioner CLI to connect to a border router and commission a new device.

External Commissioning

OT Commissioner CLI