Matter Client Example#
An example application that uses Matter to send messages to a Matter server.
Building the Example Application#
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.
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 <pairing_args> --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:XXXXXXXXwhere 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
Commission a device through a Commissioning Proxy#
When the commissioner has no radio the commissionee can be reached on, a
Commissioning Proxy (CP) can tunnel for it. A CP is a Matter device that
implements the Commissioning Proxy cluster. It opens a transport (e.g. BLE,
Wi-Fi PAF) connection to the commissionee on the commissioner’s behalf. The PASE
handshake and the commissioning flow are tunneled using ProxyMessageRequest
and ProxyMessageResponse.
The CP is an ordinary Matter node, it must already be commissioned onto the
fabric before it can tunnel anything as it requires a CASE session for the
tunnel. examples/all-devices-app provides a CP, run this with
--device commissioning-proxy:<endpoint_id>:
./out/linux-x64-all-devices-boringssl/all-devices-app --device commissioning-proxy:5 \
--wifi --wifipaf freq_list=2437
chip-tool pairing onnetwork ${PROXY_NODE_ID} 20202021
Asking the CP to scan#
The CP can scan on the commissioner’s behalf, to discover commissionable
devices. Transport is the CapabilitiesBitmap: BLE is 0x02, Wi-Fi PAF is
0x08, and 0x0A asks for both in one scan. --WiFiBands is the
WiFiBandBitmap: 2.4 GHz is 0x01, 5 GHz is 0x04.
chip-tool commissioningproxy proxy-scan-request 0x0A ${PROXY_NODE_ID} 5 \
--WiFiBands 0x01 --allow-large-payload true --timeout 30
proxy-scan-request carries the large-message quality, so it needs
--allow-large-payload true to put the invoke on a TCP session. Without it the
session is UDP/MRP and the round-trip budget expires before ScanMaxTime, which
chip-tool reports as a bare Timeout rather than as a rejected request.
Size --timeout — chip-tool’s own wait is 20 s by default — from the proxy’s
ScanMaxTime attribute:
chip-tool commissioningproxy read scan-max-time ${PROXY_NODE_ID} 5
A background scan allows the CP to scan continuously and cache what it finds, so
the results can be read or subscribed to at any time. Timeout is how long the
scan runs, in seconds:
chip-tool commissioningproxy proxy-back-ground-scan-start-request 0x0A 60 ${PROXY_NODE_ID} 5 \
--WiFiBands 0x01
chip-tool commissioningproxy read num-cached-results ${PROXY_NODE_ID} 5
chip-tool commissioningproxy read cached-results ${PROXY_NODE_ID} 5
chip-tool commissioningproxy subscribe cached-results 1 30 ${PROXY_NODE_ID} 5
chip-tool commissioningproxy proxy-back-ground-scan-stop-request 0x0A ${PROXY_NODE_ID} 5 \
--WiFiBands 0x01
Stopping every transport the scan was started on erases the fabric’s scan
record, so a repeated identical stop is answered NOT_FOUND rather than
SUCCESS. Neither background-scan command carries the large-message quality, so
neither needs --allow-large-payload.
Commissioning through the CP#
chip-tool pairing proxy ${NODE_ID_TO_ASSIGN} ${SSID} ${PASSWORD} ${SETUP_PIN_CODE} \
${DISCRIMINATOR} ${PROXY_NODE_ID} ${PROXY_CONNECT_TIMEOUT} ${PROXY_TRANSPORT} \
[--proxy-endpoint ${PROXY_ENDPOINT}] [--proxy-wifi-band 2g4|5g]
where:
${NODE_ID_TO_ASSIGN}, ${SSID}, ${PASSWORD} and ${SETUP_PIN_CODE} are as for
pairing ble-wifiabove. ${SSID} and ${PASSWORD} are the required credentials to configure the network to join, not the link the proxy tunnels over.${DISCRIMINATOR} is the discriminator of the commissionee, as reported by a scan above.
${PROXY_NODE_ID} is the node id of the already-commissioned proxy.
${PROXY_CONNECT_TIMEOUT} is how many seconds the proxy may spend establishing the transport connection to the commissionee.
0means no timeout, so the proxy keeps trying until it is cancelled.${PROXY_TRANSPORT} is
bleorwifipaf— the transport the proxy should use to reach the commissionee.--proxy-endpointis the endpoint on the proxy that hosts the Commissioning Proxy cluster. Defaults to1;all-devices-appabove puts it on5.--proxy-wifi-bandis an optional band hint,2g4or5g, and is only accepted when ${PROXY_TRANSPORT} iswifipaf.
For example, commissioning node 0x11 onto Wi-Fi network xyz through a proxy
commissioned as node 0x12, over BLE:
chip-tool pairing proxy 0x11 xyz secret 20202021 3840 0x12 0 ble --proxy-endpoint 5
or over Wi-Fi PAF, hinting the 2.4 GHz band:
chip-tool pairing proxy 0x11 xyz secret 20202021 3840 0x12 0 wifipaf \
--proxy-endpoint 5 --proxy-wifi-band 2g4
chip-tool disconnects the proxy session using ProxyDisconnectRequest when the
flow finishes, whether it succeeded or failed.
For the CP side — implementing a transport driver, or running the example CP — see the Commissioning Proxy cluster README and Getting Started: Wi-Fi PAF for the Commissioning Proxy.
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#
Commission and pair device with nodeId 1234
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
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
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
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:
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#
Command Details#
basic#
Usage:
./chip-tool basic command_name [param1 param2 ...]
+-------------------------------------------------------------------------------------+
| Commands: |
+-------------------------------------------------------------------------------------+
| * reset-to-factory-defaults |
| * ping |
| * discover |
| * read |
+-------------------------------------------------------------------------------------+
colorcontrol#
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#
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#
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#
Usage:
./chip-tool identify command_name [param1 param2 ...]
+-------------------------------------------------------------------------------------+
| Commands: |
+-------------------------------------------------------------------------------------+
| * identify |
| * identify-query |
| * discover |
| * read |
+-------------------------------------------------------------------------------------+
levelcontrol#
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#
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#
Usage:
./chip-tool pairing command_name [param1 param2 ...]
+-------------------------------------------------------------------------------------+
| Commands: |
+-------------------------------------------------------------------------------------+
| * unpair |
| * ble |
| * softap |
+-------------------------------------------------------------------------------------+
payload#
Usage:
./chip-tool payload command_name [param1 param2 ...]
+-------------------------------------------------------------------------------------+
| Commands: |
+-------------------------------------------------------------------------------------+
| * parse-setup-payload |
| * parse-additional-data-payload |
+-------------------------------------------------------------------------------------+
scenes#
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#
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: