调试 Matter 集成

1. 准备工作

Matter 为最终用户提供顺畅的跨平台设备设置和控制体验。这主要是因为有多个生态系统组件在后台协同工作。对新手开发者来说,此类问题排查系统往往会让新开发者望而却步,因此我们开发了一系列工具和技术,让使用 Google Home 的 Matter 开发者的工作更轻松。

此 Codelab 介绍了 Matter 的三个主要组件。对于上述每个系统,Google 都为开发者提供了一系列从手机和 hub 收集的问题排查分析:

调试、执行、OTA 更新

作为开发者,您能够缓解在整个设备开发周期中遇到的问题至关重要。启动项目后,您需要以汇总方式监控现场设备的问题趋势,并通过软件更新来修复这些问题。此 Codelab 介绍了可用于这两种用途的方法。

前提条件

  • 完成 Matter 使用入门指南,其中包含正常运行的 Matter 项目和设备设置
  • 拥有可连接到工作站的 Android 手机(用于获取 ADB 日志)

学习内容

  • 如何使用智能家居的分析工具大规模监控 Matter 问题。
  • 如何通过访问错误日志和收集信息来对错误进行分类。
  • 如何访问 Matter 文档和支持资源以寻求帮助。

2. 查看 Google Home 分析

监控性能对于与 Google Home 生态系统成功集成至关重要。我们在 Google Cloud Platform 上为智能家居开发者提供了一套监控工具。您可以使用这些工具来衡量项目的性能。

访问项目指标

  • 访问数据的第一步是查看 Google Home 信息中心。为此,请登录 Google Cloud 控制台,然后依次前往操作 > 监控 > 信息中心

你的项目(包括其他 GCP 产品)可以使用多个信息中心。为智能家居提供的信息中心会带有 Google Home Analytics 前缀。

Google Home Analytics 信息中心

我们目前有一个涵盖您的整个项目的常规信息中心,以及针对特定集成(云、本地、Matter)或设备类型(相机)的信息中心。仅当您集成了相应类型的集成,以及正在执行请求的项目时,这些信息中心才会包含数据。

打开其中一个信息中心时,您会看到如下所示的一系列图表:

成功率、延迟时间和设备类型细分

Google Home 信息中心包含各种图表,可显示与您的项目相关联的事件的详细信息。在每个集成信息中心中,您会看到一张显示项目处理的请求总数的图表、显示该集成类型的成功率的图表,以及显示相关设备类型和特征的多个图表。此外,在 Matter 中,你还有一组图表,用于跟踪调试成功情况以及设备更新发布情况。

请注意,你在 Google Home Analytics 信息中心内看到的图表所在的默认视图只是我们使用智能家居指标数据为你的项目创建的视图。您还可以使用 Metrics Explorer,根据相同的底层指标创建自己的图表,并将其保存在自定义信息中心内。

访问错误日志

Logs Explorer 是一系列工具,用于处理项目中生成的事件日志。您可以在 Google Cloud 控制台中依次前往操作 > Logging > 日志浏览器来访问日志。

打开日志浏览器后,您会看到如下所示的视图:

Logs Explorer

浏览器窗口包含用于查看、过滤、查询和分析日志的各种工具。默认情况下,此视图会显示由项目可用的所有系统生成的日志,包括在智能家居之外生成的日志。因此,要使用这些日志,关键是要通过过滤要调试的事件。我们将在调试部分中对此进行详细介绍。

3. 调试调试问题

我们要介绍的第一种指标是 Matter 调试事件。调试是指用户首次设置 Matter 设备所需的一系列步骤。

在设备调试期间,Matter 设备、Google Home 应用和 Matter 结构之间会发生一系列互动。下图演示了其中一些事件:

Matter 调试事件

您可以查看 Matter Primer 中的“佣金”页面,详细了解每个步骤。在本部分中,我们将介绍用于调试调试问题的工具和技术。

使用 Google Home Analytics

我们创建了一组指标,您可以通过跟踪事件并了解错误可能出现的阶段来调查调试问题。您可以在 Matter 集成信息中心内找到这些信息,如上一部分所述。

此信息中心内的图表提供了有关设备调试的数据:

设备调试指标

设备计数图表会显示指定日期内用户尝试调试的次数。“成功率”显示的是 Google 端这些事件的感知成功率。每次调试尝试都会生成一组具有关联状态的事件。当错误在上述任一状态下发生时,系统也会将其捕获到错误细分图表中。

委托状态:

  • COMMISSIONING_STARTED
  • ONBOARDING_PAYLOAD_GENERATED
  • LOCAL_DISCOVERY_SUCCESSFUL
  • PASE_CONNECTION_SUCCESSFUL
  • NOC_ADDED_SUCCESSFULLY
  • COMMISSIONING_COMPLETE

