调试智能家居

1. 准备工作

作为物联网 (IoT) 开发者,您可以构建智能家居 Action,让用户能够通过 Google Home 应用中的触控功能和 Google 助理语音指令控制自己的设备。

a4657871181b5ad2.gif

学习智能家居 Action 的调试工具,是打造与 Google 助理的生产质量集成的重要步骤。为方便监控和调试,我们提供了 Google Cloud Platform (GCP) 指标日志记录智能家居测试套件,以帮助您发现和解决与 Action 相关的问题。

前提条件

构建内容

在此 Codelab 中,你将部署一个存在 2 个缺陷的智能家居 Action 并将其与 Google 助理相关联,然后通过测试套件测试 Action 的缺陷,以便测试智能家居和 Google Cloud Platform (GCP) 指标和日志记录。

学习内容

  • 如何使用 GCP 指标和 Logging 来识别和解决生产问题
  • 如何使用智能家居测试套件来识别功能和功能问题

所需条件

2. 运行故障应用

获取源代码

点击以下链接,将此 Codelab 的示例下载到您的开发机器上:

...或者,您也可以通过命令行克隆 GitHub 代码库:

$ git clone https://github.com/google-home/smarthome-debug.git

项目简介

洗衣机应用包含以下子目录:

关联到 Firebase

在开发机器上打开终端。转到 washer-faulty 目录,然后使用在将智能家居设备关联到 Google 助理 Codelab 中构建的 Action 项目设置 Firebase CLI:

$ cd washer-faulty
$ firebase use <project-id>

部署到 Firebase

转到 functions 文件夹,然后使用 npm. 安装所有必要的依赖项

$ cd functions
$ npm install

注意:如果您看到下面的消息,可以忽略并继续。此警告是由于一些较旧的依赖项所致,您可以点击此处了解详情。

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

现在您已经安装了依赖项并配置了项目,接下来可以部署故障洗衣机应用。

$ firebase deploy

您应该会看到以下控制台输出:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<project-id>.firebaseapp.com

更新 HomeGraph

