From 79473484ecf414e085db8c9dcc02564b7b226db4 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc <41291385+greg-fer@users.noreply.github.com> Date: Fri, 23 Jun 2023 07:32:37 +0200 Subject: [PATCH] doc: chip_tool_guide: add steps for subscription (#27346) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc: chip_tool_guide: add steps for subscription Extened the CHIP Tool guide with steps for subscribing to arguments and events. Moved some existing content around to fit the new section. Signed-off-by: Grzegorz Ferenc * Restyled by prettier-markdown * Update docs/guides/chip_tool_guide.md Co-authored-by: Michał Szablowski <56074162+doublemis1@users.noreply.github.com> * address comments from reviews Signed-off-by: Grzegorz Ferenc * Restyled by prettier-markdown * remove tips as per Boris' comment Signed-off-by: Grzegorz Ferenc --------- Signed-off-by: Grzegorz Ferenc Co-authored-by: Restyled.io Co-authored-by: Justin Wood Co-authored-by: Michał Szablowski <56074162+doublemis1@users.noreply.github.com> --- docs/guides/chip_tool_guide.md | 341 +++++++++++++++++++++++++++------ 1 file changed, 286 insertions(+), 55 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 655cc226fb6e0c..f724b58f7bdb19 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -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.
+## 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). + +
+ ## Using CHIP Tool for Matter device testing The following steps depend on the application clusters that you implemented on @@ -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: @@ -1013,3 +1021,226 @@ In this command: ``` $ ./chip-tool onoff toggle 1 1 --commissioner-name beta ``` + +
+ +### 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 +> subscription to be sent with the parameter `isUrgent` set to `True`. See the +> 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 + ``` + + All of the commands that follow will be executed in the interactive mode + (`>>>`). + +1. Run the following command to display all the available attributes you can + subscribe to for the given ``: + + ``` + >>> subscribe + ``` + + The list of all available attributes for the cluster will appears. + + > **Note:** Your accessory might not support all of these attributes. You + > will get an error if the controller sends an unsupported attribute. + + For example, for the door lock cluster: + + ```bash + >>> doorlock subscribe + ``` + + The following list will appear: + + ``` + +-------------------------------------------------------------------------------------+ + | 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 + >>> subscribe + ``` + + In this command: + + - __ is the name of the cluster. + - __ is the name of the chosen argument. + - __ specifies the minimum number of seconds that must elapse + since the last report for the server to send a new report. + - __ specifies the number of seconds that must elapse since + the last report for the server to send a new report. + - __ is the user-defined ID of the commissioned node. + - __ is the ID of the endpoint where the chosen cluster is + implemented. + + For example: + + ```bash + >>> doorlock subscribe lock-state 5 10 1 1 + ``` + +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 + ``` + + All of the commands that follow will be executed in the interactive mode + (`>>>`). + +1. Run the following command to display all the available events you can + subscribe to for the given ``: + + ``` + >>> subscribe-event + ``` + + The list of all available events for the cluster will appears. + + > **Note:** Your accessory might not support all of these events. You will + > get an error if the controller sends an unsupported event. + + For example, for the door lock cluster: + + ```bash + >>> doorlock subscribe-event + ``` + + The following list will appear: + + ``` + +-------------------------------------------------------------------------------------+ + | 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 + >>> subscribe-event + ``` + + In this command: + + - __ is the name of the cluster. + - __ is the name of the chosen event. + - __ specifies the minimum number of seconds that must elapse + since the last report for the server to send a new report. + - __ specifies the number of seconds that must elapse since + the last report for the server to send a new report. + - __ is the user-defined ID of the commissioned node. + - __ is the ID of the endpoint where the chosen cluster is + implemented. + + For example: + + ```bash + >>> doorlock subscribe-event door-lock-alarm 5 10 1 1 + ``` + +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.