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 设备日志

如需启用 hub 以进行本地日志检索，请执行以下操作：

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

停用 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 Console 项目中输入正确的值和格式。

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

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

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

配对

验证您的设备凭据

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

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

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

验证与 Matter 兼容的 hub

您的 Matter hub 必须是 Google 支持的 hub 之一。它还必须位于与 Matter 兼容的 build 上。

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

可能会通过以下方式验证您的 hub 版本：从顶部边缘向下滑动手指 > 配置轮 > 设备信息 > 技术信息 > Chromecast 固件版本

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

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

调试失败并显示“无法连接到设备”错误消息

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

测试

测试套件中未显示已调试设备

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

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

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

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

如果问题仍未解决

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

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