diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index f724b58f7bdb19..ca958716de9f58 100644 --- 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. + +
+ +## 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 +``` + +In this command: + +- __ is the name of the cluster. +- __ is the name of the command supported by wildcards: + + ``` + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * read | + | * read-by-id | + | * subscribe | + | * subscribe-by-id | + +-------------------------------------------------------------------------------------+ + ``` + +- __ is the name of the chosen attribute or event. +- __ is the user-defined ID of the commissioned node. +- __ 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 [parameters of the ] +``` + +In this command: + +- __ is one of the commands supported for the `any` command, as + listed above. +- _[parameters of the ]_ are the parameters required by + __. 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 +``` + +**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 + ```