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 master 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 configuration flags and/or build switches, depending on the build mode:
||Enables the Commissioner role|
||Enables the Joiner role|
For example, to build the CC2538 example platform for use as a Joiner only:
make -f examples/Makefile-cc2538 JOINER=1
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 example's platform folder.
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 Master Key: dfd34f0f05cad978ec4e32b0413038ff Network Name: OpenThread-8f28 PAN ID: 0x8f28 PSKc: c23a76e98f1a6483639b1ac1271e2e27 Security Policy: 0, onrcb Done
dataset commit activeDone
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
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, enable the Joiner role with the same Joiner Credential specified on the Commissioner:
Wait a few seconds for confirmation:
ifconfig up Done
joiner start JO1NME Done
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
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