问题排查

示例应用

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

收集 Android 日志

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

安装 adb

如果尚未在本地机器上设置 Android 调试桥，请按以下步骤操作：

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

获取移动设备 ID

  1. 获取移动设备的 ID： 
    adb devices
     
    List of devices attached
device-id    device
  2. 将此值存储在名为 phoneid 的变量中： 
    phoneid=device-id

版本信息

我们建议您在决定收集日志时，收集与设置相关的所有版本信息。如果您需要与 Google 分享问题，则必须执行此操作。

  1. 将各种设备信息保存到变量中： 
    containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep -m 1 "versionName" || true); ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep -m 1 "versionName" || true); androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true); androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true); chimeradump=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider || true); homemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.home" || true); optionalhomemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.optional_home" || true); threadinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.threadnetwork" || true); enabledfeatures=$(echo "$chimeradump" | grep "Enabled features" | grep -i "home" | sort -u || true)
  2. 将所有变量保存到名为 _versions.txt 的文件中：

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

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

    versionfile="_versions.txt"
echo "Saving version info to $versionfile"
echo "Container version: $containerinfo" > $versionfile
echo "Home Module version: $homemoduleinfo" >> $versionfile
echo "Optional Home Module version: $optionalhomemoduleinfo" >> $versionfile
echo "Thread Module version: $threadinfo" >> $versionfile
echo "GHA version: $ghainfo" >> $versionfile
echo "Android version: $androidversion" >> $versionfile
echo "Android API version: $androidapiversion" >> $versionfile
echo "Found enabled features: $enabledfeatures" >> $versionfile
  3. 验证 _versions.txt 的内容： 
    cat _versions.txt

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

    Container version:     versionName=26.26.34 (190400-945364269)
Home Module version:             com.google.android.gms.home [v262634001]
Optional Home Module version:         com.google.android.gms.optional_home [262634025] ...
Thread Module version:             com.google.android.gms.threadnetwork [v262634001]
GHA version:     versionName=4.22.28.0
Android version: 14
Android API version: 34
Found enabled features:             Enabled features: appsearch_impl, brella_dynamite, dck_management...
    现在，您可以根据需要将此文件提供给 Google 以进行问题排查。

启用详细调试标志

在收集 Android 设备日志或运行 bug 报告之前，请配置记录器缓冲区空间，并为 Google Home 和 GMS 组件启用详细调试标志：

# Clear existing device logs and expand logger buffer size
adb -s $phoneid logcat -b all -c
adb -s $phoneid logcat -G 8M

# Enable GMS Service ID verbose flags
adb -s $phoneid shell setprop log.tag.gms_svc_id:168 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:304 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:305 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:319 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:336 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:360 VERBOSE

# Enable GHP and Matter log tags
adb -s $phoneid shell setprop log.tag.CameraCommissioningPlugin VERBOSE
adb -s $phoneid shell setprop log.tag.HomeSdk VERBOSE
adb -s $phoneid shell setprop log.tag.HomeClient VERBOSE
adb -s $phoneid shell setprop log.tag.InteractionApiChimeraService VERBOSE
adb -s $phoneid shell setprop log.tag.MatterCommissioner VERBOSE
adb -s $phoneid shell setprop log.tag.SampleApp VERBOSE

通过脚本收集 Android 日志

如需在调试会话期间捕获实时 Android 设备日志，请执行以下操作：

  1. 按照启用详细调试标志中的说明清除现有日志、扩大缓冲区空间并设置详细日志记录标志。
  2. 关闭移动设备上运行的所有应用。
  3. 在开始测试之前，清除现有日志缓冲区中的干扰信息： 
    adb -s $phoneid logcat -c
  4. 在终端窗口中启动日志收集过程： 
    adb -s $phoneid logcat | tee android-logs_$(date +%Y%m%d%H%M%S).txt
     请勿关闭此终端窗口。只要此过程运行，系统就会捕获您设备中的日志。
  5. 运行您的应用，并执行重现问题所需的所有界面操作。
  6. 完成后，按 Ctrl+C （或 Mac 上的 Cmd+C ）在终端中停止 logcat 进程。
  7. 此会话中的日志会保存在 android-logs_YYYYMMDDmmss.txt 中。将 android-logs_YYYYMMDDmmss.txt 和 _versions.txt 都附加到任何 bug 报告中。

通过 adb bugreport 收集 Android 日志

当您需要分享涵盖系统级问题、崩溃转储或低级别网络和蓝牙调试的详细诊断信息时，请捕获完整的 Android bug 报告：

  • Matter BLE 调试： 报告与 BLE 相关的 Matter 调试问题时，请先在开发者选项中启用 Bluetooth HCI 信息收集日志 （设置 > 开发者选项 > 启用 Bluetooth HCI 信息收集日志 ），然后再重现问题。
  • 测试前设置： 在运行测试之前，请按照启用详细调试标志中的步骤在设备上启用详细调试属性。
  • 捕获 bug 报告： 运行测试并重现问题后，请运行以下命令以生成完整的 bug 报告归档： 
    adb -s $phoneid bugreport ./android-bugreport_$(date +%Y%m%d%H%M%S).zip
  • 高级调试信息： 生成的 android-bugreport_YYYYMMDDmmss.zip 文件包含全面的系统级诊断数据，包括完整的系统转储、内存统计信息、电池诊断信息和低级别子系统跟踪记录，可提供更高级的调试信息。

Cast 中枢设备日志

您可以使用此方法查看 Google Nest 中枢的设备日志，此方法适用于以下型号：

  • 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参考文档。

List 函数抛出异常

调用 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 不需要进行注册。 不过，您仍需要获得批准的 Developer Console注册才能发布应用，即使您拥有来自其他集成的 已验证 OAuth 客户端也是如此。

需要注意以下几点：

  • 使用现有 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.