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. A guide on how to do both is available here.

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 OpenThread Commissioner Android App to provide the most user-friendly commissioning method.

If you want to use app commissioning process, please follow the Openthread guide on using the OT Commissioner app. However, there still are some things you need to take into account:

Cascoda Border Router Web GUI Commissioning

The Cascoda BR Commissioning process uses the Cascoda Border Router web portal to add a new device to the 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.