问题排查

示例应用

如果您在使用 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 等关键字。

记录脚本

为方便起见，示例应用提供了用于获取相关日志并将其编译为文本文件的脚本。为了提供最佳的调试体验，应将这些日志附加到报告给 Google 的任何 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 Nest Hub 的设备日志，此方法适用于以下型号：

  • Google Home
  • Google Nest Audio
  • Google Nest Hub
  • Google Nest Mini

如需启用 Cast 集线器以检索本地日志，请执行以下操作：

  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"))

当特性被取消注册时，Discovery API 会记录警告

如果 Discovery API 针对 Trait not found 记录了警告，则表示该 API 尝试将该特征用于 Discovery 候选对象，但由于该特征未在初始化期间注册，因此不会成功。例如：

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

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

在此示例中，RelativeHumidityControl 需要在应用初始化期间注册。请参阅注册特征，将您的特征添加到注册表中。

OAuth

如果您有现有的 OAuth 客户端

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

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

需要注意以下几点：

  • 使用现有 OAuth 客户端时，用户人数上限为 100 人。如需了解如何添加测试用户，请参阅设置 OAuth 权限请求页面。 除了 OAuth 验证之外，Home API 还规定了可向您的应用授予权限的用户数量上限为 100。完成 Developer Console 注册后，此限制即会解除。

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

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

Access blocked: <Project Name> has not completed the Google verification process.