Andrei Litvin | a76f75e | 2022-04-13 08:34:42 -1000 | [diff] [blame] | 1 | ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 2 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 3 | # Matter Arm Mbed OS provisioning guide |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 4 | |
| 5 | - [Overview](#overview) |
| 6 | - [Prerequisites](#prerequisites) |
| 7 | - [CHIPTool for Android](#chiptool-for-android) |
| 8 | - [Building and installing](#building-and-installing) |
| 9 | - [Accessory Matter device setup](#accessory-matter-device-setup) |
| 10 | - [Device commissioning for Android](#device-commissioning-for-android) |
Andrei Litvin | 0062c5d | 2023-03-02 12:20:44 -0500 | [diff] [blame] | 11 | - [Sending ZCL commands](#sending-zcl-commands-android) |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 12 | - [POSIX CLI CHIPTool](#posix-cli-chiptool) |
| 13 | - [Building](#building) |
| 14 | - [Device commissioning for CLI](#device-commissioning-for-cli) |
Andrei Litvin | 0062c5d | 2023-03-02 12:20:44 -0500 | [diff] [blame] | 15 | - [Sending ZCL commands](#sending-zcl-commands-posix) |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 16 | - [Python Device Controller](#python-device-controller) |
| 17 | - [Building and installing](#building-and-installing-1) |
| 18 | - [Device commissioning for Python Device Controller](#device-commissioning-for-python-device-controller) |
Andrei Litvin | 0062c5d | 2023-03-02 12:20:44 -0500 | [diff] [blame] | 19 | - [Sending ZCL commands](#sending-zcl-commands-python) |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 20 | - [ZCL commands details](#zcl-commands-details) |
| 21 | |
| 22 | <hr> |
| 23 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 24 | ## Overview |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 25 | |
| 26 | This document provides a step-by-step guide how to commission any Matter |
| 27 | application. For demonstration purposes the Lighting app is used. |
| 28 | |
| 29 | The provisioning process is composed of the following stages: |
| 30 | |
| 31 | - CHIPTool discovers a Matter accessory device over Bluetooth Low Energy |
| 32 | (BLE). |
| 33 | |
| 34 | - CHIPTool establishes a secure channel to the device over BLE, and sends |
| 35 | network credentials data. |
| 36 | |
| 37 | BLE is only used during first phase. Afterwards, only the IP connectivity |
| 38 | between the smartphone and the accessory device is needed to send messages. |
| 39 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 40 | ## Prerequisites |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 41 | |
| 42 | To complete all the steps in the tutorial, you need: |
| 43 | |
| 44 | - A smartphone with Android 8+ or PC with Ubuntu 20.04 and Bluetooth |
| 45 | connectivity |
| 46 | |
| 47 | - A WiFi Access Point (smartphone router, standalone AP, wireless router or |
| 48 | PC) |
| 49 | |
| 50 | - Any currently supported target device (for example, a Cypress PSoC6 |
| 51 | CY8CPROTO-062-4343W board) |
| 52 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 53 | ## CHIPTool for Android |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 54 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 55 | ### Building and installing |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 56 | |
| 57 | To make provisioning possible and to control the Matter device from your Android |
| 58 | based smartphone, you must first build and install the CHIPTool application. |
| 59 | |
| 60 | To build the CHIPTool application for your smartphone, read |
| 61 | [Android building guide](android_building.md). |
| 62 | |
| 63 | After building, install the application by completing the following steps: |
| 64 | |
| 65 | 1. Install the Android Debug Bridge (adb) package by running the following |
| 66 | command: |
| 67 | |
Andrei Litvin | a76f75e | 2022-04-13 08:34:42 -1000 | [diff] [blame] | 68 | ``` |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 69 | $ sudo apt install android-tools-adb |
Andrei Litvin | a76f75e | 2022-04-13 08:34:42 -1000 | [diff] [blame] | 70 | ``` |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 71 | |
| 72 | 2. Enable **USB debugging** on your smartphone. See the |
| 73 | [Configure on-device developer options](https://developer.android.com/studio/debug/dev-options) |
| 74 | guide on the Android Studio hub for detailed information. |
| 75 | 3. If the **Install via USB** option is supported for your Android version, |
| 76 | turn it on. |
| 77 | 4. Plug your smartphone into a USB port on your PC. |
| 78 | 5. Run the following command to install the application, with _matter-dir_ |
| 79 | replaced with the path to the Matter source directory: |
| 80 | |
| 81 | $ adb install out/android-$TARGET_CPU-chip-tool/outputs/apk/debug/app-debug.apk |
| 82 | |
| 83 | 6. Navigate to settings on your smartphone and grant **Camera** and |
| 84 | **Location** permissions to CHIPTool. |
| 85 | |
| 86 | Android CHIPTool is now ready to be used for commissioning. |
| 87 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 88 | ### Accessory Matter device setup |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 89 | |
| 90 | To prepare the accessory Matter device for commissioning (called rendezvous), |
| 91 | complete the following steps: |
| 92 | |
| 93 | - Open a serial terminal session to connect to the UART console of the |
| 94 | accessory device. You can use **mbed-tools** for this purpose |
| 95 | ([mbed-tools](https://github.com/ARMmbed/mbed-tools)): |
| 96 | |
Andrei Litvin | a76f75e | 2022-04-13 08:34:42 -1000 | [diff] [blame] | 97 | ``` |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 98 | mbed-tools sterm -p /dev/ttyACM0 -b 115200 -e off |
Andrei Litvin | a76f75e | 2022-04-13 08:34:42 -1000 | [diff] [blame] | 99 | ``` |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 100 | |
| 101 | To start the rendezvous, CHIPTool must get the commissioning information from |
| 102 | the Matter device. The data payload is encoded within a QR code and is printed |
| 103 | to the UART console. |
| 104 | |
| 105 | - Reset the device. |
| 106 | |
| 107 | - Find a message similar to the following one in the application logs: |
| 108 | |
Andrei Litvin | a76f75e | 2022-04-13 08:34:42 -1000 | [diff] [blame] | 109 | ``` |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 110 | [INFO][CHIP]: [SVR]Copy/paste the below URL in a browser to see the QR Code: |
Hrishikesh Dhayagude | 4cdecc9 | 2022-07-19 21:55:16 +0530 | [diff] [blame] | 111 | [INFO][CHIP]: [SVR]https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AYNJV7VSC00CMVH7SR00 |
Andrei Litvin | a76f75e | 2022-04-13 08:34:42 -1000 | [diff] [blame] | 112 | ``` |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 113 | |
| 114 | - Open URL from the console to display the QR in a web browser. |
| 115 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 116 | ### Device commissioning for Android |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 117 | |
| 118 | To commission Matter device onto the network created complete the following |
| 119 | steps: |
| 120 | |
| 121 | - Enable Bluetooth and Location services on your smartphone. |
| 122 | |
| 123 | - Connect the smartphone to the WiFi Network |
| 124 | |
| 125 | - Open the CHIPTool application on your smartphone. |
| 126 | |
| 127 | - Tap the 'PROVISION CHIP DEVICE WITH WI-FI' button and scan the commissioning |
| 128 | QR code. |
| 129 | |
| 130 | - Go through the the paring and connecting Bluetooth on your smartphone (you |
| 131 | will see a few pop-up messages appear as the commissioning progresses. |
| 132 | Finally, the network settings screen appears. |
| 133 | |
| 134 | - In the network settings screen enter the Wi-Fi credentials and tap the Save |
| 135 | Network button to send a WiFi provisioning message to the accessory device. |
| 136 | |
| 137 | - After successful completion of the process, the application returns to the |
| 138 | main screen. |
| 139 | |
Andrei Litvin | 0062c5d | 2023-03-02 12:20:44 -0500 | [diff] [blame] | 140 | ### Sending ZCL commands Android |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 141 | |
| 142 | After the accessory device has been successfully commissioned to the network, it |
| 143 | is possible to communicate with it using IP. Matter uses Zigbee Cluster Library |
| 144 | (ZCL) protocol which defines common means for applications to communicate. |
| 145 | |
| 146 | Communication with the device via ZCL commands is possible by using buttons of |
| 147 | the main screen. |
| 148 | |
| 149 | For example, selecting the 'LIGHT ON/OFF & LEVEL CLUSTER' button opens the |
| 150 | screen which allows controlling the light dimming. Tap either the ON or the OFF |
| 151 | button to toggle between min and max brightness. Use the slider to modify the |
| 152 | brightness between 0-255. |
| 153 | |
| 154 | If **Lighting LED** is available then brightness change can be observed. |
| 155 | |
| 156 | > For more details about Android CHIPTool please visit |
Yufeng Wang | a334714 | 2022-09-29 15:22:36 -0700 | [diff] [blame] | 157 | > [CHIPTool](../../examples/android/CHIPTool/README.md) |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 158 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 159 | ## POSIX CLI CHIPTool |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 160 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 161 | ### Building |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 162 | |
| 163 | To make provisioning possible and to control the Matter device from Linux-based |
| 164 | device, you can build and run the Matter Client example application on it. |
| 165 | |
| 166 | To build the POSIX CLI CHIPTool application check the guide |
| 167 | [POSIX CLI guide](../../examples/chip-tool/README.md). |
| 168 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 169 | ### Device commissioning for CLI |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 170 | |
| 171 | In order to send commands to a device, it must be paired with the client and |
| 172 | connected to the network. |
| 173 | |
| 174 | To run the commissioning process via BLE, run the built executable and pass it |
Boris Zbarsky | b9cc0e2 | 2022-01-25 23:24:41 -0500 | [diff] [blame] | 175 | the node id to assign to the newly-commissioned node, network ssid and password, |
| 176 | discriminator and pairing code of the remote device. |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 177 | |
| 178 | Example: |
| 179 | |
Boris Zbarsky | b9cc0e2 | 2022-01-25 23:24:41 -0500 | [diff] [blame] | 180 | $ chip-tool pairing ble-wifi node_id_to_assign network_ssid network_password 20202021 3840 |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 181 | |
Andrei Litvin | 0062c5d | 2023-03-02 12:20:44 -0500 | [diff] [blame] | 182 | ### Sending ZCL commands POSIX |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 183 | |
| 184 | If the commissioning process was successful, it is possible to send a ZCL |
| 185 | command to the device which initiate a certain action. |
| 186 | |
| 187 | To send a ZCL commands, run the executable and pass it the target cluster name, |
| 188 | the target command name as well as an endpoint id. |
| 189 | |
| 190 | The endpoint id must be between 1 and 240. |
| 191 | |
| 192 | For example: |
| 193 | |
| 194 | $ chip-tool onoff on 1 |
| 195 | |
| 196 | The client will send a single command packet and then exit. |
| 197 | |
| 198 | > For more details about POSIX CLI CHIPTool please visit |
| 199 | > [POSIX CLI CHIPTool](../../examples/chip-tool/README.md) |
| 200 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 201 | ## Python Device Controller |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 202 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 203 | ### Building and installing |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 204 | |
| 205 | To make provisioning possible and to control the Matter device with Python |
| 206 | application, you can build and run the Python CHIP controller. |
| 207 | |
| 208 | To build and install the Python Device Controller application check the guide |
| 209 | [Python Device Controller guide](python_chip_controller_building.md). |
| 210 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 211 | ### Device commissioning for Python Device Controller |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 212 | |
| 213 | In order to send commands to a device, it must be paired with the client and |
| 214 | connected to the network. |
| 215 | |
Artur Tynecki | fe6adc3 | 2022-01-27 22:58:56 +0100 | [diff] [blame] | 216 | To run the auto commissioning process via BLE: |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 217 | |
| 218 | - Run Device Controller: |
| 219 | |
| 220 | chip-device-ctrl |
| 221 | |
| 222 | - Scan BLE devices: |
| 223 | |
| 224 | chip-device-ctrl > ble-scan |
| 225 | |
Artur Tynecki | fe6adc3 | 2022-01-27 22:58:56 +0100 | [diff] [blame] | 226 | - Pass the Wi-Fi credentials to the device: |
| 227 | |
| 228 | chip-device-ctrl > set-pairing-wifi-credential ssid credentials |
| 229 | |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 230 | - Connect the device via BLE (provide the accessory device discriminator, |
| 231 | setup pin code and node ID): |
| 232 | |
| 233 | chip-device-ctrl > connect -ble 3840 20202021 1234 |
| 234 | |
Andrei Litvin | 0062c5d | 2023-03-02 12:20:44 -0500 | [diff] [blame] | 235 | ### Sending ZCL commands Python |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 236 | |
| 237 | If the commissioning process was successful, it is possible to send a ZCL |
| 238 | command to the device which initiates a certain action. |
| 239 | |
| 240 | `zcl <Cluster> <Command> <NodeId> <EndpointId> <GroupId> [arguments]` |
| 241 | |
| 242 | Example: |
| 243 | |
| 244 | chip-device-ctrl > zcl LevelControl MoveWithOnOff 12344321 1 0 moveMode=1 rate=2 |
| 245 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 246 | #### ZCL commands details |
Artur Tynecki | 06f9a38 | 2021-10-29 16:10:56 +0200 | [diff] [blame] | 247 | |
| 248 | To get the list of supported clusters run: |
| 249 | |
| 250 | chip-device-ctrl > zcl ? |
| 251 | |
| 252 | To get the list of available commands in cluster run: |
| 253 | |
| 254 | chip-device-ctrl > zcl ? <Cluster> |
| 255 | |
| 256 | **Format of arguments** |
| 257 | |
| 258 | For any integer and char string (null terminated) types, just use `key=value`, |
| 259 | for example: `rate=2`, `string=123`, `string_2="123 456"` |
| 260 | |
| 261 | For byte string type, use `key=encoding:value`, currently, we support `str` and |
| 262 | `hex` encoding, the `str` encoding will encode a NULL terminated string. For |
| 263 | example, `networkId=hex:0123456789abcdef` (for |
| 264 | `[0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]`), `ssid=str:Test` (for |
| 265 | `['T', 'e', 's', 't', 0x00]`). |
| 266 | |
| 267 | For boolean type, use `key=True` or `key=False` |