From 6be032d57e46e115cc0c67a873aa27aed776e313 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc <41291385+greg-fer@users.noreply.github.com> Date: Wed, 22 Mar 2023 15:08:16 +0100 Subject: [PATCH] doc: chip_tool_guide: style and consistency edits (#25731) * doc: chip_tool_guide: style and consistency edits Edited the CHIP Tool guide for style and structure consistency. Signed-off-by: Grzegorz Ferenc * Restyled by prettier-markdown --------- Signed-off-by: Grzegorz Ferenc Co-authored-by: Restyled.io --- docs/guides/chip_tool_guide.md | 310 +++++++++++++++++++-------------- 1 file changed, 179 insertions(+), 131 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 7989c5b927818f..2bc999d9ecc5ac 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -3,6 +3,7 @@ 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. @@ -65,11 +66,10 @@ cases are described in the ## 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. +The following steps depend on the application clusters that you implemented on +the device. -This tutorial is using the +The steps are 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 @@ -86,10 +86,10 @@ documentation. 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. +of the Matter device example for the chosen platform to learn how Bluetooth LE +advertising is enabled for the given example. -### Step 3: Make sure the IP network is set up +### Step 3: Set up the IP network To follow the next steps, the IP network must be up and running. For instance, the Thread network can be established using @@ -147,10 +147,14 @@ 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: +Matter uses the following values: + +- Discriminator - A 12-bit value used to discern between multiple + commissionable device advertisements. +- Setup PIN code - A 27-bit value used 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: @@ -164,24 +168,28 @@ I: 278 [DL] Manufacturing Date: (not set) I: 281 [DL] Device Type: 65535 (0xFFFF) ``` -In this printout, the _discriminator_ is `3840 (0xF00)` and the _setup PIN code_ -is equal to `20202021`. +In this printout, the discriminator is `3840 (0xF00)` and the setup PIN code is +`20202021`. ### Step 6: Commission Matter device into an 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. +Matter devices can use different commissioning channels: + +- Devices that are not yet connected to the target IP network use Bluetooth LE + as the commissioning channel. +- Devices that have already joined an IP network only need to use the IP + protocol for commissioning to the Matter network. #### 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. +In this case, your device can join the existing IP network over Bluetooth LE and +then be commissioned into a Matter network. + +Different scenarios are available for Thread and Wi-Fi networks, as described in +the following subsections. After connecting the device over Bluetooth LE, the controller prints the following log: @@ -243,13 +251,14 @@ 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. +code and the discriminator, both of which you obtained in the +[step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code). 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: +To discover devices and try to pair with the first discovered device using the +provided setup code, use the following command pattern: ``` $ ./chip-tool pairing onnetwork @@ -264,8 +273,8 @@ In this command: ##### 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. +To discover devices with a long discriminator and try to pair with the first +discovered one using the provided setup code, use the following command pattern: ``` $ ./chip-tool pairing onnetwork-long @@ -282,8 +291,9 @@ In this command: Matter devices log the QR code payload and manual pairing code when they boot. -Use the following command pattern to discover devices based on the given QR code -payload or manual pairing code and try to pair with the first discovered one: +To discover devices based on the given QR code payload or manual pairing code +and try to pair with the first discovered one, use the following command +pattern: ``` $ ./chip-tool pairing code @@ -298,8 +308,8 @@ In this command: #### Forgetting the already-commissioned device -The following command removes the device with the given node ID from the list of -commissioned Matter devices: +In case commissioning needs to be retested, the following command removes the +device with the given node ID from the list of commissioned Matter devices: ``` $ ./chip-tool pairing unpair @@ -314,39 +324,43 @@ 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). +#### Example: Matter Lighting Application Example -Use the following command pattern to toggle the LED state: +In case of the Matter Lighting Application Example we referenced in step 1, the +application implements the On/Off and Level Control clusters. This means that +you can test it by toggling the bulb (using the `onoff` cluster commands) or by +manipulating its brightness (using the `levelcontrol` cluster commands): -``` -$ ./chip-tool onoff toggle -``` +- Use the following command pattern to toggle the OnOff attribute state (e.g. + visualized by the LED state): -In this command: + ``` + $ ./chip-tool onoff toggle + ``` -- __ is the user-defined ID of the commissioned node. -- __ is the ID of the endpoint with OnOff cluster implemented. + In this command: -Alternatively, use the following command pattern to change the brightness of the -LED: + - __ is the user-defined ID of the commissioned node. + - __ is the ID of the endpoint with OnOff cluster + implemented. -``` -$ ./chip-tool levelcontrol move-to-level -``` +- Use the following command pattern to change the value of the CurrentLevel + attribute (e.g. visualized by the LED brightness): -In this command: + ``` + $ ./chip-tool levelcontrol move-to-level + ``` -- __ 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. + 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 @@ -382,34 +396,44 @@ $ ./chip-tool basic This section contains a general list of various CHIP Tool commands and options, not limited to commissioning procedure and cluster interaction. -### Interactive mode versus single command mode +### Interactive mode versus single-command mode -By default, chip-tool runs in single command mode where if any single command -does not complete within a certain timeout period, chip-tool will exit with a -timeout error. +The CHIP Tool can run in one of the following modes: -Example of error: +- Single-command mode (default) - In this mode, the CHIP Tool will exit with a + timeout error if any single command does not complete within a certain + timeout period. -``` -[1650992689511] [32397:1415601] CHIP: [TOO] Run command failure: ../../../examples/chip-tool/commands/common/CHIPCommand.cpp:392: CHIP Error 0x00000032: Timeout -``` + The timeout error will look similar to the following one: + + ``` + [1650992689511] [32397:1415601] CHIP: [TOO] Run command failure: ../../../examples/chip-tool/commands/common/CHIPCommand.cpp:392: CHIP Error 0x00000032: Timeout + ``` + +- Interactive mode - In this mode, a command will terminate with an error if + it does not complete within the timeout period. However, the CHIP Tool will + not be terminated and it will not terminate processes that previous commands + have started. + +#### Modifying timeout duration in single-command mode This timeout can be modified for any command execution by supplying the optional `--timeout` parameter, which takes a value in seconds, with the maximum being 65535 seconds. -Example of command: +**Example of command:** ``` $ ./chip-tool otasoftwareupdaterequestor subscribe-event state-transition 5 10 0x1234567890 0 --timeout 65535 ``` +#### Starting the interactive mode + For commands such as event subscriptions that need to run for an extended period -of time, chip-tool can be started in interactive mode first before running the -command. In interactive mode, there will be no timeout and multiple commands can -be issued. +of time, the CHIP Tool can be started in interactive mode first before running +the command. -Example of command: +**Example of command:** ``` $ ./chip-tool interactive start @@ -599,10 +623,11 @@ $ ./chip-tool pairing ble-thread 1 hex:0e080000000000010000000300001335060004001 ##### Using message tracing -Message tracing allows to capture CHIP Tool secure messages that can be used for -test automation. +Message tracing allows capturing CHIP Tool secure messages that can be used for +test automation. The tracing uses several types of flags that control where the +traces should go. -The following flags that control where the traces should go are available: +The following flags are available: - Trace file flag: @@ -631,43 +656,25 @@ The following flags that control where the traces should go are available: 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. - -#### Example: running `TestClusters` test +- To get the list of available tests, run the following command: -As an example of running one test suite test: + ``` + $ ./chip-tool tests + ``` -``` -# Clean initialization of state. -rm -fr /tmp/chip_* +- To execute a particular test against the paired device, use the following + command pattern: -# In a shell window, start the DUT device. -./out/debug/standalone/chip-all-clusters-app + ``` + $ ./chip-tool tests + ``` -# In a second shell window, pair the DUT with chip-tool. -./out/debug/standalone/chip-tool pairing onnetwork 333221 20202021 + In this command: -# Now run the test -./out/debug/standalone/chip-tool tests TestCluster --nodeId 333221 -``` + - __ is the name of the particular test. -Developer details on how the test suite is structured can be found -[here](../../src/app/tests/suites/README.md). +See the [Examples](#running-testclusters-test) section for an example of how to +run a test from the test suite. ### Parsing the setup payload @@ -861,19 +868,50 @@ In this command: - __ is the ID of the endpoint on which the `binding` cluster is implemented. +##### Running `TestClusters` test + +Complete the following steps to +[run one test from the test suite](#running-a-test-suite-against-a-paired-peer-device): + +1. Clean the initialization of state using the following command: + ``` + rm -fr /tmp/chip_* + ``` +1. In a shell window, start the DUT device: + ``` + ./out/debug/standalone/chip-all-clusters-app + ``` +1. In a second shell window, pair the DUT with the CHIP Tool: + ``` + ./out/debug/standalone/chip-tool pairing onnetwork 333221 20202021 + ``` +1. Run the test with the following command: + ``` + ./out/debug/standalone/chip-tool tests TestCluster --nodeId 333221 + ``` + +Read the [CHIP Test Suits](../../src/app/tests/suites/README.md) page for more +information about how the test suite is structured. + ### Multi-admin scenario Multi-admin feature allows you to join Matter device to several Matter fabrics -and administer it by several different Matter administrators. First you need to -commission the Matter device to first fabric following the +and have several different Matter administrators administer it. + +Complete the steps mentioned in the following sections. + +#### Step 1: Commission to fabric + +Commission the Matter device to first fabric following the [Using CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing) section. -Before it is possible to commission a Matter device to a new fabric, the -administrator from first fabric must open the commissioning window for a new -administrator from another fabric. +#### Step 2: Open the commissioning window + +Make sure the administrator from the first fabric opens the commissioning window +for a new administrator from another fabric. -To open the commissioning window on the paired Matter device, use the following +Open the commissioning window on the paired Matter device by using the following command pattern: ``` @@ -882,15 +920,15 @@ $ ./chip-tool pairing open-commissioning-window