[![](https://openthread.io/static/images/icon-github.svg)View source on GitHub](https://github.com/openthread/ot-docs/tree/main/site/en/guides/build/commissioning.md)
[![Commissioner and Joiner](https://openthread.io/guides/images/ot-primer-joiner.png)](https://openthread.io/guides/images/ot-primer-joiner.png)

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](https://openthread.io/guides/border-router/external-commissioning/index.md).

For an example of commissioning using virtual devices, see the
[OpenThread Simulation Codelab](https://openthread.io/codelabs/openthread-simulation#3).

> [!IMPORTANT]
> **Key Point:** Thread network management can also be done with the [Thread Network SDK for Android](https://developers.home.google.com/thread) and [iOS Thread APIs](https://developer.apple.com/documentation/threadnetwork/).

## Enable roles

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

| Option | Description |
|---|---|
| `-DOT_COMMISSIONER=ON` | Enables the Commissioner role |
| `-DOT_JOINER=ON` | Enables the Joiner role |

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](https://github.com/openthread) 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

> [!NOTE]
> **Note:** The Joiner Credential is a device-specific string of all uppercase alphanumeric characters (0-9 and A-Y, excluding I, O, Q and Z for readability), with a length between 6 and 32 characters.

### 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