From 5385882038d42cd5b75b14d2391e47d541d2a436 Mon Sep 17 00:00:00 2001 From: markaj-nordic <98948394+markaj-nordic@users.noreply.github.com> Date: Thu, 31 Mar 2022 04:11:14 +0200 Subject: [PATCH] [docs] Added a guide for the chip-tool. (#16637) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: “markaj-nordic” --- .github/.wordlist.txt | 6 + docs/guides/chip_tool_guide.md | 814 +++++++++++++++++++++++++++++++++ examples/chip-tool/README.md | 5 + 3 files changed, 825 insertions(+) create mode 100644 docs/guides/chip_tool_guide.md diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 807ce7b5edd996..37131914b0f8ce 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -56,7 +56,9 @@ apk AppConfig AppImpl ApplianceControl +applianceeventsandalert ApplianceIdentification +appliancestatistics ApplicationBasic ApplicationId ApplicationIdentifier @@ -247,6 +249,7 @@ ColorControl Comcast Commandline Commissionable +commissionables CommissioningFlow commondatastorage CONF @@ -479,6 +482,7 @@ fb fbb fbd FC +FCJ FDDE fddead fde @@ -612,6 +616,7 @@ InetLayer Infineon ini init +InitArgs inlined InputLoop installDebug @@ -1174,6 +1179,7 @@ subtype sudo SulfateConcentrationMeasurement SulfurDioxideConcentrationMeasurement +suppressResponse svg SVR SWD diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md new file mode 100644 index 00000000000000..461d7322864724 --- /dev/null +++ b/docs/guides/chip_tool_guide.md @@ -0,0 +1,814 @@ +# Working with the CHIP Tool + +The CHIP Tool (`chip-tool`) is a Matter controller implementation that allows to +commission a Matter device into the network and to communicate with it using +Matter messages, which may encode Data Model actions, such as cluster commands. +The tool also provides other utilities specific to Matter, such as parsing of +the setup payload or performing discovery actions. + +
+ +- [Source files](#source) +- [Building and running the CHIP Tool](#building) +- [Using the CHIP Tool for Matter device testing](#using) +- [Supported commands and options](#commands) + +
+ + + +## Source files + +You can find source files of the CHIP Tool in the `examples/chip-tool` +directory. + +> **Note:** The CHIP Tool caches the configuration state in the +> `/tmp/chip_tool_config.ini` file. Deleting this and other `.ini` files in the +> `/tmp` directory can sometimes resolve issues related to stale configuration. + +
+ + + +## Building and running the CHIP Tool + +Before you can use the CHIP Tool, you must compile it from source on Linux +(amd64/aarch64) or macOS. If you want to run it on Raspberry Pi, it must use a +64-bit OS. + +> **Note:** To ensure compatibility, always build the CHIP Tool and the Matter +> device from the same revision of the `connectedhomeip` repository. + +### Building the CHIP Tool + +To build and run the CHIP Tool: + +1. Install all required packages for Matter and prepare the source code and the + build system. Read the [Building Matter](BUILDING.md) guide for instructions. +2. Open a command prompt in the `connectedhomeip` directory. +3. Run the following command: + + ``` + ./scripts/examples/gn_build_example.sh examples/chip-tool BUILD_PATH + ``` + + In this command, `BUILD_PATH` specifies where the target binaries are to be + placed. + +### Running the CHIP Tool + +To check if the CHIP Tool runs correctly, execute the following command from the +`BUILD_PATH` directory: + +``` +$ ./chip-tool +``` + +As a result, the CHIP Tool prints all available commands. These are called +_clusters_ in this context, but not all listed commands correspond to the +_clusters_ in the Data Model (for example, pairing or discover commands). Each +listed command can however become the root of the new more complex command by +appending it with sub-commands. Examples of specific commands and their use +cases are described in the [Supported commands and options](#commands) section. + +
+ + + +## Using CHIP Tool for Matter device testing + +This section describes how to use CHIP Tool to test the Matter device. The +following steps depend on the application clusters that you implemented on the +device. + +This tutorial is using the +[Matter Lighting Application Example](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app) +with the Bluetooth LE commissioning method support. You can use other Matter +examples and still follow this procedure. If you use a different example, the +[Step 7](#step-7-control-application-data-model-clusters) may vary depending on +the clusters implemented in your application. + +### Step 1: Prepare the Matter device + +Build and program the device with the Matter device firmware by following the +[Matter Lighting Application Example](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app) +documentation. + +### Step 2: Enable Bluetooth LE advertising on Matter device + +Some examples are configured to advertise automatically on boot. Other examples +require physical trigger, for example pushing a button. Follow the documentation +of the Matter device example to learn how Bluetooth LE advertising is enabled +for the given example. + +### Step 3: Make sure the IP network is set up + +To follow the next steps, the IP network must be up and running. For instance, +the Thread network can be established using +[OpenThread Border Router](https://openthread.io/codelabs/openthread-border-router#0). + +### Step 4: Determine network pairing credentials + +You must provide the CHIP Tool with network credentials that will be used in the +device commissioning procedure to configure the device with a network interface, +such as Thread or Wi-Fi. + +The Matter specification does not define the preferred way of how the network +credentials are to be obtained by controller. In this guide, we are going to +obtain Thread network credentials. + +#### Thread network credentials + +Fetch and store the current Active Operational Dataset from the Thread Border +Router. This step may vary depending on the Thread Border Router implementation. + +If you are using +[OpenThread Border Router](https://openthread.io/codelabs/openthread-border-router#0) +(OTBR), retrieve this information using one of the following commands: + +- For OTBR running in Docker: + + ``` + sudo docker exec -it otbr sh -c "sudo ot-ctl dataset active -x" + 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 + Done + ``` + +- For OTBR native installation: + + ``` + sudo ot-ctl dataset active -x + 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 + Done + ``` + +For Thread, you might also use a different out-of-band method to fetch the +network credentials. + +#### Wi-Fi network credentials + +You must get the following Wi-Fi network credentials to commission the Matter +device to the Wi-Fi network in the following steps: + +- Wi-Fi SSID +- Wi-Fi password + +The steps required to determine the SSID and password may vary depending on the +setup. For instance, you might need to contact your local Wi-Fi network +administrator. + +### Step 5: Determine Matter device's discriminator and setup PIN code + +Matter uses a 12-bit value called _discriminator_ to discern between multiple +commissionable device advertisements and a 27-bit _setup PIN code_ to +authenticate the device. You can find these values in the logging terminal of +the device (for instance, UART) when the device boots up. For example: + +``` +I: 254 [DL]Device Configuration: +I: 257 [DL] Serial Number: TEST_SN +I: 260 [DL] Vendor Id: 65521 (0xFFF1) +I: 263 [DL] Product Id: 32768 (0x8000) +I: 267 [DL] Hardware Version: 1 +I: 270 [DL] Setup Pin Code: 20202021 +I: 273 [DL] Setup Discriminator: 3840 (0xF00) +I: 278 [DL] Manufacturing Date: (not set) +I: 281 [DL] Device Type: 65535 (0xFFFF) +``` + +In above printout, the _discriminator_ is `3840 (0xF00)` and the _setup PIN +code_ is equal to `20202021`. + +### Step 6: Commission Matter device into existing IP network + +Before communicating with the Matter device, first it must join an existing IP +network. + +Matter devices may use different commissioning channel. Typically, devices which +are not yet connected to the target IP network use Bluetooth LE as the +commissioning channel. However, if the device has already joined an IP network, +the only thing needed is to commission it to the Matter network over the IP +protocol. + +#### Commissioning over Bluetooth LE + +This section describes how your device can join the existing IP network over +Bluetooth LE and then be commissioned into a Matter network. + +After connecting the device over Bluetooth LE, the controller will print the +following log: + +``` +Secure Session to Device Established +``` + +This log will mean that the PASE (Password-Authenticated Session Establishment) +session using SPAKE2+ protocol has been established. + +##### Commissioning into Thread network over Bluetooth LE + +To commission the device to the existing Thread network, use the following +command pattern: + +``` +$ ./chip-tool pairing ble-thread hex: +``` + +In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ is the Operational Dataset determined in the + step 3. +- __ and __ are device-specific keys determined in + the step 4. + +##### Commissioning into Wi-Fi network over Bluetooth LE + +To commission the device to the existing Wi-Fi network, use the following +command pattern: + +``` +$ ./chip-tool pairing ble-wifi +``` + +In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ and __ are credentials determined in the step 3. +- __ and __ are device-specific keys determined in + the step 4. + +If you prefer the hexadecimal format, use the `hex:` prefix. For example: + +``` +$ ./chip-tool pairing ble-wifi hex: hex: +``` + +> **Note:** The __ can be provided as a hexadecimal value with the `0x` +> prefix. + +#### Commissioning into a network over IP + +This option is available when the Matter device is already present in an IP +network, but it has not been commissioned to a Matter network yet. + +To commission the device, you can use either the setup PIN code or the setup PIN +code and the discriminator, both of which you obtained in the step 5. +Alternatively, you can also use a QR code payload. + +##### Commissioning with setup PIN code + +Use the following command pattern to discover devices and try to pair with the +first discovered one using the provided setup code: + +``` +$ ./chip-tool pairing onnetwork +``` + +In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ is device specific _setup PIN code_ determined in the step 4 + and used to discover the device. + +##### Commissioning with long discriminator + +Use the following command pattern to discover devices with a long discriminator +and try to pair with the first discovered one using the provided setup code. + +``` +$ ./chip-tool pairing onnetwork-long +``` + +In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ and __ are device specific keys determined in + the step 4. + +##### Commissioning with QR code payload + +Matter devices log the QR code and its payload when they boot. + +Use the following command pattern to discover devices based on the given QR code +payload and try to pair with the first discovered one: + +``` +$ ./chip-tool qrcode +``` + +In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ is the QR code payload ID, for example + `MT:Y.K9042C00KA0648G00`. + +#### Forgetting the already-commissioned device + +The following command removes the device with the given node ID from the list of +commissioned Matter devices: + +``` +$ ./chip-tool pairing unpair +``` + +In this command, __ is the user-defined ID of the node which is going +to be forgotten by the CHIP Tool. + +### Step 7: Control application Data Model clusters + +Having completed all previous steps, you have the Matter device successfully +commissioned to the network. You can now test the device by interacting with +Data Model clusters. + +For instance, in case of the lighting application, the application has the +On/Off and Level Control clusters implemented. This means that you can test it +by toggling the bulb (using the `onoff` cluster commands) or manipulating its +brightness (using the `levelcontrol` cluster commands). + +Use the following command pattern to toggle the LED state: + +``` +$ ./chip-tool onoff toggle +``` + +In this command: + +- __ is the user-defined ID of the commissioned node. +- __ is the ID of the endpoint with OnOff cluster implemented. + +Alternatively, use the following command pattern to change the brightness of the +LED: + +``` +$ ./chip-tool levelcontrol move-to-level +``` + +In this command: + +- __ is the brightness level encoded between `0` and `254`, unless a + custom range is configured in the cluster. +- __ is the transition time. +- __ is the option mask. +- __ is the option override. +- __ is the user-defined ID of the commissioned node. +- __ is the ID of the endpoint with LevelControl cluster + implemented. + +### Step 8: Read basic information from the Matter device + +Every Matter device supports the Basic cluster, which maintains the collection +of attributes that a controller can obtain from a device. These attributes can +include the vendor name, the product name, or the software version. + +Use the CHIP Tool's `read` command on the `basic` cluster to read those values +from the device: + +``` +$ ./chip-tool basic read vendor-name +$ ./chip-tool basic read product-name +$ ./chip-tool basic read software-version +``` + +In these commands: + +- __ is the user-defined ID of the commissioned node. +- __ is the ID of the endpoint with Basic cluster implemented. + +You can also use the following command to list all available commands for Basic +cluster: + +``` +$ ./chip-tool basic +``` + +
+ + + +## Supported commands and options + +This section contains a general list of various CHIP Tool commands and options, +not limited to commissioning procedure and cluster interaction. + +### Printing all supported clusters + +To print all clusters supported by the CHIP Tool, run the following command: + +``` +$ ./chip-tool +``` + +**Example of output:** + +```bash + +[1647346057.900626][394605:394605] CHIP:TOO: Missing cluster name +Usage: + ./chip-tool cluster_name command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Clusters: | + +-------------------------------------------------------------------------------------+ + | * accesscontrol | + | * accountlogin | + | * administratorcommissioning | + | * alarms | + | * any | + | * appliancecontrol | + | * applianceeventsandalert | + | * applianceidentification | + | * appliancestatistics | + | * applicationbasic | + +``` + +### Getting the list of commands supported for a specific cluster + +To print the list of commands supported by a specific cluster, use the following +command pattern: + +``` +$ ./chip-tool +``` + +In this command: + +- __ is one of the available clusters (listed with + `chip-tool`). + +**Example of command:** + +``` +$ ./chip-tool onoff +``` + +**Example of output:** + +```bash +[1647417645.182824][404411:404411] CHIP:TOO: Missing command name +Usage: + ./chip-tool onoff command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * command-by-id | + | * off | + | * on | + | * toggle | + | * off-with-effect | + | * on-with-recall-global-scene | + | * on-with-timed-off | + | * read-by-id | + | * read | + | * write-by-id | + | * write | + | * subscribe-by-id | + | * subscribe | + | * read-event-by-id | + | * subscribe-event-by-id | + +-------------------------------------------------------------------------------------+ +[1647417645.183836][404411:404411] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:84: Error 0x0000002F + +``` + +### Getting the list of attributes supported for a specific cluster + +To get the list of attributes for a specific cluster, use the following command +pattern: + +``` +$ ./chip-tool read +``` + +In this command: + +- __ is one of the available clusters (listed with + `chip-tool`). + +**Example of command:** + +``` +$ ./chip-tool onoff read +``` + +**Example of output:** + +```bash +[1647417857.913942][404444:404444] CHIP:TOO: Missing attribute name +Usage: + ./chip-tool onoff read attribute-name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Attributes: | + +-------------------------------------------------------------------------------------+ + | * on-off | + | * global-scene-control | + | * on-time | + | * off-wait-time | + | * start-up-on-off | + | * server-generated-command-list | + | * client-generated-command-list | + | * attribute-list | + | * feature-map | + | * cluster-revision | + +-------------------------------------------------------------------------------------+ +[1647417857.914110][404444:404444] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:120: Error 0x0000002F +``` + +### Getting the list of command options + +To get the list of parameters for a specific command, use the following command +pattern: + +``` +$ ./chip-tool +``` + +In this command: + +- __ is one of the available clusters (listed with + `chip-tool`). +- __ is one of the target command names. + +**Example of command:** + +``` +$ ./chip-tool onoff on +``` + +**Example of output:** + +```bash +[1647417976.556313][404456:404456] CHIP:TOO: InitArgs: Wrong arguments number: 0 instead of 2 +Usage: + ./chip-tool onoff on node-id/group-id endpoint-id-ignored-for-group-commands [--paa-trust-store-path] [--commissioner-name] [--trace_file] [--trace_log] [--ble-adapter] [--timedInteractionTimeoutMs] [--suppressResponse] +[1647417976.556362][404456:404456] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:135: Error 0x0000002F + +``` + +#### Selected command options + +This section lists selected options that can be used to configure the input +command. + +##### Choosing the Bluetooth adapter + +To choose the Bluetooth adapter used by the CHIP Tool, use the following command +pattern: + +``` +--ble-adapter +``` + +In this command: + +- __ is the ID of HCI device. + +**Example of usage:** + +``` +$ ./chip-tool pairing ble-thread 1 hex:0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 20202021 3840 --ble-adapter 0 +``` + +##### Using message tracing + +Message tracing allows to capture CHIP Tool secure messages that can be used for +test automation. + +The following flags that control where the traces should go are available: + +- Trace file flag: + + ``` + --trace_file + ``` + + Here, __ is the name of the file where the trace data is stored. + It can be appended to a command in the following way: + + ``` + $ ./chip-tool pairing --trace_file + ``` + +- Trace log flag: + + ``` + --trace_log + ``` + + Here, __ is a `[0/1]` flag, which when set to `1` prints the trace + data with automation logs to the console. + +### Running a test suite against a paired peer device + +The CHIP Tool allows to run a set of tests, already compiled in the tool, +against a paired Matter device. + +To get the list of available tests, run the following command: + +``` +$ ./chip-tool tests +``` + +To execute a particular test against the paired device, use the following +command pattern: + +``` +$ ./chip-tool tests +``` + +In this command: + +- __ is the name of the particular test. + +### Parsing the setup payload + +The CHIP Tool offers a utility for parsing the Matter onboarding setup payload +and printing it in a readable form. For example, the payload can be printed on +the device console during boot. + +To parse the setup code, use the `payload` command with the +`parse-setup-payload` sub-command, as in the following command pattern: + +``` +$ ./chip-tool payload parse-setup-payload +``` + +Here, __ is the ID of the payload to be parsed. + +**Examples of commands:** + +- Setup QR code payload: + + ``` + $ ./chip-tool payload parse-setup-payload MT:6FCJ142C00KA0648G00 + ``` + +- Manual pairing code: + + ``` + $ ./chip-tool payload parse-setup-payload 34970112332 + ``` + +### Parsing additional data payload + +To parse additional data payload, use the following command pattern: + +``` +$ ./chip-tool parse-additional-data-payload +``` + +In this command: + +- __ is the ID of the payload with additional data to be parsed. + +### Discover actions + +The `discover` command can be used to resolve node ID and discover available +Matter devices. + +Use the following command to print the available sub-commands of the `discover` +command: + +``` +$ ./chip-tool discover +``` + +#### Resolving node name + +To resolve the DNS-SD name corresponding with the given Node ID and update the +address of the node in the device controller, use the following command pattern: + +``` +$ ./chip-tool discover resolve +``` + +In this command: + +- __ is the ID of node to be resolved. +- __ is the ID of the Matter fabric to which the node belongs. + +#### Discovering available Matter devices + +To discover all Matter commissionables available in the operation area, run the +following command: + +``` +$ ./chip-tool discover commissionables +``` + +#### Discovering available Matter commissioners + +To discover all Matter commissioners available in the operation area, run the +following command: + +``` +$ ./chip-tool discover commissioners +``` + +### Pairing + +The `pairing` command supports different means regarding Matter device +commissioning procedure. + +Thread and Wi-Fi commissioning use cases are described in the +[Using the CHIP Tool for Matter device testing](#using) section. + +To list all `pairing` sub-commands, run the following command: + +``` +$ ./chip-tool pairing +``` + +### Interacting with Data Model clusters + +As mentioned in the [Using the CHIP Tool for Matter device testing](#using) +section, executing the `chip-tool` command with a particular cluster name lists +all operations supported for this cluster, as in the following command pattern: + +``` +$ ./chip-tool +``` + +**Example of command:** + +``` +$ ./chip-tool binding +``` + +**Example of output:** + +```bash +[1647502596.396184][411686:411686] CHIP:TOO: Missing command name +Usage: + ./chip-tool binding command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * command-by-id | + | * read-by-id | + | * read | + | * write-by-id | + | * write | + | * subscribe-by-id | + | * subscribe | + | * read-event-by-id | + | * subscribe-event-by-id | + +-------------------------------------------------------------------------------------+ +[1647502596.396299][411686:411686] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:84: Error 0x0000002F +``` + +According to this list, the `binding` cluster supports operations such as read +or write. Attributes from that cluster can also be subscribed by the controller, +which means that the CHIP Tool will receive notifications, for instance when the +attribute value is changed or a specific event happens. + +#### Examples + +This section lists examples of the CHIP Tool commands dedicated to specific use +cases. + +##### Writing ACL to the `accesscontrol` cluster + +The Access Control List (ACL) concept allows to govern all Data Model +interactions (such as read attribute, write attribute, invoke command). For more +information about ACL, see +[Access Control Guide](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/access-control-guide.md). + +To write ACL to the `accesscontrol` cluster, use the following command pattern: + +``` +$ ./chip-tool accesscontrol write acl +``` + +In this command: + +- __ is the ACL data formatted as a JSON array. +- __ is the ID of the node that is going to receive ACL. +- __ is the ID of the endpoint on which the `accesscontrol` + cluster is implemented. + +##### Adding a binding table to the `binding` cluster + +Binding describes a relationship between the device that contains the binding +cluster and the end device. The proper ACL must be added to allow the end device +to receive commands from the bonded device. After the binding process, the +bonded device contains information about connected device, such as IPv6 address +and the route to the endpoint in the Matter network. + +To add a binding table to the `binding` cluster, use the following command +pattern: + +``` +$ ./chip-tool binding write binding +``` + +In this command: + +- __ is the binding data formatted as a JSON array. +- __ is the ID of the node that is going to receive the binding. +- __ is the ID of the endpoint on which the `binding` cluster is + implemented. diff --git a/examples/chip-tool/README.md b/examples/chip-tool/README.md index c31348a1780e98..b825b5b307612b 100644 --- a/examples/chip-tool/README.md +++ b/examples/chip-tool/README.md @@ -574,3 +574,8 @@ Usage: | * report | +-------------------------------------------------------------------------------------+ ``` + +To learn more about the tool, how to build it, use its commands and advanced +features, read the following guide: + +- [Working with the CHIP Tool](https://github.com/project-chip/connectedhomeip/tree/master/docs/guides/chip_tool_guide.md)