Build a Matter virtual 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, using SDKs and dependencies provided for you in a preconfigured Docker image.

To learn about Matter, visit the Google Home Developer Center or the Connectivity Standards Alliance website.

What you'll learn

  • How to set up a Matter build environment
  • How to build a virtual Matter device that runs on your computer
  • How to commission and control the virtual Matter device with Google Home

What you'll need

2. Set up your environment

We'll be using a previously-configured Docker container on a Linux host machine. This container includes all the necessary dependencies for building and running a Matter virtual device.

Check your hardware

Windows and MacOS computers are not currently supported by this Docker installation. You may manually install and build Matter on MacOS or Windows.

Also, these instructions assume that your Linux machine is running the X11 windowing system. If your Linux machine runs Wayland, make sure that X.Org is also installed.

Set up Docker

  1. Install Docker Engine (do not use Docker Desktop).
  2. Pull the Docker image from Docker Hub. In a terminal window, run:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    This operation might take a few minutes to complete.
  3. Start the Docker container running:
    user@host> xhost local:1000
user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

After starting the container, you should see some diagnostic output followed by a message affirming that your container configuration is correct, and finally, the container shell prompt:

Environment looks good, you are ready to go!
$

Let's understand the docker command and the options we passed to it:

  • xhost local:1000 allows the X Window System to receive connections from the local host on port 1000, thus allowing a graphic user interface to be used.
  • docker run … image runs the given image, pulling it from the Docker registry if necessary.
  • --ipc=host allows Docker to share the interprocess communication namespace with your host machine.
  • --net=host allows Docker to use the host's network stack inside the container, which is required in order for it pass mDNS traffic from the host to the container, and to share the host X11 display.
  • -e DISPLAY exports $DISPLAY to the host, providing access to your system graphic interface. This is required to run the ZAP tool when editing Matter clusters.
  • -it runs Docker with an interactive terminal (tty), instead of as a background process.

Optionally you may run a second terminal session instance:

user@host> docker exec -it matter-container /bin/bash
$

Stop and start the Matter Docker container

Whenever you run a docker run command, you'll create a new container with the specified image. When you do this, your old data, which was saved on a previous container instance, will be lost. Sometimes this is what you want to happen, because it allows you to start with a fresh installation. But there are times when you'd prefer to save your work and environment configuration between sessions.

For this reason, after creating your container, you may stop the container to prevent losing your work.

user@host> docker stop matter-container

When you are ready to run again, start the container and open a terminal window:

user@host> docker start matter-container
user@host> docker exec -it matter-container /bin/bash

You may open additional terminal sessions to your container with:

user@host> docker exec -it matter-container /bin/bash

Or start a root session using:

user@host> docker exec -u 0 -it matter-container /bin/bash

Initial Matter setup

When your terminal opens, it will already be on the Matter cloned repository at ~/connectedhomeip. No additional Matter setup steps are needed.

Share files between the host and container

To access files on your host machine from within the container, you may use a bind mount. You may also write files to the mounted directory from within the container for easy access from the host.

Run your container with the additional argument --mount source=$(pwd),target=/workspace,type=bind to mount your current working directory into the container at /workspace.

user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

The container user's permissions on the mounted directory must be managed in the host.

Obtain the container user's group ID from within the container.

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

Open another terminal session on the container host and set the working directory to the directory mounted by the container.

Recursively set the group for files in the mounted directory to the container user's group.

user@host> sudo chgrp -R 1000 .

Grant your desired permissions in the directory to the group. This example gives the container user's group read, write, and execute permissions on all files in the mounted directory.

user@host> sudo chmod -R g+rwx .

Note that these commands do not impact the permission of new files created by the host user. Remember to update permissions of new files created in the host as needed.

You may add your host user to the container user's group to inherit permissions on files created by the container user.

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

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:

  1. On the Manage projects page, click Create a project.
    Google Home Developer Center
  2. On the Get started page, click Create project.

  1. Enter a unique project name and then click Create new project. Create new project dialog
  2. Click + Add integration, which takes you to the ‘Matter resources' screen, where you can view Matter development documentation and read about some tools.
  3. When you're ready to continue, click Next: Develop, which displays the Matter checklist page.
  4. Click Next: Setup
  5. On the Setup page, enter your Product name.
  6. Click Select device type and select the device type from the dropdown menu (in this case, Light).
  7. In Vendor ID (VID), select Test VID, and select 0xFFF1 from the Test VID dropdown menu. In Product ID (PID), enter 0x8000 and click Save & continue, and then click Save in the following page.
    Setting up a project
  8. Now you will see one Matter device under Matter integrations. Matter integrations
  9. 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 a device

All the examples in Matter are found in the examples folder in the Github repository. There are several samples available, but our focus on this codelab is on Chef.

Chef is both:

  • A sample app that provides a terminal interface, wrapping features also found on the examples/shell app.
  • A script that embraces the principle of convention-over-configuration to encapsulate several of the common tasks necessary for developing a Matter-enabled device.

Navigate to the Chef example folder and make your first Matter build:

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

