Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

问题排查

示例应用

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

收集 Android 日志

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

安装 adb

如果您尚未在本地机器上设置 Android 调试桥，请先进行设置：

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

获取移动设备 ID

获取移动设备的 ID：

adb devices

List of devices attached
device-id    device

将此值存储在名为 phoneid 的变量中：
```
phoneid=device-id
```

版本信息

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

将各种设备信息保存到变量中：

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)

将所有变量保存到名为 _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

验证 _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 displaying seconds on the screen
adb -s $phoneid shell settings put secure clock_seconds 1

# 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 设备日志，请执行以下操作：

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

通过 adb bugreport 收集 Android 日志

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

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

投屏中心设备日志

您可以使用此方法查看 Google Nest Hub 的设备日志，以下型号支持此方法：

Google Home
Google Nest Audio
Google Nest Hub
Google Nest Mini

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

设置 Android 调试桥。
获取 Hub 的 IP 地址：
- 通过带屏幕的集线器：
  1. 从屏幕顶部向下滑动。
  2. 点按“设置”图标
  3. 查找设备 IP 地址：在Nest Hub (2nd gen)上，依次前往设备信息 > 技术信息 > IP 地址
- 在手机上通过GHA：
  1. 点按相应设备，打开设备详情页面
  2. 点按“设置”图标，调出设置页面
  3. 查找设备 IP 地址：前往设备信息 > 技术信息 > IP 地址
在与设备连接到同一 Wi-Fi 网络的计算机上：
```
  adb connect ip-address
  adb logcat
```
如需向某人提供日志，请执行失败的操作并将输出通过管道传输到文本文件：
```
  adb logcat -d > platform-logs.txt
```

自动化操作

边缘检测

Google Home 生态系统中的自动化操作具有边缘检测功能，该逻辑可验证启动方式仅在实际状态发生变化时才会激活，而不是在状态更新仅重复设备的先前状态时激活。

例如，如果启动器是开灯，边缘检测会验证启动器是否仅在灯具设备从关闭状态变为开启状态时激活，而不是从开启状态变为开启状态（无变化）。

自动化操作未按预期运行

如果自动化操作在考虑边缘检测后仍未按预期运行，请执行以下操作：

检查每个设备，确保其在不依赖自动化操作的情况下也能正常运行。
查看自动化操作的自动化图，并将其与自动化 DSL 进行比较，以找出您可能存在的任何不正确的假设。
在执行自动化操作期间，在 Google Home 应用中观察设备状态。
检查并确保自动化操作引用的所有设备都位于您预期的结构中。删除自动化操作所依赖的设备可能会产生意外后果。请参阅删除设备对自动化操作的影响。

自动化操作在不该运行的时候运行

如果自动化操作在不该运行的时候运行，请检查启动方式条件。您可能需要添加额外的逻辑，以确保状态变化仅被捕获一次，并且仅触发自动化操作一次。

自动化操作无法编译

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

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

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

List 函数抛出异常

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

为此，请执行以下操作：

检查以确保已安装 adb。请参阅安装 adb。

通过调用以下命令，从 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

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

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

Discovery API 会在特征未注册时记录警告

如果 Discovery API 记录了 Trait not found 的警告，则表示该 API 正在尝试将该 trait 用于 Discovery 候选设备，但由于该 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 确定特征名称，请参阅特征索引。

在此示例中，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 注册后，此限制即会解除。
Developer Console 注册应在您准备好通过 OAuth 限制设备类型授权时发送以供审批，以便为使用 Home API 更新应用做好准备。

重要提示：Google Home Developer Console 尚不开放注册。

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

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