如需查看这些事件的详细版本,请转到操作 > Logging > 日志浏览器。若要过滤佣金错误,您可以在查询字段中搜索“clientUpdateLog”和“severity>=ERROR”。

Matter 的调试错误日志如下所示:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "clientUpdateLog": {
      "MatterUpdate": {
        "reportedProductId": 55,
        "sessionId": "1584879052892229997",
        "reportedVendorId": 4800,
        "commissioningState": "GENERIC_COMMISSIONING_ERROR",
        "status": "GENERIC_ERROR"
      }
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T07:09:55.216425297Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}

除了调试状态和状态代码之外,错误日志还包含所捕获错误的时间戳,以及通过诉讼或调查产品 ID,您可以确定哪个产品导致了错误。通过同一调试尝试生成的一组日志共享一个 sessionId

通过 Google Home Analytics 中的指标,您可以初步了解问题可能发生在哪个阶段。要找出设备调试错误的根本原因,有时您可能需要使用在调试过程中所用移动设备生成的日志,进行其他调试。对于这些功能,您需要使用 Android 调试桥。

使用 Android 调试桥 (ADB)

排查调试问题的另一种方法是使用 Android 调试桥 (ADB) 命令行工具。由于调试主要在移动设备和 Matter 设备之间处理,因此可以在调试过程中使用 ADB 工具访问 Google Home 应用生成的日志。

安装平台工具

ADB 包含在 Android SDK 平台工具中,您可以使用 Android Studio 或通过 sdkmanager 命令行工具来安装该工具。

在系统上成功安装平台工具后,使用以下命令从终端检查版本号,以验证 ADB:

$ adb -- version

这应该会显示已安装 ADB 实用程序的版本号,而不会出现任何错误。

启用 USB 调试

下一步是在 Android 设备上启用 USB 调试。

首先按照相关步骤在设备上启用开发者选项,然后启用 USB 调试

这样一来,ADB 就可以访问由设备上当前运行的应用生成的日志。

检索设备 ID

  1. 使用以下命令运行 ADB 服务器:
$ adb start-server
  1. 将手机连接到运行 ADB 服务器的计算机。

您可能会在手机上收到一条有关 USB 调试的警告消息,询问您是否允许计算机访问手机中的信息:

USB 调试提示

  1. 如果您收到此警告消息,请点击允许
  2. 从终端发出 list devices 命令,查看您的计算机能否通过 ADB 访问手机,方法是使用以下命令:
$ adb devices

系统应返回类似如下的响应:

List of devices attached
<phone-id>    device

您的 <phone-id> 是唯一标识您的设备的字母数字字符串。

  1. 请记住 <phone-id> 值,以便在后续步骤中使用。

收集系统信息

接下来,查看设备上的应用和系统的版本信息。

  • 如需查看 Android OS 版本,请执行以下操作:
$ adb -s <phone-id> shell getprop ro.build.version.release
  • 如要查看 Google Home 应用版本,请执行以下操作:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
  • 如需查看 Google Play 服务版本,请执行以下操作:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
  • 如需通过 Play 服务检查您是否有 Home / Matter 控制模块,请执行以下操作:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

确保这些返回值受到我们的生态系统的支持。就调试失败问题联系支持团队时,请始终在支持服务工单中提供系统信息。

收集错误日志

