nRF5 SDK for Thread and Zigbee v4.1.0
Thread commissioning

Table of Contents

Commissioning is the process that allows a new Thread device to join a Thread network. The new device must be authenticated and authorized to become part of the network.

In the commissioning process, devices have different Commissioning roles. The whole process can happen within the Thread network (connectivity within the Thread network) or can involve devices that are outside the network (other network provides connectivity, for example Ethernet or WiFi). This is the main difference between On-mesh Thread commissioning and External Thread commissioning, respectively. The whole commissioning process benefits from several security measures, especially the DTLS protocol.

Once familiar with this page, check also Configuring Thread commissioning.

Commissioning roles

During the commissioning process, the devices involved are assigned one of the following roles:

While the Border Router is typically used only in the external commissioning process, the Nordic Border Router, which is based on the OpenThread Border Router (OTBR), supports both on-mesh and external commissioning.

Once a device is assigned one of the roles in the network, it can combine it with other roles. An exception is the Joiner role, which is exclusive to the Joiner and cannot be combined with other roles. For example:

For details about scenarios that include devices with multiple roles, see Thread Group's Commissioning White Paper.

See Commissioning CLI commands for the list of commands used to assign the commissioning roles.

On-mesh and external commissioning

The commissioning can be either on-mesh or external.

On-mesh Thread commissioning

In the on-mesh Thread commissioning, the commissioning takes place inside the Thread network. The Thread Leader approves a Commissioner connected either to the Thread network (on-mesh Commissioner) or to a Thread device, and accepts it into the Thread network. Border Agent then authenticates it. After authentication, the Commissioner instructs the Joiner Router to transfer Thread network credentials to the Joiner.

In this type of commissioning, Thread network credentials are transferred between devices over the radio. At the end of its own authentication process, the Joiner joins the Thread network and becomes an active device that communicates with other Thread devices.

For security purposes, the on-mesh Thread commissioning requires exchanging a DTLS handshake between Commissioner and Joiner. See Security, authentication, and credentials for more information.

On-mesh Thread commissioning.

For information about how to configure on-mesh Thread Commissioning, see Configuring on-mesh Thread commissioning.

External Thread commissioning

In the external Thread commissioning, the commissioning involves a Commissioner device connected to a network other than the Thread network, like WiFi or Ethernet. This external Commissioner (for example, a mobile phone) commissions new devices onto the network using the Thread Border Router as forwarding interface.

For security purposes, the external Thread commissioning requires exchanging a DTLS handshake. Two DTLS sessions are established:

External Thread commissioning.

For information about how to configure external Thread Commissioning, see Configuring external Thread Commissioning.

Commissioning phases

The commissioning process has the following phases:


Petitioning concerns only the Commissioner role.

Petitioning occurs in both commissioning scenarios. The Commissioner Candidate that is either connected to an external network (external candidate) or is part of the network (on-mesh candidate) must petition the Leader of the Thread network through the Thread Border Agent to become the only authorized Commissioner. The petitioning involves up to two phases:

The Leader accepts the petition based on only one criterium: whether there is already an active Commissioner in the Thread network. If there is none, the petition is accepted. If the petition is rejected, a rejection message is sent with the ID of the active Commissioner.

After the petition is accepted by the Leader:


Joining concerns the Joiner role.

Joining occurs in both commissioning scenarios. It involves the following phases:

After the Joiner received the payload from the Joiner Router:

Security, authentication, and credentials

To avoid a situation in which rogue devices join the Thread network, the communication between Commissioner and Joiner (in both scenarios), and Commissioner and Border Agent (in external commissioning) is secured with the Datagram Transport Layer Security (DTLS) authentication protocol session. The session is established automatically.

Also the communication between Joiner and Joiner Router is secured, but only when Joiner Router sends network credentials to Joiner using one time key generated by the Commissioner.

During commissioning, the on-mesh Thread Commissioner posseses the network master key by default, while the external Thread Commissioner never gains possession of the network master key.

The commissioning uses the following passwords and credentials:

For details and full overview of security credentials, see Thread protocol specification, table 8.2.

Commissioning CLI commands

See the following pages in the OpenThread CLI Reference on GitHub for an overview of available CLI commands:

Documentation feedback | Developer Zone | Subscribe | Updated