构建 Matter 虚拟设备

1. 简介

Matter 是一种连接协议，可为智能设备开发带来令人兴奋的机会。在此 Codelab 中，您将使用 Matter SDK 中的资源构建您的首个 Matter 设备。

如需了解 Matter，请访问 Google Home 开发者中心或 Connectivity Standards Alliance 网站。

学习内容

• 如何设置 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）。
   file_download下载 Docker
2. 克隆 Matter SDK，并记下我们在下文中使用的提交。

   git clone https://github.com/project-chip/connectedhomeip.git
   cd connectedhomeip
   git show
   commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
   

3. 使用 SDK 的公共 CI 映像运行 build 容器，并在此容器内执行新构建的虚拟设备。找到要使用的与我们的 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 使用容器内部的主机网络堆栈，这是将 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

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

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 Developer Console 是一款 Web 应用，您可以在其中管理与 Google Home 的 Matter 集成。

任何通过连接标准联盟 (Alliance) Matter 认证的 Matter 设备都可以在 Google Home 生态系统中运行。在某些条件下，尚未获得认证的开发中设备可以在 Google Home 生态系统中完成调试 - 如需了解详情，请参阅配对限制。

创建开发者项目

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

前往 Google Home 开发者控制台

1. 点击 Create project。
2. 输入唯一的项目名称，然后点击创建项目。
   
3. 点击 + 添加集成，系统会将您带到 Matter 资源界面，您可以在其中查看 Matter 开发者文档并了解一些工具。
4. 准备好继续操作后，点击下一步：开发，系统随即会显示 Matter 清单页面。
5. 点击下一步：设置
6. 在设置页面上，输入您的产品名称。
7. 点击选择设备类型，然后从下拉菜单中选择设备类型（在本例中为 Light）。
8. 在“供应商 ID (VID)”中，选择测试 VID，然后从“测试 VID”下拉菜单中选择 0xFFF1。在“产品 ID (PID)”中，输入 0x8000，然后点击 Save & continue，接着在下一页中点击 Save。请使用这些确切的 VID/PID 值，后续 Codelab 步骤将依赖于这些值。
   
9. 现在，您会在 Matter 集成下看到您的集成。
10. 重新启动中枢，确保其接收最新的 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 有几个选项，可以通过运行 chef.py -h 查看。我们在此处使用的选项如下：

• -d：定义要使用的设备类型。在本例中，我们将创建一个具有开/关和亮度控制功能的照明应用。
• -z：调用 ZAP 工具以生成实现设备类型的源文件。也就是说，根据您选择的灯具，ZAP 会自动创建要纳入构建中的代码，该代码定义了灯具（数据模型）及其与其他设备的互动方式（互动模型）。
• -b：builds。
• -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 的本地执行方式路径。

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

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

• 中枢已与您在 Google Home 控制台中登录时所用的 Google 账号配对。
• 中枢与您用于运行虚拟 Matter 设备的计算机连接到同一 Wi-Fi 网络。
• 中枢位于您在 Google Home 应用中使用的同一结构中。（Google Home Graph 中的“住宅”代表您的结构）。

获取二维码

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

执行调试操作

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

完成这些步骤后，Matter 虚拟设备应已成功完成调试，并应在 Google Home 应用中显示为新图标。

问题排查

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

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

在“扫描设备”后长时间无法完成调试

• 确认计算机的防火墙已关闭，并且您正在运行虚拟设备。
• 断开所有物理网络接口（以太网），确保您的计算机仅使用 WLAN。

6. 控制设备

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

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

Google 助理

在手机或中枢上使用 Google 助理，通过语音指令切换设备状态，例如说“Hey Google，切换灯的状态”。

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

Google Home 应用

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

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

7. 恭喜！

您已成功创建首个 Matter 设备。也很棒！

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

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

如需详细了解 Matter，请参阅以下资源：

• Google Home 开发者中心上的 Matter 基础知识，您可以在其中了解 Matter 概念的基础知识。
• 由连接标准联盟发布的 Matter 规范、Matter 设备库和 Matter 应用集群库。
• Matter GitHub 代码库。