Chef has a few options that can be viewed by running chef.py -h. The options we're using here are:

  • -d: defines the device type to be used. In this case, we are creating a lighting app with on/off and level controls.
  • -z: invokes the ZAP tool to generate the source files that implement the device type. That is, based on your pick of lighting, ZAP will automatically create code to be incorporated into the build that defines the light (the Data Model) and how it interacts with other devices (the Interaction Model).
  • -b: builds.
  • -r: [optional] enables the RPC server on the virtual Matter device so that other components (such as the GUI) can communicate with the device to to set and retrieve Data Model Attributes.
  • -t linux: target platform. The support platforms are linux, nrfconnect and esp32. You may run ./chef.py -h to see all available commands and supported target platforms. linux is used for virtual Matter devices.

Run the device

Matter uses TCP/UDP port 5540, so if you have a firewall running in your computer, either shut it down, or allow incoming TCP/UDP connections on port 5540.

Run the virtual device in the container with:

$ ./linux/out/rootnode_dimmablelight_bCwGYSDpoe
   [1648589956496] [14264:16538181] CHIP: [DL] _Init]
...
[1648562026.946882][433632:433632] CHIP:SVR: SetupQRCode: [MT:Y3.13Y2N00KA0648G00]
[1648562026.946893][433632:433632] CHIP:SVR: Copy/paste the below URL in a browser to see the QR Code:
[1648562026.946901][433632:433632] CHIP:SVR: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY3.13Y2N00KA0648G00
[1648562026.946915][433632:433632] CHIP:SVR: Manual pairing code: [34970112332]

Leave your device running. Now we'll turn our attention to the Google Home App so we can commission your device into the Google Home.

Stop the device

You may quit the program with CTRL+C. If the app does not exit, you may need to use CTRL+\ as well.

The credentials for your virtual device are stored in the /tmp/ directory, in files starting with chip prefix.

If you want to repeat the entire commissioning process from the beginning, you'll have to delete those files by running the following command:

$ rm /tmp/chip*

5. The Virtual Device Controller

The Virtual Device Controller is a standalone app that provides a graphical user interface to control and display the states of your virtual Matter devices. It uses an RPC client to communicate with the Matter devices connected to your development environment.

The Virtual Device Controller

The Virtual Device Controller provides a visual representation of your virtual device.

You can interact with the virtual device through the Virtual Device Controller graphic user interface (GUI). Your changes in the GUI affect the underlying data model. Currently, the Virtual Device Controller supports the Dimmable Light device type.

Install the Virtual Device Controller

The Virtual Device Controller comes pre-installed on the Ubuntu LTS 20.04 Docker container.

Run the Virtual Device Controller

Create the second terminal session instance:

user@host> docker exec -it matter-container /bin/bash
$

Start the Virtual Device Controller by providing the network socket that will be used to communicate with the virtual device:

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

If you start the Controller without providing any arguments, it will default to the network socket option using localhost port 33000. Once the Controller is able to connect to the virtual device, it will display a screen showing your device state:

Virtual Device graphic user interface

The app sends requests to the device's RPC server as you make changes on the Virtual Controller app, and polls the RPC server once per second to retrieve state.

The Virtual Device Controller app can also be used to retrieve the QR code as part of your device commissioning flow. Click on the QR code icon next to the device image to display the QR code for this device:

QR Code

You can use this QR code to commission your device.

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).

Get a QR Code

The commissioning process needs Matter onboarding information provided through a QR code. You can obtain the QR code for your virtual device from the Virtual Device Controller.

Perform the commission operation

  1. Open the Google Home app.
  2. Tap the + in the upper-left corner.
  3. Tap Set up device.
  4. Tap New device.
  5. Select your home and tap Next.
  6. The Google Home app scans for your device. If prompted with the message "Matter Device found...", tap ‘Yes'. Otherwise, tap Set up a different device, then select Matter device from the list of devices.
  7. Point your camera at your device's QR code or the website-generated QR code.
  8. Continue the pairing process as indicated in the Google Home app flow.

Once you complete these steps, the Matter virtual device should be successfully commissioned, and should appear as a new icon in your Google Home App.

Paired bulb on Google Home App

Troubleshooting

Commissioning fails with "Connectivity problem" or "Could not contact Google" error messages

  • Make sure you have created a project with the correct VID/PID combination in the Google Home Console and you don't have other projects using the same VID/PID combination.

Commissioning fails after "Scanning your device" for a long period

7. Control the device

Once your Matter-enabled device is successfully commissioned and appears in the Google Home app as a light bulb, you may test the control of the device by different methods:

  • Using Google Assistant.
  • Using the Google Home app.
  • Using the Virtual Device GUI.

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 the Control devices with the Google Home app section of Control smart home devices added to the Google Home app for more information.

Virtual Device GUI

You can interact with the Virtual Device GUI to change the state of the device. Whether you control the virtual device with the Virtual Device Controller, Google Home App on your phone, or with your hub, all of these interfaces will reflect the current state of the virtual device.

8. Congratulations!

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

In this codelab you learned how to:

  • Install a Matter development environment using a pre-packaged Docker image.
  • Build and run a Matter virtual device.
  • Commission and control your virtual device from Google Home.

To learn more about Matter, explore these references: