Skip to content

Commit

Permalink
docs: chip-tool: fix markdown for code sections (#19425)
Browse files Browse the repository at this point in the history
The markdown used to indicate a code section must start at the beginning
of the line. Prior to this commit, the three backticks were indented
several spaces, causing the entire line to be literally interpretted and
displaying the backtick symbols in the rendered page. Fixed by removing
the leading space which will give the intended result.

This changeset also removes the "$ " characters in front of command line
steps (and adds line continuation characters \ as needed), enabling
them to copy-and-pasted more easily.
  • Loading branch information
presto8 authored and pull[bot] committed Jan 15, 2024
1 parent eecb34a commit 4914569
Showing 1 changed file with 91 additions and 90 deletions.
181 changes: 91 additions & 90 deletions examples/chip-tool/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,9 @@ remote device, as well as the network credentials to use.
The command below uses the default values hard-coded into the debug versions of
the ESP32 all-clusters-app to commission it onto a Wi-Fi network:

```
$ chip-tool pairing ble-wifi ${NODE_ID_TO_ASSIGN} ${SSID} ${PASSWORD} 20202021 3840
```
```
chip-tool pairing ble-wifi ${NODE_ID_TO_ASSIGN} ${SSID} ${PASSWORD} 20202021 3840
```

where:

Expand All @@ -81,38 +81,38 @@ where:

For example:

```
$ chip-tool pairing ble-wifi 0x11 xyz secret 20202021 3840
```
```
chip-tool pairing ble-wifi 0x11 xyz secret 20202021 3840
```

or equivalently:

```
$ chip-tool pairing ble-wifi 17 hex:787980 hex:736563726574 20202021 3840
```
```
chip-tool pairing ble-wifi 17 hex:787980 hex:736563726574 20202021 3840
```

#### Pair a device over IP

The command below will discover devices and try to pair with the first one it
discovers using the provided setup code.

```
$ chip-tool pairing onnetwork ${NODE_ID_TO_ASSIGN} 20202021
```
```
chip-tool pairing onnetwork ${NODE_ID_TO_ASSIGN} 20202021
```

The command below will discover devices with long discriminator 3840 and try to
pair with the first one it discovers using the provided setup code.

```
$ chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840
```
```
chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840
```

The command below will discover devices based on the given QR code (which
devices log when they start up) and try to pair with the first one it discovers.

```
$ chip-tool pairing code ${NODE_ID_TO_ASSIGN} MT:#######
```
```
chip-tool pairing code ${NODE_ID_TO_ASSIGN} MT:#######
```

In all these cases, the device will be assigned node id `${NODE_ID_TO_ASSIGN}`
(which must be a decimal number or a 0x-prefixed hex number).
Expand All @@ -129,15 +129,15 @@ Attestation Verification. It will also discover devices with long discriminator
3840 and try to pair with the first one it discovers using the provided setup
code.

```
$ chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 --paa-trust-store-path path/to/PAAs
```
```
chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 --paa-trust-store-path path/to/PAAs
```

### Forget the currently-commissioned device

```
$ chip-tool pairing unpair
```
```
chip-tool pairing unpair
```

## Using the Client to Send Matter Commands

Expand All @@ -146,9 +146,9 @@ the target cluster name, the target command name as well as an endpoint id.

The endpoint id must be between 1 and 240.

```
$ chip-tool onoff on 1
```
```
chip-tool onoff on 1
```

The client will send a single command packet and then exit.

Expand All @@ -158,27 +158,28 @@ The client will send a single command packet and then exit.

2. Add Group to device

```
$ chip-tool groups add-group GroupId GroupName node-id endpoint-id
$ chip-tool groups add-group 0x4141 Light 1234 1
```
```
chip-tool groups add-group GroupId GroupName node-id endpoint-id
chip-tool groups add-group 0x4141 Light 1234 1
```

3. Add group Keyset to device

```
$ chip-tool groupkeymanagement key-set-write GroupKeySet node-id endpoint-id
$ chip-tool groupkeymanagement key-set-write '{"groupKeySetID": 42,
"groupKeySecurityPolicy": 0, "epochKey0":
"d0d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime0": 2220000,"epochKey1":
"d1d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime1": 2220001,"epochKey2":
```
chip-tool groupkeymanagement key-set-write GroupKeySet node-id endpoint-id
chip-tool groupkeymanagement key-set-write '{"groupKeySetID": 42, \
"groupKeySecurityPolicy": 0, "epochKey0": \
"d0d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime0": 2220000,"epochKey1": \
"d1d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime1": 2220001,"epochKey2": \
"d2d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime2": 2220002 }' 1234 0
```
```

4. Bind Key to group
```
$ chip-tool groupkeymanagement write group-key-map attr-value node-id endpoint-id
$ chip-tool groupkeymanagement write group-key-map '[{"groupId": 16705, "groupKeySetID": 42}]' 1234 0
```

```
chip-tool groupkeymanagement write group-key-map attr-value node-id endpoint-id
chip-tool groupkeymanagement write group-key-map '[{"groupId": 16705, "groupKeySetID": 42}]' 1234 0
```

## Configuring the client for Group Commands

Expand All @@ -187,35 +188,35 @@ must be configured appropriately.

To configure the client please use the groupsettings option

```
$ chip-tool groupsettings
```
```
chip-tool groupsettings
```

A group with a valid encryption key needs to be set. The groupid and the
encryption key must match the one configured on the end device.

To add a group

```
$ chip-tool groupsettings add-group groupName groupId
$ chip-tool groupsettings add-group TestName 0x4141
```
```
chip-tool groupsettings add-group groupName groupId
chip-tool groupsettings add-group TestName 0x4141
```

To add a keyset

```
$ chip-tool groupsettings add-keysets keysetId keyPolicy validityTime EpochKey
$ chip-tool groupsettings add-keysets 0xAAAA 0 0x000000000021dfe0 hex:d0d1d2d3d4d5d6d7d8d9dadbdcdddedf
```
```
chip-tool groupsettings add-keysets keysetId keyPolicy validityTime EpochKey
chip-tool groupsettings add-keysets 0xAAAA 0 0x000000000021dfe0 hex:d0d1d2d3d4d5d6d7d8d9dadbdcdddedf
```

Take note that the epoch key must be in hex form with the 'hex:' prefix

Finally to bind the keyset to the group

```
$ chip-tool groupsettings bind-keyset groupId keysetId
$ chip-tool groupsettings bind-keyset 0x4141 0xAAAA
```
```
chip-tool groupsettings bind-keyset groupId keysetId
chip-tool groupsettings bind-keyset 0x4141 0xAAAA
```

## Using the Client to Send Group (Multicast) Matter Commands

Expand All @@ -226,9 +227,9 @@ and attributes write can be send with Group Id.

E.G. sending to group Id 0x4141

```
$ chip-tool onoff on 0xffffffffffff4141 1
```
```
chip-tool onoff on 0xffffffffffff4141 1
```

The client will send a single multicast command packet and then exit.

Expand All @@ -237,9 +238,9 @@ The client will send a single multicast command packet and then exit.
To get the list of supported clusters, run the built executable without any
arguments.

```
$ chip-tool
```
```
chip-tool
```

Example output:

Expand Down Expand Up @@ -271,33 +272,33 @@ Usage:
To get the list of commands for a specific cluster, run the built executable
with the target cluster name.

```
$ chip-tool onoff
```
```
chip-tool onoff
```

### How to get the list of supported attributes for a specific cluster

To the the list of attributes for a specific cluster, run the built executable
with the target cluster name and the `read` command name.

```
$ chip-tool onoff read
```
```
chip-tool onoff read
```

### How to get the list of parameters for a command

To get the list of parameters for a specific command, run the built executable
with the target cluster name and the target command name

```
$ chip-tool onoff on
```
```
chip-tool onoff on
```

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

```
$ chip-tool tests Test_TC_OO_1_1
```
```
chip-tool tests Test_TC_OO_1_1
```

## Using the Client for Setup Payload

Expand All @@ -306,36 +307,36 @@ with the target cluster name and the target command name
To parse a setup code, run the built executable with the `payload` cluster name
and the `parse-setup-payload` command

```
$ chip-tool payload parse-setup-payload code
```
```
chip-tool payload parse-setup-payload code
```

#### QR Code

```
$ chip-tool payload parse-setup-payload "MT:#####"
```
```
chip-tool payload parse-setup-payload "MT:#####"
```

#### QR Code with optional Vendor Info

```
$ chip-tool payload parse-setup-payload "MT:#####"
```
```
chip-tool payload parse-setup-payload "MT:#####"
```

#### Manual Setup Code

```
$ chip-tool payload parse-setup-payload "#####"
```
```
chip-tool payload parse-setup-payload "#####"
```

# Using the Client for Additional Data Payload

To parse an additional data payload, run the built executable with the `payload`
cluster name and the `parse-additional-data-payload` command

```
$ chip-tool payload parse-additional-data-payload "#####"
```
```
chip-tool payload parse-additional-data-payload "#####"
```

# Command Reference

Expand Down

0 comments on commit 4914569

Please sign in to comment.