构建 Matter 设备

1. 简介

Matter 是一种连接协议，为智能设备的开发带来了令人兴奋的机会。在此 Codelab 中，您将构建自己的首台 Matter 设备。如需了解 Matter，请访问 Google Home 开发者中心：Matter 或 连接标准联盟网站。

学习内容

• 如何将实体设备与 Matter 集成。
• 如何使用 Google Home 调试和控制 Matter 设备。

所需条件

• hub，即任何支持 Matter 的 Google Nest 设备，例如 Nest Hub（第 2 代）。
• Espressif Systems ESP32-DevkitC 或 ESP32 M5STACK Matter 评估板。
• 运行 Linux 的 PC。
• Linux 基础知识。

2. 设置您的环境

识别串行设备

设置开发环境的第一步是确定设备连接到的串行端口。借助此信息，您可以对开发者板进行编程并与之互动。

1. 使用 USB 数据线将开发者板连接到计算机。
2. 在 /dev 文件系统中查找开发者板设备。您可以通过指定开发者板的设备前缀来缩小搜索范围。Espressif 的 ESP32 使用 /dev/ttyUSBx：

   user@host $ ls /dev/ttyUSB*
   /dev/ttyUSB0
   

设置 hub

使用您打算在此 Codelab 中使用的 Google 账号 设置 hub。

设置您的开发环境

前提条件

这些说明已在 Debian Linux 上进行过测试，应适用于大多数基于 Debian 的 Linux 发行版，包括 Ubuntu。如果您使用的是其他 Linux 发行版，依赖项设置过程可能与以下内容有所不同。

安装依赖项

运行以下命令以安装可能尚未安装的必需 Linux 软件包二进制文件：

$ sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \
python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev screen

设置 SDK

如需继续学习此 Codelab，您需要 Espressif SDK（Espressif IoT 开发框架或“ESP-IDF”）。

1. 创建一个目录来存放 ESP-IDF：

   $ mkdir ~/esp-idf_tools
   

2. 将 ESP-IDF 从 GitHub 克隆到此目录：

   $ cd ~/esp-idf_tools
   $ git clone -b v4.4.3 --recursive https://github.com/espressif/esp-idf.git
   

3. 完成工具链安装：

   $ cd ./esp-idf
   $ ./install.sh
   $ cd ~/
   

设置 Matter SDK

1. 克隆开源 Matter 代码库：

   $ git clone https://github.com/project-chip/connectedhomeip.git
   $ cd ./connectedhomeip
   $ git fetch origin v1.0-branch
   $ git checkout FETCH_HEAD
   

2. 提取代码库子模块：

   $ ./scripts/checkout_submodules.py --shallow --platform esp32
   

3. 引导 Matter 开发环境：

   $ source ./scripts/bootstrap.sh
   

3. Google Home 开发者控制台

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

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

创建开发者项目

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

前往 Google Home 开发者控制台

1. 点击 Create project 。
2. 输入唯一的项目名称，然后点击 Create project 。
   
3. 点击 + Add integration，系统会将您带到 Matter resources 屏幕，您可以在其中查看 Matter 开发文档并了解一些工具。
4. 准备好继续后，点击 Next: Develop，系统会显示 Matter checklist 页面。
5. 点击 Next: Setup
6. 在 Setup 页面上，输入您的 Product name 。
7. 点击 Select device type ，然后从下拉菜单中选择设备类型（在本例中为 Light）。
8. 在 Vendor ID (VID) 中，选择 Test VID，然后从 Test VID 下拉菜单中选择 0xFFF1。在 Product ID (PID) 中，输入 0x8000，然后点击 Save &continue ，并在下一页中点击 Save 。请使用这些确切的 VID/PID 值，后续 Codelab 步骤将依赖于这些值。
   
9. 现在，您会在 Matter integrations 下看到您的集成。
10. 重启 hub，确保其收到最新的 Matter 集成项目配置。如果您稍后必须更改 VID 或 PID，则还需要在保存项目后重启，才能使更改生效。如需了解分步重启说明，请参阅重启 Google Nest 或 Google Wifi 设备。

4. 构建设备

Matter 中的所有示例都位于 GitHub 代码库中的 examples 文件夹中。有多个示例可用，但在此 Codelab 中，我们将重点介绍 lighting-app。

此示例是一个简单的设备，在 Google Home 中显示为“开/关灯”，响应“开”和“关”命令。使其控制实际的电灯超出了此 Codelab 的范围。

配置构建

