From fcad1b324ba1d51a3e901cafe95bdfcfdc02c846 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Tue, 20 Jun 2023 13:47:38 +0200 Subject: [PATCH 1/6] 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 --- docs/guides/chip_tool_guide.md | 287 +++++++++++++++++++++++++++------ 1 file changed, 237 insertions(+), 50 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 655cc226fb6e0c..e06c0dd485377a 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -54,7 +54,7 @@ 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 +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 @@ -64,6 +64,61 @@ cases are described in the
+## 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 +453,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 +1019,184 @@ 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 seubscription 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 + ``` + +1. Run the following command to display all the available attributes you can subscribe to for the given ``: + + ``` + $ ./chiptool subscribe + ``` + + For example: + + ```bash + $ ./chiptool doorlock subscribe + ``` + + The list of available attributes appears: + + ``` + +-------------------------------------------------------------------------------------+ + | 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 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 + $ ./chiptool doorlock subscribe lock-state 5 10 node_1 0 + ``` + +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 ``: + + ``` + $ ./chiptool subscribe-event + ``` + + For example: + + ```bash + $ ./chiptool doorlock subscribe-event + ``` + + 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 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 + $ ./chiptool doorlock subscribe-event door-lock-alarm 5 10 node_1 0 + ``` + +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. From dd8ce0f475801650bd1e4374931e484402bf39e2 Mon Sep 17 00:00:00 2001 From: "Restyled.io" Date: Tue, 20 Jun 2023 14:50:44 +0000 Subject: [PATCH 2/6] Restyled by prettier-markdown --- docs/guides/chip_tool_guide.md | 350 ++++++++++++++++++--------------- 1 file changed, 189 insertions(+), 161 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index e06c0dd485377a..356d3d0b905762 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -54,12 +54,13 @@ To check if the CHIP Tool runs correctly, execute the following command from the $ ./chip-tool ``` -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 +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.
@@ -70,8 +71,8 @@ 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. +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: @@ -79,8 +80,8 @@ 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. +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 @@ -96,11 +97,12 @@ $ ./chip-tool otasoftwareupdaterequestor subscribe-event state-transition 5 10 0 ### 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. +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 @@ -114,8 +116,8 @@ 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). +In this mode, you can subscribe to events or attributes. For detailed steps, see +[Subscribing to events or attributes](#subscribing-to-events-or-attributes).
@@ -1024,179 +1026,205 @@ $ ./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. +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. +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). +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 Matter specification for more information. +> **Note:** The subscription behavior will be different if you set the +> seubscription 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: +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 ``: + + ``` + $ ./chiptool subscribe + ``` + + For example: + + ```bash + $ ./chiptool doorlock subscribe + ``` + + The list of available attributes appears: + + ``` + +-------------------------------------------------------------------------------------+ + | 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 subscribe + ``` + + In this command: -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 ``: - - ``` - $ ./chiptool subscribe - ``` - - For example: - - ```bash - $ ./chiptool doorlock subscribe - ``` - - The list of available attributes appears: - - ``` - +-------------------------------------------------------------------------------------+ - | 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 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 - $ ./chiptool doorlock subscribe lock-state 5 10 node_1 0 - ``` - -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. + - __ 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 + $ ./chiptool doorlock subscribe lock-state 5 10 node_1 0 + ``` + +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 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: +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: +1. Start the CHIP Tool in [interactive mode](#interactive-mode) by running the + following command: - ``` - $ ./chiptool interactive start - ``` + ``` + $ ./chiptool interactive start + ``` -1. Run the following command to display all the available events you can subscribe to for the given ``: +1. Run the following command to display all the available events you can + subscribe to for the given ``: - ``` - $ ./chiptool subscribe-event - ``` + ``` + $ ./chiptool subscribe-event + ``` - For example: + For example: - ```bash - $ ./chiptool doorlock subscribe-event - ``` + ```bash + $ ./chiptool doorlock subscribe-event + ``` - The list of available attributes appears: + The list of available attributes appears: - ``` - +-------------------------------------------------------------------------------------+ - | Events: | - +-------------------------------------------------------------------------------------+ - | * door-lock-alarm | - | * door-state-change | - | * lock-operation | - | * lock-operation-error | - | * lock-user-change | - +-------------------------------------------------------------------------------------+ - ``` + ``` + +-------------------------------------------------------------------------------------+ + | 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: +1. Add the event of your choice to the subscription command, using the following + pattern: - ```bash - $ ./chiptool subscribe-event - ``` + ```bash + $ ./chiptool subscribe-event + ``` - In this command: + 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. + - __ 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: + For example: - ```bash - $ ./chiptool doorlock subscribe-event door-lock-alarm 5 10 node_1 0 - ``` + ```bash + $ ./chiptool doorlock subscribe-event door-lock-alarm 5 10 node_1 0 + ``` -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. +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: +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` +- `subscribe-by-id` +- `subscribe-event-by-id` The steps are the same as for the `subscribe` or `subscribe-event` commands. From 90fcfb38f710d72cc772a9ce06aa4c7c462e48d2 Mon Sep 17 00:00:00 2001 From: Justin Wood Date: Tue, 20 Jun 2023 11:00:08 -0400 Subject: [PATCH 3/6] Update docs/guides/chip_tool_guide.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Szablowski <56074162+doublemis1@users.noreply.github.com> --- docs/guides/chip_tool_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 356d3d0b905762..3341aaae473f1d 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1040,7 +1040,7 @@ 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 +> subscription to be sent with the parameter `isUrgent` set to `True`. See the > Matter specification for more information. #### Subscribing to an attribute From f04163099198482fc54d42e5af48aec6a3236808 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Wed, 21 Jun 2023 11:00:37 +0200 Subject: [PATCH 4/6] address comments from reviews Signed-off-by: Grzegorz Ferenc --- docs/guides/chip_tool_guide.md | 38 +++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 3341aaae473f1d..13e47c09ac86f9 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1055,20 +1055,25 @@ the following steps: $ ./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 ``: ``` - $ ./chiptool subscribe + >>> subscribe ``` - For example: + 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 - $ ./chiptool doorlock subscribe + >>> doorlock subscribe ``` - The list of available attributes appears: + The following list will appear: ``` +-------------------------------------------------------------------------------------+ @@ -1123,7 +1128,7 @@ the following steps: following pattern: ```bash - $ ./chiptool subscribe + >>> subscribe ``` In this command: @@ -1141,9 +1146,11 @@ the following steps: For example: ```bash - $ ./chiptool doorlock subscribe lock-state 5 10 node_1 0 + >>> doorlock subscribe lock-state 5 10 1 1 ``` + > **Tip:** You can also set the ``$NODE_ID`` and ``$ENDPOINT_ID`` variables for the __ and __, respectively, and use them in your commands. + 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. @@ -1163,20 +1170,25 @@ the following steps: $ ./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 ``: ``` - $ ./chiptool subscribe-event + >>> subscribe-event ``` - For example: + 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 - $ ./chiptool doorlock subscribe-event + >>> doorlock subscribe-event ``` - The list of available attributes appears: + The following list will appear: ``` +-------------------------------------------------------------------------------------+ @@ -1194,7 +1206,7 @@ the following steps: pattern: ```bash - $ ./chiptool subscribe-event + >>> subscribe-event ``` In this command: @@ -1212,9 +1224,11 @@ the following steps: For example: ```bash - $ ./chiptool doorlock subscribe-event door-lock-alarm 5 10 node_1 0 + >>> doorlock subscribe-event door-lock-alarm 5 10 1 1 ``` + > **Tip:** You can also set the ``$NODE_ID`` and ``$ENDPOINT_ID`` variables for the __ and __, respectively, and use them in your commands. + 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. From 0626f5add2ded49b4239cf1de2692f8dbfa52aef Mon Sep 17 00:00:00 2001 From: "Restyled.io" Date: Wed, 21 Jun 2023 09:01:23 +0000 Subject: [PATCH 5/6] Restyled by prettier-markdown --- docs/guides/chip_tool_guide.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 13e47c09ac86f9..bda3c436ad02a9 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1055,7 +1055,9 @@ the following steps: $ ./chiptool interactive start ``` - All of the commands that follow will be executed in the interactive mode (``>>>``). + 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 ``: @@ -1065,7 +1067,8 @@ the following steps: 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. + > **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: @@ -1149,7 +1152,9 @@ the following steps: >>> doorlock subscribe lock-state 5 10 1 1 ``` - > **Tip:** You can also set the ``$NODE_ID`` and ``$ENDPOINT_ID`` variables for the __ and __, respectively, and use them in your commands. + > **Tip:** You can also set the `$NODE_ID` and `$ENDPOINT_ID` variables for + > the __ and __, respectively, and use them in your + > commands. 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 @@ -1170,7 +1175,9 @@ the following steps: $ ./chiptool interactive start ``` - All of the commands that follow will be executed in the interactive mode (``>>>``). + 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 ``: @@ -1180,7 +1187,8 @@ the following steps: 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. + > **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: @@ -1227,7 +1235,9 @@ the following steps: >>> doorlock subscribe-event door-lock-alarm 5 10 1 1 ``` - > **Tip:** You can also set the ``$NODE_ID`` and ``$ENDPOINT_ID`` variables for the __ and __, respectively, and use them in your commands. + > **Tip:** You can also set the `$NODE_ID` and `$ENDPOINT_ID` variables for + > the __ and __, respectively, and use them in your + > commands. 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 From 1d01dea68df38be58bc2f4033e1c77470a177c5f Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Thu, 22 Jun 2023 10:20:55 +0200 Subject: [PATCH 6/6] remove tips as per Boris' comment Signed-off-by: Grzegorz Ferenc --- docs/guides/chip_tool_guide.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index bda3c436ad02a9..f724b58f7bdb19 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1152,10 +1152,6 @@ the following steps: >>> doorlock subscribe lock-state 5 10 1 1 ``` - > **Tip:** You can also set the `$NODE_ID` and `$ENDPOINT_ID` variables for - > the __ and __, respectively, and use them in your - > commands. - 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. @@ -1235,10 +1231,6 @@ the following steps: >>> doorlock subscribe-event door-lock-alarm 5 10 1 1 ``` - > **Tip:** You can also set the `$NODE_ID` and `$ENDPOINT_ID` variables for - > the __ and __, respectively, and use them in your - > commands. - 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.