接下来,启动日志收集流程,然后完成调试步骤以生成要调试的错误事件。

  1. 运行以下命令,方法是提供 <phone-id> 以及将日志保存在计算机中的 <file-name>(例如debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>

这会立即开始记录日志。若文件不存在,系统会创建一个具有所提供名称的文件,并在每次事件后将手机日志添加到该文件中。

请使用您的 Matter 设备执行调试步骤。

  1. 遇到要调试的错误后,请在正在运行的终端窗口中按 Control+C 停止日志记录。

您的日志现在应存储在 <file-name> 日志记录文件中。由于此流程会记录设备中跟踪的每个正在运行的进程的日志,因此该文件中会有大量的日志。因此,您应始终通过搜索所需条目来使用这些日志。

分析错误日志

调试流程通过 GHA 中名为 MatterCommissioner 的子系统处理。

  1. 按照分析调试错误时使用的主要策略,使用以下命令查找由 MatterCommissioner 子系统生成的错误:
$ grep "MatterCommissioner" <file-name>

这将生成一个输出,其中包含调试流程中的事件。

  1. 如果您的 Matter 设备正在使用 Thread,还可以通过以下命令查找 Thread 子系统生成的错误:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

在分析 ADB 调试过程生成的日志文件时,请同时查找某些模式。很多调试错误都会在错误消息中包含“commissioning failure”字符串。

  1. 使用以下命令搜索调试失败消息:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. 调试设备控制问题

用户设置并调试 Matter 设备以加入 Google Home 生态系统后,他们可以通过使用 Google 助理的语音发出命令(例如,“Ok Google,打开客厅的灯”),也可以使用 Home 应用或 Google Nest 显示屏设备上的界面发出指令。

由于最终设备和 Google Hub 之间的控制规范由 Matter 进行中介,因此设备控制端的错误预计会减少。无论如何,我们都会提供指标和日志,以便您调试这些类型的问题。

使用指标

在 Matter 集成信息中心内,您将看到多个关于设备控制的指标。以下三个图表对于评估设备在实际运行中的性能至关重要:

成功、延迟时间和错误细分图表

在控制问题期间,成功率百分比呈现下降趋势,错误明细图表呈现上升趋势。错误细分图表显示了 Google Nest Hubs 捕获的有关设备控制尝试失败原因的错误。

使用日志

每个 Matter 设备控制问题还会在系统中生成错误日志。您可以通过搜索“executionLog”从日志浏览器中过滤这些错误。

Matter 设备控制错误日志如下所示:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "executionLog": {
      "executionResults": [
        {
          "executionType": "MATTER",
          "latencyMsec": "6000",
          "actionResults": [
            {
              "action": {
                "actionType": "ONOFF_OFF",
                "trait": "TRAIT_ON_OFF"
              },
              "status": {
                "externalDebugString": "No message was received before the deadline.",
                "statusType": "RESPONSE_TIMEOUT",
                "fallbackToCloud": false,
                "isSuccess": false
              },
              "device": {
                "deviceType": "OUTLET"
              }
            }
          ],
          "requestId": "1487232799486580805"
        }
      ]
    },
    "locale": "en-US"
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T15:47:27.311673018Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}

每个错误日志都包含时间戳、设备类型和特征,以及与 statusType 中的控制请求相关的错误。许多控件错误还包含 externalDebugString,这是一条简短的错误消息,会说明具体错误。

5. 调试其他功能

到目前为止,您已经了解了如何处理 Matter 的设备调试和控制问题。您还可以使用我们推荐的技术确保生态系统中的其他功能获得高质量的集成。

跟踪 OTA 更新

为了跟踪 Google Home 设备的无线下载 (OTA) 更新版本,我们提供了一组指标,用于显示现场设备的硬件和软件版本。

从控制台发出更新后,请留意以下指标:

软件和硬件细分

您会发现,随着新版本的发布,越来越多的设备获得与您的 OTA 软件版本关联的新软件版本。

6. 寻求支持

Google 提供了相关工具和文档来帮助您调试 Matter 问题,但随着 Matter 生态系统不断发展,这些资源不会涵盖某些问题。对于这些情况,您可以随时联系我们或社区寻求支持。

访问开发者频道

Google 内部有三个开发者渠道主动监控:

Stack Overflow、问题跟踪器、开发者论坛

虽然同一个团队会定期监控所有这些渠道,但在何时使用哪个渠道方面存在一些关键区别。

  • Stack Overflow:如果有实现问题或寻求指导,请联系我们和智能家居开发者社区。此类渠道最适合用于询问如何排查问题或实现特定功能
  • 问题跟踪器:这是 Google 运行的官方问题跟踪器系统,外部受众可以在这里报告生态系统中的错误。它提供了用于附加文件并根据需要分享敏感信息的网络工具。如要报告生态系统问题或分享功能请求,使用问题跟踪器是最佳选择。
  • 开发者论坛:如需向 Google 官方支持和社区专家寻求帮助,您可以通过 Nest 开发者论坛与我们联系。此论坛最适合用于获取官方开发指导

订阅开发者简报

除了访问开发者频道提问之外,我们还会发布季度简报,重点介绍新功能并提供有关 Google 智能家居生态系统动态的新闻。

您可以使用注册表单接收开发者简报。

7. 恭喜

Google Home

恭喜!您已成功了解如何使用我们建议的工具和技术调试 Matter 集成。祝您在构建 Matter 与 Google Home 之间的集成过程中一切顺利!

后续步骤

尝试完成以下练习并探索其他资源:

  • 除了使用分析工具排查问题之外,您还可以使用测试套件来测试您的集成是否存在任何潜在问题。
  • 一旦您的集成准备好与全世界分享,下一步就是让您的项目获得“支持 Google Home”认证。为此,您可以按照认证页面中的步骤操作。