示例应用
如果您在使用 Home API 时遇到任何问题，可以收集日志以进行进一步调试。从移动设备收集日志需要 Android 调试桥 (adb)。如果您需要 Google 的帮助，请从 Android 设备和中枢收集日志，并在问题跟踪器中提交工单，其中包含相关信息和日志。
收集 Android 日志
对于涉及 adb 的所有步骤
，您的移动设备都必须连接到本地机器。
安装 adb
如果尚未在本地机器上设置 Android 调试桥，请按以下步骤操作：
- 在您的 计算机上安装“adb”。
- 在 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 分享问题，则必须执行此操作。
- 获取移动设备的 ID：
adb devicesList of devices attached device-id device
- 将此值存储在名为
phoneid的变量中：phoneid=device-id - 将各种设备信息保存到变量中：
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) - 将所有变量保存到名为
_versions.txt的文件中：展开即可显示将变量保存到文件的命令
您可以一次性复制整个代码块并将其粘贴到终端。
versionfile=$logtimestamp"_versions.txt" echo "Saving version info to $versionfile"
echo "Container version:" >> $versionfile echo $containerinfo >> $versionfile echo "" >> $versionfileecho "Home Module version:" >> $versionfile echo $homemoduleinfo >> $versionfile echo "" >> $versionfileecho "Optional Home Module version:" >> $versionfile echo $optionalhomemoduleinfo >> $versionfile echo "" >> $versionfileecho "Policy Home Module version:" >> $versionfile echo $policyhomemoduleinfo >> $versionfile echo "" >> $versionfileecho "Thread Module version:" >> $versionfile echo $threadinfo >> $versionfile echo "" >> $versionfileecho "GHA version:" >> $versionfile echo $ghainfo >> $versionfile echo "" >> $versionfileecho "Android version: " >> $versionfile echo $androidversion >> $versionfile echo "" >> $versionfileecho "Android API version: " >> $versionfile echo $androidapiversion >> $versionfile echo "" >> $versionfileecho "Found enabled features (blank if missing):" >> $versionfile echo $enabledfeatures >> $versionfile echo "" >> $versionfile - 验证
_versions.txt的内容：cat _versions.txt现在，您可以根据需要将此文件提供给 Google 以进行问题排查。展开即可显示示例文件输出
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.1Android version: 13Android API version: 33Found enabled features (blank if missing):
收集日志
如需收集日志，请关闭移动设备上运行的所有应用。然后，执行以下操作：
- 打开终端窗口并清除现有的设备日志：
adb logcat -b all -c - 开始日志收集流程：
adb logcat >> _logs.txt - 运行示例应用并捕获所有界面操作。完成后，按 Ctrl+C （或 Mac 上的 Cmd+C ）停止在终端上运行的
logcat进程。 - 此会话中的日志会保存在名为
_logs.txt的文件中。
您可以通过多种方式分析此文件中的信息，包括搜索 error、exception 或 crash 等关键字。
日志脚本
为方便起见，示例应用提供了用于获取相关日志并将其编译到文本文件中的脚本。为了提供最佳调试体验，这些日志应附加到报告的任何 bug，以便 Google 分析根本原因。
这些日志位于示例应用源代码树的 scripts 目录中。
从项目根目录执行以下步骤：
- 获取移动设备的 ID：
adb devices -lList of devices attached device-id device
- 运行
get_logs.sh脚本：./scripts/get_logs.sh device-idCleared 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)
- 重现问题。
- 按
CTRL+C停止脚本。
该脚本将生成一个包含所有相关信息且带有时间戳的日志文件。将这些日志附加到您遇到的任何 bug 的报告中。
Cast 中枢设备日志
您可以使用此方法查看 Google Nest 中枢的设备日志，此方法适用于以下型号：
- Google Home
- Google Nest Audio
- Google Nest Hub
- Google Nest Mini
如需启用 Cast 中枢以检索本地日志，请执行以下操作：
- 设置 Android 调试桥。
获取中枢的 IP 地址：
- 从中枢（如果中枢有屏幕）：
- 从屏幕顶部向下滑动。
- 点按“设置”图标
- 找到设备 IP 地址：在 Nest Hub (2nd gen) 上，依次前往 设备信息 > 技术信息 > IP 地址
- 从手机上的 GHA：
- 点按相应设备以打开对应的设备详情页面
- 点按“设置”图标 以打开“设置”页面
- 找到设备 IP 地址：依次前往设备信息 > 技术信息 > IP 地址
- 从中枢（如果中枢有屏幕）：
在与设备位于同一 Wi-Fi 网络中的计算机上：
adb connect ip-addressadb 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 尝试将该特性用于 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.