构建 Matter 虚拟设备

1. 简介

Matter 是一种连接协议，为智能设备的发展带来了激动人心的机会。在此 Codelab 中，您将使用 Matter SDK 中的资源构建您的第一台 Matter 设备。

如需了解 Matter，请访问 Google Home 开发者中心或连接标准联盟网站。

学习内容

  • 如何设置 Matter 构建环境
  • 如何构建在计算机上运行的虚拟 Matter 设备
  • 如何使用 Google Home 调试和控制虚拟 Matter 设备

所需条件

  • 集线器，即任何支持 Matter 的 Google Nest 设备，例如 Nest Hub（第 2 代）。
  • 一台运行 X11 窗口系统的 Linux 机器。
  • Docker
  • Git。
  • 具备 Linux 基础知识。
    • 请注意，此 Codelab 中所有命令的假定 shell 是 BASH。

2. 设置您的环境

检查硬件

此 Docker 安装不支持 Windows 和 macOS 计算机。您可以在 macOS 上手动安装和构建 Matter。

此外，以下说明假定您的 Linux 计算机运行的是 X11 窗口系统。如果您的 Linux 计算机运行的是 Wayland，请务必同时安装 X.Org。

设置开发环境

  1. 安装 Docker Engine（请勿使用 Docker Desktop）。
  2. 克隆 Matter SDK，请注意我们在以下代码中使用的提交。
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. 使用 SDK 的公共 CI 映像运行构建容器，并从此容器中执行新构建的虚拟设备。找到要使用的与 SDK 版本匹配的图片，如下所示：
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    如果您使用的是相同的提交，您应该会看到ghcr.io/project-chip/chip-build:66首先，转发 xhost 端口，以便我们稍后可以使用界面应用：
    xhost local:1000
    接下来，使用从主机转发的相应资源（我们的 SDK 检出、网络和显示/通信资源）启动容器。
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

我们来了解一下 docker 命令以及传递给它的选项：

  • xhost local:1000 允许 X Window System 在端口 1000 上接收来自本地主机的连接，从而允许使用图形界面。
  • docker run … image 运行指定的映像，如有必要，会从 Docker 注册表中拉取该映像。
  • --ipc=host 允许 Docker 与您的主机共享进程间通信命名空间。
  • --net=host 允许 Docker 在容器内使用主机的网络堆栈，这是必需的，这样 Docker 才能将 mDNS 流量从主机传递到容器，并共享主机 X11 显示屏。
  • -e DISPLAY 会将 $DISPLAY 导出到主机，从而提供对系统图形界面的访问权限。在修改 Matter 集群时，必须这样运行 ZAP 工具。
  • -it 使用交互式终端 (tty)（而不是作为后台进程）运行 Docker。
  • --mount 会将我们之前签出的 SDK 装载到容器中。
  • --workdir 会在启动时将工作目录设置为装载的 SDK 目录。

您可以选择运行第二个终端会话实例：

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

停止和启动 Matter Docker 容器

每当您运行 docker run 命令时，您都需要使用指定映像创建一个新容器。如果执行此操作，保存在先前容器实例的旧数据将会丢失。有时这是您需要执行的操作，因为它允许您从全新安装开始。但有时您更希望在不同会话之间保存工作和环境配置。

因此，在创建容器后，您可以停止容器，以免丢失工作成果。

user@host> docker stop matter-container

当您准备好再次运行时，请启动容器并打开一个终端窗口：

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

您可以使用以下命令打开容器的其他终端会话：

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

或者使用以下命令启动根会话：

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

初始 Matter 设置

初始化 SDK

初始化 Matter SDK。此操作需要几分钟才能完成。

source scripts/bootstrap.sh
python3 scripts/checkout_submodules.py --shallow --platform linux

你的 Matter SDK 现已初始化。如需在将来快速重新初始化环境，请运行以下命令：

sudo docker exec -it  matter-container /bin/bash
source ./scripts/activate.sh

在主机和容器之间共享文件

