Build a Matter device

1. Introduction

Matter is a connectivity protocol that brings exciting opportunities for the development of smart devices. In this codelab, you'll build your first Matter device. To learn about Matter, visit Google Home Developer Center: Matter or the Connectivity Standards Alliance website.

What you'll learn

How to integrate a physical device with Matter.
How to commission and control your Matter device with Google Home.

What you'll need

A hub, which is any Google Nest device that supports Matter, such as the Nest Hub (2nd generation).
Either an Espressif Systems ESP32-DevkitC or ESP32 M5STACK Matter evaluation board.
A PC running Linux.
Basic knowledge of Linux.

2. Set up your environment

Identify the serial device

The first step in setting up your development environment is to determine which serial port your device is connected to. This information will allow you to program and interact with your developer board.

Connect the developer board to your computer using a USB cable.
Look in the /dev file system to find the developer board device. You can narrow your search by specifying your developer board's device prefix. Espressif's ESP32 uses /dev/ttyUSBx:
```
user@host $ ls /dev/ttyUSB*
/dev/ttyUSB0
```

Set up your hub

Set up your hub using the same Google Account you intend to use for this codelab.

Set up your development environment

Prerequisites

These instructions were tested on Debian Linux and should work on most Debian-based Linux distributions, including Ubuntu. If you're working with a different Linux distribution, the dependency setup procedure may vary from what follows.

Install dependencies

Run the following command to install required Linux package binaries that may not already be installed:

$ sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev screen

Set up the SDK

To continue this codelab, you'll need the Espressif SDK (the Espressif IoT Development Framework or ‘ESP-IDF').

Create a directory to contain the ESP-IDF:
```
$ mkdir ~/esp-idf_tools
```

Clone the ESP-IDF from GitHub into this directory:

$ cd ~/esp-idf_tools
$ git clone -b v4.4.3 --recursive https://github.com/espressif/esp-idf.git

Complete the toolchain installation:
```
$ cd ./esp-idf
$ ./install.sh
$ cd ~/
```

Set up the Matter SDK

Clone the open source Matter repository:

$ git clone https://github.com/project-chip/connectedhomeip.git
$ cd ./connectedhomeip
$ git fetch origin v1.0-branch
$ git checkout FETCH_HEAD

Fetch the repository submodules:

$ ./scripts/checkout_submodules.py --shallow --platform esp32

Bootstrap the Matter development environment:
```
$ source ./scripts/bootstrap.sh
```

3. Google Home Developer Console

The Google Home Developer Console is the web application where you manage your Matter integrations with Google Home.

Any Matter device that has passed Connectivity Standards Alliance (Alliance) Matter certification works in the Google Home ecosystem. Devices under development that have not been certified can be commissioned in the Google Home ecosystem under certain conditions - see Pairing restrictions for more information.

Create a developer project

Begin by going to the Google Home Developer Console:

Click Create project.
Enter a unique project name and then click Create project.
Important: When devising a project name, it's good practice make it meaningful and distinct. Consider including your company name and the device type or Action that it will implement. For example, ‘encom-smartlight-switch' uses both of these elements.
Click + Add integration, which takes you to the Matter resources screen, where you can view Matter development documentation and read about some tools.
When you're ready to continue, click Next: Develop, which displays the Matter checklist page.
Click Next: Setup
On the Setup page, enter your Product name.
Click Select device type and select the device type from the drop-down menu (in this case, Light).
In Vendor ID (VID), select Test VID, and select 0xFFF1 from the Test VID drop-down menu. In Product ID (PID), enter 0x8000 and click Save & continue, and then click Save in the following page. Use these exact VID/PID values, later codelab steps depend on them.
Note: The VIDs 0xFFF1, 0xFFF2, 0xFFF3 and 0xFFF4 are reserved for testing. Before you launch a product you'll need to apply for a VID at the Connected Standards Alliance. Also, the PIDs 0x8000 to 0x801F have test (Device Attestation Certificates) DACs that can be used for examples. Unless you're planning on setting up your own DAC, use a PID within this range.
Now you'll see your integration under Matter integrations.
Reboot your hub to ensure that it receives the most recent Matter integration project configuration. If you have to change the VID or PID later, you'll also need to reboot after saving the project for the change to take effect. See Restart Google Nest or Google Wifi devices for step-by-step reboot instructions.

4. Build the device

All the examples in Matter are placed in the examples folder in the Github repository. There are several samples available, but our focus on this codelab is on the lighting-app.

This example is a simple device that appears in Google Home as an On/Off Light, responding to On and Off commands. Making it control an actual electric light is beyond the scope of this codelab.

Configure the build

Configure the Matter SDK and activate the Matter build environment:

$ cd ~/esp-idf_tools/esp-idf
$ source export.sh
$ cd ~/connectedhomeip
$ source ./scripts/activate.sh