1. 配置 Matter SDK 并激活 Matter 构建环境：

   $ cd ~/esp-idf_tools/esp-idf
   $ source export.sh
   $ cd ~/connectedhomeip
   $ source ./scripts/activate.sh
   

2. 启用 Ccache，以加快构建流程：

   $ export IDF_CCACHE_ENABLE=1
   

3. 移至 lighting-app ESP32 构建目录并设置目标架构：

   $ cd ./examples/lighting-app/esp32
   $ idf.py set-target esp32
   

   1. 运行配置实用程序：

      $ idf.py menuconfig
      

   2. 选择 Demo -> Device Type，并将 Device Type 设置为 ESP32-DevKitC。
   3. 按向左键可返回到顶级菜单。
   4. 选择 Component config --->。
   5. 选择 CHIP Device Layer --->。
   6. 选择 Device Identification Options --->。
   7. 将 Vendor ID 设置为联盟分配的 VID 或测试 VID。
   8. 将 Product ID 设置为您在 Google Home 开发者控制台中的 Matter 集成上设置的 PID。
   9. 按 S 保存。
   10. 按 Return 接受将保存配置的默认路径。
   11. 按 Return 关闭保存确认对话框。
   12. 按 Q 退出配置实用程序。

运行构建

调用构建脚本：

idf.py build

构建应顺利完成，不会出现任何错误。

为设备编程

1. 使用 USB 数据线将开发者板连接到计算机。
2. 清除设备上的任何先前固件（如果您仅将一个开发者板连接到计算机，则可以省略 -p {device} 选项 - 系统应会自动检测到该设备）：

   idf.py -p {device} erase-flash
   

3. 使用以下命令将新应用复制到开发者板：

   idf.py -p {device} flash
   

如需详细了解刷写选项，请参阅 Espressif esptool.py 文档页面。

5. 连接到设备

1. 打开一个终端窗口。
2. 记下您所在的目录，然后使用 GNU screen 连接到新的 Matter 设备：

   $ screen -L {device} 115200
   

3. 如果您看到空白控制台，请按 RESET 按钮以启动设备启动过程。

6. 调试设备

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

Nest Hub

您需要一个 hub 才能在 Matter 结构上调试设备。这是一个 Google Nest 设备，例如 Nest Hub（第 2 代），它支持 Matter，并且将同时充当支持 Thread 的设备的边界路由器，以及用于路由智能家居 intent 的本地实现路径。

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

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

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

配对设备

按照 ESP32 配对说明 配对设备。

注意：如果您使用的是 M5STACK，请注意，刷写后其屏幕将保持空白，因此您必须使用控制台中显示的网址查看二维码。或者，您可以改为输入手动配对码。

显示二维码网址的控制台输出示例：

I (1926) chip[DL]: Done driving station state, nothing else to do...
I (1936) chip[SVR]: SetupQRCode: [MT:X.XXXXXXXXXXXXXXXXX]
I (1936) chip[SVR]: Copy/paste the below URL in a browser to see the QR Code:
I (1946) chip[SVR]: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3XX.KXXXXXXXXXXXXXXXX
I (1956) chip[SVR]: Manual pairing code: [XXXXXXXXXXX]]

问题排查

调试失败

• 确保您已在 Google Home 控制台中创建具有正确 VID/PID 组合的项目。
• 确保您在构建配置中输入了正确的 VID 和 PID。
• 确保您选择了正确的 Device Type 在 build 配置中。

如需了解更多问题排查提示，请参阅 Matter 问题排查页面。

7. 控制设备

成功调试符合 Matter 标准的设备并在 Google Home 应用中显示为灯泡后，您可以尝试使用 Google 助理、Google Home 应用或 Google Home Extension for VS Code 中的 Google 助理模拟器控制设备。

Google 助理

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

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

Google Home 应用

您可以点按 Google Home 应用中显示的灯泡图标旁边的 On 和 Off 标签。

如需了解详情，请参阅 使用 Google Home 应用控制设备。

Google 助理模拟器

在 Google Home Extension for VS Code 中，您可以使用 Google 助理模拟器 通过类似聊天的界面向设备发出话语。

8. 恭喜！

您已成功创建并调试了您的首台 Matter 设备。太棒了！

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

• 从要求到工作状态安装 Matter 开发环境。
• 构建并运行 Matter 设备。
• 使用 Google Home 调试和控制设备。

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

• Google Home 的 Matter 入门指南，您将在其中了解 Matter 协议的重要概念和原则。
• 连接标准联盟发布的 Matter 规范、Matter 设备库和 Matter 应用集群库。
• Matter GitHub 代码库。