How to commission and control Matter devices with Chip Tool¶
Chip Tool is an open source Matter Controller with a command-line interface (CLI). It is useful for development and testing of Matter devices from a Linux machine.
Chip Tool offers a wide range of capabilities, ranging from device commissioning and control to setup and operational payload generation and parsing.
This document guides you through setting up and configuring Chip Tool using a Snap. This makes it extremely easy to securely run and use the tool on Linux.
Install¶
First and foremost, make sure to have SnapD installed. It is pre-installed on some distributions such as Ubuntu. Refer to installing SnapD for details.
Install the dependencies:
sudo apt update
sudo apt install bluez avahi-daemon
sudo snap install bluez avahi
Install the Chip Tool snap:
sudo snap install chip-tool
Tip
Pre-release versions of Chip Tool are available in different channels.
Once installed, the application should be available as chip-tool on your machine.
The snap restricts the app’s access to only the necessary resources on the host. This access is managed via snap interface connections.
By default, the snap auto connects the following interfaces:
network to access the host network
network-bind to listen on a port (Chip Tool’s interactive mode)
avahi-observe to discover devices over DNS-SD
bluez to communicate with devices over Bluetooth Low Energy (BLE)
To verify the interface connections, run: snap connections chip-tool
Commission¶
Discover using DNS-SD and pair:
chip-tool pairing onnetwork 110 20202021
where:
110is the node id being assigned to the device20202021is the pin code set on the device
To commission a Thread device advertising itself over BLE, you need an active Thread network (formed by a Thread Border Router) and a Bluetooth interface. Chip Tool discovers the Thread Border Router via DNS-SD and communicates with it over WiFi/Ethernet network.
Here, we assume the use of OpenThread implementation of the Thread Border Router.
Note
You may need to enable experimental Bluetooth support to allow BLE advertising and discovery.
Obtain the Active Operational Dataset for the existing Thread network:
sudo openthread-border-router.ot-ctl dataset active -x
sudo docker exec -it otbr sh -c "sudo ot-ctl dataset active -x"
sudo ot-ctl dataset active -x
The dataset is encoded in hex and contains several values including the network’s security key.
Discover over Bluetooth Low Energy (BLE) and pair:
chip-tool pairing ble-thread 110 hex:0e08...f7f8 20202021 3840
where:
110is the node id being assigned to the device0e08...f7f8is the Thread network credential operational dataset, truncated for readability.20202021is the pin code set on the device3840is the discriminator id
Note
It is also possible to commission a Thread device using a manual pairing code, without using Bluetooth Low Energy (BLE).
chip-tool pairing code-thread 110 hex:0e08...f7f8 34970112332
where:
34970112332is the short manual pairing code
Details on how to use this can be found in the Matter documentation.
(optional) On the OTBR GUI, under the Topology tab, you can now see the two connected Thread nodes:
Control¶
Toggle:
chip-tool onoff toggle 110 1
where:
onoffis the matter cluster nameon/off/toggleis the command name.110is the node id of the app assigned during the commissioning1is the endpoint of the configured device
More reading¶
This documentation covered only some of the common scenarios for commissioning and controlling Matter devices via Chip Tool. The project provides a guide with various usage examples.
However, for a complete list of sub-commands and options, it is best to use the tool’s usage instructions using the terminal.