Enable Ccache, which accelerates the build process:
```
$ export IDF_CCACHE_ENABLE=1
```
Move to the lighting-app ESP32 build directory and set the target architecture:
```
$ cd ./examples/lighting-app/esp32
$ idf.py set-target esp32
```
1. Run the configuration utility:
```
$ idf.py menuconfig
```
2. Select Demo -> Device Type and set Device Type to ESP32-DevKitC.
3. Press the left arrow key to return to the top level menu.
4. Select Component config --->.
5. Select CHIP Device Layer --->.
6. Select Device Identification Options --->.
7. Set Vendor ID to your Alliance-assigned VID, or a test VID.
8. Set Product ID to the PID you set on the Matter integration in the Google Home Developer Console.
9. Press S to Save.
10. Press Return to accept the default path where the configuration will be saved.
11. Press Return to dismiss the save confirmation dialog.
12. Press Q to Quit out of the configuration utility.

Run the build

Invoke the build script:

idf.py build

The build should complete with no errors.

Program the device

Connect your developer board to your computer using a USB cable.
Wipe out any previous firmware on the device (if you only have one developer board connected to your computer, you may leave off the -p {device} option - the device should be detected automatically):
```
idf.py -p {device} erase-flash
```
Copy your new application to the developer board with:
```
idf.py -p {device} flash
```

More information about the flashing options may be found at the Espressif esptool.py documentation page.

5. Connect to the device

Open a terminal window.
Make a note of what directory you're in, then connect to your new Matter device using GNU screen:
```
$ screen -L {device} 115200
```
If you see a blank console, press the RESET button to start the device boot process.
Important: When you connect to the device with screen, the console quickly fills up with output. If you need to scroll back and look at earlier output, and your terminal emulator doesn't have a scrollable buffer, you'll need another way to view it.

The workaround is to view the screen0.log file, which is a log file that contains the GNU screen output, and is located in the same directory where you ran screen. You can do this using a text editor, or in another terminal window using pager, more, or whatever paging utility is installed on your Linux system.

6. Commission the device

Note: This step will only succeed if you have already set up your project in the Google Home Developer Console.

Nest Hub

A hub is required to commission your device on the Matter fabric. This is a Google Nest device, such as the Nest Hub (2nd generation), that supports Matter and which will serve as both a Border Router for Thread-enabled devices and as a local fulfillment path for routing Smart Home intents.

Refer to this list to see which hubs support Matter.

Before starting the commissioning process, check to make sure that:

Your hub is paired with the same Google account you used to sign in on the Google Home Console.
Your hub is on the same Wi-Fi network as the computer you are using to run your Virtual Matter Device.
Your hub is in the same structure you are using on your Google Home App. (The "house" in the Google Home Graph represents your structure).

Pair the device

Follow the ESP32 pairing instructions to pair your device.

Note: If you're using an M5STACK, be aware that its screen will remain blank after being flashed, so you'll have to view the QR code using the URL that appears in the console. Or, you can type in the manual pairing code instead.

Example console output showing QR code URL:

I (1926) chip[DL]: Done driving station state, nothing else to do...
I (1936) chip[SVR]: SetupQRCode: [MT:X.XXXXXXXXXXXXXXXXX]
I (1936) chip[SVR]: Copy/paste the below URL in a browser to see the QR Code:
I (1946) chip[SVR]: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3XX.KXXXXXXXXXXXXXXXX
I (1956) chip[SVR]: Manual pairing code: [XXXXXXXXXXX]]

Troubleshooting

Commissioning fails

Make sure you have created a project with the correct VID/PID combination in the Google Home Console.
Make sure you entered the correct VID and PID in the build configuration.
Make sure you selected the correct Device Type in the build configuration.

For more troubleshooting tips, see the Matter Troubleshooting page.

7. Control the device

Once your Matter-compliant device is successfully commissioned and appears in the Google Home app as a light bulb, you may try controlling the device using Google Assistant, the Google Home app, or the Google Assistant Simulator in the Google Home Extension for VS Code.

Google Assistant

Use Google Assistant on your phone or hub to toggle the device state from voice commands, such as saying "Hey Google, toggle my lights".

See the Control smart home devices with voice commands section of Control smart home devices added to the Google Home app for more examples of commands.

Google Home app

You may tap the On and Off labels next to the bulb icon shown on the Google Home App.

See Control devices with the Google Home app for more information.

Google Assistant Simulator

In the Google Home Extension for VS Code, using the Google Assistant Simulator, you can issue utterances to your device using a chat-like interface.

8. Congratulations!

You've successfully created and commissioned your first Matter device. Awesome!

In this codelab you learned how to:

Install a Matter development environment from requirements to a working state.
Build and run a Matter device.
Commission and control your device from Google Home.

To learn more about Matter, explore these references:

The Matter Primer by Google Home, where you'll learn the important concepts and principles of the Matter protocol.
The Matter Specification, Matter Device Library and Matter Application Cluster Library, published by the Connected Standard Alliance.
The Matter GitHub repository.