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.
To enable the Commissioner and Joiner roles, use the following cmake options:
|Enables the Commissioner role
|Enables the Joiner role
For example, to build the CC2538 example platform for use as a Joiner only:
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 newDone
datasetActive 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 activeDone
Wait a few seconds and verify that the device has become a Thread Leader:
Start the Commissioner role
On that same device, start the Commissioner role:
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
Restrict to a specific Joiner
To restrict commissioning to a specific Joiner device, use the
parameter, which is the device's factory-assigned IEEE EUI-64.
On the device serving as the Joiner, get the EUI-64:
Use that value instead of the * wildcard in the
commissioner joiner command on
the Commissioner device:
commissioner joiner add 2f57d222545271f1 J01NME
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:
joiner start J01NMEDone
Wait a few seconds for confirmation:
The Joiner device has successfully authenticated itself with the Commissioner and received Thread Network credentials.
Now start Thread on the Joiner device:
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:
statechild Done ...