OpenThread Border Router (OTBR) features a Thread Border Agent, which supports external Thread Commissioning. In external Thread Commissioning, a device outside of the Thread network (for example, a mobile phone) commissions new devices onto the network.
The Thread Commissioner serves to authenticate a user (external Commissioner) or a Thread device onto the Thread network. After authentication, the Commissioner instructs the Border Router to transfer Thread network credentials, such as the master key, to the device directly.
This is an example of in-band commissioning, where Thread network credentials are transferred between devices over the radio.
This guide details how to commission an OpenThread device onto a network created and managed by the OTBR Web GUI, using one of the following external Commissioners:
To learn how to commission without an external Commissioner, see Thread Commissioning.
Select Commissioner type
Use the buttons to filter this guide based on Commissioner type:
Selected: OT Commissioner Android App
Form the Thread network
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.
The Thread network can also be formed manually on the command line of
OpenThread POSIX, using
- Initialize a new operational dataset:
sudo ot-ctl dataset init newDone
- Set the network credentials:
sudo ot-ctl dataset panid 0xdeadDone
sudo ot-ctl dataset extpanid dead1111dead2222Done
sudo ot-ctl dataset networkname OpenThreadGuideDone
sudo ot-ctl dataset masterkey 11112233445566778899DEAD1111DEADDone
- 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:
./pskc J01NME DEAD1111DEAD2222 OpenThreadGuide
- Set the PSKc:
sudo ot-ctl dataset pskc 198886f519a8fd7c981fee95d72f4ba7Done
- Commit the active dataset, set the on-mesh prefix, and form the Thread
sudo ot-ctl dataset commit activeDone
sudo ot-ctl prefix add fd11:22::/64 pasorDone
sudo ot-ctl ifconfig upDone
sudo ot-ctl thread startDone
sudo ot-ctl netdata registerDone
- Confirm the network configuration:
sudo ot-ctl stateleader Done
sudo ot-ctl pskc198886f519a8fd7c981fee95d72f4ba7 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.
JOINER=1 build switch to enable the Joiner role.
For example, to build the CC2538 example platform for use as a Joiner:
make -f examples/Makefile-cc2538 JOINER=1
Specific instructions on building supported platforms with GNU Autotools can be found in each example's platform folder/examples/platforms).
Once the Joiner device is ready, obtain its factory-assigned IEEE EUI-64. Use
eui64 command in the OpenThread CLI:
eui64 0000b57fffe15d68 Done
Download the app
External commissioning is supported by the OT Commissioner Android App, available for download at the and building on the GitHub repository. Follow the instructions in the README to build and install the app on an Android device..
Connect to the Border Router
- Connect the device with the OT Commissioner Android App to the Wi-Fi access point on the Border Router.
- Open the OT Commissioner Android App and select the desired Border Router from the available list. The name is the same as the Thread network created by the OTBR Web GUI. If the same Border Router shows up multiple times with different IPv4 and IPv6 addresses, select the one with the static IPv4 address used for the Wi-Fi access point setup.
- Enter the Passphrase (Commissioner Credential) set in the OTBR Web GUI (and used to generate the PSKc) when prompted for a password.
Commission the Joiner
Once connected to the Border Router, the app provides the option to scan a Connect QR Code or enter a Join Passphrase manually. The Join Passphrase is also called the Joiner Credential, and is used (along with the Extended PAN ID and Network Name) to generate the Pre-Shared Key for the Device (PSKd). The PSKd is then used to authenticate a device during Thread Commissioning. The Joiner Credential should be unique to each device.
Thread Connect QR Codes are created with the following text string format:
eui is the Joiner device's EUI64 value and
cc is the Joiner
Credential. Use this text string with an online QR Code generator to create a QR
Code for scanning.
- In the OT Commissioner Android App, scan the Connect QR Code of the Joiner device, or enter the EUI64 and Joiner Credential manually. This generates the PSKd, propagates the steering data through the Thread network, and establishes a DTLS session.
- While the app is waiting, enter the OpenThread CLI on the Joiner device and
start the Joiner role with that same Joiner Credential:
ifconfig up Done
joiner start J01NU5 Done
- Wait a minute for the DTLS handshake to complete between the Commissioner
- The OT Commissioner Android App also updates with an "Commission Succeed" confirmation message.
The Joiner has obtained the Thread network credentials, and can now join the network.
Join the network
On the Joiner device, start the Thread protocol to automatically join the network.
thread start Done
Check the state after a few moments to confirm. It may initially start as a child, but within two minutes it should upgrade to a router.
state router Done
Also check the device's IPv6 addresses. It should have a Global address using the On-Mesh Prefix specified during formation of the Thread network through the OTBR Web GUI.
ipaddr fdde:ad11:11de:0:0:ff:fe00:9400 fd11:22:0:0:3a15:3211:2723:dbe1 fe80:0:0:0:6006:41ca:c822:c337 fdde:ad11:11de:0:ed8c:1681:24c4:3562
Ping the external internet
Test the connectivity between the Joiner device in the Thread network and the external internet by pinging a public IPv4 address.
For example, the Well-Known NAT64 prefix of
64:ff9b::/96 and an IPv4 address
184.108.40.206 combine to form an IPv6 address of
Add an external route for the NAT64 Prefix:
sudo ot-ctl route add 64:ff9b::/96 s medDone
sudo ot-ctl netdata registerDone
Ping the synthesized IPv6 address
64:ff9b::808:808 from the OpenThread CLI on the Joiner device:
ping 64:ff9b::808:80816 bytes from 64:ff9b:0:0:0:0:808:808: icmp_seq=3 hlim=45 time=72ms