How to run Matter applications with Thread networking on Ubuntu¶

This is a tutorial on setting up and running Matter applications that use Thread for networking on Ubuntu. We will scope the tutorial to Matter applications built using the Matter SDK and OpenThread Border Router (OTBR).

Prerequisites¶

Two amd64/arm64 machines, with:
- Ubuntu Server/Desktop 22.04 or newer
- Thread Radio Co-Processor (RCP)

In this tutorial, we’ll use the following:

Machine A
- Ubuntu Desktop 23.10 amd64
- Nordic Semiconductor nRF52840 dongle, using the OpenThread (OT) RCP firmware
Machine B (Raspberry Pi 4)
- Ubuntu Server 22.04 arm64
- Nordic Semiconductor nRF52840 dongle, using the OT RCP firmware

Machine A will host the Border Router (OTBR) and Matter Controller. Machine B will act as the Matter device and run the Matter application and another instance of OTBR. The second OTBR instance will not act as a Border Router, but rather as an agent which complements the Matter application for Thread networking capabilities.

Note

The API version of OTBR agents running on Machines A and B must match!

In this tutorial, we’ve used the following:

Component	Upstream Commit/Version	API Version	snap channel
Matter lighting app	connectedhomeip `6b01cb9`	-	-
OTBR snap	ot-br-posix `thread-reference-20230119`	6	latest/edge
OTBR RCP firmware	ot-nrf528xx `00ac6cd`	6	-

1. Set up Border Router on Machine A¶

Refer to How to set up OpenThread Border Router on Ubuntu to set up and configure OTBR.

Then form a Thread network, using the following commands:

sudo openthread-border-router.ot-ctl dataset init new
sudo openthread-border-router.ot-ctl dataset commit active
sudo openthread-border-router.ot-ctl ifconfig up
sudo openthread-border-router.ot-ctl thread start

These steps could also be performed with the Web GUI, served by default at http://localhost:80. Please refer to the instructions here to form, join, or check the status of a Thread network using the GUI.

The Thread network is now ready for new joiners. Head over to Machine B to setup the Matter application.

2. Run OTBR on Machine B¶

The OTBR Agent is required for adding Thread networking capabilities to the Matter application. The Matter app communicates with OTBR Agent via the DBus Message Bus.

Similar to Machine A, set up and configure OTBR by following: How to set up OpenThread Border Router on Ubuntu.

On Machine B, connecting the avahi-control interface isn’t required as this OTBR Agent’s DNS-SD registration isn’t needed.

Note that we do not form a Thread network on Machine B.

3. Run Matter Application on Machine B¶

The Matter Application can implement any Matter functionality. The requirement for this tutorial is that the application is created using the Matter SDK and runs on Ubuntu.

Tip

Most reference examples from the Matter SDK support Thread networking. For example, the lighting app for Linux can run in Thread mode by setting the --thread CLI argument. For more details, refer to its README.

The recommended option here is to use the Pi GPIO Commander application, which helps turn a Raspberry Pi into a Lighting Matter device 💡. The application enables control of a GPIO pin via Matter.

There is a separate tutorial on setting up and running that application. Make sure to follow the Thread-related instructions to set it up and start the application. Then head back here to continue with Thread commissioning and control.

The tutorial for Pi GPIO Commander is available at: Build your first Matter device with a Raspberry Pi

4. Control the Matter Application from Machine A¶

Setup Matter Controller¶

First, install Chip Tool, a Matter Controller with a command-line interface:

sudo snap install chip-tool

Chip Tool depends on third-party services for DNS-SD and BLE discovery. If you don’t already have them, install Avahi Daemon and BlueZ:

sudo apt update
sudo apt install avahi-daemon bluez

Pair the device¶

Get the OTBR operational dataset (OTBR network’s credentials), for the network formed in previous sections:

sudo openthread-border-router.ot-ctl dataset active -x

Now, pair the Thread device over BLE:

chip-tool pairing ble-thread 110 hex:<active-dataset> 20202021 3840

where:

110 is the assigned node ID for the app.
<active-dataset> is the Thread network’s Active Operational Dataset in hex, taken using the ot-ctl command above.
20202021 is the PIN code set on the app.
3840 is the discriminator ID.

If this succeeds, skip to the controlling the device.

If it didn’t work, it may be because it has taken too long to reach this step and the device has stopped advertising and listening to commissioning requests. Try restarting it on the application on Machine B with sudo snap restart matter-pi-gpio-commander.

Control the device¶

There are a few ways to control the device. The toggle command is stateless and the simplest:

chip-tool onoff toggle 110 1

To turn on and off:

chip-tool onoff on 110 1
chip-tool onoff off 110 1