Matter 问题排查

建筑物

验证您的手机是否兼容

所有 Android O（8.1、API 级别 27）及更高版本的设备都与 Matter 兼容。请按照以下步骤检查您的手机是否具有必要的模块。

设置 Android 调试桥

在进行问题排查之前，应设置 Android 调试桥 (adb)。如需进行设置，请执行以下操作：

  1. 在计算机上安装“adb”。
  2. 在 Android 手机上开启“开发者选项”和“USB 调试”。

验证您的 Google Play 服务 (GPS) Matter 模块

如需检查您是否有 Google Play services Matter 模块，请执行以下操作：

  1. 设置 Android 调试桥。
  2. 使用 USB 线将 Android 手机连接到计算机。
  3. 在终端中运行此命令，验证是否已安装必要的 Matter 模块： 
      adb shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
    如果您看到类似于以下内容的输出，则表明您已安装 Matter 模块： 
    com.google.android.gms.home [v222110900]
    请注意，上面的版本号可能与您的设备不同。
  4. 在终端中运行以下命令，以验证是否已安装必要的 Thread 模块：
      adb shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork"
    如果您看到类似于以下示例的输出，则表示已安装 Thread 模块：
    com.google.android.gms.threadnetwork [v222106301]
    请注意，您设备上的版本号可能会有所不同。

如果未列出模块，则表示：

  1. 您的 Android 版本已过时。确保它是 Android O (8.1) 或更高版本。
  2. Matter 模块尚未下载。请等待至少 24 小时，以便其下载。确保您的设备在此期间已开机且正在充电，以免下载延迟。如果您在 24 小时内未收到模块，可以尝试将设备恢复出厂设置，以强制下载模块。

Fuchsia hub 设备日志

如需启用用于检索本地日志的中心，请执行以下操作：

  1. 请向您的 Google Technical Account Manager (TAM) 发送电子邮件，并附上设备的序列号和型号。您可以在设备下方找到这些信息，它们以小写字母显示。
  2. 列入许可名单后，您必须按照以下步骤启用该功能：
    • 在中心：
      1. 从屏幕顶部向下滑动。
      2. 点按“设置”图标
      3. 查找 Fuchsia 版本：在 Google Nest Hub (2nd gen) 上，依次前往设备信息 > 技术信息 > Fuchsia 版本
      4. 点按“Fuchsia 版本”7 次。这将启用开发者选项
      5. 返回顶级菜单
      6. 点按“开发者选项”
      7. 点按“合作伙伴日志记录”
    • 该功能将启用 24 小时。之后，从第 5 步开始重新启用日志记录功能。
  3. 获取集线器的 IP 地址：
    • 在集线器上（如果有屏幕）：
      1. 从屏幕顶部向下滑动。
      2. 点按“设置”图标
      3. 查找设备 IP 地址：在 Nest Hub (2nd gen) 上，依次前往设备信息 > 技术信息 > IP 地址
    • 在手机上的 Google Home app (GHA) 中：
      1. 点按相应设备以调出设备详情页面
      2. 点按“设置”图标 以调出设置页面
      3. 找到设备 IP 地址：依次前往设备信息 > 技术信息 > IP 地址
  4. 如需从集线器检索日志，您需要通过同一 Wi-Fi 网络中的计算机向集线器发出 GET HTTP 请求。
    • 记下端点的端口和路径：
      curl -k -X GET https://ip-address:8443/setup/get_logs --output output-file
    • 连接只能保持打开状态一分钟，但从缓冲区检索的数据通常包含过去 20-30 分钟的事件。
      • 理想情况下，应在完成测试流程后立即使用此方法提取日志，以确保缓冲区包含与测试相关的内容（类似于 Android 错误报告）。

停用 Android 日志的隐去功能

  • 出于隐私和安全考虑，此功能应仅用于工程测试用途。
  • 请勿将此选项用于正式版设备或用户。
  • 步骤：
    1. 将尚未隐去日志的用户的 Google 账号发送到您的 Google TAM。
    2. 确认您的账号已添加到许可名单后，请重新启动手机。

