Thread Commissioning Guide

This is a practical guide for adding new Thread Devices to a Thread Network for the first time. It includes an overview of the commissioning process - more detail can be found in the Thread Group Commissioning White Paper and the Thread Specification.

What is Commissioning

In a Thread network, all communication is secured by a network-wide key. Without that key, a device cannot participate in the network. The network also has other parameters that must be consistent and can be configured, such as the extended PAN ID, admin password, channel and network name.

In Thread, the Commissioner is the user-controlled admin interface to the Thread network. The primary purpose of the Commissioner is to add new devices to the network by securely provisioning them with the network credentials. It can also be used to modify the network parameters safely after the network is formed. Multiple commissioners can control a Thread Network, but only one can be active at a time.

A Commissioner can take many forms, such as:

But the general principles are the same. On a high level, the process is:

  1. The Commissioner forms a secure connection to the Thread Network (Using the Admin Password if not already on the Thread Network)
  2. The Commissioner is provided the credentials for the new device (The EUI64 address, and Joiner Credential)
    • For a product, this is usually by scanning a QR code on the device, but details can also be entered manually
    • The EUI64 address is propagated through the network
      • This allows joining devices to search for the network that is expecting them
    • The Joiner Credential is held by the Commissioner, and is used to establish a secure commissioning session with the joiner
  3. The joining device “discovers” the nearby network, and attempts to join the network(s) which are expecting it.
  4. The Commissioner authenticates the joiner using the Joining Device Credential and, if successful, the joiner is provided with the Thread Network Credentials.

The network credentials are stored in non-volatile storage of the device, so Commissioning is only necessary the very first time a device joins the network. If power is lost, the device is reset or otherwise loses connection temporarily, the Thread device can simply rejoin the network with the automatic ‘attach’ process.

How to Commission with the Cascoda SDK

In the Cascoda-SDK, there are many ways to perform the joining/commissioning procedure, based on the capabilities of the device. These can be used together in any combination - select one commissioning method and one joining method. It should be noted that a network must be formed either via the OpenThread CLI or the OpenThread Web GUI, before commissioning can take place.

Note that the commissioning and joining procedures happen in parallel, with the commissioner being provided with the joiner credentials just before the joiner starts discovering the network.

Select one commissioning method and one joining method:


CLI Commissioning

CLI Commissioning uses the OpenThread CLI of a device already on the network in order to commission another device. It is useful for development purposes and testing.

App Commissioning

The App Commissioning process uses the official Thread Commissioning app in order to provide the most user-friendly method of commissioning. The source code of the Thread Commissioning app is available to members of the Thread Group, so it is possible to develop custom versions.

OT-BR Web GUI Commissioning

The OT-BR Commissioning process uses the Openthread Border Router web portal to add a new device to the network. It provides an example for how a production border router might allow a customer to add devices to the Thread Network.

Known issues

The Web GUI can sometimes lock up or crash, returning ‘Join Success’ even though the joining process has failed. As a workaround, the web gui can be restarted from the raspberry pi terminal using the command sudo systemctl restart otbr-web.service.

The Web GUI does not utilise the EUI64 of the joining device, and therefore does not set the commissioner ‘steering data’. This does not pose a problem if only a single device nearby is attempting to join a Thread network, but can lead to wasted joining attempts if devices try to join the incorrect network.


CLI Joining

CLI Joining uses the OpenThread CLI in order to join a device to the network. It is useful for development purposes and testing.

Automatic Joining

Automatic Joining is used with some of the demos in the Cascoda SDK that do not have openthread CLI interfaces, such as ot-sed-sensorif. This kind of joining is suitable for real-world products, and sleepy devices that do not have a user interface.

In the case of our examples, we make use of the evbme-get utility to extract the credentials of the device. For real products, a label or other associated material would be more appropriate.

Automatic Joining with Hardcoded Credentials

Using CASCODA_OT_JOINER_CRED it is possible to assign a hardcoded joiner credential to a device, eliminating the need to force full network credentials to devices that don’t have serial interfaces, which is useful for development purposes.