打开浏览器中的 Hosting 网址 (https://<project-id>.firebaseapp.com) 以查看 Web 应用。在网页界面上,点击刷新ae8d3b25777a5e30.png 按钮,通过请求同步更新 HomeGraph 中的错误洗衣机应用的最新设备元数据:

6f2b1344179977cf.png

打开 Google Home 应用,验证您是否能看到名为 Faulty Washer 的洗衣机设备。

e357de6a7faff925.png

3. 测试您的 Action

部署项目后,请测试 Action 是否控制洗衣机。

测试洗衣机

当您使用手机尝试执行以下任意语音指令时,请检查值是否更改:

“Ok Google,启动洗衣机。”

“Ok Google,运行洗衣机。”

“Ok Google,暂停我的洗衣机。”

“Ok Google,恢复洗衣机。”

“Ok Google,让洗衣机停止运行。”

当你暂停 / 继续洗衣机时,你会注意到 Google 助理通过语音提示出了点问题:

“抱歉,我无法访问<project display name>。”

要调试此问题,您首先需要详细了解关于该错误的信息,以便缩小范围,确定根本原因。

智能家居 Google Analytics(分析)信息中心

检查 Errorhome Analytics 信息中心是不错的去处,其中汇总了你的云执行方式的用量和健康指标图表:

  • 用量指标反映了智能家居 Action 的用量趋势,包括执行方式的日活跃用户数和请求总数。
  • 运行状况指标可帮助您监控智能家居 Action 中的异常情况,包括请求延迟时间、成功百分比和错误细分。

如需缩小错误原因,请按照以下步骤访问项目信息中心。

  1. Actions 控制台中,前往“Projects”页面。
  2. 选择你的智能家居项目。
  3. 选择 Analytics 标签页,然后点击 Go to Google Cloud Platform

b1735bbe11a7aff8.png

  1. 此操作会将您转到 Google Cloud 上的项目信息中心列表。选择 Google Home Analytics - 云集成信息中心。

5edd3751323176dd.png

  1. 向下滚动到 Cloud Fulfillment 错误 - 状态细分图表,以查看突出显示的时间范围的错误代码。

c468743c20a11c15.png

PARTNER_RESPONSE_MISSING_DEVICE 错误代码提供了根本原因提示。接下来,根据错误代码检索事件日志,以获取更多详细信息。

访问事件日志

如需详细了解该错误,请通过 Cloud Logging 访问智能家居 Action 的事件日志。

在 Google Cloud Platform 中打开导航菜单,在操作下选择 Logging > 日志浏览器以访问项目的事件日志。您也可以在搜索框中搜索日志浏览器

查询部分,输入查询 PARTNER_RESPONSE_MISSING_DEVICE,然后点击运行查询。与查询匹配的日志会显示在查询结果部分中。

747cca0f1249a5a.png

错误日志会显示智能家居事件,以及错误详情:

  • 用户执行的操作为“恢复洗衣机”(actionType:STARTSTOP_UNPAUSE”),对应于最近失败的语音指令。
  • 关联的调试消息为“JSON response does not include device.

根据调试消息,您应该检查洗衣机应用为何未在 EXECUTE 响应中添加正确的设备。

确定错误的根本原因

functions/index.js 中,找到返回每个命令的状态和新设备状态的 EXECUTE 处理程序(在 onExecute 数组中)。将设备 ID 插入 EXECUTE 响应取决于对 updateDevice 函数的解析:

index.js

app.onExecute(async (body) => {
 ...

 for (const command of intent.payload.commands) {
   for (const device of command.devices) {
     for (const execution of command.execution) {
       executePromises.push(
           updateDevice(execution, device.id)
               .then((data) => {
                 result.ids.push(device.id);
                 Object.assign(result.states, data);
               })
               .catch((e) =>
                 functions.logger.error('EXECUTE',
                     device.id, e.message)));
     }
   }
 }

进一步检查 updateDevice 函数在洗衣机上如何处理暂停 / 恢复,您会发现与暂停 / 恢复命令匹配的字符串不正确:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpausePause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

修正错误

现在,您已经确定了错误的根本原因,接下来可以更正暂停 / 恢复命令的字符串:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpause':
     state = {isPaused: params.pause};
     if (params.pause) state.isRunning = false;
     ref = firebaseRef.child(deviceId).child('StartStop');
     break;
 }

 return ref.update(state)
     .then(() => state);
};

测试修正效果

使用 Firebase CLI 部署更新后的代码:

firebase deploy --only functions

请再次尝试以下语音指令,现在暂停 / 恢复洗衣机时,您会发现 Google 助理会正确响应。

“Ok Google,让洗衣机暂停运行。”

=>

“好的,正在暂停洗衣机。”

“Ok Google,恢复洗衣机。”

=>

“知道了,恢复洗衣机。”

你还可以通过提问来测试洗衣机的当前状态。

“Ok Google,我的洗衣机启动了吗?”

“Ok Google,我的洗衣机在运行吗?”

“Ok Google,我的洗衣机洗到哪一步了?”

4. 使用测试套件测试您的 Action

除了手动测试之外,你还可以使用自动化的智能家居测试套件,以根据与你的 Action 关联的设备类型和特征来验证用例。该测试套件会运行一系列测试来检测 Action 中的问题,并会显示失败测试用例的参考性消息,以便在调试事件日志之前加快调试速度。

运行智能家居测试套件

如需按照以下说明测试智能家居 Action by Test Suite,请按以下步骤操作:

  1. 在网络浏览器中,打开智能家居测试套件
  2. 使用右上角的按钮登录 Google。这样一来,测试套件就可以直接将命令发送给 Google 助理。
  3. 项目 ID 字段中,输入智能家居 Action 的项目 ID。然后点击下一步以继续。
  4. Test Settings(测试设置)步骤中,您会看到测试套件列出了洗衣机的设备类型和特征。

78ed6a1ebdb581bf.png

  1. 停用测试请求同步选项,因为示例洗衣机应用没有添加 / 移除 / 重命名洗衣机的界面。在生产系统中,每当用户添加 / 移除 / 重命名设备时,您都必须触发请求同步
  2. 点击下一步以开始运行测试。

测试套件运行完毕后,查看测试用例的结果。您会发现,系统捕获了两个失败的测试用例,并分别显示了相应的错误消息:

5838d10631c98ed2.png

为了调试失败的智能家居 Action,你需要先分析错误消息,以找出错误的根本原因。

分析错误消息

为了帮助开发者确定根本原因,测试套件会显示每个失败的测试用例的错误消息,指出失败的原因。

对于上述第一个失败的测试用例,

99e4e5d06965a8a7.png

但其错误消息表明,在智能家居 Action 报告的状态下,测试套件需要 "isPause": true,但实际状态仅包含 "isPause": false

此外,第二个失败测试用例的错误消息表示QUERY来自智能家居 Action 的响应中的状态包括 "isPause": true,这与智能家居 Action 报告的状态不同的 "isPause": false

fdb5124102e3a37.png

根据上述错误消息,您应检查你的 Action 是否报告了状态为 isPaused 的正确值。

确定错误的根本原因

打开 functions/index.js,其中包含 reportstate 函数,该函数通过报告状态将状态更改发布到 Home Graph。检查报告状态载荷,您将发现该载荷缺失 isPaused 状态,这正是测试套件在失败的测试用例中检查到的结果。

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };

      const res = await homegraph.devices.reportStateAndNotification({
        requestBody,
      });
      ...
    });

修正错误

现在,您已经确定了错误的根本原因,请将 isPaused 状态添加到报告状态载荷中来修改 functions/index.js

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: true,
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };
      ...
    });

测试修正效果

使用 Firebase CLI 部署更新后的代码:

$ firebase deploy --only functions

重新运行智能家居测试套件,您会看到所有测试用例均已通过。

148837f85d377dd6.png

5. 恭喜

17d485868a6771bc.png

恭喜!您已成功了解如何通过测试套件排查智能家居 Action 问题,以获取智能家居和 GCP 指标和日志记录。

了解详情

在此 Codelab 的基础上,尝试做以下练习并浏览其他资源:

您还可以详细了解如何测试和提交 Action 以供审核,包括向用户发布 Action 的认证流程。