Overview
This document provides a step-by-step guide how to commission any Matter application. For demonstration purposes the Lighting app is used.
The provisioning process is composed of the following stages:
CHIPTool discovers a Matter accessory device over Bluetooth Low Energy (BLE).
CHIPTool establishes a secure channel to the device over BLE, and sends network credentials data.
BLE is only used during first phase. Afterwards, only the IP connectivity between the smartphone and the accessory device is needed to send messages.
Prerequisites
To complete all the steps in the tutorial, you need:
A smartphone with Android 8+ or PC with Ubuntu 20.04 and Bluetooth connectivity
A WiFi Access Point (smartphone router, standalone AP, wireless router or PC)
Any currently supported target device (for example, a Cypress PSoC6 CY8CPROTO-062-4343W board)
CHIPTool for Android
Building and installing
To make provisioning possible and to control the Matter device from your Android based smartphone, you must first build and install the CHIPTool application.
To build the CHIPTool application for your smartphone, read Android building guide.
After building, install the application by completing the following steps:
Install the Android Debug Bridge (adb) package by running the following command:
``` $ sudo apt install android-tools-adb ```
Enable USB debugging on your smartphone. See the Configure on-device developer options guide on the Android Studio hub for detailed information.
If the Install via USB option is supported for your Android version, turn it on.
Plug your smartphone into a USB port on your PC.
Run the following command to install the application, with matter-dir replaced with the path to the Matter source directory:
$ adb install out/android-$TARGET_CPU-chip-tool/outputs/apk/debug/app-debug.apk
Navigate to settings on your smartphone and grant Camera and Location permissions to CHIPTool.
Android CHIPTool is now ready to be used for commissioning.
Accessory Matter device setup
To prepare the accessory Matter device for commissioning (called rendezvous), complete the following steps:
Open a serial terminal session to connect to the UART console of the accessory device. You can use mbed-tools for this purpose (mbed-tools):
``` mbed-tools sterm -p /dev/ttyACM0 -b 115200 -e off ```
To start the rendezvous, CHIPTool must get the commissioning information from the Matter device. The data payload is encoded within a QR code and is printed to the UART console.
Reset the device.
Find a message similar to the following one in the application logs:
``` [INFO][CHIP]: [SVR]Copy/paste the below URL in a browser to see the QR Code: [INFO][CHIP]: [SVR]https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AYNJV7VSC00CMVH7SR00 ```
Open URL from the console to display the QR in a web browser.
Device commissioning for Android
To commission Matter device onto the network created complete the following steps:
Enable Bluetooth and Location services on your smartphone.
Connect the smartphone to the WiFi Network
Open the CHIPTool application on your smartphone.
Tap the ‘PROVISION CHIP DEVICE WITH WI-FI’ button and scan the commissioning QR code.
Go through the the paring and connecting Bluetooth on your smartphone (you will see a few pop-up messages appear as the commissioning progresses. Finally, the network settings screen appears.
In the network settings screen enter the Wi-Fi credentials and tap the Save Network button to send a WiFi provisioning message to the accessory device.
After successful completion of the process, the application returns to the main screen.
Sending ZCL commands
After the accessory device has been successfully commissioned to the network, it is possible to communicate with it using IP. Matter uses Zigbee Cluster Library (ZCL) protocol which defines common means for applications to communicate.
Communication with the device via ZCL commands is possible by using buttons of the main screen.
For example, selecting the ‘LIGHT ON/OFF & LEVEL CLUSTER’ button opens the screen which allows controlling the light dimming. Tap either the ON or the OFF button to toggle between min and max brightness. Use the slider to modify the brightness between 0-255.
If Lighting LED is available then brightness change can be observed.
For more details about Android CHIPTool please visit CHIPTool
POSIX CLI CHIPTool
Building
To make provisioning possible and to control the Matter device from Linux-based device, you can build and run the Matter Client example application on it.
To build the POSIX CLI CHIPTool application check the guide POSIX CLI guide.
Device commissioning for CLI
In order to send commands to a device, it must be paired with the client and connected to the network.
To run the commissioning process via BLE, run the built executable and pass it the node id to assign to the newly-commissioned node, network ssid and password, discriminator and pairing code of the remote device.
Example:
$ chip-tool pairing ble-wifi node_id_to_assign network_ssid network_password 20202021 3840
Sending ZCL commands
If the commissioning process was successful, it is possible to send a ZCL command to the device which initiate a certain action.
To send a ZCL commands, run the executable and pass it the target cluster name, the target command name as well as an endpoint id.
The endpoint id must be between 1 and 240.
For example:
$ chip-tool onoff on 1
The client will send a single command packet and then exit.
For more details about POSIX CLI CHIPTool please visit POSIX CLI CHIPTool
Python Device Controller
Building and installing
To make provisioning possible and to control the Matter device with Python application, you can build and run the Python CHIP controller.
To build and install the Python Device Controller application check the guide Python Device Controller guide.
Device commissioning for Python Device Controller
In order to send commands to a device, it must be paired with the client and connected to the network.
To run the auto commissioning process via BLE:
Run Device Controller:
chip-device-ctrl
Scan BLE devices:
chip-device-ctrl > ble-scan
Pass the Wi-Fi credentials to the device:
chip-device-ctrl > set-pairing-wifi-credential ssid credentials
Connect the device via BLE (provide the accessory device discriminator, setup pin code and node ID):
chip-device-ctrl > connect -ble 3840 20202021 1234
Sending ZCL commands
If the commissioning process was successful, it is possible to send a ZCL command to the device which initiates a certain action.
zcl <Cluster> <Command> <NodeId> <EndpointId> <GroupId> [arguments]
Example:
chip-device-ctrl > zcl LevelControl MoveWithOnOff 12344321 1 0 moveMode=1 rate=2
ZCL commands details
To get the list of supported clusters run:
chip-device-ctrl > zcl ?
To get the list of available commands in cluster run:
chip-device-ctrl > zcl ? <Cluster>
Format of arguments
For any integer and char string (null terminated) types, just use key=value, for example: rate=2, string=123, string_2="123 456"
For byte string type, use key=encoding:value, currently, we support str and hex encoding, the str encoding will encode a NULL terminated string. For example, networkId=hex:0123456789abcdef (for [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]), ssid=str:Test (for ['T', 'e', 's', 't', 0x00]).
For boolean type, use key=True or key=False