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 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 use the Thread Commissioning App to commission an OpenThread device onto a network created and managed by the OTBR Web GUI.

To learn how to commission without an external Commissioner, see Thread Commissioning.

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 the OTBR NCP, using wpanctl.

  1. Set the network credentials:
    sudo wpanctl setprop Network:PANID 0xDEAD
    sudo wpanctl setprop Network:XPANID DEAD1111DEAD2222
    sudo wpanctl setprop Network:Key 11112233445566778899DEAD1111DEAD
    
  2. Set the on-mesh prefix:
    sudo wpanctl config-gateway -d "fd11:22::"
    
  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:
    cd ~/borderrouter/tools
    ./pskc J01NME DEAD1111DEAD2222 OpenThreadGuide
    198886f519a8fd7c981fee95d72f4ba7
  4. Set the PSKc:
    sudo wpanctl setprop Network:PSKc --data 198886f519a8fd7c981fee95d72f4ba7
    
  5. Form the Thread network. Make sure to use the same Network Name used to generate the PSKc:
    sudo wpanctl form "OpenThreadGuide"
    Forming WPAN "OpenThreadGuide" as node type "router"
    Successfully formed!
    
  6. Confirm the network configuration:
    sudo wpanctl status
    wpan0 => [
        "NCP:State" => "associated"
        "Daemon:Enabled" => true
        "NCP:Version" => "OPENTHREAD/g95f744fb-dirty; NRF52840; Oct 12 2017 09:24:19"
        "Daemon:Version" => "0.08.00d (0.07.01-124-g038e8b0/0.07.01-153-g6752c40; Oct  3 2017 17:55:05)"
        "Config:NCP:DriverName" => "spinel"
        "NCP:HardwareAddress" => [CCEED0CA9B5A12DB]
        "NCP:Channel" => 14
        "Network:NodeType" => "leader"
        "Network:Name" => "OpenThreadGuide"
        "Network:XPANID" => 0xDEAD1111DEAD2222
        "Network:PANID" => 0xDEAD
        "IPv6:LinkLocalAddress" => "fe80::bc53:88e7:f6bf:9046"
        "IPv6:MeshLocalAddress" => "fdde:ad11:11de:0:8f4:2c2f:e2de:d3e1"
        "IPv6:MeshLocalPrefix" => "fdde:ad11:11de::/64"
        "com.nestlabs.internal:Network:AllowingJoin" => false
    ]
    sudo wpanctl getprop Thread:OnMeshPrefixes
    Thread:OnMeshPrefixes = [
        "fd11:22::              prefix_len:64   origin:user     stable:yes flags:0x33 [on-mesh:1 def-route:1 config:0 dhcp:0 slaac:1 pref:1 prio:med]"
    ]
    sudo wpanctl getprop Network:PSKc
    Network:PSKc = [198886F519A8FD7C981FEE95D72F4BA7]
    

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.

Enable the Joiner role for the build. Use the --enable-joiner configuration flag or the JOINER=1 build switch, depending on the build mode.

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.

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

eui64
000b57fffe15d68
Done

Download the Thread Commissioning App

External commissioning is supported by the Thread Commissioning App, available for download on the Google Play Store for Android devices.

Connect to the Border Router

Thread App Border Router
  1. Connect the device with the Thread Commissioning App to the Wi-Fi access point on the Border Router.
  2. Open the Thread Commissioning 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.
  3. 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:

v=1&&eui=000b57fffe15d68&&cc=J01NU5

Where 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.

Thread App Commissioning
  1. In the Thread Commissioning 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.
  2. 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
  3. Wait a minute for the DTLS handshake to complete between the Commissioner and Joiner:
    
    Join success!
  4. The Thread Commissioning App also updates with an "Added My Thread Product" 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. If NAT64 was set up as detailed in Wi-Fi Access Point Setup for OpenThread Border Router, use the prefix value configured there, combined with the translated IPv4 address.

For example, the Well-Known 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.

Ping this address 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

Thread Commissioning App troubleshooting

You may encounter issues with the Thread Commissioning App, due to changed or stale network information. The app retains OTBR network information locally and does not always prompt for updates.

To resolve these issues, delete all local application data, restart the app, and try the commissioning process again.

To delete local application data:

  1. On the Android device, open the Settings app
  2. Go to Apps & notifications > App info > Thread > Storage
  3. Select CLEAR DATA
  4. Go back to App info and select FORCE STOP
  5. Close the Settings app and restart the Thread app