Hands-on Matter - The Matter Light Bulb (Part 2)

Tim Conrad – Senior Security Consultant

4 October 2022

In Part 1 of this blog series, we provided a theoretical overview by following Alice’s journey from unboxing a new Matter switch to commission the device into the Fabric and binding it to a Matter light bulb.

In the following parts, we will recreate Alice’s setup. In this part we will start with a Matter light bulb, we will guide you through the process of setting up a low-cost example to get real hands-on experience with Matter and evaluate it for yourself. We will use a ESP32 with a basic LED and a resistor to create our own light bulb as a proof of concept.

Note:
This blog post is written for developers and other people with a technical background and interest in a security focused overview of Matter.

Attention:
Please note that the Matter code open source, so a lot and examples and tools might change throughout the process. We will do everything on Ubuntu 20.04. For other systems, we will provide the link to the original document in the Matter repository.

Hardware Setup and Components

ESP32 and LED Schematics:

LED and ESP32 Schematics

To build our light bulb, we need the following components:

ESP32-WROOM DevKitC
330 Ohm Resistor
LED
Wires
Breadboard
Micro-USB Cable
Computer with BLE and Wi-Fi

The costs of the hardware should be below 10,- € for our Matter light bulb setup. Place the ESP32 on the breadboard and connect the LED and resistor with the wires as shown in the picture. The GPIO 2 (labeled “G2” or “2”) is used in our case. After setting up our basic circuit, we will connect the ESP32 with our computer via the USB cable.

(Matter) Chip GitHub Repository

The Matter GitHub repository can be found here: https://github.com/project-chip/connectedhomeip First we will bootstrap the repository as detailed here and then take a look at the directory structure as detailed in BUILDING.md.

Git

Looking at our repository structure, we have a few areas that are of the most interest for us:

docs/guides - here are platform-specific instructions and user guides to help setup-specific tools, e.g. the chip-tool which is the CLI tool to interact with Matter devices.
examples/ - here are all example projects for different platforms sorted by application, e.g. the all-cluster-app includes all available functionality of Matter in one application and is the go-to app to start firsts steps with.

For our setup we will need to build two applications, first the chip-tool and secondly the all-cluster-app for the ESP32.

Building the Chip-Tool

From the root of the repository, you can build the chip-tool directly via the following command.

scripts/examples/ gn_build_example.sh 
examples/chip-tool out/chip-tool

Code changes:
While working with the master branch of the Matter repository gives you access to the newest features, there may be some issues from time to time due to the rapid code changes. Most of the time, making a new pull and restarting the bootstrapping solves the issue. If the bootstrapping fails, delete the folder .environment/ and start again.

After successfully building the chip-tool, you can start it with the following command.

out/chip-tool/chip-tool

The output will look something like this.

Cluster

Our output will have the error message [1649943820.702390][30597:30597] CHIP:TOO: Missing cluster name which we will ignore now. After building and flashing the firmware for the ESP32 we will come back to the topic of Clusters and discuss this concepts in more detail.

Building the all-cluster-app

First, you need to install Espressif’s ESP-IDF to build and flash the examples (all instructions can be found in the example as well, if something does not work as described look here).

mkdir ${HOME}/tools
cd ${HOME}/tools
git clone https://github.com/espressif/esp-idf.git
cd esp-idf
git checkout v4.4
git submodule update --init
./install.sh
. ./export.sh

Now move back to the Matter repository and activate the environment.

cd /path/to/connectedhomeip
source scripts/activate.sh

cd examples/all-clusters-app/esp32
idf.py set-target esp32
idf.py build

After the firmware is successfully built, you can now flash the ESP32 and monitor the results. Here /dev/ttyUSB0 is the ESP32, this might be different on your system or if you have more than one development board attached.

idf.py -p /dev/ttyUSB0 flash monitor

Erase the flash of the ESP3:

The ESP32 will persist changes such as network credentials, ACLs or NOCs on the flash, there you will need to erase the flash before starting with a blank device.

idf.py -p /dev/ttyUSB0 erase-flash

The following will show the flashing of the ESP and monitoring the device.

