An example application that uses Matter to send messages to a Matter server.
See the build guide 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.
Message tracing allows capture of the secure messages which can be used for test automation.
gn gen out/with_trace/ --args='import("//with_pw_trace.gni")'
ninja -C out/with_trace chip-tool
This enables tracing and adds additional flags to chip-tool to control where the traces should go:
For example:
out/with_trace/chip-tool --trace_file trace.log pairing <pairing_args>
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.
To initiate a client commissioning request to a device, run the built executable and choose the pairing mode.
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} 0 20202021 3840
where:
For example:
$ chip-tool pairing ble-wifi 0x11 xyz secret 0 20202021 3840
or equivalently:
$ chip-tool pairing ble-wifi 17 hex:787980 hex:736563726574 0 20202021 3840
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 qrcode ${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).
$ chip-tool pairing unpair
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.
To get the list of supported clusters, run the built executable without any arguments.
$ chip-tool
Example output:
Usage: ./chip-tool cluster_name command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Clusters: | +-------------------------------------------------------------------------------------+ | * barriercontrol | | * basic | | * colorcontrol | | * doorlock | | * groups | | * iaszone | | * identify | | * levelcontrol | | * onoff | | * pairing | | * payload | | * scenes | | * temperaturemeasurement | +-------------------------------------------------------------------------------------+
To get the list of commands for a specific cluster, run the built executable with the target cluster name.
$ chip-tool onoff
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
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
$ chip-tool tests Test_TC_OO_1_1
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
$ chip-tool payload parse-setup-payload "MT:#####"
$ chip-tool payload parse-setup-payload "MT:#####"
$ chip-tool payload parse-setup-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 "#####"
Usage: ./chip-tool barriercontrol command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * barrier-control-go-to-percent | | * barrier-control-stop | | * discover | | * read | +-------------------------------------------------------------------------------------+
Usage: ./chip-tool basic command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * reset-to-factory-defaults | | * ping | | * discover | | * read | +-------------------------------------------------------------------------------------+
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 | +-------------------------------------------------------------------------------------+
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 | +-------------------------------------------------------------------------------------+
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 | +-------------------------------------------------------------------------------------+
Usage: ./chip-tool iaszone command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * discover | | * read | | * write | +-------------------------------------------------------------------------------------+
Usage: ./chip-tool identify command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * identify | | * identify-query | | * discover | | * read | +-------------------------------------------------------------------------------------+
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 | +-------------------------------------------------------------------------------------+
Usage: ./chip-tool onoff command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * off | | * on | | * toggle | | * discover | | * read | | * report | +-------------------------------------------------------------------------------------+
Send the OFF command to the ONOFF cluster on the given endpoint.
Send the ON command to the ONOFF cluster on the given endpoint.
Send the TOGGLE command to the ONOFF cluster on the given endpoint.
Send the DISCOVER command to the ONOFF cluster on the given endpoint.
Usage: ./chip-tool pairing command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * unpair | | * ble | | * softap | +-------------------------------------------------------------------------------------+
Usage: ./chip-tool payload command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * parse-setup-payload | | * parse-additional-data-payload | +-------------------------------------------------------------------------------------+
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 | +-------------------------------------------------------------------------------------+
Usage: ./chip-tool temperaturemeasurement command_name [param1 param2 ...] +-------------------------------------------------------------------------------------+ | Commands: | +-------------------------------------------------------------------------------------+ | * discover | | * read | | * report | +-------------------------------------------------------------------------------------+