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

doc: chip_tool_guide: add steps for subscription #27346

Merged
merged 8 commits into from
Jun 23, 2023
Merged

doc: chip_tool_guide: add steps for subscription #27346

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
fcad1b3
doc: chip_tool_guide: add steps for subscription
greg-fer Jun 20, 2023
dd8ce0f
Restyled by prettier-markdown
restyled-commits Jun 20, 2023
d1af60f
Merge branch 'master' into doc_update_chip_tool_guide_with_new_sections
greg-fer Jun 20, 2023
90fcfb3
Update docs/guides/chip_tool_guide.md
woody-apple Jun 20, 2023
f041630
address comments from reviews
greg-fer Jun 21, 2023
0626f5a
Restyled by prettier-markdown
restyled-commits Jun 21, 2023
1d01dea
remove tips as per Boris' comment
greg-fer Jun 22, 2023
d2072a2
Merge branch 'master' into doc_update_chip_tool_guide_with_new_sections
greg-fer Jun 22, 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
325 changes: 270 additions & 55 deletions docs/guides/chip_tool_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,16 +54,73 @@ To check if the CHIP Tool runs correctly, execute the following command from the
$ ./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
As a result, the CHIP Tool starts in the default
[single-command mode](#single-command-mode-default) and 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](#supported-commands-and-options) section.

<hr>

## CHIP Tool modes

The CHIP Tool can run in one of the following modes:

### 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.

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
```

Moreover, when using the single-command mode, the CHIP Tool will establish a new
CASE session with every command sent.

#### 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:**

```
$ ./chip-tool otasoftwareupdaterequestor subscribe-event state-transition 5 10 0x1234567890 0 --timeout 65535
```

### 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. Moreover, when
using the interactive mode, the CHIP Tool will establish a new CASE session only
when there is no session available yet. On the following commands, it will use
the existing session.

#### Starting the interactive mode

For commands such as event subscriptions that need to run for an extended period
of time, the CHIP Tool can be started in interactive mode first before running
the command.

To start the interactive mode, run the following command:

```
$ ./chip-tool interactive start
```

In this mode, you can subscribe to events or attributes. For detailed steps, see
[Subscribing to events or attributes](#subscribing-to-events-or-attributes).

<hr>

## Using CHIP Tool for Matter device testing

The following steps depend on the application clusters that you implemented on
Expand Down Expand Up @@ -398,55 +455,6 @@ $ ./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

The CHIP Tool can run in one of the following modes:

- 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.

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
```

Moreover, when using the single-command mode, the CHIP Tool will establish a
new CASE session with every command sent.

- 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. Moreover, when using the interactive mode, the CHIP Tool will
establish a new CASE session only when there is no session available yet. On
the following commands, it will use the existing session.

#### 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:**

```
$ ./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, the CHIP Tool can be started in interactive mode first before running
the command.

**Example of command:**

```
$ ./chip-tool interactive start
otasoftwareupdaterequestor subscribe-event state-transition 5 10 ${NODE_ID} 0
```

### Printing all supported clusters

To print all clusters supported by the CHIP Tool, run the following command:
Expand Down Expand Up @@ -1013,3 +1021,210 @@ In this command:
```
$ ./chip-tool onoff toggle 1 1 --commissioner-name beta
```

<hr>

### Subscribing to events or attributes

Subscribing to an event or an attribute lets you mirror the state of the event
or the attribute as it changes in the Matter network. The list of events or
attributes you can subscribe to depends on the chosen cluster.

You can have more than one subscription at any given time and subscribe to more
than one attribute or event within one subscription (those attributes or events
can come from different clusters). However, you cannot subscribe to both
attributes and events as part of a single subscription. In other words, each
subscription must be dedicated exclusively to either attributes or events.

For more information about subscriptions, see the Matter specification at
chapter 8, section 5 (Subscribe Interaction).

> **Note:** The subscription behavior will be different if you set the
> seubscription to be sent with the parameter `isUrgent` set to `True`. See the
woody-apple marked this conversation as resolved.
Show resolved Hide resolved
> Matter specification for more information.

#### Subscribing to an attribute

The following procedure will use the `doorlock` cluster as an example. Complete
the following steps:

1. Start the CHIP Tool in [interactive mode](#interactive-mode) by running the
following command:

```
$ ./chiptool interactive start
```

1. Run the following command to display all the available attributes you can
subscribe to for the given `<cluster-name>`:

```
$ ./chiptool <cluster-name> subscribe
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
```

For example:

```bash
$ ./chiptool doorlock subscribe
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
```

The list of available attributes appears:
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved

```
+-------------------------------------------------------------------------------------+
| Attributes: |
+-------------------------------------------------------------------------------------+
| * lock-state |
| * lock-type |
| * actuator-enabled |
| * door-state |
| * door-open-events |
| * door-closed-events |
| * open-period |
| * number-of-total-users-supported |
| * number-of-pinusers-supported |
| * number-of-rfidusers-supported |
| * number-of-week-day-schedules-supported-per-user |
| * number-of-year-day-schedules-supported-per-user |
| * number-of-holiday-schedules-supported |
| * max-pincode-length |
| * min-pincode-length |
| * max-rfidcode-length |
| * min-rfidcode-length |
| * credential-rules-support |
| * number-of-credentials-supported-per-user |
| * language |
| * ledsettings |
| * auto-relock-time |
| * sound-volume |
| * operating-mode |
| * supported-operating-modes |
| * default-configuration-register |
| * enable-local-programming |
| * enable-one-touch-locking |
| * enable-inside-status-led |
| * enable-privacy-mode-button |
| * local-programming-features |
| * wrong-code-entry-limit |
| * user-code-temporary-disable-time |
| * send-pinover-the-air |
| * require-pinfor-remote-operation |
| * expiring-user-timeout |
| * generated-command-list |
| * accepted-command-list |
| * event-list |
| * attribute-list |
| * feature-map |
| * cluster-revision |
+-------------------------------------------------------------------------------------+
```

1. Add the argument of your choice to the subscription command, using the
following pattern:

```bash
$ ./chiptool <cluster-name> subscribe <argument> <min-interval> <max-interval> <node_id> <endpoint_id>
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
```

In this command:

- _<cluster-name\>_ is the name of the cluster.
- _<argument\>_ is the name of the chosen argument.
- _<min-interval\>_ specifies the minimum number of seconds that must elapse
since the last report for the server to send a new report.
- _<max-interval\>_ specifies the number of seconds that must elapse since
the last report for the server to send a new report.
- _<node-id\>_ is the user-defined ID of the commissioned node.
- _<endpoint_id\>_ is the ID of the endpoint where the chosen cluster is
implemented.

For example:

```bash
$ ./chiptool doorlock subscribe lock-state 5 10 node_1 0
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
```

After this command is run, the CHIP Tool will check the state of the door lock
every time it changes (for example, as a result of a button press or an external
ecosystem action) and update it in its own records.

#### Subscribing to an event

The procedure for subscribing to an event is similar to
[subscribing to an attribute](#subscribing-to-an-attribute).

The following procedure will use the `doorlock` cluster as an example. Complete
the following steps:

1. Start the CHIP Tool in [interactive mode](#interactive-mode) by running the
following command:

```
$ ./chiptool interactive start
```

1. Run the following command to display all the available events you can
subscribe to for the given `<cluster-name>`:

```
$ ./chiptool <cluster-name> subscribe-event
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
```

For example:

```bash
$ ./chiptool doorlock subscribe-event
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
```

The list of available attributes appears:

```
+-------------------------------------------------------------------------------------+
| Events: |
+-------------------------------------------------------------------------------------+
| * door-lock-alarm |
| * door-state-change |
| * lock-operation |
| * lock-operation-error |
| * lock-user-change |
+-------------------------------------------------------------------------------------+
```

1. Add the event of your choice to the subscription command, using the following
pattern:

```bash
$ ./chiptool <cluster-name> subscribe-event <event-name> <min-interval> <max-interval> <node_id> <endpoint_id>
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
```

In this command:

- _<cluster-name\>_ is the name of the cluster.
- _<event-name\>_ is the name of the chosen event.
- _<min-interval\>_ specifies the minimum number of seconds that must elapse
since the last report for the server to send a new report.
- _<max-interval\>_ specifies the number of seconds that must elapse since
the last report for the server to send a new report.
- _<node_id\>_ is the user-defined ID of the commissioned node.
- _<endpoint_id\>_ is the ID of the endpoint where the chosen cluster is
implemented.

For example:

```bash
$ ./chiptool doorlock subscribe-event door-lock-alarm 5 10 node_1 0
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
kkasperczyk-no marked this conversation as resolved.
Show resolved Hide resolved
```

After this command is run, the CHIP Tool will check the state of the door lock
every time it changes (for example, as a result of a button press or an external
ecosystem action) and update it in its own records.

#### Subscribing using attribute ID or event ID

You can also use the following commands instead of `subscribe` to subscribe
using the attribute ID or the event ID:

- `subscribe-by-id`
- `subscribe-event-by-id`

The steps are the same as for the `subscribe` or `subscribe-event` commands.