External Commissioning for Android

View source on GitHub

External commissioning is supported by the OT Commissioner Android App, available on the ot-commissioner GitHub repository. Follow the instructions in the README to build and install the app on an Android device.

To use the Thread 1.1 Commissioning App, refer to Thread Group Android App.

OT Commissioner Android App

Connect to the Border Router

  1. With both devices on the same network, connect the device with the OT Commissioner Android App to the Border Router.
  2. Open the OT Commissioner Android App and select the desired Border Router from the available list. The name is the same as the Thread network created by the OTBR Web GUI.

    App Border Router
  3. Enter the Passphrase (Commissioner Credential) set in the OTBR Web GUI (and used to generate the PSKc) when prompted for a password.

Commission the Joiner

Once connected to the Border Router, the app provides the option to scan a Connect QR Code or enter a Join Passphrase manually. The Join Passphrase is also called the Joiner Credential, and 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.

Thread Connect QR Codes are created with the following text string format:

v=1&&eui=0000b57fffe15d68&&cc=J01NU5

Where eui is the Joiner device's EUI64 value and cc is the Joiner Credential. Use this text string with an online QR Code generator to create a QR Code for scanning.

  1. In the OT Commissioner Android App, scan the Connect QR Code of the Joiner device, or enter the EUI64 and Joiner Credential manually. This generates the PSKd, propagates the steering data through the Thread network, and establishes a DTLS session.

    App Commissioning
  2. While the app is waiting, enter the OpenThread CLI on the Joiner device and start the Joiner role with that same Joiner Credential:

    ifconfig up
    Done
    joiner start J01NU5
    Done
    

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

    
    Join success!
    

  4. The OT Commissioner Android App also updates with an "Commission Succeed" confirmation message.

The Joiner has obtained the Thread network credentials, and can now join the network.

Thread Group Android App

Thread 1.1 external commissioning is supported by the Thread 1.1 Commissioning App, available for download at the Google Play Store for Android devices.

Connect to the Border Router

  1. With both devices on the same network, connect the device with the Thread Group Android App to the Border Router.
  2. Open the Thread Group Android App and select the desired Border Router from the available list. The name is the same as the Thread network created by the OTBR Web GUI.

    Thread 1.1 App Border Router
  3. Enter the Passphrase (Commissioner Credential) set in the OTBR Web GUI (and used to generate the PSKc) when prompted for a password.

Commission the Joiner

Once connected to the Border Router, the app provides the option to scan a Connect QR Code or enter a Join Passphrase manually. The Join Passphrase is also called the Joiner Credential, and 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.

Thread Connect QR Codes are created with the following text string format:

v=1&&eui=0000b57fffe15d68&&cc=J01NU5

Where eui is the Joiner device's EUI64 value and cc is the Joiner Credential. Use this text string with an online QR Code generator to create a QR Code for scanning.

  1. In the Thread Group Android App, scan the Connect QR Code of the Joiner device, or enter the EUI64 and Joiner Credential manually. This generates the PSKd, propagates the steering data through the Thread network, and establishes a DTLS session.

    App Commissioning
  2. While the app is waiting, enter the OpenThread CLI on the Joiner device and start the Joiner role with that same Joiner Credential:

    ifconfig up
    Done
    joiner start J01NU5
    Done
    

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

    
    Join success!
    

  4. The Thread Group Android App also updates with an "Added My Thread Product" confirmation message.

The Joiner has obtained the Thread network credentials, and can now join the network.

Thread Commissioning App troubleshooting

You may encounter issues with the Thread Commissioning App, due to changed or stale network information. The app retains OTBR network information locally and does not always prompt for updates.

To resolve these issues, delete all local application data, restart the app, and try the commissioning process again.

To delete local application data:

  1. On the Android device, open the Settings app
  2. Go to Apps & notifications > App info > Thread > Storage
  3. Select CLEAR DATA
  4. Go back to App info and select FORCE STOP
  5. Close the Settings app and restart the Thread app

Join the Thread network

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