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.
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.
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.
To build and run the CHIP Tool:
Install all required packages for Matter and prepare the source code and the build system. Read the Building Matter guide for instructions.
Open a command prompt in the connectedhomeip
directory.
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.
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 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 section.
This section describes how to use CHIP Tool to test the Matter device. The following steps depend on the application clusters that you implemented on the device.
This tutorial is using the Matter Lighting Application Example 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 may vary depending on the clusters implemented in your application.
Build and program the device with the Matter device firmware by following the Matter Lighting Application Example documentation.
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 to learn how Bluetooth LE advertising is enabled for the given example.
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.
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 obtain 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 (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.
You must get the following Wi-Fi network credentials to commission the Matter device to the Wi-Fi network in the following steps:
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.
Matter uses a 12-bit value called discriminator to discern between multiple commissionable device advertisements and a 27-bit setup PIN code 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 above printout, the discriminator is 3840 (0xF00)
and the setup PIN code is equal to 20202021
.
Before communicating with the Matter device, first it must join an existing IP network.
Matter devices may use different commissioning channel. Typically, devices which are not yet connected to the target IP network use Bluetooth LE as the commissioning channel. However, if the device has already joined an IP network, the only thing needed is to commission it to the Matter network over the IP protocol.
This section describes how your device can join the existing IP network over Bluetooth LE and then be commissioned into a Matter network.
After connecting the device over Bluetooth LE, the controller will print the following log:
Secure Session to Device Established
This log will mean that the PASE (Password-Authenticated Session Establishment) session using SPAKE2+ protocol has been established.
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:
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:
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.
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. Alternatively, you can also use a QR code payload.
Use the following command pattern to discover devices and try to pair with the first discovered one using the provided setup code:
$ ./chip-tool pairing onnetwork <node_id> <pin_code>
In this command:
Use the following command pattern to discover devices with a long discriminator and try to pair with the first discovered one using the provided setup code.
$ ./chip-tool pairing onnetwork-long <node_id> <pin_code> <discriminator>
In this command:
Matter devices log the QR code and its payload when they boot.
Use the following command pattern to discover devices based on the given QR code payload and try to pair with the first discovered one:
$ ./chip-tool qrcode <node_id> <qrcode_payload>
In this command:
MT:Y.K9042C00KA0648G00
.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.
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.
For instance, in case of the lighting application, the application has the On/Off and Level Control clusters implemented. This means that you can test it by toggling the bulb (using the onoff
cluster commands) or manipulating its brightness (using the levelcontrol
cluster commands).
Use the following command pattern to toggle the LED state:
$ ./chip-tool onoff toggle <node_id> <endpoint_id>
In this command:
Alternatively, use the following command pattern to change the brightness of the LED:
$ ./chip-tool levelcontrol move-to-level <level> <transition_time> <option_mask> <option_override> <node_id> <endpoint_id>
In this command:
0
and 254
, unless a custom range is configured in the cluster.Every Matter device supports the Basic 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 basic
cluster to read those values from the device:
$ ./chip-tool basic read vendor-name <node_id> <endpoint_id> $ ./chip-tool basic read product-name <node_id> <endpoint_id> $ ./chip-tool basic read software-version <node_id> <endpoint_id>
In these commands:
You can also use the following command to list all available commands for Basic cluster:
$ ./chip-tool basic
This section contains a general list of various CHIP Tool commands and options, not limited to commissioning procedure and cluster interaction.
To print all clusters supported by the CHIP Tool, run the following command:
$ ./chip-tool
Example of output:
[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 |
To print the list of commands supported by a specific cluster, use the following command pattern:
$ ./chip-tool <cluster_name>
In this command:
chip-tool
).Example of command:
$ ./chip-tool onoff
Example of output:
[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
To get the list of attributes for a specific cluster, use the following command pattern:
$ ./chip-tool <cluster_name> read
In this command:
chip-tool
).Example of command:
$ ./chip-tool onoff read
Example of output:
[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
To get the list of parameters for a specific command, use the following command pattern:
$ ./chip-tool <cluster_name> <target_command>
In this command:
chip-tool
).Example of command:
$ ./chip-tool onoff on
Example of output:
[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
This section lists selected options that can be used to configure the input command.
To choose the Bluetooth adapter used by the CHIP Tool, use the following command pattern:
--ble-adapter <id>
In this command:
Example of usage:
$ ./chip-tool pairing ble-thread 1 hex:0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 20202021 3840 --ble-adapter 0
Message tracing allows to capture CHIP Tool secure messages that can be used for test automation.
The following flags that control where the traces should go 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.
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:
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 ```
To parse additional data payload, use the following command pattern:
$ ./chip-tool parse-additional-data-payload <payload>
In this command:
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
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:
To discover all Matter commissionables available in the operation area, run the following command:
$ ./chip-tool discover commissionables
To discover all Matter commissioners available in the operation area, run the following command:
$ ./chip-tool discover commissioners
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 section.
To list all pairing
sub-commands, run the following command:
$ ./chip-tool pairing
As mentioned in the Using the 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:
[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.
This section lists examples of the CHIP Tool commands dedicated to specific use cases.
accesscontrol
clusterThe 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.
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:
accesscontrol
cluster is implemented.binding
clusterBinding 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
cluster is implemented.