构建 Matter 虚拟设备

1. 简介

Matter 是一种连接协议，为智能设备的开发带来了激动人心的机会。在此 Codelab 中，您将使用在预配置的 Docker 映像中提供的 SDK 和依赖项，构建您的第一台 Matter 设备。

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

学习内容

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

所需条件

  • 集线器，即任何支持 Matter 的 Google Nest 设备，例如 Nest Hub（第 2 代）。
  • 一台运行 X11 窗口系统的 Linux 计算机。
  • Docker
  • 具备 Linux 基础知识。

2. 设置您的环境

我们将在 Linux 主机上使用先前配置的 Docker 容器。此容器包含构建和运行 Matter 虚拟设备所需的所有依赖项。

检查硬件

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

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

设置 Docker

  1. 安装 Docker Engine（不要使用 Docker 桌面）。
  2. 从 Docker Hub 拉取 Docker 映像。在终端窗口中，运行以下命令：
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    此操作可能需要几分钟时间才能完成。
  3. 启动 Docker 容器运行：
    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

启动容器后，您应该会看到一些诊断输出，后跟一条确认您的容器配置正确无误的消息，最后是容器 shell 提示符：

Environment looks good, you are ready to go!
$

让我们了解一下 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。

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

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 初始设置

终端打开后，它已位于位于 ~/connectedhomeip 的 Matter 克隆代码库中。您无需执行额外的 Matter 设置步骤。

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

如需从容器内访问宿主机上的文件，您可以使用绑定装载。您还可以将文件从容器内写入装载的目录，以便从主机轻松访问。

使用附加参数 --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 的集成。

任何已通过连接标准联盟 (Alliance) Matter 认证的 Matter 设备都可以在 Google Home 生态系统中运行。正在开发中未经认证的设备在某些情况下可以委托加入 Google Home 生态系统。如需了解详情，请参阅配对限制。

创建开发者项目

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

  1. 点击 Create project。
  2. 输入唯一的项目名称，然后点击创建项目。 “创建新项目”对话框
  3. 点击 + 添加集成，系统会将您转到 Matter 资源界面，您可以在其中查看 Matter 开发文档并了解一些工具。
  4. 准备好继续操作后，请点击下一步：开发，其中将显示 Matter 核对清单页面。
  5. 点击下一步：设置
  6. 在 Setup（设置）页面上，输入您的 Product name（产品名称）。
  7. 点击选择设备类型，然后从下拉菜单中选择设备类型（在本例中为 Light）。
  8. 在“供应商 ID”(VID) 中，选择 Test VID，然后从“Test 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 build：

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

Chef 有几个选项，可通过运行 chef.py -h 进行查看。我们在此处使用的选项包括：

  • -d：定义要使用的设备类型。在本例中，我们将创建一个具有开/关和水平控件的照明应用。
  • -z：调用 ZAP 工具以生成实现相应设备类型的源文件。也就是说，ZAP 会根据您选择的照明，自动创建要整合到构建中的代码，从而定义灯光（数据模型）及其与其他设备交互的方式（互动模型）。
  • -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. 虚拟设备控制器

虚拟设备控制器是一款独立的应用，可提供图形界面来控制和显示虚拟 Matter 设备的状态。它使用 RPC 客户端与连接到开发环境的 Matter 设备进行通信。

虚拟设备控制器

虚拟设备控制器提供虚拟设备的可视化表示。

您可以通过虚拟设备控制器图形界面 (GUI) 与虚拟设备进行交互。您在 GUI 中的更改会影响底层数据模型。如需查看支持的 Matter 虚拟设备类型的完整列表，请参阅支持的设备。

安装虚拟设备控制器

虚拟设备控制器已预安装在 Ubuntu LTS 20.04 Docker 容器中。

运行虚拟设备控制器

创建第二个终端会话实例：

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

通过提供用于与虚拟设备通信的网络套接字来启动虚拟设备控制器：

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

如果您在未提供任何参数的情况下启动控制器，控制器将默认使用本地主机端口 33000 的网络套接字选项。当控制器能够连接到虚拟设备后，它将显示一个屏幕来展示您的设备状态：

虚拟设备图形界面

当您在虚拟控制器应用中进行更改时，该应用会向设备的 RPC 服务器发送请求，并且每秒轮询 RPC 服务器一次以检索状态。

虚拟设备控制器应用还可用于在设备调试流程中检索二维码。点击设备图片旁边的二维码图标即可显示此设备的二维码。使用此二维码调试您的设备。

6. 调试设备

注意：仅当您已在 Google Home 开发者控制台中设置了项目时，此步骤才会成功。

Nest Hub

您需要有 hub 才能在 Matter 结构上调试设备。这是一台支持 Matter 的 Google Nest 设备（例如 Nest Hub，第 2 代），它既可用作支持 Thread 的设备的边界路由器，也可用作路由智能家居 intent 的本地执行方式路径。

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

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

  • 您的 Hub 已与您在 Google Home 控制台中登录的 Google 帐号配对。
  • 您的 hub 与运行 Virtual Matter 设备的计算机连接到同一 Wi-Fi 网络。
  • 你的 Hub 属于你在 Google Home 应用中使用的结构（Google Home Graph 中的“房子”代表你的结构）。

获取二维码

调试流程需要通过二维码提供的 Matter 新手入门信息。您可以从虚拟设备控制器获取虚拟设备的二维码。

执行佣金操作

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

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

Google Home 应用中的已配对灯泡

问题排查

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

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

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

7. 控制设备

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

  • 使用 Google 助理。
  • 正在使用 Google Home 应用。
  • 使用虚拟设备 GUI。

Google 助理

在手机或 hub 上使用 Google 助理，根据语音指令切换设备状态，例如说“Ok Google，切换灯具”。

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

Google Home 应用

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

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

虚拟设备 GUI

您可以与虚拟设备 GUI 交互，以更改设备的状态。无论您是使用虚拟设备控制器、手机上的 Google Home 应用还是 hub 控制虚拟设备，所有这些界面都会反映虚拟设备的当前状态。

8. 恭喜！

您已成功创建您的第一台 Matter 设备。也很棒！

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

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

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