| # Working with the CHIP Tool |
| |
| The CHIP Tool (`chip-tool`) is a Matter controller implementation that allows to |
| commission a Matter device into the network and to communicate with it using |
| Matter messages, which may encode Data Model actions, such as cluster commands. |
| |
| The tool also provides other utilities specific to Matter, such as parsing of |
| the setup payload or performing discovery actions. |
| |
| <hr> |
| |
| ## Source files |
| |
| You can find source files of the CHIP Tool in the `examples/chip-tool` |
| directory. |
| |
| > **Note:** The CHIP Tool caches the configuration state in the |
| > `/tmp/chip_tool_config.ini` file. Deleting this and other `.ini` files in the |
| > `/tmp` directory can sometimes resolve issues related to stale configuration. |
| |
| <hr> |
| |
| ## Building and running the CHIP Tool |
| |
| Before you can use the CHIP Tool, you must compile it from source on Linux |
| (amd64/aarch64) or macOS. If you want to run it on Raspberry Pi, it must use a |
| 64-bit OS. |
| |
| > **Note:** To ensure compatibility, always build the CHIP Tool and the Matter |
| > device from the same revision of the `connectedhomeip` repository. |
| |
| ### Building the CHIP Tool |
| |
| To build and run the CHIP Tool: |
| |
| 1. Install all required packages for Matter and prepare the source code and the |
| build system. Read the [Building Matter](BUILDING.md) guide for instructions. |
| 2. Open a command prompt in the `connectedhomeip` directory. |
| 3. Run the following command: |
| |
| ``` |
| ./scripts/examples/gn_build_example.sh examples/chip-tool BUILD_PATH |
| ``` |
| |
| In this command, `BUILD_PATH` specifies where the target binaries are to be |
| placed. |
| |
| ### Running the CHIP Tool |
| |
| To check if the CHIP Tool runs correctly, execute the following command from the |
| `BUILD_PATH` directory: |
| |
| ``` |
| $ ./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 |
| [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 |
| the device. |
| |
| The steps are using the |
| [Matter Lighting Application Example](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app) |
| with the Bluetooth LE commissioning method support. You can use other Matter |
| examples and still follow this procedure. If you use a different example, the |
| [Step 7](#step-7-control-application-data-model-clusters) may vary depending on |
| the clusters implemented in your application. |
| |
| ### Step 1: Prepare the Matter device |
| |
| Build and program the device with the Matter device firmware by following the |
| [Matter Lighting Application Example](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app) |
| documentation. |
| |
| ### Step 2: Enable Bluetooth LE advertising on Matter device |
| |
| Some examples are configured to advertise automatically on boot. Other examples |
| require physical trigger, for example pushing a button. Follow the documentation |
| of the Matter device example for the chosen platform to learn how Bluetooth LE |
| advertising is enabled for the given example. |
| |
| ### Step 3: Set up the IP network |
| |
| To follow the next steps, the IP network must be up and running. For instance, |
| the Thread network can be established using |
| [OpenThread Border Router](https://openthread.io/codelabs/openthread-border-router#0). |
| |
| ### Step 4: Determine network pairing credentials |
| |
| You must provide the CHIP Tool with network credentials that will be used in the |
| device commissioning procedure to configure the device with a network interface, |
| such as Thread or Wi-Fi. |
| |
| The Matter specification does not define the preferred way of how the network |
| credentials are to be obtained by controller. In this guide, we are going to |
| provide steps for obtaining Thread and Wi-Fi network credentials. |
| |
| #### Obtaining Thread network credentials |
| |
| Fetch and store the current Active Operational Dataset from the Thread Border |
| Router. This step may vary depending on the Thread Border Router implementation. |
| |
| If you are using |
| [OpenThread Border Router](https://openthread.io/codelabs/openthread-border-router#0) |
| (OTBR), retrieve this information using one of the following commands: |
| |
| - For OTBR running in Docker: |
| |
| ``` |
| sudo docker exec -it otbr sh -c "sudo ot-ctl dataset active -x" |
| 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 |
| Done |
| ``` |
| |
| - For OTBR native installation: |
| |
| ``` |
| sudo ot-ctl dataset active -x |
| 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 |
| Done |
| ``` |
| |
| For Thread, you might also use a different out-of-band method to fetch the |
| network credentials. |
| |
| #### Obtaining Wi-Fi network credentials |
| |
| You must get the following Wi-Fi network credentials to commission the Matter |
| device to the Wi-Fi network: |
| |
| - Wi-Fi SSID |
| - Wi-Fi password |
| |
| The steps required to determine the SSID and password may vary depending on the |
| setup. For instance, you might need to contact your local Wi-Fi network |
| administrator. |
| |
| ### Step 5: Determine Matter device's discriminator and setup PIN code |
| |
| Matter uses the following values: |
| |
| - Discriminator - A 12-bit value used to discern between multiple |
| commissionable device advertisements. |
| - Setup PIN code - A 27-bit value used to authenticate the device. |
| |
| You can find these values in the logging terminal of the device (for instance |
| UART) when the device boots up. For example: |
| |
| ``` |
| I: 254 [DL]Device Configuration: |
| I: 257 [DL] Serial Number: TEST_SN |
| I: 260 [DL] Vendor Id: 65521 (0xFFF1) |
| I: 263 [DL] Product Id: 32768 (0x8000) |
| I: 267 [DL] Hardware Version: 1 |
| I: 270 [DL] Setup Pin Code: 20202021 |
| I: 273 [DL] Setup Discriminator: 3840 (0xF00) |
| I: 278 [DL] Manufacturing Date: (not set) |
| I: 281 [DL] Device Type: 65535 (0xFFFF) |
| ``` |
| |
| In this printout, the discriminator is `3840 (0xF00)` and the setup PIN code is |
| `20202021`. |
| |
| ### Step 6: Commission Matter device into an existing IP network |
| |
| Before communicating with the Matter device, first it must join an existing IP |
| network. |
| |
| Matter devices can use different commissioning channels: |
| |
| - Devices that are not yet connected to the target IP network use Bluetooth LE |
| as the commissioning channel. |
| - Devices that have already joined an IP network only need to use the IP |
| protocol for commissioning to the Matter network. |
| |
| #### Commissioning over Bluetooth LE |
| |
| In this case, your device can join the existing IP network over Bluetooth LE and |
| then be commissioned into a Matter network. |
| |
| Different scenarios are available for Thread and Wi-Fi networks, as described in |
| the following subsections. |
| |
| After connecting the device over Bluetooth LE, the controller prints the |
| following log: |
| |
| ``` |
| Secure Session to Device Established |
| ``` |
| |
| This log message means that the PASE (Password-Authenticated Session |
| Establishment) session using SPAKE2+ protocol has been established. |
| |
| ##### Commissioning into a Thread network over Bluetooth LE |
| |
| To commission the device to the existing Thread network, use the following |
| command pattern: |
| |
| ``` |
| $ ./chip-tool pairing ble-thread <node_id> hex:<operational_dataset> <pin_code> <discriminator> |
| ``` |
| |
| In this command: |
| |
| - _<node_id\>_ is the user-defined ID of the node being commissioned. |
| - _<operational_dataset\>_ is the Operational Dataset determined in the |
| [step 4](#step-4-determine-network-pairing-credentials). |
| - _<pin_code\>_ and _<discriminator\>_ are device-specific keys determined in |
| the |
| [step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code). |
| |
| ##### Commissioning into a Wi-Fi network over Bluetooth LE |
| |
| To commission the device to the existing Wi-Fi network, use the following |
| command pattern: |
| |
| ``` |
| $ ./chip-tool pairing ble-wifi <node_id> <ssid> <password> <pin_code> <discriminator> |
| ``` |
| |
| In this command: |
| |
| - _<node_id\>_ is the user-defined ID of the node being commissioned. |
| - _<ssid\>_ and _<password\>_ are credentials determined in the step 3. |
| - _<pin_code\>_ and _<discriminator\>_ are device-specific keys determined in |
| the |
| [step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code). |
| |
| If you prefer the hexadecimal format, use the `hex:` prefix. For example: |
| |
| ``` |
| $ ./chip-tool pairing ble-wifi <node_id> hex:<ssid> hex:<password> <pin_code> <discriminator> |
| ``` |
| |
| > **Note:** The _<node_id>_ can be provided as a hexadecimal value with the `0x` |
| > prefix. |
| |
| #### Commissioning into a network over IP |
| |
| This option is available when the Matter device is already present in an IP |
| network, but it has not been commissioned to a Matter network yet. |
| |
| To commission the device, you can use either the setup PIN code or the setup PIN |
| code and the discriminator, both of which you obtained in the |
| [step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code). |
| Alternatively, you can also use a QR code payload. |
| |
| ##### Commissioning with setup PIN code |
| |
| To discover devices and try to pair with one of them using the provided setup |
| code, use the following command pattern: |
| |
| ``` |
| $ ./chip-tool pairing onnetwork <node_id> <pin_code> |
| ``` |
| |
| The command keeps trying devices until pairing with one of them succeeds or |
| until it runs out of pairing possibilities. In this command: |
| |
| - _<node_id\>_ is the user-defined ID of the node being commissioned. |
| - _<pin_code\>_ is device specific _setup PIN code_ determined in the |
| [step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code) |
| and used to discover the device. |
| |
| ##### Commissioning with long discriminator |
| |
| To discover devices with a long discriminator and try to pair with one of them |
| using the provided setup code, use the following command pattern: |
| |
| ``` |
| $ ./chip-tool pairing onnetwork-long <node_id> <pin_code> <discriminator> |
| ``` |
| |
| The command keeps trying devices until pairing with one of them succeeds or |
| until it runs out of pairing possibilities. In this command: |
| |
| - _<node_id\>_ is the user-defined ID of the node being commissioned. |
| - _<pin_code\>_ and _<discriminator\>_ are device specific keys determined in |
| the |
| [step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code). |
| |
| ##### Commissioning with QR code payload or manual pairing code |
| |
| Matter devices log the QR code payload and manual pairing code when they boot. |
| |
| To discover devices based on the given QR code payload or manual pairing code |
| and try to pair with one of them, use the following command pattern: |
| |
| ``` |
| $ ./chip-tool pairing code <node_id> <qrcode_payload-or-manual_code> |
| ``` |
| |
| The command keeps trying devices until pairing with one of them succeeds or |
| until it runs out of pairing possibilities. In this command: |
| |
| - _<node_id\>_ is the user-defined ID of the node being commissioned. |
| - _<qrcode_payload-or-manual_code\>_ is the QR code payload ID, for example |
| `MT:Y.K9042C00KA0648G00`, or a manual pairing code like |
| `749701123365521327694`. |
| |
| #### Forgetting the already-commissioned device |
| |
| In case commissioning needs to be retested, the following command removes the |
| device with the given node ID from the list of commissioned Matter devices: |
| |
| ``` |
| $ ./chip-tool pairing unpair <node_id> |
| ``` |
| |
| In this command, _<node_id\>_ is the user-defined ID of the node which is going |
| to be forgotten by the CHIP Tool. |
| |
| ### Step 7: Control application Data Model clusters |
| |
| Having completed all previous steps, you have the Matter device successfully |
| commissioned to the network. You can now test the device by interacting with |
| Data Model clusters. |
| |
| #### Example: Matter Lighting Application Example |
| |
| In case of the Matter Lighting Application Example we referenced in step 1, the |
| application implements the On/Off and Level Control clusters. This means that |
| you can test it by toggling the bulb (using the `onoff` cluster commands) or by |
| manipulating its brightness (using the `levelcontrol` cluster commands): |
| |
| - Use the following command pattern to toggle the OnOff attribute state (e.g. |
| visualized by the LED state): |
| |
| ``` |
| $ ./chip-tool onoff toggle <node_id> <endpoint_id> |
| ``` |
| |
| In this command: |
| |
| - _<node_id\>_ is the user-defined ID of the commissioned node. |
| - _<endpoint_id\>_ is the ID of the endpoint with OnOff cluster |
| implemented. |
| |
| - Use the following command pattern to change the value of the CurrentLevel |
| attribute (e.g. visualized by the LED brightness): |
| |
| ``` |
| $ ./chip-tool levelcontrol move-to-level <level> <transition_time> <option_mask> <option_override> <node_id> <endpoint_id> |
| ``` |
| |
| In this command: |
| |
| - _<level\>_ is the brightness level encoded between `0` and `254`, unless |
| a custom range is configured in the cluster. |
| - _<transition_time\>_ is the transition time. |
| - _<option_mask\>_ is the option mask. |
| - _<option_override\>_ is the option override. |
| - _<node_id\>_ is the user-defined ID of the commissioned node. |
| - _<endpoint_id\>_ is the ID of the endpoint with LevelControl cluster |
| implemented. |
| |
| ### Step 8: Read basic information from the Matter device |
| |
| Every Matter device supports the Basic Information cluster, which maintains the |
| collection of attributes that a controller can obtain from a device. These |
| attributes can include the vendor name, the product name, or the software |
| version. |
| |
| Use the CHIP Tool's `read` command on the `basicinformation` cluster to read |
| those values from the device: |
| |
| ``` |
| $ ./chip-tool basicinformation read vendor-name <node_id> <endpoint_id> |
| $ ./chip-tool basicinformation read product-name <node_id> <endpoint_id> |
| $ ./chip-tool basicinformation read software-version <node_id> <endpoint_id> |
| ``` |
| |
| In these commands: |
| |
| - _<node_id\>_ is the user-defined ID of the commissioned node. |
| - _<endpoint_id\>_ is the ID of the endpoint with Basic Information cluster |
| implemented. |
| |
| You can also use the following command to list all available commands for the |
| Basic Information cluster: |
| |
| ``` |
| $ ./chip-tool basicinformation |
| ``` |
| |
| <hr> |
| |
| ## Supported commands and options |
| |
| This section contains a general list of various CHIP Tool commands and options, |
| not limited to commissioning procedure and cluster interaction. |
| |
| ### Printing all supported clusters |
| |
| To print all clusters supported by the CHIP Tool, run the following command: |
| |
| ``` |
| $ ./chip-tool |
| ``` |
| |
| **Example of output:** |
| |
| ```bash |
| |
| [1647346057.900626][394605:394605] CHIP:TOO: Missing cluster name |
| Usage: |
| ./chip-tool cluster_name command_name [param1 param2 ...] |
| |
| +-------------------------------------------------------------------------------------+ |
| | Clusters: | |
| +-------------------------------------------------------------------------------------+ |
| | * accesscontrol | |
| | * accountlogin | |
| | * administratorcommissioning | |
| | * alarms | |
| | * any | |
| | * appliancecontrol | |
| | * applianceeventsandalert | |
| | * applianceidentification | |
| | * appliancestatistics | |
| | * applicationbasic | |
| |
| ``` |
| |
| ### Getting the list of commands supported for a specific cluster |
| |
| To print the list of commands supported by a specific cluster, use the following |
| command pattern: |
| |
| ``` |
| $ ./chip-tool <cluster_name> |
| ``` |
| |
| In this command: |
| |
| - _<cluster_name\>_ is one of the available clusters (listed with |
| `chip-tool`). |
| |
| **Example of command:** |
| |
| ``` |
| $ ./chip-tool onoff |
| ``` |
| |
| **Example of output:** |
| |
| ```bash |
| [1647417645.182824][404411:404411] CHIP:TOO: Missing command name |
| Usage: |
| ./chip-tool onoff command_name [param1 param2 ...] |
| |
| +-------------------------------------------------------------------------------------+ |
| | Commands: | |
| +-------------------------------------------------------------------------------------+ |
| | * command-by-id | |
| | * off | |
| | * on | |
| | * toggle | |
| | * off-with-effect | |
| | * on-with-recall-global-scene | |
| | * on-with-timed-off | |
| | * read-by-id | |
| | * read | |
| | * write-by-id | |
| | * write | |
| | * subscribe-by-id | |
| | * subscribe | |
| | * read-event-by-id | |
| | * subscribe-event-by-id | |
| +-------------------------------------------------------------------------------------+ |
| [1647417645.183836][404411:404411] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:84: Error 0x0000002F |
| |
| ``` |
| |
| ### Getting the list of attributes supported for a specific cluster |
| |
| To get the list of attributes for a specific cluster, use the following command |
| pattern: |
| |
| ``` |
| $ ./chip-tool <cluster_name> read |
| ``` |
| |
| In this command: |
| |
| - _<cluster_name\>_ is one of the available clusters (listed with |
| `chip-tool`). |
| |
| **Example of command:** |
| |
| ``` |
| $ ./chip-tool onoff read |
| ``` |
| |
| **Example of output:** |
| |
| ```bash |
| [1647417857.913942][404444:404444] CHIP:TOO: Missing attribute name |
| Usage: |
| ./chip-tool onoff read attribute-name [param1 param2 ...] |
| |
| +-------------------------------------------------------------------------------------+ |
| | Attributes: | |
| +-------------------------------------------------------------------------------------+ |
| | * on-off | |
| | * global-scene-control | |
| | * on-time | |
| | * off-wait-time | |
| | * start-up-on-off | |
| | * server-generated-command-list | |
| | * client-generated-command-list | |
| | * attribute-list | |
| | * feature-map | |
| | * cluster-revision | |
| +-------------------------------------------------------------------------------------+ |
| [1647417857.914110][404444:404444] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:120: Error 0x0000002F |
| ``` |
| |
| ### Getting the list of command options |
| |
| To get the list of parameters for a specific command, use the following command |
| pattern: |
| |
| ``` |
| $ ./chip-tool <cluster_name> <target_command> |
| ``` |
| |
| In this command: |
| |
| - _<cluster_name\>_ is one of the available clusters (listed with |
| `chip-tool`). |
| - _<target_command\>_ is one of the target command names. |
| |
| **Example of command:** |
| |
| ``` |
| $ ./chip-tool onoff on |
| ``` |
| |
| **Example of output:** |
| |
| ```bash |
| [1647417976.556313][404456:404456] CHIP:TOO: InitArgs: Wrong arguments number: 0 instead of 2 |
| Usage: |
| ./chip-tool onoff on node-id/group-id endpoint-id-ignored-for-group-commands [--paa-trust-store-path] [--commissioner-name] [--trace_file] [--trace_log] [--ble-adapter] [--timedInteractionTimeoutMs] [--suppressResponse] |
| [1647417976.556362][404456:404456] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:135: Error 0x0000002F |
| |
| ``` |
| |
| #### Selected command options |
| |
| This section lists selected options that can be used to configure the input |
| command. |
| |
| ##### Choosing the Bluetooth adapter |
| |
| To choose the Bluetooth adapter used by the CHIP Tool, use the following command |
| pattern: |
| |
| ``` |
| --ble-adapter <id> |
| ``` |
| |
| In this command: |
| |
| - _<id\>_ is the ID of HCI device. |
| |
| **Example of usage:** |
| |
| ``` |
| $ ./chip-tool pairing ble-thread 1 hex:0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 20202021 3840 --ble-adapter 0 |
| ``` |
| |
| ##### Using message tracing |
| |
| Message tracing allows capturing CHIP Tool secure messages that can be used for |
| test automation. The tracing uses several types of flags that control where the |
| traces should go. |
| |
| The following flags are available: |
| |
| - Trace file flag: |
| |
| ``` |
| --trace_file <filename> |
| ``` |
| |
| Here, _<filename\>_ is the name of the file where the trace data is stored. |
| It can be appended to a command in the following way: |
| |
| ``` |
| $ ./chip-tool pairing <pairing_options> --trace_file <filename> |
| ``` |
| |
| - Trace log flag: |
| |
| ``` |
| --trace_log <onoff> |
| ``` |
| |
| Here, _<onoff\>_ is a `[0/1]` flag, which when set to `1` prints the trace |
| data with automation logs to the console. |
| |
| ### Running a test suite against a paired peer device |
| |
| The CHIP Tool allows to run a set of tests, already compiled in the tool, |
| against a paired Matter device. |
| |
| - To get the list of available tests, run the following command: |
| |
| ``` |
| $ ./chip-tool tests |
| ``` |
| |
| - To execute a particular test against the paired device, use the following |
| command pattern: |
| |
| ``` |
| $ ./chip-tool tests <test_name> |
| ``` |
| |
| In this command: |
| |
| - _<test_name\>_ is the name of the particular test. |
| |
| See the [Examples](#running-testclusters-test) section for an example of how to |
| run a test from the test suite. |
| |
| ### Parsing the setup payload |
| |
| The CHIP Tool offers a utility for parsing the Matter onboarding setup payload |
| and printing it in a readable form. For example, the payload can be printed on |
| the device console during boot. |
| |
| To parse the setup code, use the `payload` command with the |
| `parse-setup-payload` sub-command, as in the following command pattern: |
| |
| ``` |
| $ ./chip-tool payload parse-setup-payload <payload> |
| ``` |
| |
| Here, _<payload\>_ is the ID of the payload to be parsed. |
| |
| **Examples of commands:** |
| |
| - Setup QR code payload: |
| |
| ``` |
| $ ./chip-tool payload parse-setup-payload MT:6FCJ142C00KA0648G00 |
| ``` |
| |
| - Manual pairing code: |
| |
| ``` |
| $ ./chip-tool payload parse-setup-payload 34970112332 |
| ``` |
| |
| ### Parsing additional data payload |
| |
| To parse additional data payload, use the following command pattern: |
| |
| ``` |
| $ ./chip-tool parse-additional-data-payload <payload> |
| ``` |
| |
| In this command: |
| |
| - _<payload\>_ is the ID of the payload with additional data to be parsed. |
| |
| ### Discover actions |
| |
| The `discover` command can be used to resolve node ID and discover available |
| Matter devices. |
| |
| Use the following command to print the available sub-commands of the `discover` |
| command: |
| |
| ``` |
| $ ./chip-tool discover |
| ``` |
| |
| #### Resolving node name |
| |
| To resolve the DNS-SD name corresponding with the given Node ID and update the |
| address of the node in the device controller, use the following command pattern: |
| |
| ``` |
| $ ./chip-tool discover resolve <node_id> <fabric_id> |
| ``` |
| |
| In this command: |
| |
| - _<node_id\>_ is the ID of node to be resolved. |
| - _<fabric_id\>_ is the ID of the Matter fabric to which the node belongs. |
| |
| #### Discovering available Matter devices |
| |
| To discover all Matter commissionables available in the operation area, run the |
| following command: |
| |
| ``` |
| $ ./chip-tool discover commissionables |
| ``` |
| |
| #### Discovering available Matter commissioners |
| |
| To discover all Matter commissioners available in the operation area, run the |
| following command: |
| |
| ``` |
| $ ./chip-tool discover commissioners |
| ``` |
| |
| ### Pairing |
| |
| The `pairing` command supports different means regarding Matter device |
| commissioning procedure. |
| |
| Thread and Wi-Fi commissioning use cases are described in the |
| [Using the CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing) |
| section. |
| |
| To list all `pairing` sub-commands, run the following command: |
| |
| ``` |
| $ ./chip-tool pairing |
| ``` |
| |
| ### Interacting with Data Model clusters |
| |
| As mentioned in the |
| [Using the CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing) |
| section, executing the `chip-tool` command with a particular cluster name lists |
| all operations supported for this cluster, as in the following command pattern: |
| |
| ``` |
| $ ./chip-tool <cluster_name> |
| ``` |
| |
| **Example of command:** |
| |
| ``` |
| $ ./chip-tool binding |
| ``` |
| |
| **Example of output:** |
| |
| ```bash |
| [1647502596.396184][411686:411686] CHIP:TOO: Missing command name |
| Usage: |
| ./chip-tool binding command_name [param1 param2 ...] |
| |
| +-------------------------------------------------------------------------------------+ |
| | Commands: | |
| +-------------------------------------------------------------------------------------+ |
| | * command-by-id | |
| | * read-by-id | |
| | * read | |
| | * write-by-id | |
| | * write | |
| | * subscribe-by-id | |
| | * subscribe | |
| | * read-event-by-id | |
| | * subscribe-event-by-id | |
| +-------------------------------------------------------------------------------------+ |
| [1647502596.396299][411686:411686] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:84: Error 0x0000002F |
| ``` |
| |
| According to this list, the `binding` cluster supports operations such as read |
| or write. Attributes from that cluster can also be subscribed by the controller, |
| which means that the CHIP Tool will receive notifications, for instance when the |
| attribute value is changed or a specific event happens. |
| |
| #### Examples |
| |
| This section lists examples of the CHIP Tool commands dedicated to specific use |
| cases. |
| |
| ##### Writing ACL to the `accesscontrol` cluster |
| |
| The Access Control List (ACL) concept allows to govern all Data Model |
| interactions (such as read attribute, write attribute, invoke command). For more |
| information about ACL, see |
| [Access Control Guide](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/access-control-guide.md). |
| |
| To write ACL to the `accesscontrol` cluster, use the following command pattern: |
| |
| ``` |
| $ ./chip-tool accesscontrol write acl <acl_data> <node_id> <endpoint_id> |
| ``` |
| |
| In this command: |
| |
| - _<acl_data\>_ is the ACL data formatted as a JSON array. |
| - _<node_id\>_ is the ID of the node that is going to receive ACL. |
| - _<endpoint_id\>_ is the ID of the endpoint on which the `accesscontrol` |
| cluster is implemented. |
| |
| ##### Adding a binding table to the `binding` cluster |
| |
| Binding describes a relationship between the device that contains the binding |
| cluster and the end device. The proper ACL must be added to allow the end device |
| to receive commands from the bonded device. After the binding process, the |
| bonded device contains information about connected device, such as IPv6 address |
| and the route to the endpoint in the Matter network. |
| |
| To add a binding table to the `binding` cluster, use the following command |
| pattern: |
| |
| ``` |
| $ ./chip-tool binding write binding <binding_data> <node_id> <endpoint_id> |
| ``` |
| |
| In this command: |
| |
| - _<binding_data\>_ is the binding data formatted as a JSON array. |
| - _<node_id\>_ is the ID of the node that is going to receive the binding. |
| - _<endpoint_id\>_ is the ID of the endpoint on which the `binding` cluster is |
| implemented. |
| |
| ##### Running `TestClusters` test |
| |
| Complete the following steps to |
| [run one test from the test suite](#running-a-test-suite-against-a-paired-peer-device): |
| |
| 1. Clean the initialization of state using the following command: |
| ``` |
| rm -fr /tmp/chip_* |
| ``` |
| 1. In a shell window, start the DUT device: |
| ``` |
| ./out/debug/standalone/chip-all-clusters-app |
| ``` |
| 1. In a second shell window, pair the DUT with the CHIP Tool: |
| ``` |
| ./out/debug/standalone/chip-tool pairing onnetwork 333221 20202021 |
| ``` |
| 1. Run the test with the following command: |
| ``` |
| ./out/debug/standalone/chip-tool tests TestCluster --nodeId 333221 |
| ``` |
| |
| Read the [CHIP Test Suits](../../src/app/tests/suites/README.md) page for more |
| information about how the test suite is structured. |
| |
| ### Multi-admin scenario |
| |
| Multi-admin feature allows you to join Matter device to several Matter fabrics |
| and have several different Matter administrators administer it. |
| |
| Complete the steps mentioned in the following sections. |
| |
| #### Step 1: Commission to fabric |
| |
| Commission the Matter device to first fabric following the |
| [Using CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing) |
| section. |
| |
| #### Step 2: Open the commissioning window |
| |
| Make sure the administrator from the first fabric opens the commissioning window |
| for a new administrator from another fabric. |
| |
| Open the commissioning window on the paired Matter device by using the following |
| command pattern: |
| |
| ``` |
| $ ./chip-tool pairing open-commissioning-window <node_id> <option> <window_timeout> <iteration> <discriminator> |
| ``` |
| |
| In this command: |
| |
| - _<node_id\>_ is the ID of the node that should open commissioning window. |
| - _<option\>_ is equal to 1 for Enhanced Commissioning Method and 0 for Basic |
| Commissioning Method. |
| - _<window_timeout\>_ is time in seconds, before the commissioning window |
| closes. |
| - _<iteration\>_ is number of PBKDF iterations to use to derive the PAKE |
| verifier. |
| - _<discriminator\>_ is device specific discriminator determined during |
| commissioning. |
| |
| > **Note:** The _<iteration\>_ and _<discriminator\>_ values are ignored if the |
| > _<option\>_ is set to 0. |
| |
| **Example of command:** |
| |
| ``` |
| $ ./chip-tool pairing open-commissioning-window 1 1 300 1000 2365 |
| ``` |
| |
| #### Step 3: Save the pairing code |
| |
| Write down the manual pairing code or the QR code payload printed in the command |
| output, as it will be required by the second Matter admin to join Matter device |
| to its fabric. |
| |
| **Example of output:** |
| |
| ``` |
| [1663675289.149337][56387:56392] CHIP:DMG: Received Command Response Status for Endpoint=0 Cluster=0x0000_003C Command=0x0000_0000 Status=0x0 |
| [1663675289.149356][56387:56392] CHIP:CTL: Successfully opened pairing window on the device |
| [1663675289.149409][56387:56392] CHIP:CTL: Manual pairing code: [36281602573] |
| [1663675289.149445][56387:56392] CHIP:CTL: SetupQRCode: [MT:4CT91AFN00YHEE7E300] |
| ``` |
| |
| #### Step 4: Commission the Matter device to a new fabric |
| |
| Complete the following steps: |
| |
| 1. Open another instance of the CHIP Tool. |
| 1. In the new instance of the CHIP Tool, commission the Matter device to a new |
| fabric by using the following command pattern: |
| |
| ``` |
| $ ./chip-tool pairing code <node_id> <payload> --commissioner-name <commissioner_name> |
| ``` |
| |
| In this command: |
| |
| - _<node_id\>_ is the user-defined ID of the node being commissioned. It |
| doesn't need to be the same ID, as for the first fabric. |
| - _<payload\>_ is the the QR code payload or a manual pairing code generated |
| by the first commissioner instance when opened commissioning window |
| - _<commissioner_name\>_ is the name of the second fabric. Valid values are |
| "alpha", "beta", "gamma", and integers greater than or equal to 4. The |
| default if not specified is "alpha". |
| |
| **Example of command:** |
| |
| ``` |
| $ ./chip-tool pairing code 1 36281602573 --commissioner-name beta |
| ``` |
| |
| #### Step 5: Test reception of commands |
| |
| After completing the above steps, the Matter device should be able to receive |
| and answer Matter commands sent in the second fabric. For example, you can use |
| the following command pattern to toggle the `OnOff` attribute state on a device |
| supporting `OnOff` cluster: |
| |
| ``` |
| $ ./chip-tool onoff toggle <node_id> <endpoint_id> --commissioner-name <commissioner_name> |
| ``` |
| |
| In this command: |
| |
| - _<node_id\>_ is the user-defined ID of the commissioned node. |
| - _<endpoint_id\>_ is the ID of the endpoint with OnOff cluster implemented. |
| - _<commissioner_name\>_ is the name of the second fabric. Valid values are |
| "alpha", "beta", "gamma", and integers greater than or equal to 4. The |
| default if not specified is "alpha". |
| |
| **Example of 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 |
| > 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 `<cluster-name>`: |
| |
| ``` |
| >>> <cluster-name> 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 |
| >>> <cluster-name> subscribe <argument> <min-interval> <max-interval> <node_id> <endpoint_id> |
| ``` |
| |
| 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 |
| >>> 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 `<cluster-name>`: |
| |
| ``` |
| >>> <cluster-name> 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 |
| >>> <cluster-name> subscribe-event <event-name> <min-interval> <max-interval> <node_id> <endpoint_id> |
| ``` |
| |
| 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 |
| >>> 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. |
| |
| <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 |
| ``` |
| |
| <hr> |
| |
| ## Saving users and credentials on door lock devices |
| |
| Matter door lock devices can store pools of users and credentials that allow you |
| to configure different access scenarios. Each user and credential in the pool |
| has an index value. Additionally, each user has a list of Occupied Credentials. |
| |
| By default, each door lock device comes with no user or credential defined, but |
| it reserves several slots in both pools that can be populated with new users and |
| credentials, up to the value specified in the the `NumberOfTotalUsersSupported` |
| attribute and the `NumberOfCredentialsSupportedPerUser` attribute, respectively. |
| |
| All communication between users and credentials happens only using their |
| respective index values. No other information is shared between both pools. |
| |
| The CHIP Tool lets you add users and credentials on door lock devices and |
| securely match their indexes to one another. This is an optional feature |
| available only when working with devices that implement the `doorlock` cluster. |
| |
| > **Note:** Users and credentials can only be modified by whoever has the right |
| > permissions, as specified in the Access Control List. |
| |
| To save credentials and users, you need to complete the following steps, |
| described in detail in the following sections: |
| |
| 1. Set up a user on the device. |
| 1. Assign a credential for the newly created user. |
| |
| ### Step 1: Set up a user |
| |
| To set up a user on a door lock device with the CHIP Tool, use the following |
| command pattern: |
| |
| ``` |
| $ ./chip-tool doorlock set-user <operation-type> <user-index> <user-name> <user-unique-id> <user-status> <user-type> <credential-rule> <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value> |
| ``` |
| |
| In this command: |
| |
| - _<operation-type\>_ is one of the available types of operation for the user: |
| |
| - `Add` - This operation sets a new user in the slot at _<user-index\>_. |
| - `Clear` - This operation removes an existing user from the slot at |
| _<user-index\>_. |
| - `Modify` - This operation modifies an existing user at the slot at |
| _<user-index\>_. |
| |
| - _<user-index\>_ is the index value of the user, between `1` and the value of |
| the `NumberOfTotalUsersSupported` attribute. Setting the user index to `0` |
| will cause an error. |
| - _<user-name\>_ is the name of the user, which can have maximum 10 bytes of |
| size. Can be set to `null`. |
| - _<user-unique-id\>_ is a 4-byte number that describes the unique user ID. |
| Can be set to `null`. |
| - _<user-status\>_ can be set to `null` or to one of the following values: |
| |
| - `1` (`OccupiedEnabled`) - This status indicates that the given user slot |
| is used and active. |
| - `3` (`OccupiedDisabled`) - This status indicates that the given user |
| slot is used, but disabled. Unlike `0` and `1`, supporting this status |
| is optional. |
| |
| - _<user-type\>_ is the type of the user, which can have one of the values |
| specified in the Matter Application Clusters specification for the |
| `doorlock` cluster (see section "5.2.9.16. `UserTypeEnum`"). Can be set to |
| `null`. |
| - _<credential-rule\>_ is the number of credentials that must be used to |
| unlock the door lock. This parameter can be set to `null` or to one of the |
| following values: |
| |
| - `0` (Single) - One credential type is required to unlock. |
| - `1` (Dual) - Two credential types are required to unlock. |
| - `2` (Triple) - Three credential types are required to unlock. |
| |
| - _<destination-id\>_ is the node ID of the door lock device. |
| - _<endpoint-id\>_ is the ID of the endpoint on the door lock device. |
| - `--timedInteractionTimeoutMs` is the duration in milliseconds (_<ms_value>_) |
| of the time window for receiving a request on the server side. This should |
| allow enough time for receiving the request. |
| |
| **Examples of command:** |
| |
| The following command runs the `set-user` command that adds (`0`) a user at the |
| index `1`; the user has the name `AAA` and the unique ID `6452`. The user's |
| status is set to `OccupiedEnabled` (`1`), the user type is set to |
| `UnrestrictedUser` (`0`), the credential rule is set to single (`0`), the |
| targeted node ID of the destination door lock device is `1` and the targeted |
| `doorlock` cluster's endpoint ID on that device is `1`. The |
| `--timedInteractionTimeoutMs` has a custom value. |
| |
| ``` |
| $ ./chip-tool doorlock set-user 0 1 AAA 6452 1 0 0 1 1 --timedInteractionTimeoutMs 1000 |
| ``` |
| |
| The following command mirrors the action of the command above, but it targets an |
| empty user name (`null`) and has `null` for the unique ID. The user status |
| defaults to `OccupiedEnabled`, the user type defaults to `UnrestrictedUser`, and |
| the credential rule defaults to single. |
| |
| ``` |
| $ ./chip-tool doorlock set-user 0 1 null null null null null 1 1 --timedInteractionTimeoutMs 1000 |
| ``` |
| |
| For more use cases for this command, see the "5.2.7.34. Set User Command" |
| section in the Matter Application Clusters specification. |
| |
| ### Step 2: Assign a credential |
| |
| Once you have a user created on the door lock device, use the following command |
| pattern to assign a credential to it: |
| |
| ``` |
| $ ./chip-tool doorlock set-credential <operation-type> <{Credential}> <credential-data> <user-index> <user-status> <user-type> <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value> |
| ``` |
| |
| In this command: |
| |
| - _<operation-type\>_ is one of the available types of operation for the |
| credential: |
| |
| - `Add` - This operation adds a new credential to a user at the slot at |
| _<user-index\>_. |
| - `Clear` - This operation removes an existing credential from the user at |
| the slot at _<user-index\>_. |
| - `Modify` - This operation modifies an existing credential for the user |
| at the slot at _<user-index\>_. |
| |
| - _<{Credential}\>_ is a JSON object, with the following two fields: |
| |
| - `"credentialType"` is the key field for the type of the credential. It |
| can have one of the following values: |
| |
| - `0` - Programming PIN |
| - `1` - PIN |
| - `2` - RFID |
| - `3` - Fingerprint |
| - `4` - Finger vein |
| |
| - `"credentialIndex"` is the key field for the index of the credential. If |
| `"credentialType"` is not "Programming PIN", `"credentialIndex"` must be |
| between `1` and the value of the `NumberOfCredentialsSupportedPerUser` |
| attribute (see the section 5.2.3.20 of the Matter Application Clusters |
| specification for details). `0` is required for the Programming PIN. In |
| other cases, setting the credential index to `0` will cause an error. |
| |
| - _<credential-data\>_ is an octet string parameter with the secret credential |
| data. For example, the PIN code value (`12345` in the example below). |
| - _<user-index\>_ is the index of the user that will be associated with the |
| credential. Can be set to `null` to create a new user. |
| - _<user-status\>_ is the status of the user that will be associated with the |
| credential. See the description of this parameter in |
| [Set up a user](#step-1-set-up-a-user). Can be set to `null`. |
| - _<user-type\>_ is the type of the user, which can have one of the values |
| specified in the Matter Application Clusters specification for the |
| `doorlock` cluster (see section "5.2.9.16. `UserTypeEnum`"). Can be set to |
| `null`. |
| - _<destination-id\>_ is the node ID of the door lock device. |
| - _<endpoint-id\>_ is the ID of the endpoint on the door lock device. |
| - `--timedInteractionTimeoutMs` is the duration in milliseconds (_<ms_value>_) |
| of the time window for receiving a request on the server side. This should |
| allow enough time for receiving the request. |
| |
| **Example of command:** |
| |
| The following command runs the `set-credential` command that adds (`0`) a PIN |
| credential (type `1`) at the index `1`. The credential data is set to `12345` |
| (PIN code value). This credential is associated with the user at the index `1`. |
| The `null` parameters for the user status and the user type indicate that the |
| credentials are added to an existing user. The targeted node ID of the |
| destination door lock device is `1` and the targeted `doorlock` cluster's |
| endpoint ID on that device is `1`. The `--timedInteractionTimeoutMs` has a |
| custom value. |
| |
| ``` |
| $ ./chip-tool doorlock set-credential 0 '{ "credentialType": 1, "credentialIndex": 1 }' "12345" 1 null null 1 1 --timedInteractionTimeoutMs 1000 |
| ``` |
| |
| For more use cases for this command, see the "5.2.7.40. Set Credential Command" |
| section in the Matter Application Clusters specification. |
| |
| ### Operations on users and credentials |
| |
| After you set up users and credentials on your door lock device, you can use |
| several CHIP Tool commands to interact with them. |
| |
| All commands reuse the parameters explained earlier in this section. The |
| following command patterns are available: |
| |
| - Reading the status of the user: |
| |
| ``` |
| $ ./chip-tool doorlock get-user <user-index> <destination-id> <endpoint-id> |
| ``` |
| |
| This command returns the status of the user at the specified _<user-index\>_ |
| at the specified _<destination-id\>_ and _<endpoint-id\>_. |
| |
| - Reading the status of the credential: |
| |
| ``` |
| $ ./chip-tool doorlock get-credential-status <{Credential}> <destination-id> <endpoint-id> |
| ``` |
| |
| This command returns the status of the credential of the specified |
| _<{Credential}\>_ at the specified _<destination-id\>_ and _<endpoint-id\>_. |
| |
| - Cleaning the user: |
| |
| ``` |
| $ ./chip-tool doorlock clear-user <user-index> <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value> |
| ``` |
| |
| This command cleans the slot containing the specified _<user-index\>_ at the |
| specified _<destination-id\>_ and _<endpoint-id\>_. |
| |
| - Cleaning the credential: |
| |
| ``` |
| $ ./chip-tool doorlock clear-credential <{Credential}> <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value> |
| ``` |
| |
| This command cleans the slot containing the specified _<{Credential}\>_ at |
| the specified _<destination-id\>_ and _<endpoint-id\>_. |
| |
| ### Operations with user PIN code |
| |
| If you set the _<credential-type\>_ to PIN when |
| [assigning credentials](#step-2-assign-a-credential), you can use the following |
| command patterns to verify if it works and invoke it to open or close the door |
| lock: |
| |
| - Verifying the PIN code: |
| |
| ``` |
| $ ./chip-tool doorlock read require-pinfor-remote-operation <destination-id> <endpoint-id> |
| ``` |
| |
| This command returns either `false` or `true`: |
| |
| - `false` indicates that providing the PIN code is not required to close |
| or open the door lock. |
| - `true` indicates that the PIN code is required to close or open the door |
| lock. |
| |
| - Changing the requirement for the PIN code usage: |
| |
| ``` |
| $ ./chip-tool doorlock write require-pinfor-remote-operation true <destination-id> <endpoint-id> |
| ``` |
| |
| This command modifies the setting of `require-pinfor-remote-operation` to |
| `true`. After you run it, you will have to use the PIN code to lock or |
| unlock the door. |
| |
| - Closing the door lock with the PIN code: |
| |
| ``` |
| $ ./chip-tool doorlock lock-door <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value> --PinCode 12345 |
| ``` |
| |
| In this command, you need to provide `--PinCode` corresponding to the PIN |
| code you set with _<credential-data\>_ (for example `12345`). |
| |
| - Opening the door lock with the PIN code: |
| |
| ``` |
| $ ./chip-tool doorlock unlock-door <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value> --PinCode 12345 |
| ``` |
| |
| In this command, you need to provide `--PinCode` corresponding to the PIN |
| code you set with _<credential-data\>_ (for example `12345`). |
