doc: chip_tool_guide: info about wildcards (#27432)

* doc: chip_tool_guide: info about wildcards Added a section about wildcards to the CHIP Tool guide. Signed-off-by: Grzegorz Ferenc <[email protected]> * Restyled by prettier-markdown --------- Signed-off-by: Grzegorz Ferenc <[email protected]> Co-authored-by: Restyled.io <[email protected]>
project-chip · Jan 2, 2024 · 4681069 · 4681069
1 parent b5defa8
commit 4681069
Showing 1 changed file with 147 additions and 0 deletions.
diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md
@@ -1244,3 +1244,150 @@ using the attribute ID or the event ID:
 -   `subscribe-event-by-id`
 
 The steps are the same as for the `subscribe` or `subscribe-event` commands.
+
+<hr>
+
+## Using wildcards
+
+The CHIP Tool supports command wildcards for parameter values for clusters,
+attributes or events, or endpoints, or any combination of these. With the
+wildcards, you can for example read all attributes for the cluster `0x101` on a
+specific endpoint with a specific node ID on all devices in the Matter network.
+This allows you to parse and gather cluster information faster and more
+efficiently.
+
+The following wildcards are available:
+
+-   For all attributes: `0xFFFFFFFF`
+-   For all clusters: `0xFFFFFFFF`
+-   For all endpoints: `0xFFFF`
+
+You can combine these wildcards within a single command. Wildcards can be used
+in both [single-command](#single-command-mode-default) and
+[interactive](#interactive-mode) modes.
+
+You can use the following command pattern:
+
+```
+$ ./chip-tool <cluster_name> <command> <attribute_event_name> <node_id> <endpoint_id>
+```
+
+In this command:
+
+-   _<cluster-name\>_ is the name of the cluster.
+-   _<command\>_ is the name of the command supported by wildcards:
+
+    ```
+    +-------------------------------------------------------------------------------------+
+    | Commands:                                                                           |
+    +-------------------------------------------------------------------------------------+
+    | * read                                                                              |
+    | * read-by-id                                                                        |
+    | * subscribe                                                                         |
+    | * subscribe-by-id                                                                   |
+    +-------------------------------------------------------------------------------------+
+    ```
+
+-   _<attribute_event_name\>_ is the name of the chosen attribute or event.
+-   _<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.
+
+**Examples of commands:**
+
+-   To read all attributes (wildcard `0xFFFFFFFF`) from the cluster `doorlock`
+    for the node with ID `1` and on the endpoint `1`, run the following command:
+
+    ```
+    $ ./chip-tool doorlock read-by-id 0xFFFFFFFF 1 1
+    ```
+
+-   To read the `lock-state` attribute from the cluster `doorlock` for the node
+    with ID `1` and on all endpoints (wildcard `0xFFFF`), run the following
+    command:
+
+    ```
+    $ ./chip-tool doorlock read lock-state 1 0xFFFF
+    ```
+
+-   To read all attributes (wildcard `0xFFFFFFFF`) from the cluster `doorlock`
+    for the node with ID `1` and on all endpoints (wildcard `0xFFFF`), run the
+    following command:
+
+    ```
+    $ ./chip-tool doorlock read-by-id 0xFFFFFFFF 1 0xFFFF
+    ```
+
+### Using wildcards with `any` command
+
+Using the `any` command lets you use wildcards also for the cluster names. The
+`any` command can be combined with the following commands:
+
+```
++-------------------------------------------------------------------------------------+
+| Commands:                                                                           |
++-------------------------------------------------------------------------------------+
+| * command-by-id                                                                     |
+| * read-by-id                                                                        |
+| * write-by-id                                                                       |
+| * subscribe-by-id                                                                   |
+| * read-event-by-id                                                                  |
+| * subscribe-event-by-id                                                             |
+| * read-all                                                                          |
+| * subscribe-all                                                                     |
++-------------------------------------------------------------------------------------+
+```
+
+As a result, you can use the following command pattern:
+
+```
+$ ./chip-tool any <command_name> [parameters of the <command_name>]
+```
+
+In this command:
+
+-   _<command_name\>_ is one of the commands supported for the `any` command, as
+    listed above.
+-   _[parameters of the <command_name\>]_ are the parameters required by
+    _<command_name\>_. You can check them by running the command without any
+    parameters.
+
+**Example of command pattern for `read-by-id`:**
+
+```
+$ ./chip-tool any read-by-id <cluster-ids> <attribute-ids> <destination-id> <endpoint-ids>
+```
+
+**Examples of commands:**
+
+-   To read the `0x0` attribute (`lock state`) on the cluster `0x101`
+    (`doorlock`) for the node with ID `1` and on the endpoint `1`, run the
+    following command:
+
+    ```
+    $ ./chip-tool any read-by-id 0x101 0x0 1 1
+    ```
+
+-   To read all attributes (wildcard `0xFFFFFFFF`) from the cluster `0x101`
+    (`doorlock`) for the node with ID `1` and on the endpoint `1`, run the
+    following command:
+
+    ```
+    $ ./chip-tool any read-by-id 0x101 0xFFFFFFFF 1 1
+    ```
+
+-   To read all attributes (wildcard `0xFFFFFFFF`) on all clusters (wildcard
+    `0xFFFFFFFF`) for the node with ID `1` and on the endpoint `1`, run the
+    following command:
+
+    ```
+    ./chip-tool any read-by-id 0xFFFFFFFF 0xFFFFFFFF 1 1
+    ```
+
+-   To read all attributes (wildcard `0xFFFFFFFF`) on all clusters (wildcard
+    `0xFFFFFFFF`) for the node with ID `1` and on all endpoints (wildcard
+    `0xFFFF`), run the following command:
+
+    ```
+    ./chip-tool any read-by-id 0xFFFFFFFF 0xFFFFFFFF 1 0xFFFF
+    ```