# Matter Client Example An example application that uses Matter to send messages to a Matter server. --- - [Building the Example Application](#building-the-example-application) - [Using the Client to Commission a Device](#using-the-client-to-commission-a-device) --- ## Building the Example Application See [the build guide](../../docs/guides/BUILDING.md#prerequisites) for general background on build prerequisites. Building the example application is quite straightforward. It can either be done as part of an overall "build everything" build: ``` ./gn_build.sh ``` which puts the binary at `out/debug/standalone/chip-tool` or directly via: ``` scripts/examples/gn_build_example.sh examples/chip-tool SOME-PATH/ ``` which puts the binary at `SOME-PATH/chip-tool`. ### Using message tracing Message tracing allows capture of the secure messages which can be used for test automation. There are additional flags to chip-tool to control where the traces should go: - --trace_file Outputs trace data to the specified file. - --trace_log <0/1> Outputs trace data to the console with automation logs if set to 1 For example: ``` out/with_trace/chip-tool pairing --trace_file trace.log ``` ## Using the Client to commission a device In order to send commands to a device, it must be commissioned with the client. chip-tool currently only supports commissioning and remembering one device at a time. The configuration state is stored in `/tmp/chip_tool_config.ini`; deleting this and other `.ini` files in `/tmp` can sometimes resolve issues due to stale configuration. #### Commission a device To initiate a client commissioning request to a device, run the built executable and choose the pairing mode. #### Commission a device over BLE Run the built executable and pass it the discriminator and pairing code of the remote device, as well as the network credentials to use. The command below uses the default values hard-coded into the debug versions of the ESP32 all-clusters-app to commission it onto a Wi-Fi network: ``` chip-tool pairing ble-wifi ${NODE_ID_TO_ASSIGN} ${SSID} ${PASSWORD} 20202021 3840 ``` where: - \${NODE_ID_TO_ASSIGN} (which must be a decimal number or a `0x`-prefixed hex number) is the node id to assign to the node being commissioned. - \${SSID} is the Wi-Fi SSID either as a string, or in the form `hex:XXXXXXXX` where the bytes of the SSID are encoded as two-digit hex numbers. - \${PASSWORD} is the Wi-Fi password, again either as a string or as hex data For example: ``` chip-tool pairing ble-wifi 0x11 xyz secret 20202021 3840 ``` or equivalently: ``` chip-tool pairing ble-wifi 17 hex:787980 hex:736563726574 20202021 3840 ``` #### Pair a device over IP The command below will discover devices and try to pair with the first one it discovers using the provided setup code. ``` chip-tool pairing onnetwork ${NODE_ID_TO_ASSIGN} 20202021 ``` The command below will discover devices with long discriminator 3840 and try to pair with the first one it discovers using the provided setup code. ``` chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 ``` The command below will discover devices based on the given QR code (which devices log when they start up) and try to pair with the first one it discovers. ``` chip-tool pairing code ${NODE_ID_TO_ASSIGN} MT:####### ``` In all these cases, the device will be assigned node id `${NODE_ID_TO_ASSIGN}` (which must be a decimal number or a 0x-prefixed hex number). #### Trust Store Trust store will be automatically created using the default Test Attestation PAA. To use a different set of PAAs, pass the path using the optional parameter --paa-trust-store-path while running the built executable. Trusted PAAs are available at credentials/development/paa-root-certs/. The command below will select a set of trusted PAAs to be used during Attestation Verification. It will also discover devices with long discriminator 3840 and try to pair with the first one it discovers using the provided setup code. ``` chip-tool pairing onnetwork-long ${NODE_ID_TO_ASSIGN} 20202021 3840 --paa-trust-store-path path/to/PAAs ``` ### Forget the currently-commissioned device ``` chip-tool pairing unpair ``` ## Using the Client to Send Matter Commands To use the Client to send Matter commands, run the built executable and pass it the target cluster name, the target command name as well as an endpoint id. The endpoint id must be between 1 and 240. ``` chip-tool onoff on 1 ``` The client will send a single command packet and then exit. ## Configuring the server side for Group Commands 1. Commission and pair device with nodeId 1234 2. Add group Keyset to device ``` chip-tool groupkeymanagement key-set-write GroupKeySet node-id endpoint-id chip-tool groupkeymanagement key-set-write '{"groupKeySetID": 42, \ "groupKeySecurityPolicy": 0, "epochKey0": \ "d0d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime0": 2220000,"epochKey1": \ "d1d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime1": 2220001,"epochKey2": \ "d2d1d2d3d4d5d6d7d8d9dadbdcdddedf", "epochStartTime2": 2220002 }' 1234 0 ``` 3. Bind Key to group ``` chip-tool groupkeymanagement write group-key-map attr-value node-id endpoint-id chip-tool groupkeymanagement write group-key-map '[{"groupId": 16705, "groupKeySetID": 42}]' 1234 0 ``` 4. Add Group to device ``` chip-tool groups add-group GroupId GroupName node-id endpoint-id chip-tool groups add-group 0x4141 Light 1234 1 ``` ## Configuring the client for Group Commands Prior to sending a Group command, both the end device and the Client (Chip-tool) must be configured appropriately. To configure the client please use the groupsettings option ``` chip-tool groupsettings ``` A group with a valid encryption key needs to be set. The groupid and the encryption key must match the one configured on the end device. To add a group ``` chip-tool groupsettings add-group groupName groupId chip-tool groupsettings add-group TestName 0x4141 ``` To add a keyset ``` chip-tool groupsettings add-keysets keysetId keyPolicy validityTime EpochKey chip-tool groupsettings add-keysets 0xAAAA 0 0x000000000021dfe0 hex:d0d1d2d3d4d5d6d7d8d9dadbdcdddedf ``` Take note that the epoch key must be in hex form with the 'hex:' prefix Finally to bind the keyset to the group ``` chip-tool groupsettings bind-keyset groupId keysetId chip-tool groupsettings bind-keyset 0x4141 0xAAAA ``` ## Using the Client to Send Group (Multicast) Matter Commands To use the Client to send Matter commands, run the built executable and pass it the target cluster name, the target command name, the Group Id in Node Id form (`0xffffffffffffXXXX`) and an used endpoint Id. Take note that Only commands and attributes write can be send with Group Id. Also note that a group ACL needs to be installed before a command sent to the group will be accepted. See [the access control guide](../../docs/guides/access-control-guide.md#installing-a-group-acl) E.G. sending to group Id 0x4141 ``` chip-tool onoff on 0xffffffffffff4141 1 ``` The client will send a single multicast command packet and then exit. ### How to get the list of supported clusters To get the list of supported clusters, run the built executable without any arguments. ``` chip-tool ``` Example output: ```bash Usage: ./chip-tool cluster_name command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Clusters: | +-------------------------------------------------------------------------------------+ | * basic | | * colorcontrol | | * doorlock | | * groups | | * identify | | * levelcontrol | | * onoff | | * pairing | | * payload | | * scenes | | * temperaturemeasurement | +-------------------------------------------------------------------------------------+ ``` ### How to get the list of supported commands for a specific cluster To get the list of commands for a specific cluster, run the built executable with the target cluster name. ``` chip-tool onoff ``` ### How to get the list of supported attributes for a specific cluster To the the list of attributes for a specific cluster, run the built executable with the target cluster name and the `read` command name. ``` chip-tool onoff read ``` ### How to get the list of parameters for a command To get the list of parameters for a specific command, run the built executable with the target cluster name and the target command name ``` chip-tool onoff on ``` ### Run a test suite against a paired peer device ``` chip-tool tests Test_TC_OO_1_1 ``` ## Using the Client for Setup Payload ### How to parse a setup code To parse a setup code, run the built executable with the `payload` cluster name and the `parse-setup-payload` command ``` chip-tool payload parse-setup-payload code ``` #### QR Code ``` chip-tool payload parse-setup-payload "MT:#####" ``` #### QR Code with optional Vendor Info ``` chip-tool payload parse-setup-payload "MT:#####" ``` #### Manual Setup Code ``` chip-tool payload parse-setup-payload "#####" ``` # Using the Client for Additional Data Payload To parse an additional data payload, run the built executable with the `payload` cluster name and the `parse-additional-data-payload` command ``` chip-tool payload parse-additional-data-payload "#####" ``` # Command Reference ## Command List - [basic](#basic) - [colorcontrol](#colorcontrol) - [doorlock](#doorlock) - [groups](#groups) - [identify](#identify) - [levelcontrol](#levelcontrol) - [onoff](#onoff) - [pairing](#pairing) - [payload](#payload) - [scenes](#scenes) - [temperaturemeasurement](#temperaturemeasurement) ## Command Details ### basic ```bash Usage: ./chip-tool basic command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * reset-to-factory-defaults | | * ping | | * discover | | * read | +-------------------------------------------------------------------------------------+ ``` ### colorcontrol ```bash Usage: ./chip-tool colorcontrol command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * move-color | | * move-color-temperature | | * move-hue | | * move-saturation | | * move-to-color | | * move-to-color-temperature | | * move-to-hue | | * move-to-hue-and-saturation | | * move-to-saturation | | * step-color | | * step-color-temperature | | * step-hue | | * step-saturation | | * stop-move-step | | * discover | | * read | | * report | +-------------------------------------------------------------------------------------+ ``` ### doorlock ```bash Usage: ./chip-tool doorlock command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * clear-all-pins | | * clear-all-rfids | | * clear-holiday-schedule | | * clear-pin | | * clear-rfid | | * clear-weekday-schedule | | * clear-yearday-schedule | | * get-holiday-schedule | | * get-pin | | * get-rfid | | * get-user-type | | * get-weekday-schedule | | * get-yearday-schedule | | * lock-door | | * set-holiday-schedule | | * set-pin | | * set-rfid | | * set-user-type | | * set-weekday-schedule | | * set-yearday-schedule | | * unlock-door | | * unlock-with-timeout | | * discover | | * read | | * report | +-------------------------------------------------------------------------------------+ ``` ### groups ```bash Usage: ./chip-tool groups command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * add-group | | * add-group-if-identifying | | * get-group-membership | | * remove-all-groups | | * remove-group | | * view-group | | * discover | | * read | +-------------------------------------------------------------------------------------+ ``` ### identify ```bash Usage: ./chip-tool identify command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * identify | | * identify-query | | * discover | | * read | +-------------------------------------------------------------------------------------+ ``` ### levelcontrol ```bash Usage: ./chip-tool levelcontrol command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * move | | * move-to-level | | * move-to-level-with-on-off | | * move-with-on-off | | * step | | * step-with-on-off | | * stop | | * stop-with-on-off | | * discover | | * read | | * report | +-------------------------------------------------------------------------------------+ ``` ### onoff ```bash Usage: ./chip-tool onoff command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * off | | * on | | * toggle | | * discover | | * read | | * report | +-------------------------------------------------------------------------------------+ ``` ### onoff off [endpoint-id] Send the OFF command to the ONOFF cluster on the given endpoint. ### onoff on [endpoint-id] Send the ON command to the ONOFF cluster on the given endpoint. ### onoff toggle [endpoint-id] Send the TOGGLE command to the ONOFF cluster on the given endpoint. ### onoff discover [endpoint-id] Send the DISCOVER command to the ONOFF cluster on the given endpoint. ### pairing ```bash Usage: ./chip-tool pairing command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * unpair | | * ble | | * softap | +-------------------------------------------------------------------------------------+ ``` ### payload ```bash Usage: ./chip-tool payload command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * parse-setup-payload | | * parse-additional-data-payload | +-------------------------------------------------------------------------------------+ ``` ### scenes ```bash Usage: ./chip-tool scenes command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * add-scene | | * get-scene-membership | | * recall-scene | | * remove-all-scenes | | * remove-scene | | * store-scene | | * view-scene | | * discover | | * read | +-------------------------------------------------------------------------------------+ ``` ### temperaturemeasurement ```bash Usage: ./chip-tool temperaturemeasurement command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * discover | | * read | | * report | +-------------------------------------------------------------------------------------+ ``` To learn more about the tool, how to build it, use its commands and advanced features, read the following guide: - [Working with the CHIP Tool](https://github.com/project-chip/connectedhomeip/tree/master/docs/development_controllers/chip-tool/chip_tool_guide.md)