Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: chip_tool: pairing and commissioner flags #28358

Merged
merged 2 commits into from
Sep 21, 2023
Merged

doc: chip_tool: pairing and commissioner flags #28358

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6f322e6
doc: chip_tool: pairing and commissioner flags
greg-fer Jul 28, 2023
55013ab
Restyled by prettier-markdown
restyled-commits Sep 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 173 additions & 10 deletions docs/guides/chip_tool_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -489,6 +489,8 @@ Usage:

```

<hr>

### Getting the list of commands supported for a specific cluster

To print the list of commands supported by a specific cluster, use the following
Expand Down Expand Up @@ -539,6 +541,8 @@ Usage:

```

<hr>

### Getting the list of attributes supported for a specific cluster

To get the list of attributes for a specific cluster, use the following command
Expand Down Expand Up @@ -583,6 +587,8 @@ Usage:
[1647417857.914110][404444:404444] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:120: Error 0x0000002F
```

<hr>

### Getting the list of command options

To get the list of parameters for a specific command, use the following command
Expand Down Expand Up @@ -668,6 +674,69 @@ The following flags are available:
Here, _<onoff\>_ is a `[0/1]` flag, which when set to `1` prints the trace
data with automation logs to the console.

<hr>

### Commissioner name and ID flags

All CHIP Tool commands can be used together with the following
commissioner-related flags:

- `--commissioner-name`
- `--commissioner-nodeid`

These flags let you control which fabric and node ID are used for the CHIP Tool
when interacting with devices. They are especially useful in scenarios where you
are working with more than one fabric, but you can also use them with a single
CHIP Tool node identity.

#### `--commissioner-name` flag

This flag lets you control which fabric is used by selecting a specific fabric
commissioner.

As per the CHIP Tool implementation, the commissioners are required to have the
greg-fer marked this conversation as resolved.
Show resolved Hide resolved
following names: `alpha` for the first one, `beta` for the second one, `gamma`
for the third one, `4` for the fourth one, `5` for the fifth one, and so on.

If you don't use this flag, the CHIP Tool assumes that the command is meant for
the `alpha` commissioner and hence for the fabric associated with this
commissioner.

**Example of commands:**

```
$ ./chip-tool any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 1 '0,0,1,0,0,0' --keepSubscriptions true
$ ./chip-tool any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 2 '0,0,1,0,0,0' --keepSubscriptions true --commissioner-name beta
$ ./chip-tool any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 3 '0,0,1,0,0,0' --keepSubscriptions true --commissioner-name gamma
```

#### `--commissioner-nodeid` flag

This flag lets you select the node ID to use on the fabric specified with the
`--commissioner-name` flag.

If you don't use this flag, the CHIP Tool assumes that the command is sent with
the ID value that the CHIP Tool has in storage. If there's none, the CHIP Tool
sends the command with the default fallback node ID `112233`.

> **Note:** If the device has been already commissioned with a specific
> `--commissioner-nodeid`, you must always provide the `--commissioner-nodeid`
> flag with the CHIP Tool commands or update the Access Control List (ACL) on
> the device. Otherwise, the default fallback node ID `112233` is used and the
> communication will fail.

**Example of commands:**

```
$ ./chip-tool pairing code-thread 1 hex:000030000150208562618342348532605109bd31cda6908667addca8789211addac0102c4a9 34970112332 --commissioner-name alpha --commissioner-nodeid 999999
```

```
$ ./chip-tool basicinformation read vendor-id --commissioner-name alpha --commissioner-nodeid 999999
```

<hr>

### Running a test suite against a paired peer device

The CHIP Tool allows to run a set of tests, already compiled in the tool,
Expand All @@ -693,6 +762,8 @@ against a paired Matter device.
See the [Examples](#running-testclusters-test) section for an example of how to
run a test from the test suite.

<hr>

### Parsing the setup payload

The CHIP Tool offers a utility for parsing the Matter onboarding setup payload
Expand Down Expand Up @@ -722,6 +793,8 @@ Here, _<payload\>_ is the ID of the payload to be parsed.
$ ./chip-tool payload parse-setup-payload 34970112332
```

<hr>

### Parsing additional data payload

To parse additional data payload, use the following command pattern:
Expand All @@ -734,6 +807,8 @@ In this command:

- _<payload\>_ is the ID of the payload with additional data to be parsed.

<hr>

### Discover actions

