In our previous article, we set up an external commissioner outside a Thread network using a command-line tool on a PC. However, OpenThread also provides a mobile app that can serve as an external commissioner.

This guide will walk you through building and using the OpenThread Commissioner mobile app to provision a device onto a Thread network.

Building the OpenThread Commissioner Mobile App

OpenThread provides an Android app source, which requires Android Studio and Android NDK to build. The official OpenThread documentation provides step-by-step instructions for building the app, as follows.

Build Commissioner Native Libraries

To begin, set the required environment variables (ANDROID_ABI and ANDROID_NDK_HOME) and proceed with the build process. This will generate the commissioner native library and JNI wrappers, which are bundled into the Android app.

➜ ~$ git clone https://github.com/openthread/ot-commissioner

➜ ~$ cd ot-commissioner/android

➜ android $ ../script/bootstrap.sh
OS is Darwin
==> Updating Homebrew...
Updated 3 taps (homebrew/services, homebrew/core and homebrew/cask).
==> New Formulae
bombardier        cspell            dyff              flow-control      garnet            mdq               ruby-lsp          taskflow          vscli             zns


➜ android $ ANDROID_ABI=arm64-v8a ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/29.0.13113456 ./build-commissioner-libs.sh

➜ android $ ll -a
total 24
drwxr-xr-x   7 thw8316  staff   224B Mar  5 10:33 .
drwxr-xr-x  26 thw8316  staff   832B Mar  5 13:28 ..
drwxr-xr-x  12 thw8316  staff   384B Mar  5 10:35 .build-arm64-v8a
-rw-r--r--   1 thw8316  staff   1.5K Mar  5 10:30 BUILDING.md
-rw-r--r--   1 thw8316  staff   226B Mar  5 10:30 README.md
-rwxr-xr-x   1 thw8316  staff   3.5K Mar  5 10:30 build-commissioner-libs.sh
drwxr-xr-x  14 thw8316  staff   448B Mar  5 13:29 openthread_commissioner

This script creates .build-arm64-v8a and openthread_commissionerdirectory, It would have all the libs and JNI packaged in a jar

Building and Running the Android App

• Open the openthread_commissioner folder in Android Studio.
• Click Gradle Sync to set up the project.
• Build the project to generate an APK and install to android phone
• or Connect an Android phone via USB with Developer Options enabled.
• Run the app from Android Studio to install it on your phone.

Using the Mobile App Commissioner

Ensure the mobile device is connected to the same wifi network as the Thread Border Router and follow steps below :

Select a Thread Network

The app will discover border routers over DNS. Select one from the list.

In will ask a password — Enter the Commissioner Passphrase/Credentials defined in the Border Router

Add a Joiner Device Rule

Next, it we add a Joiner device rule, Tap “ADD DEVICE” — this will open a QR Code Scanner to scan the device EUI64 and PSKd (Joiner Key).

• Get an EUI64 from a Thread End Device

  > eui64
  f4ce3601fbe48430
  done
  >
  

• Generate a QR Code with a string like this “eui=f4ce3601fbe48430&cc=J01NME”

This registers the device ID (EUI64) and the Joiner Key (PSKd) in the Commissioner, waiting for the Joiner device to connect.

Joining the Thread Network

On a Thread End Device, initiate the joining process with the following command:

> joiner start  J01NME
joiner success
Done
>

The Commissioner Mobile App will receive the Joiner request and approve it.

📝 Note: The Joiner ID is the SHA256 hash of the EUI64.

This completes the mobile app-based commissioning process for adding a device to a Thread network. 🎉

Find the IoT Practices Publication for more details.