之前，我们使用绑定装载从容器内访问了主机上的文件。您还可以从容器内将文件写入装载的目录，以便从主机进行访问。

一般来说，通过附加参数 --mount source=$(pwd),target=/workspace,type=bind 运行容器，使用绑定装载，将当前工作目录装载到位于 /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

容器用户对于装载的目录的权限必须在主机中管理。

从容器中获取容器用户的群组 ID。

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

在容器主机上打开另一个终端会话，并将工作目录设置为容器装载的目录。

以递归方式将已装载目录中文件的群组设置为容器用户的群组。

user@host> sudo chgrp -R 1000 .

在目录中向该群组授予所需的权限。此示例向容器用户的群组授予对装载目录中所有文件的读取、写入和执行权限。

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

请注意，这些命令不会影响主机用户创建的新文件的权限。请记得根据需要更新在主机中创建的新文件的权限。

您可以将主机用户添加到容器用户的群组，以继承该容器用户所创建文件的权限。

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

3. Google Home 开发者控制台

Google Home 开发者控制台是一款 Web 应用，你可以在其中管理 Matter 与 Google Home 的集成。

任何已通过连接标准联盟（联盟）Matter 认证的 Matter 设备可以在 Google Home 生态系统中运行。在特定条件下，正在开发且未经认证的设备可以在 Google Home 生态系统中进行调试。如需了解详情，请参阅配对限制。

创建开发者项目

首先，前往 Google Home 开发者控制台：

  1. 点击 Create project。
  2. 输入唯一的项目名称，然后点击 Create project（创建项目）。 “Create new project”对话框
  3. 点击 + 添加集成，你将进入 Matter resources 界面，您可以在其中查看 Matter 开发文档以及了解一些工具。
  4. 准备好继续操作后，请点击下一步：开发，此时系统会显示诉讼或调查核对清单页面。
  5. 点击下一步：设置
  6. 在 Setup（设置）页面上，输入您的 Product name（产品名称）。
  7. 点击选择设备类型，然后从下拉菜单中选择设备类型（在本例中为 Light）。
  8. 在供应商 ID (VID) 中，选择 Test VID，然后从“测试 VID”下拉菜单中选择 0xFFF1。在“产品 ID (PID)”中，输入“0x8000”，然后点击保存 &继续，然后在下一页中点击保存。请使用这些确切的 VID/PID 值，后续 Codelab 步骤将依赖于这些值。
    设置项目
  9. 现在，您会在 Matter 集成下看到您的集成。
  10. 请重新启动 hub，以确保其接收最新的 Matter 集成项目配置。如果您稍后必须更改 VID 或 PID，则还需要在保存项目后重新启动，才能使更改生效。如需了解分步重新启动说明，请参阅重启 Google Nest 或 Google Wifi 设备。

4. 构建设备

Matter 中的所有示例都位于 GitHub 代码库的 examples 文件夹中。我们提供几个示例，但此 Codelab 主要介绍 Chef。

Chef 可以是：

  • 一个示例应用，提供终端接口，封装功能也可在 examples/shell 应用中找到。
  • 一个脚本采用规范而非配置原则，用于封装开发支持 Matter 的设备所需的几项常见任务。

导航到 Chef 示例文件夹，并制作你的第一个 Matter 版本：

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

运行 chef.py -h 可查看 Chef 的一些选项。我们在这里使用的选项包括：

  • -d：定义要使用的设备类型。在本例中，我们将创建一个具有开/关和水平控件的照明应用。
  • -z：调用 ZAP 工具以生成实现相应设备类型的源文件。也就是说，ZAP 会根据您选择的光源自动创建要整合到 build 中的代码，用于定义光源（数据模型）及其与其他设备的交互方式（互动模型）。
  • -b：build。
  • -r：[可选] 启用虚拟 Matter 设备上的 RPC 服务器，以便其他组件（如 GUI）可以与设备通信，以设置和检索数据模型属性。
  • -t linux：目标平台。支持平台为 linux、nrfconnect 和 esp32。您可以运行 ./chef.py -h 来查看所有可用的命令和支持的目标平台。linux 用于虚拟 Matter 设备。

