请注意！新的开发者预览版计划即将推出。点击此处申请，抢先试用新工具并提供反馈。

构建 Matter 虚拟设备

1. 简介

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

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

学习内容

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

所需条件

  • 集线器，即支持 Matter 的任何 Google Nest 设备，例如 Nest Hub（第 2 代）。您可以在 Google 商店或您首选的零售商处购买 hub。
  • 一台运行 X11 窗口系统的 Linux 机器。
  • Docker。
  • 具备 Linux 基础知识。

2. 设置您的环境

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

检查您的硬件

此 Docker 安装目前不支持 Windows 和 MacOS 计算机。您可以在 MacOS 或 Windows 上手动安装和构建 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 窗口系统接收来自端口 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 设置

当终端打开时，它已经在 Matter 克隆的代码库中，位于 ~/connectedhomeip。无需执行其他 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 的集成。

任何通过 CSA Matter 认证的 Matter 设备都可以在 Google Home 生态系统中使用。在特定条件下，开发中尚未认证的设备可以在 Google Home 生态系统中委托 - 详见配对限制。

创建开发者项目

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

  1. 在管理项目页面上，点击创建项目。
    Google Home 开发者中心
  2. 在开始使用页面上，点击创建项目。

  1. 输入唯一项目名称，然后点击 Create new project（创建新项目）。 “Create new project”对话框
  2. 点击 + 添加集成，系统会将您转到“Matter 资源”屏幕，以便您查看 Matter 开发文档并阅读一些工具。
  3. 当您准备好继续操作时，请点击下一步：开发，系统随即会显示诉讼或调查核对清单页面。
  4. 点击下一步：设置
  5. 在设置页面上，输入您的产品名称。
  6. 点击 Select device type，然后从下拉菜单中选择设备类型（在本例中为 Light）。
  7. 在供应商 ID (VID) 中，选择测试 VID，然后从“测试 VID”下拉菜单中选择 0xFFF1。在产品 ID (PID) 中，输入 0x8000 并点击保存并继续，然后在随后出现的页面中点击保存。
    设置项目
  8. 现在，您会在 Matter 集成下方看到一台 Matter 设备。Matter 集成
  9. 重新启动 hub，以确保它收到最新的 Matter 集成项目配置。如果您稍后必须更改 VID 或 PID，则还需要在保存项目后重新启动，以使更改生效。

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.py -h，Chef 可以查看几个选项。我们在这里使用的选项包括：

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

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

虚拟设备控制器

虚拟设备控制器直观呈现您的虚拟设备。

您可以通过虚拟设备控制器图形界面 (GUI) 与虚拟设备互动。您在 GUI 中所做的更改会影响底层数据模型。目前，虚拟设备控制器支持调光灯设备类型。

安装虚拟设备控制器

虚拟设备控制器预安装在 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

如果您在没有提供任何参数的情况下启动控制器，则控制器将使用 localhost 端口 33000 的网络套接字选项。控制器能够连接该虚拟设备后，会显示一个显示设备状态的屏幕：

虚拟设备图形界面

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

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

二维码

您可以使用此二维码来调试设备。

6. 调试设备

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

Nest Hub

需要 hub 才能在 Matter 面料上调试设备。这是一款支持 Matter 的 Google Nest 设备（例如 Nest Hub（第 2 代），将既用作支持线程的设备的边界路由器，又可用作智能家居 intent 路由的本地执行方式路径。

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

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

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

获取二维码

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

执行佣金操作

  1. 打开 Google Home 应用。
  2. 点按左上角的 +。
  3. 点按设置设备。
  4. 点按新设备。
  5. 选择你的住宅，然后点按下一步。
  6. Google Home 应用会扫描你的设备。如果系统提示“Matter Device found...”消息，请点按“Yes”。否则，请点按设置其他设备，然后从设备列表中选择 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，请参考以下参考资料：