The `discover` command can be used to resolve node ID and discover available
Expand Down Expand Up @@ -778,25 +853,111 @@ following command:
$ ./chip-tool discover commissioners
```

<hr>

### Pairing

The `pairing` command supports different means regarding Matter device
commissioning procedure.
The `pairing` command supports different methods for Matter device commissioning
procedure. The recommended methods are the following:

Thread and Wi-Fi commissioning use cases are described in the
[Using the CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing)
section.
- `code-thread` - For Thread commissioning.
- `code-wifi` - For Wi-Fi commissioning.
- `code` - For commissioning the device when it is already present in an IP
network.

Alternatively, you can also use the following methods described in the
[Using CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing)
section:

To list all `pairing` sub-commands, run the following command:
- `ble-thread` - For Thread commissioning; described under
[Commissioning into a Thread network over Bluetooth LE](#commissioning-into-a-thread-network-over-bluetooth-le).
- `ble-wifi` - For Wi-Fi commissioning; described under
[Commissioning into a Wi-Fi network over Bluetooth LE](#commissioning-into-a-wi-fi-network-over-bluetooth-le)
- `onnetwork` - For commissioning the device when it is already present in an
IP network; described under
[Commissioning with setup PIN code](#commissioning-with-setup-pin-code)
bzbarsky-apple marked this conversation as resolved.
Show resolved Hide resolved

To list all `pairing` sub-commands and commissioning methods, run the following
command:

```
$ ./chip-tool pairing
```

**Example of commands:**

The following command commissions the Thread device with the node ID `1` to the
Matter fabric. The `hex:...` parameter is the operational dataset that contains
information about the Thread network to which the device is going to be
commissioned. The onboarding dataset payload `34970112332` (short manual pairing
code) is used to discover and commission the device.

```
$ ./chip-tool pairing code-thread 1 hex:000030000150208562618342348532605109bd31cda6908667addca8789211addac0102c4a9 34970112332
```

The following command commissions the Wi-Fi device with the node ID `1` to the
Matter fabric The SSID `wifi_test` and the password `admin123` is the required
information about the Wi-Fi network to which the device is going to be
commissioned. The onboarding dataset payload `34970112332` (short manual pairing
code) is used to discover and commission the device.

```
$ ./chip-tool pairing code-wifi 1 wifi_test admin123 34970112332
```

The following command commissions the device with the node ID `1` to the Matter
fabric. The onboarding dataset payload `MT:8IXS142C00KA0648G00` (QR code
payload) is used to discover and commission the device.

```
$ ./chip-tool pairing code 1 MT:8IXS142C00KA0648G00
```

#### Attestation-related flags

The `pairing` commissioning command can be run with several flags that allow you
to modify attestation-related settings:

- `--paa-trust-store-path` - Use to provide the path to the directory that
contains the information about Product Attestation Authority (PAA)
certificates. The path can be absolute or relative to the current working
directory. With this flag, the CHIP Tool looks for the PAA certificate that
matches the PAI and the DAC certificates programmed on the device. Without
this flag, the CHIP Tool uses the built-in test PAA certificate.

- `--cd-trust-store-path` - Use to provide the path to the directory
containing the key that is used to validate the device's Certification
Declaration. The path can be absolute or relative to the current working
directory. With this flag, the CHIP tool looks for additional public keys,
in addition to the well-known built-in public keys (built-in public keys
`src/credentials/attestation_verifier/DefaultDeviceAttestationVerifier.cpp`),
to be used to validate Certification Declaration signatures.

* `--only-allow-trusted-cd-keys` - Use to only allow the keys from
`--cd-trust-store-path` and not the built-in test key. If the flag is not
provided or it is provided with the value `false`, untrusted CD verifying
keys are allowed. If it is provided with the value `true`
(`--only-allow-trusted-cd-keys true`), test keys are disallowed and CD
signed with the test key will not be accepted.

* `--bypass-attestation-verifier` - Use to bypass the attestation verifier. If
the flag is not provided or it is provided with the value `false`, the
attestation verifier is not bypassed. If it is provided with the value
`true` (`--bypass-attestation-verifier true`), the commissioning will
continue in case of the attestation verification failure. The failure can be
caused by errors in Certification Declaration, PAA or PAI certificates, or
in the Device Attestation Certificate. This option can be helpful if you
want to quickly commission a device with PAI and DAC certificates based on
an unknown PAA and/or with a Certification Declaration signed by an unknown
key.

<hr>

### Interacting with Data Model clusters

As mentioned in the
[Using the CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing)
[Using CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing)
section, executing the `chip-tool` command with a particular cluster name lists
all operations supported for this cluster, as in the following command pattern:

Expand Down Expand Up @@ -845,9 +1006,9 @@ 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
The Access Control List 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:
Expand Down Expand Up @@ -910,6 +1071,8 @@ Complete the following steps to
Read the [CHIP Test Suits](../../src/app/tests/suites/README.md) page for more
information about how the test suite is structured.

<hr>

### Multi-admin scenario

Multi-admin feature allows you to join Matter device to several Matter fabrics
Expand Down
Loading