运行设备

Matter 使用 TCP/UDP 端口 5540，因此，如果您的计算机正在运行防火墙，请将其关闭或允许端口 5540 的传入 TCP/UDP 连接。

使用以下命令在容器中运行虚拟设备：

$ ./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]

让设备保持运行状态。现在，我们将注意力转向 Google Home 应用，以便调试您的设备，使其成为 Google Home。

停止设备

如果您需要停止设备，可以按 CTRL+C 退出该程序。如果应用未退出，您可能还需要使用 CTRL+\。

虚拟设备的凭据存储在 /tmp/ 目录下，位于以 chip 前缀开头的文件中。

如果要从头开始重复整个调试过程，则必须运行以下命令删除相应文件：

$ rm /tmp/chip*

5. 调试设备

注意：只有在 Google Home 开发者控制台中设置了项目的情况下，此步骤才会成功。

Nest Hub

需要使用集线器才能在 Matter 结构上调试设备。这是一部支持 Matter 的 Google Nest 设备，例如 Nest Hub（第 2 代），并将用作支持 Thread 的设备的边界路由器，以及用于路由智能家居 intent 的本地执行方式路径。

请参阅此列表，了解哪些 hub 支持 Matter。

在开始调试流程之前，请检查确保：

  • 你的 hub 会与你在 Google Home 控制台中登录的 Google 账号配对。
  • 您的 hub 与您用来运行虚拟 Matter 设备的计算机连接到同一 Wi-Fi 网络。
  • 你的基座与 Google Home 应用中的结构相同。（Google Home 图谱中的“房子”代表你的结构）。

获取二维码

调试流程需要通过二维码提供的 Matter 新手入门信息。检查 Matter 应用的控制台输出，其中包含与调试相关的二维码链接。

执行佣金操作

  1. 打开 Google Home 应用。
  2. 点按左上角的 +。
  3. 点按设置设备。
  4. 点按新设备。
  5. 选择您的住宅，然后点按下一步。
  6. Google Home 应用会扫描您的设备。如果系统提示“找到诉讼或调查...”，请点按“是”。否则，请点按设置其他设备，然后从设备列表中选择诉讼或调查。
  7. 将摄像头对准设备的二维码或网站生成的二维码。
  8. 按照 Google Home 应用流程中的说明，继续配对流程。

完成上述步骤后，Matter 虚拟设备应会成功调试，并应作为新图标出现在 Google Home 应用中。

Google Home 应用中的已配对灯泡

问题排查

调试失败并显示“连接问题”或“无法联系 Google”错误消息

  • 确保您已在 Google Home 控制台中创建了具有正确的 VID/PID 组合 的项目，并且您没有其他项目使用相同的 VID/PID 组合。

“正在扫描您的设备”后调试失败长期

6. 控制设备

支持 Matter 的设备成功调试并在 Google Home 应用中显示为灯泡后，你就可以通过不同的方法测试对设备的控制：

  • 正在使用 Google 助理。
  • 使用 Google Home 应用。

Google 助理

在手机或 hub 上使用 Google 助理通过语音指令（例如说“Hey Google，把灯调暗”）来切换设备状态。

如需查看更多指令示例，请参阅控制已添加到 Google Home 应用的智能家居设备中的使用语音指令控制智能家居设备部分。

Google Home 应用

你可以点按 Google Home 应用中显示的灯泡图标旁边的开启和关闭标签。

如需了解详情，请参阅控制已添加到 Google Home 应用的智能家居设备中的使用 Google Home 应用控制设备部分。

7. 恭喜！

你已成功创建了自己的第一台 Matter 设备。也很棒！

在此 Codelab 中，您学习了如何执行以下操作：

  • 安装 Matter 开发环境。
  • 构建并运行 Matter 虚拟设备。
  • 通过 Google Home 调试和控制您的虚拟设备。

如需详细了解 Matter，请浏览以下参考资料：