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

此页面由 Cloud Translation API 翻译。

Switch to English

构建 Matter 虚拟设备

1. 简介

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

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

学习内容

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

所需条件

hub 是指任何支持 Matter 的 Google Nest 设备，例如 Nest Hub（第二代）。
一台运行 X11 窗口系统的 Linux 机器。
Docker。
Linux 基础知识。

2. 设置您的环境

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

检查您的硬件

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

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

设置 Docker

安装 Docker Engine（请勿使用 Docker 桌面）。
从 Docker Hub 中拉取 Docker 映像。在终端窗口中运行以下命令：
```
user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
```
此操作可能需要几分钟才能完成。

启动正在运行的 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 的集成。

任何通过了 Connectivity Standards Alliance (Alliance) Matter 认证的 Matter 设备都可以在 Google Home 生态系统中使用。在特定条件下，开发中且未经认证的设备可在 Google Home 生态系统中调试 - 如需了解详情，请参阅配对限制。

创建开发者项目

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

在管理项目页面上，点击创建项目。
在使用入门页面上，点击创建项目。

输入具有唯一性的项目名称，然后点击 Create new project（创建新项目）。
重要提示：在设计项目名称时，最好让名称有意义且明确。考虑添加公司名称以及将实现的设备类型或操作。例如，“encom-smartlight-switch”同时使用这两个元素。
点击 + 添加集成，您将转到“Matter 资源”屏幕，您可以在其中查看 Matter 开发文档并查看一些工具。
准备好继续操作后，点击下一步：开发，系统会显示诉讼或调查核对清单页面。
点击下一步：设置
在设置页面上，输入您的产品名称。
点击选择设备类型，然后从下拉菜单中选择设备类型（在本例中为 Light）。
在供应商 ID (VID) 中，选择测试 VID，然后从“测试 VID”下拉菜单中选择 0xFFF1。在产品 ID (PID) 中，输入 0x8000，点击保存并继续，然后在随后出现的页面中点击保存。
注意：VID 0xFFF1、0xFFF2、0xFFF3 和 0xFFF4 已预留用于测试。在发布产品之前，您需要在互联标准联盟 (Connect Standards Alliance) 中申请 VID。此外，PID 0x8000 至 0x801F 具有测试（设备认证证书）DAC，DAC 可用于示例。除非您计划设置自己的 DAC，否则请使用此范围内的 PID。
现在，您会在 Matter 集成下方看到一台 Matter 设备。
重新启动 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 会自动创建代码，以整合到用于定义光（数据模型）及其与其他设备（交互模型）交互的 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 代），既可用作支持 Thread 的设备的边界路由器，又可作为路由智能家居 intent 的本地执行方式路径。

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

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

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

获取二维码

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

执行佣金操作

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

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

Google Home 应用中的配对灯泡

问题排查

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

确保在 Google Home 控制台中创建了一个项目，其中包含正确的 VID/PID 组合，而且您没有其他采用相同 VID/PID 组合的项目。

长时间“扫描设备”后调试失败

确认计算机的防火墙已关闭，并且您使用的是虚拟设备。
断开所有物理网络接口（以太网）的连接，以确保您的计算机仅使用 Wi-Fi。

7. 控制设备

当支持 Matter 的设备成功调试并作为 Google 灯泡在 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，请查看以下参考资料：

Google Home 开发者中心中的 Matter Primer，您将学习 Matter 概念的基础知识。
由连接标准联盟发布的 Matter 规范、Matter 设备库和 Matter 应用集群库。
Matter GitHub 代码库。