Commissioning nRF Connect Accessory using Android CHIPTool

You can use CHIPTool for Android smartphones to commission a Nordic Semiconductor's development kit programmed with a Matter example for the nRF Connect platform into a Matter fabric.

This guide references the nRF52840 DK and Matter nRF Connect Lighting Example Application that communicates with other nodes over a Thread network, but the instructions can be adapted to other platforms and applications. For instance, some sections of this guide include steps for testing a Wi-Fi device, which are adapted from the original Thread-based procedure.

Overview

The commissioning process is composed of the following main stages:

  1. CHIPTool discovers a Matter accessory device over Bluetooth LE.
  2. CHIPTool establishes a secure channel to the device over Bluetooth LE, and sends Matter operational credentials and Thread or Wi-Fi credentials.
  3. The accessory device joins the operational IPv6 network.

CHIPTool uses both Bluetooth LE and the IPv6 connectivity. Bluetooth LE is used only during the commissioning phase. Afterwards, only the IPv6 connectivity between the smartphone and the accessory device is needed to send operational messages. The IPv6 address of the device is not exchanged during the commissioning process and CHIPTool must use DNS Service Discovery (DNS-SD) to learn or refresh the address before the controller initiates the IPv6-based communication.

Since a typical smartphone does not have a Thread radio built-in, preparing the fully-fledged testing environment for Matter over Thread requires a Thread Border Router configured on a Raspberry Pi.

The following diagram shows the connectivity between network components required to allow communication between devices running CHIPTool and Matter nRF Connect Lighting Example Application:

Matter nodes connectivity

Requirements

You need the following hardware and software for commissioning the nRF Connect accessory using Android CHIPTool:

  • 1x smartphone with Android 8+

  • 1x Wi-Fi Access Point supporting IPv6 (without the IPv6 Router Advertisement Guard enabled on the router)

  • 1x nRF52840 DK (PCA10056) for running the example application. You can replace this DK with another compatible device, such as the nRF5340 DK or nRF7002 DK. nRF52840 DK and nRF5340 DK can be used to test Matter over Thread, and nRF7002 DK can be used to test Matter over Wi-Fi.

  • 1x nRF52840 DK for running the OpenThread Radio Co-Processor firmware. You can replace this DK with another compatible device, such as the nRF52840 Dongle.

    Note: This piece of hardware is only needed if you're testing a Thread device. Skip it if the tested device operates in a Wi-Fi network.

  • 1x Raspberry Pi Model 3B+ or newer (along with an SD card with at least 8 GB of memory)

    Note: This piece of hardware is only needed if you're testing a Thread device. Skip it if the tested device operates in a Wi-Fi network.

Setting up Thread Border Router

Note: This step is only needed if you're testing a Thread device. Skip it if the tested device operates in a Wi-Fi network.

Follow the OpenThread Border Router article to set up OpenThread Border Router on the Raspberry Pi, with either the nRF52840 DK or the nRF52840 Dongle acting as the OpenThread Radio Co-Processor. During the setup, make sure that the Raspberry Pi is connected to your Wi-Fi Access Point.

Building and programming nRF Connect Example Application

Build and program the example application onto your compatible device.

For this guide, see the documentation of Matter nRF Connect Lighting Example Application to learn how to build and program the example onto an nRF52840 DK.

Building and installing Android CHIPTool

To build the CHIPTool application for your smartphone, read the Building Android guide.

After building, install the application by completing the following steps:

  1. Install the Android Debug Bridge (adb) package by running the following command:

    ```
sudo apt install android-tools-adb
```

  2. Enable USB debugging on the smartphone. See the Configure on-device developer options guide on the Android Studio hub for detailed information.

  3. If the Install via USB option is supported for your Android version, turn it on.

  4. Plug the smartphone into a USB port on your PC.

  5. Run the following command to install the application, with chip-dir replaced with the path to the Matter source directory:

    ```
adb install -r chip-dir/examples/android/CHIPTool/app/build/outputs/apk/debug/app-debug.apk
```

  6. Navigate to settings on your smartphone and grant Camera and Location permissions to CHIPTool.

CHIPTool is now ready to be used for commissioning.

Preparing accessory device

To prepare the accessory device for commissioning, complete the following steps:

  1. Use a terminal emulator to connect to the UART console of the accessory device. For details, see the Using CLI in nRF Connect examples guide. This will grant you access to the application logs.

  2. Hold the appropriate button on the accessory device for more than 6 s to trigger the factory reset of the device. See the user interface section in the example documentation to check the button number.

  3. Find a message similar to the following one in the application logs:

    I: 615 [SVR]Copy/paste the below URL in a browser to see the QR Code:
I: 621 [SVR]https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00

  4. Open the URL in a web browser to have the commissioning QR code generated.

  5. Press the appropriate button on the device to start the Bluetooth LE advertising. See the user interface section in the example documentation to check the button number.

Commissioning accessory device

To commission the accessory device into the Matter fabric, complete the following steps:

  1. Enable Bluetooth and Location services on your smartphone.

  2. Connect the smartphone to your Wi-Fi Access Point.

  3. Open the CHIPTool application on your smartphone.

  4. Depending on your testing scenario, tap one of the following buttons and scan the commissioning QR code:

    • PROVISION CHIP DEVICE WITH THREAD for Matter over Thread
    • PROVISION CHIP DEVICE WITH WI-FI for Matter over Wi-Fi

    The network credentials screen appears.

  5. In the network credentials screen, specify parameters of network and tap the SAVE NETWORK button. Several notifications appear, informing you of the progress of scanning, connecting, and pairing with the device. At the end of this process, the application returns to the main menu.

Sending Matter commands

Once the device is commissioned, the main application screen appears.

Check the IPv6 connectivity with the device using the following steps:

  1. Tap LIGHT ON/OFF & LEVEL CLUSTER. The following screen appears:

    CHIPTool device control screen

    The two textboxes at the top contain Fabric ID and Node ID of the last commissioned device.

  2. Tap the following buttons to change the lighting state of the Matter nRF Connect Lighting Example Application referenced in this guide:

    • ON and OFF buttons turn on and off the light, respectively.
    • TOGGLE changes the lighting state to the opposite.

The LED 2 on the device turns on or off based on the changes of the lighting state.