问题排查

示例应用

如果您在使用 Home API 时遇到任何问题，可以收集日志以进行进一步调试。如需从移动设备收集日志，需要使用 Android 调试桥 (adb)。如果您需要 Google 的帮助，请收集 Android 设备和集线器的日志，然后在问题跟踪器中创建工单，并附上相关信息和相关日志。

收集 Android 日志

在涉及 adb 的所有步骤中，您的移动设备都必须连接到本地机器。

安装 adb

如果您尚未在本地计算机上设置 Android 调试桥，请执行以下操作：

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

适用于 Android Studio 的 Google Home 插件

Google Home Plugin for Android Studio 是一款有用的日志收集和分析工具，专为 Google Home platform 开发者打造。借助此插件，您可以访问 Google Assistant Simulator、Cloud Logging 和其他工具，从而简化 smart home 开发流程。

将此工具与 adb 结合使用，以进一步分析 Matter 设备日志。

如需了解详情并获取该工具，请参阅 Google Home Plugin for Android Studio。

版本信息

每当您决定收集日志时，我们都建议您收集与您的设置相关的所有版本信息。如果您需要与 Google 分享问题，则必须提供此信息。

  1. 获取移动设备的 ID： 
    adb devices
     
    List of devices attached
device-id    device
  2. 将此值存储在名为 phoneid 的变量中： 
    phoneid=device-id
  3. 将各种设备信息保存到变量： 
    containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep "versionName" || true);
homemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home " || true);
optionalhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.optional_home " || true);
policyhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.policy_home" || true);
threadinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork" || true);
ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep versionName || true);
enabledfeatures=$((adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "Enabled features" | grep -i "home") || true);
androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true);
androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true)
  4. 将所有变量保存到名为 _versions.txt 的文件中：

    展开即可显示用于将变量保存到文件的命令

    您可以一次性复制整个代码块并将其粘贴到终端。

    versionfile=$logtimestamp"_versions.txt"
echo "Saving version info to $versionfile"

echo "Container version:" >> $versionfile
echo $containerinfo >> $versionfile
echo "" >> $versionfile

echo "Home Module version:" >> $versionfile
echo $homemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Optional Home Module version:" >> $versionfile
echo $optionalhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Policy Home Module version:" >> $versionfile
echo $policyhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Thread Module version:" >> $versionfile
echo $threadinfo >> $versionfile
echo "" >> $versionfile

echo "GHA version:" >> $versionfile
echo $ghainfo >> $versionfile
echo "" >> $versionfile

echo "Android version: " >> $versionfile
echo $androidversion >> $versionfile
echo "" >> $versionfile

echo "Android API version: " >> $versionfile
echo $androidapiversion >> $versionfile
echo "" >> $versionfile

echo "Found enabled features (blank if missing):" >> $versionfile
echo $enabledfeatures >> $versionfile
echo "" >> $versionfile
  5. 验证 _versions.txt 的内容： 
    cat _versions.txt

    展开即可显示示例文件输出

    Container version:
versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)

Home Module version:
com.google.android.gms.home [v230508900]

Optional Home Module version:


Policy Home Module version:
com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]

Thread Module version:
com.google.android.gms.threadnetwork [v231912000]

GHA version:
versionName=3.2.32.1

Android version:
13

Android API version:
33

Found enabled features (blank if missing):
    现在，您可以根据需要向 Google 提供此文件以进行问题排查。

收集日志

如需收集日志，请关闭移动设备上运行的所有应用。然后，执行以下操作：

  1. 打开一个终端窗口并清除现有设备日志： 
    adb logcat -b all -c
  2. 开始日志收集流程： 
    adb logcat >> _logs.txt
     请勿关闭此终端。只要该进程在运行，系统就会从您的设备收集日志。
  3. 运行示例应用并捕获所有界面操作。完成后，按 Ctrl+C（在 Mac 上为 Cmd+C）停止终端上运行的 logcat 进程。
  4. 此会话的日志会保存在名为 _logs.txt 的文件中。

您可以通过多种方式分析此文件中的信息，包括搜索 error、exception 或 crash 等关键字。

日志脚本

为方便起见，示例应用提供了脚本来获取相关日志并将其编译为文本文件。为了提供最佳调试体验，您应将这些日志附加到报告的所有 bug 中，以便 Google 进行原因分析。

这些日志位于示例应用源代码树的 scripts 目录中。如需执行这些测试，请从项目根目录执行以下步骤：

  1. 获取移动设备的 ID： 
    adb devices -l
     
    List of devices attached
device-id device
  2. 运行 get_logs.sh 脚本： 
     ./scripts/get_logs.sh device-id
     
    Cleared previous logs from device.
Saving version information to home_api_sample_logs_20240605233243.txt...
Saving logs to home_api_sample_logs_20240605233243.txt...
(Press CTRL+C to stop the script)
  3. 重现问题。
  4. 按 CTRL+C 停止脚本。

该脚本将生成一个带时间戳的日志文件，其中包含所有相关信息。请将这些信息附加到您遇到的任何 bug 报告中。

Cast 集线器设备日志

