OT Commissioner CLI

View source on GitHub

External commissioning is supported by the OT Commissioner CLI, available on the ot-commissioner GitHub repository.

In this guide, you'll build and install OT Commissioner and commission a Joiner.

Set up OT Commissioner

To use OT Commissioner CLI, first Build OT Commissioner.

Discover your network

To start OT Commissioner, you'll need to find the IP address and port number of your border agent service. For help on locating this information, refer to mDNS Discovery. The Border Agent supports both IPv4 and IPv6 connections.

Connect to the Border Router

  1. Start the OT Commissioner CLI:

  2. Set your PSKc:

    config set pskc 198886f519a8fd7c981fee95d72f4ba7
  3. Connect to OTBR, providing your mDNS IP address and port:

    start FD00::74D0:6FC9:6BE6:3582 49155
  4. Verify that the Commissioner is active:


Commission the Joiner

Once connected to the Border Router, OT Commissioner can commission the Joiner device.

  1. In OT Commissioner, enable Thread MeshCoP joiner for all Joiners with a password of J01NU5:

    joiner enableall meshcop J01NU5

  2. On the Joiner device, start the Joiner role with the password configured in OT Commissioner:

    ifconfig up
    joiner start J01NU5

  3. Wait a minute for the DTLS handshake to complete between the Commissioner and Joiner:

    Join success!

Join the Thread network

Next, on the Joiner device, join the Thread network and test network connectivity.


If you're having issues with OT Commissioner, check the commissioner.log, if available. To configure logging, refer to Build OT Commissioner.

IO_ERROR: connect socket to peer addr

Try using a different IP address to start OT Commissioner.

IO_ERROR: NET - Reading information from the socket failed

The socket APIs return this error message when a call to bind or connect to OTBR fails. If you're receiving this error message, try the following:

  • Make sure that you're passing the correct port number when you start OT Commissioner. OTBR may use a different port after it's restarted or you reboot your platform.
  • Make sure that OTBR is running and that your Thread network is properly configured, including your PSKc. Your Passphrase/Commissioner Credential must be a string between 6 and 255 characters.
  • Check your global IP addresses, for example ifconfig eth0. You may be using the wrong IP address to start OT Commissioner.

SECURITY: SSL - A fatal alert message was received from our peer

OT Commissioner establishes a secure DTLS session with the border agent service. A fatal SSL error typically indicates that the secure DTLS session fails.

If you receive this message, check your PSKc.

From OTBR:

sudo ot-ctl pskc

From OT Commissioner:

config get pskc


For additional commissioner-cli commands, refer to OT Commissioner CLI.