验证设备的 VID/PID

如果您想开始开发与 Google 的集成，则必须在 Google Home 控制台中创建项目和集成。

排查蓝牙嗅探器问题

设备发送的信标 VID/PID 值应与您输入到 Google Home Developer Console 项目中的 VID/PID 相匹配。

  • VID 0xFFF1 - 0xFFF4 已预留用于测试。它们可用于基本的调试和控制测试，但不可用于以下开发阶段：

使用蓝牙工程应用（例如 nRF Connect for Mobile），您可以在服务数据字段中查看信标设备的 VID/PID。

在来自 Android 版本的 nRF Connect 的屏幕截图中，可以看到 VID/PID 列为 5A23FFFE，从 Service Data（服务数据）字段的第 4 个字节开始。这表示 VID 为 5A23，PID 为 FFFE，两者均采用小端字节序格式。

BLE 应用以小端字节顺序显示值，但您输入 Developer Console 项目中的 VID/PID 值采用的是大端字节顺序。

根据蓝牙嗅探器显示的内容，验证您是否已在 Actions 控制台项目中输入正确的值和格式。

对于示例屏幕截图中的值，Developer Console 中的 VID 和 PID 分别为 235A 和 FEFF。

验证你的设备是使用兼容的 Matter SDK 分支构建的

Google Matter 中心与 Matter 1.0 兼容，并且已通过使用稳定分支 v1.0-branch 中的提交内容的 build 进行测试。请查看公开版本说明，了解建议与每个新 Hub 版本搭配使用的具体提交内容。

正在配对

验证设备的凭据

使用您自己的 Alliance 分配的 VID 时，请确保您在设备上拥有正确的凭据：

  • 认证声明 (CD)。
  • 设备认证证书 (DAC) 及其证书链。

如需了解详情，请参阅创建 Matter 设备测试证书。

验证您的 Matter 兼容集线器

您的 Matter 集线器必须是 Google 支持的集线器之一。它还必须搭载与 Matter 兼容的build。

一些 hub 也是线程边界路由器，因此您可以开发和测试 Thread 设备。其他集线器仅支持 Wi-Fi 和以太网 Matter 设备，除非您的网络中有其他边界路由器来启用 Thread 连接。

您可以通过以下步骤验证集线器 build：从顶部边缘向下滑动手指 > 配置轮 > 设备信息 > 技术信息 > Chromecast 固件版本

调试失败并显示“无法联系 Google”错误消息

请确保您已在 Developer Console 中创建了使用正确 VID/PID 组合的集成。如需了解详情，请参阅创建 Matter 集成。

配置失败，并显示“无法访问设备”错误消息

如果您在调试 Thread 设备时一直收到“无法连接到设备”错误消息，并且已尝试所有可用的调试选项，不妨清除 Android 手机上存储的首选 Thread 凭据，以便通过以下步骤进行完整设置：依次前往设置 > 应用 > 应用的应用 > Google Play 服务 > 存储和缓存 > 管理空间 > 清除所有数据。

测试

已委托的设备未显示在测试套件中

如果您已将设备与测试供应商 ID (VID) 和产品 ID (PID) 配对，但当您尝试在 Developer Console 中使用测试套件来测试设备时，该 ID 未显示，这可能是因为在多次集成中使用相同的测试 VID 和 PID 组合。

如需进行问题排查，请从 Developer Console 中移除所有测试设备，然后重新配对要测试的设备。

如需验证您是否配对了正确的设备，您可以在测试固件中将设备的制造商和型号信息（CHIP_DEVICE_CONFIG_DEVICE_* 值）设置为唯一值。

如需了解详情，请参阅设备信息。

如果问题仍然存在

如果按照此处的所有问题排查步骤操作后，您的问题仍未解决，也没有问题！

在问题排查步骤中，您收集了有关设备、控制台项目和环境的重要数据。掌握这些数据后，请参阅支持页面，了解如何最好地与社区和 Google Home 支持团队分享您的问题。