Now you have successfully set up the chip-tool and the ESP with everything you need for your first Matter device. Now we need a bit more theory on how the interaction model works. After this, we will commission our new device into our own Wi-Fi network. If you don’t have a Wi-Fi that you can use, you can create your own access point with Ubuntu as described here.

Endpoints, Clusters, Commands and Attributes

The interaction model is quite simple to understand. We will continue to explain it with our light bulb example. For the demonstration purposes we consider the light as dimmable, no color changing or any other fancy features. So, typically features of a conventional dimmable light are:

Turning light on
Turning light off
Set the brightness to a specific level

In Matter terms, we will group these features in clusters and expose them on endpoints and the node/device. The following figure will give a simplified overview of the interaction model.

Node, Endpoints and Clusters

Let’s discuss this figure step by step:

Node - The physical device on the network, represented by a Node ID in our Fabric.
Endpoint - Are related to one device characteristic. e.g. a lighting device with two light bulbs would have two identical endpoints to control each light bulb separately. Endpoint 0 is reserved for Matter-specific features, such as pairing the device with the network.
Cluster - A set of features to control on a specific endpoint. E.g. the feature of turning the device on and off is called the OnOff Cluster.
- Servers - A light bulb would implement a Cluster Server awaiting commands to turn on and off the light.
- Clients - A light switch would implement a Cluster Client to send on/off commands to the light bulb.
Commands - Will trigger a specific action on the Cluster. E.g. turn on light.
Attributes - Will store information about a specific Cluster state. E.g. is light turned on or off?

With this background, we can start using the chip-tool to commission our ESP32 Matter device.

Commissioning the ESP32

To start the commissioning, we will need the following things:

Wi-Fi Network Credentials (we will use SSID “IoT Testing” and Password “NotTheRealPassword”)
Device Discriminator (in this example it is “3840“)
Device Passcode (in this example it is “20202021”)

Discriminator:
A Discriminator value helps to further identify potential devices during the setup process and helps to improve the speed and robustness of the setup experience for the user. The Discriminator should be different for each individual device.

At first, we want to pair our laptop with the chip-tool (the Commissioner) with our ESP32 (the Commissionee) and provide the Wi-Fi credentials, the following command will do this for us. The Node ID (here “12344321”) can be chosen freely.

# ./chip-tool pairing ble-wifi node-id ssid password setup-pin-code discriminator 
./chip-tool pairing ble-wifi 12344321 "IoT Testing" NotTheRealPassword 20202021 3840

This will perform the complete commissioning discussed in Part 1. In the GIF below, you can see both the monitoring of the device (bottom) and the commissioning with the chip-tool (top).

Pairing the Matter device

Let’s have a look at the logs of the chip-tool for the commissioning process and match the output to what we learned in Part 1.

The location where the Fabric credentials are stored. You need to back up these files if you want to keep access to your matter devices, as they will be removed after reboot, when the /tmp folder is cleared.

Protocol Output

The log output with comments to explain each section and a summary after the listing.

Protocol Output

In summary, the chip-tool does the following:

1.) Discover device via BLE using the discriminator

2.) Setup secure communication (PASE)

3.) Communicate basic information

4.) Perform device attestation

5.) Configure operational credentials on the device

6.) Enable Wi-Fi access on the device

7.) Test connection to the device (CASE)

8.) Close and cleanup all sessions.

Now you can easily turn the light on and off by sending the following command.

# ./chip-tool onoff toggle destination-id endpoint-id
./chip-tool onoff toggle 12344321 1

The following GIF will demonstrate toggling the light.

Pairing the Matter device

A brief look at the chip-tool output to explain what is happening.

Chip Tool Output

In summary, the chip-tool does the following:

1.) Setup credentials for Fabric 1

2.) Find Node 12344321 (0xbc5c01) and establish a session using CASE

3.) Send the toggle command (0x2) to the OnOff cluster (0x6) and endpoint 1. (OnOff cluster definitions here)

4.) Receive a response from the node if the command was successful.

We now can see a bright light and controlled our first hand made Matter device. We used many of the concepts explained in Part 1 and the Part 3 of this series we will take a look at binding a light switch to the light bulb to have a more complete setup and get rid of the chip-tool to control the light.