您可以通过执行以下操作查看 Google 集线器的设备日志：

  1. 设置 Android 调试桥。

  2. 获取集线器的 IP 地址：

    • 在集线器上（如果有屏幕）：
      1. 从屏幕顶部向下滑动。
      2. 点按“设置”图标
      3. 查找设备 IP 地址：在 Nest Hub (2nd gen) 上，依次前往设备信息 > 技术信息 > IP 地址
    • 在手机上的 GHA 中：
      1. 点按相应设备以调出设备详情页面
      2. 点按“设置”图标 以调出“设置”页面
      3. 查找设备 IP 地址：依次前往设备信息 > 技术信息 > IP 地址

  3. 在与设备连接到同一 Wi-Fi 网络的计算机上： 

      adb connect ip-address
  adb logcat

  4. 如需向某人提供日志，请执行失败的操作，并将输出管道传输到文本文件： 

      adb logcat -d > platform-logs.txt

自动化操作

边缘检测

Google Home 生态系统中的自动化操作具有边缘检测功能，该功能是一种逻辑，可确保仅在发生实际状态变化时启用启动器，而不是仅重复设备的先前状态的状态更新。

例如，如果开灯是启动器，边缘检测可确保启动器仅在相应灯具从关闭状态切换到开启状态时激活，而不是从开启状态切换到开启状态（无变化）。

自动化操作的行为不符合预期

考虑边缘检测后，如果自动化操作的行为不符合预期，请执行以下操作：

  1. 检查每台设备，确保其独立于自动化操作正常运行。

  2. 查看自动化操作的自动化图表，并将其与自动化 DSL 进行比较，以找出您可能做出的任何错误假设。

  3. 在自动化操作执行期间，在 Google Home 应用中观察设备状态。

  4. 检查并确保自动化操作引用的所有设备都位于您预期的结构中。删除自动化操作依赖的设备可能会产生意外后果。请参阅设备删除对自动化操作的影响。

自动化操作在不需要时运行

如果自动化操作在不需要运行时运行，请检查启动条件。 您可能需要添加其他逻辑，以确保仅捕获一次状态变化并仅触发一次自动化操作。

自动化操作无法编译

确保您的应用包含所有必要的导入内容，包括与不同节点类型对应的每个类以及您引用的特征。

自动化操作创建失败并未通过验证

如果自动化操作创建不通过验证，系统会通过警告或错误消息提供有关问题的信息。如需了解详情，请参阅 ValidationIssueType 参考文档。

列表函数会抛出异常

调用 Automation API List 函数时，由于缺少 API 功能，读取处理程序可能会抛出异常。如需缓解此问题，请删除受影响的自动化操作。

具体操作步骤如下：

  1. 确保您已安装 adb。请参阅安装 adb。

  2. 通过调用以下命令，从 Android 日志中检索自动化操作的 ID：

    adb logcat -s GhpNative

    日志示例：

    adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse

INTERACTION RESPONSE -> SendCommandsResponse:
1 {
1: "automation@global"
3 {
  1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
  2:
  5 {
    1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
    1 {
        1: "1111-2222-3333-44444-55555" // Automation ID to delete
        2: "structure@2222-3333-4444-5555-6666"
...

    如果需要删除多个自动化 ID，您可以使用终端分页器来控制输出：

    adb logcat -s GhpNative level:debug | less

  3. 使用自动化操作的 ID 删除自动化操作：

    structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))

当某个 trait 未注册时，Discovery API 会记录警告

如果 Discovery API 为 Trait not found 记录警告，则表示该 API 尝试为 Discovery 候选项使用 trait，但由于 trait 未在初始化期间注册，因此无法成功。例如：

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

trait 标识符为 home.matter.6006.clusters.fc43，对应于 RelativeHumidityControl。如需根据 ID 确定 trait 名称，请参阅 Trait 索引。

从此示例可以看出，需要在应用初始化期间注册 RelativeHumidityControl。请参阅注册 trait，将 trait 添加到注册表。

OAuth

如果您已有 OAuth 客户端

如果您已为已发布的应用拥有经过验证的 OAuth 客户端，则可以使用现有的 OAuth 客户端测试 Home API。

无需进行 Google Home Developer Console 注册即可测试和使用 Home API。不过，即使您有通过其他集成获得验证的 OAuth 客户端，仍需要获得已获批准的 Developer Console 注册才能发布应用。

需要注意以下几点：

  • 使用现有 OAuth 客户端时，用户数上限为 100 人。如需了解如何添加测试用户，请参阅设置 OAuth 权限请求页面。无论是否通过 OAuth 验证，Home API 都限制只能有 100 位用户可以向您的应用授予权限。完成 Developer Console 注册后，此限制将解除。

  • 当您准备好通过 OAuth 限制设备类型授予权限，以便使用 Home API 更新应用时，应发送Developer Console注册 以供审批。

对于仍在等待 OAuth 验证的 Google Cloud 应用，用户在验证完成之前无法完成 OAuth 流程。尝试授予权限将会失败，并显示以下错误：

Access blocked: <Project Name> has not completed the Google verification process.
上一页
错误处理
下一页
调试 API