On-Mesh Commissioning

View source on GitHub

Commissioning requires one device with the Commissioner role, and one device with the Joiner role. The Commissioner is either a Thread device in an existing Thread network, or a device external to the Thread network (such as a mobile phone) that performs the Commissioner role. The Joiner is the device wishing to join the Thread network.

A Thread Commissioner is used to authenticate a device onto the network. It does not transfer or have possession of Thread network credentials such as the network key.

This guide covers basic, on-mesh commissioning without an external Commissioner or Border Router. To learn how to use an external Commissioner, see External Thread Commissioning.

For an example of commissioning using virtual devices, see the OpenThread Simulation Codelab.

Enable roles

To enable the Commissioner and Joiner roles, use the following cmake options:

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

./script/build -DOT_JOINER=ON

Flash each binary to the desired device. One device serves as the Commissioner, the other as the Joiner.

Specific instructions on building and flashing supported platforms can be found in each platform's OpenThread repository. See the OpenThread GitHub organization to find the repository.

Create a network

Create a network on the device acting as the Commissioner:

dataset init new
Done
dataset
Active Timestamp: 1
Channel: 13
Channel Mask: 07fff800
Ext PAN ID: d63e8e3e495ebbc3
Mesh Local Prefix: fd3d:b50b:f96d:722d/64
Network Key: dfd34f0f05cad978ec4e32b0413038ff
Network Name: OpenThread-8f28
PAN ID: 0x8f28
PSKc: c23a76e98f1a6483639b1ac1271e2e27
Security Policy: 0, onrcb
Done
dataset commit active
Done
ifconfig up
Done
thread start
Done

Wait a few seconds and verify that the device has become a Thread Leader:

state
leader
Done

Start the Commissioner role

On that same device, start the Commissioner role:

commissioner start
Done

Use the * wildcard to allow any Joiner with the specified Joiner Credential to commission onto the network. The Joiner Credential 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.

commissioner joiner add * J01NME
Done

Restrict to a specific Joiner

To restrict commissioning to a specific Joiner device, use the eui64 parameter, which is the device's factory-assigned IEEE EUI-64.

On the device serving as the Joiner, get the EUI-64:

eui64
2f57d222545271f1
Done

Use that value instead of the * wildcard in the commissioner joiner command on the Commissioner device:

commissioner joiner add 2f57d222545271f1 J01NME
Done

Start the Joiner role

On the device serving as the Joiner, perform a factory reset, then enable the Joiner role with the same Joiner Credential specified on the Commissioner:

factoryreset
ifconfig up
Done
joiner start J01NME
Done

Wait a few seconds for confirmation:

Join success!

The Joiner device has successfully authenticated itself with the Commissioner and received Thread Network credentials.

Now start Thread on the Joiner device:

thread start
Done

Validate authentication

Check the state on the Joiner device, to validate that it has joined the network. Within two minutes, the state transitions from child to router:

state
child
Done
...
state
router
Done