blob: 8b6987878aacb837d4415fef42dfa3fab8f72a65 [file] [log] [blame] [view]
Andrei Litvina76f75e2022-04-13 08:34:42 -10001![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png)
Artur Tynecki06f9a382021-10-29 16:10:56 +02002
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +01003# Matter Arm Mbed OS provisioning guide
Artur Tynecki06f9a382021-10-29 16:10:56 +02004
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 Litvin0062c5d2023-03-02 12:20:44 -050011 - [Sending ZCL commands](#sending-zcl-commands-android)
Artur Tynecki06f9a382021-10-29 16:10:56 +020012- [POSIX CLI CHIPTool](#posix-cli-chiptool)
13 - [Building](#building)
14 - [Device commissioning for CLI](#device-commissioning-for-cli)
Andrei Litvin0062c5d2023-03-02 12:20:44 -050015 - [Sending ZCL commands](#sending-zcl-commands-posix)
Artur Tynecki06f9a382021-10-29 16:10:56 +020016- [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 Litvin0062c5d2023-03-02 12:20:44 -050019 - [Sending ZCL commands](#sending-zcl-commands-python)
Artur Tynecki06f9a382021-10-29 16:10:56 +020020 - [ZCL commands details](#zcl-commands-details)
21
22<hr>
23
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +010024## Overview
Artur Tynecki06f9a382021-10-29 16:10:56 +020025
26This document provides a step-by-step guide how to commission any Matter
27application. For demonstration purposes the Lighting app is used.
28
29The 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
37BLE is only used during first phase. Afterwards, only the IP connectivity
38between the smartphone and the accessory device is needed to send messages.
39
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +010040## Prerequisites
Artur Tynecki06f9a382021-10-29 16:10:56 +020041
42To 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 Lundee7347ea2023-01-09 19:43:07 +010053## CHIPTool for Android
Artur Tynecki06f9a382021-10-29 16:10:56 +020054
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +010055### Building and installing
Artur Tynecki06f9a382021-10-29 16:10:56 +020056
57To make provisioning possible and to control the Matter device from your Android
58based smartphone, you must first build and install the CHIPTool application.
59
60To build the CHIPTool application for your smartphone, read
61[Android building guide](android_building.md).
62
63After building, install the application by completing the following steps:
64
651. Install the Android Debug Bridge (adb) package by running the following
66 command:
67
Andrei Litvina76f75e2022-04-13 08:34:42 -100068 ```
Artur Tynecki06f9a382021-10-29 16:10:56 +020069 $ sudo apt install android-tools-adb
Andrei Litvina76f75e2022-04-13 08:34:42 -100070 ```
Artur Tynecki06f9a382021-10-29 16:10:56 +020071
722. 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.
753. If the **Install via USB** option is supported for your Android version,
76 turn it on.
774. Plug your smartphone into a USB port on your PC.
785. 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
836. Navigate to settings on your smartphone and grant **Camera** and
84 **Location** permissions to CHIPTool.
85
86Android CHIPTool is now ready to be used for commissioning.
87
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +010088### Accessory Matter device setup
Artur Tynecki06f9a382021-10-29 16:10:56 +020089
90To prepare the accessory Matter device for commissioning (called rendezvous),
91complete 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 Litvina76f75e2022-04-13 08:34:42 -100097 ```
Artur Tynecki06f9a382021-10-29 16:10:56 +020098 mbed-tools sterm -p /dev/ttyACM0 -b 115200 -e off
Andrei Litvina76f75e2022-04-13 08:34:42 -100099 ```
Artur Tynecki06f9a382021-10-29 16:10:56 +0200100
101To start the rendezvous, CHIPTool must get the commissioning information from
102the Matter device. The data payload is encoded within a QR code and is printed
103to the UART console.
104
105- Reset the device.
106
107- Find a message similar to the following one in the application logs:
108
Andrei Litvina76f75e2022-04-13 08:34:42 -1000109 ```
Artur Tynecki06f9a382021-10-29 16:10:56 +0200110 [INFO][CHIP]: [SVR]Copy/paste the below URL in a browser to see the QR Code:
Hrishikesh Dhayagude4cdecc92022-07-19 21:55:16 +0530111 [INFO][CHIP]: [SVR]https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AYNJV7VSC00CMVH7SR00
Andrei Litvina76f75e2022-04-13 08:34:42 -1000112 ```
Artur Tynecki06f9a382021-10-29 16:10:56 +0200113
114- Open URL from the console to display the QR in a web browser.
115
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +0100116### Device commissioning for Android
Artur Tynecki06f9a382021-10-29 16:10:56 +0200117
118To commission Matter device onto the network created complete the following
119steps:
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 Litvin0062c5d2023-03-02 12:20:44 -0500140### Sending ZCL commands Android
Artur Tynecki06f9a382021-10-29 16:10:56 +0200141
142After the accessory device has been successfully commissioned to the network, it
143is possible to communicate with it using IP. Matter uses Zigbee Cluster Library
144(ZCL) protocol which defines common means for applications to communicate.
145
146Communication with the device via ZCL commands is possible by using buttons of
147the main screen.
148
149For example, selecting the 'LIGHT ON/OFF & LEVEL CLUSTER' button opens the
150screen which allows controlling the light dimming. Tap either the ON or the OFF
151button to toggle between min and max brightness. Use the slider to modify the
152brightness between 0-255.
153
154If **Lighting LED** is available then brightness change can be observed.
155
156> For more details about Android CHIPTool please visit
Yufeng Wanga3347142022-09-29 15:22:36 -0700157> [CHIPTool](../../examples/android/CHIPTool/README.md)
Artur Tynecki06f9a382021-10-29 16:10:56 +0200158
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +0100159## POSIX CLI CHIPTool
Artur Tynecki06f9a382021-10-29 16:10:56 +0200160
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +0100161### Building
Artur Tynecki06f9a382021-10-29 16:10:56 +0200162
163To make provisioning possible and to control the Matter device from Linux-based
164device, you can build and run the Matter Client example application on it.
165
166To build the POSIX CLI CHIPTool application check the guide
167[POSIX CLI guide](../../examples/chip-tool/README.md).
168
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +0100169### Device commissioning for CLI
Artur Tynecki06f9a382021-10-29 16:10:56 +0200170
171In order to send commands to a device, it must be paired with the client and
172connected to the network.
173
174To run the commissioning process via BLE, run the built executable and pass it
Boris Zbarskyb9cc0e22022-01-25 23:24:41 -0500175the node id to assign to the newly-commissioned node, network ssid and password,
176discriminator and pairing code of the remote device.
Artur Tynecki06f9a382021-10-29 16:10:56 +0200177
178Example:
179
Boris Zbarskyb9cc0e22022-01-25 23:24:41 -0500180 $ chip-tool pairing ble-wifi node_id_to_assign network_ssid network_password 20202021 3840
Artur Tynecki06f9a382021-10-29 16:10:56 +0200181
Andrei Litvin0062c5d2023-03-02 12:20:44 -0500182### Sending ZCL commands POSIX
Artur Tynecki06f9a382021-10-29 16:10:56 +0200183
184If the commissioning process was successful, it is possible to send a ZCL
185command to the device which initiate a certain action.
186
187To send a ZCL commands, run the executable and pass it the target cluster name,
188the target command name as well as an endpoint id.
189
190The endpoint id must be between 1 and 240.
191
192For example:
193
194 $ chip-tool onoff on 1
195
196The 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 Lundee7347ea2023-01-09 19:43:07 +0100201## Python Device Controller
Artur Tynecki06f9a382021-10-29 16:10:56 +0200202
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +0100203### Building and installing
Artur Tynecki06f9a382021-10-29 16:10:56 +0200204
205To make provisioning possible and to control the Matter device with Python
206application, you can build and run the Python CHIP controller.
207
208To build and install the Python Device Controller application check the guide
209[Python Device Controller guide](python_chip_controller_building.md).
210
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +0100211### Device commissioning for Python Device Controller
Artur Tynecki06f9a382021-10-29 16:10:56 +0200212
213In order to send commands to a device, it must be paired with the client and
214connected to the network.
215
Artur Tyneckife6adc32022-01-27 22:58:56 +0100216To run the auto commissioning process via BLE:
Artur Tynecki06f9a382021-10-29 16:10:56 +0200217
218- Run Device Controller:
219
220 chip-device-ctrl
221
222- Scan BLE devices:
223
224 chip-device-ctrl > ble-scan
225
Artur Tyneckife6adc32022-01-27 22:58:56 +0100226- Pass the Wi-Fi credentials to the device:
227
228 chip-device-ctrl > set-pairing-wifi-credential ssid credentials
229
Artur Tynecki06f9a382021-10-29 16:10:56 +0200230- 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 Litvin0062c5d2023-03-02 12:20:44 -0500235### Sending ZCL commands Python
Artur Tynecki06f9a382021-10-29 16:10:56 +0200236
237If the commissioning process was successful, it is possible to send a ZCL
238command to the device which initiates a certain action.
239
240`zcl <Cluster> <Command> <NodeId> <EndpointId> <GroupId> [arguments]`
241
242Example:
243
244 chip-device-ctrl > zcl LevelControl MoveWithOnOff 12344321 1 0 moveMode=1 rate=2
245
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +0100246#### ZCL commands details
Artur Tynecki06f9a382021-10-29 16:10:56 +0200247
248To get the list of supported clusters run:
249
250 chip-device-ctrl > zcl ?
251
252To get the list of available commands in cluster run:
253
254 chip-device-ctrl > zcl ? <Cluster>
255
256**Format of arguments**
257
258For any integer and char string (null terminated) types, just use `key=value`,
259for example: `rate=2`, `string=123`, `string_2="123 456"`
260
261For 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
263example, `networkId=hex:0123456789abcdef` (for
264`[0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]`), `ssid=str:Test` (for
265`['T', 'e', 's', 't', 0x00]`).
266
267For boolean type, use `key=True` or `key=False`