Google is committed to advancing racial equity for Black communities. See how.

External Thread Commissioning

Thread External Commissioning

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 network 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 CLI

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.

  1. Initialize a new operational dataset:
    sudo ot-ctl dataset init new
    Done
    
  2. 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
    
  3. 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
  4. Set the PSKc:
    sudo ot-ctl dataset pskc 198886f519a8fd7c981fee95d72f4ba7
    Done
    
  5. 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
    
  6. 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.

For example, to build the CC2538 example platform for use as a Joiner:

./script/build -DOT_JOINER=ON

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 the eui64 command in the OpenThread CLI:

eui64
0000b57fffe15d68
Done

Build and install OT Commissioner

Build and install OT Commissioner. See OT Commissioner Build and Configuration for instructions.

Connect to the Border Router

  1. Open the Non-CCM configuration file located at /usr/local/etc/commissioner/non-ccm-config.json and change the PSKc to 198886f519a8fd7c981fee95d72f4ba7:
    "PSKc" : "198886f519a8fd7c981fee95d72f4ba7"
  2. Start the OT Commissioner CLI with the Non-CCM configuration:
    commissioner-cli /usr/local/etc/commissioner/non-ccm-config.json
    
  3. Connect to OTBR:
    start :: 49191
    [done]
    
  4. Verify that the Commissioner is active:
    active
    true
    [done]
    

Commission the Joiner

Once connected to the Border Router, OT Commissioner can commission the Joiner device.

  1. In OT Commissioner, enable Thread 1.1 MeshCoP joiner for all Joiners with a password of J01NU5:
    joiner enableall meshcop J01NU5
    [done]
    
  2. On the Joiner device, start the Joiner role with the password configured in OT Commissioner:
    ifconfig up
    Done
    joiner start J01NU5
    Done
  3. Wait a minute for the DTLS handshake to complete between the Commissioner and Joiner:
    
    Join success!

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 of 8.8.8.8 combine to form an IPv6 address of 64:ff9b::808:808.

Add an external route for the NAT64 Prefix:

sudo ot-ctl route add 64:ff9b::/96 s med
Done
sudo ot-ctl netdata register
Done

Ping the synthesized IPv6 address 64:ff9b::808:808 from the OpenThread CLI on the Joiner device:

ping 64:ff9b::808:808
16 bytes from 64:ff9b:0:0:0:0:808:808: icmp_seq=3 hlim=45 time=72ms