Debugging the Smart Home [Japanese]

モノのインターネット (IoT) の開発者は、ユーザーが Google Home アプリのタッチコントロールと Google アシスタントの音声コマンドでデバイスを制御できるスマートホームアクションを構築できます。

スマートホームアクションのデバッグツールを学習することは、Google アシスタントとの製品品質の統合を構築するための重要なステップです。モニタリングとデバッグを容易にするために、 Google Cloud Platform (GCP) Metrics and Logging および Test Suite for smart home を利用して、アクションの問題を特定して解決することができます。

事前準備

Create a smart home Action 開発者ガイドを読んでおいてください。
Connect smart home devices to the Google Assistant コードラボを実施しておいてください。

作るものはなんですか

このコードラボでは、2 つの欠陥があるスマートホームアクションをデプロイしてアシスタントに接続し、スマートホームと Google Cloud Platform (GCP) のメトリックとロギングのテストスイートを介してアクションの欠陥をデバッグします。

何を学びますか

GCP のメトリクスとロギングを使用して本番環境の問題を特定して解決する方法
Test Suite for Smart Home を使用して機能と API の問題を特定する方法

何が必要ですか

Google Chrome のようなウェブブラウザ。
Google Home アプリがインストールされている iOS または Android デバイス。
Node.js バージョン 10.16 以上。
Google Cloud の請求アカウント。

ソースコードを入手する

次のリンクをクリックして、開発マシンにこのコードラボのサンプルをダウンロードします。

Download source code

または、コマンドラインからGitHubリポジトリをcloneすることができます。

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

プロジェクトについて

ウォッシャーアプリは以下のサブディレクトリを含んでいます。

public: スマートウォッシャーの状態を簡単に制御および監視するためのフロントエンド UI。
functions: Cloud Functions for Firebase および Firebase Realtime Database を使用してスマートウォッシャーを管理する完全に実装されたクラウドサービス。

Firebaseに接続する

開発マシンでターミナルを開きます。 washer-faulty ディレクトリに移動し、 Connect smart home devices to the Google Assistant コードラボにて構築されたアクションプロジェクトで Firebase CLI を設定します。

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

Firebaseにデプロイする

functions フォルダーに移動し、npm を使用して必要なすべての依存関係をインストールします。

$ cd functions
$ npm install

Note: 以下のメッセージが表示された場合は、無視して続行できます。この警告は、一部の古い依存関係が原因であり、詳細はこちらで確認できます。

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 を更新する

Web アプリを表示するには、ブラウザで Hosting URL を開きます ( https://.firebaseapp.com ) 。 Web UI で Refresh ボタンをクリックして、障害のある洗濯機アプリからの最新のデバイスメタデータで、 Request Sync を介して HomeGraph を更新します。

Google Homeアプリを開いて、Faulty Washer という名前でウォッシャーデバイスを見ることができるかどうか確認してください。

プロジェクトをデプロイした後、アクションがウォッシャーを制御することをテストします。

ウォッシャーをテストする

"Hey Google, turn on my washer."

"Hey Google, start my washer."

"Hey Google, pause my washer."

"Hey Google, resume my washer."

"Hey Google, stop my washer."

洗濯機を一時停止/再開すると、アシスタントが音声で何か問題があると応答します。

"Sorry, I couldn't reach <project display name>."

この問題をデバッグするには、まずエラーに関する詳細情報を絞り込み、根本原因を特定する必要があります。

スマートホームアナリティクスダッシュボード

エラーを検査するのに適した場所は、クラウドフルフィルメントの Usage and Health metrics のグラフを集約する Smarthome Analytics ダッシュボード です。

Usage の指標は、1 日のアクティブユーザー数やフルフィルメントへの合計リクエスト数など、スマートホームアクションの使用傾向を反映しています。
Health メトリクスは、スマートホームアクションでの異常の発生を監視するのに役立ち、リクエストのレイテンシ、成功率、エラーの内訳をカバーします。

エラーの原因を絞り込むには、ダッシュボードの error breakdown チャートでエラーの手がかりを確認してください。

まず、次の手順に従ってプロジェクトのダッシュボードにアクセスします。

Actions console にて、Project ページに行きます。
あなたのスマートホームアクションを選択します。
Analytics タブを選択して、 Go to Google Cloud Platform をクリックします。

Smarthome Error Breakdown グラフ (上から 4 行目の左側) を含む複数のグラフが表示され、失敗した要求の数とそれぞれのエラーコードが示されます。

INVALID_JSON エラーコードは、根本原因へのヒントを提供します。次に、詳細について、エラーコードに基づいてイベントログを取得します。

イベントログにアクセスする

エラーの詳細を取得するには、Cloud Logging を介してスマートホームアクションのイベントログにアクセスします。

Google Cloud Platform でナビゲーションメニューを開きます。 Operations で Logging > Logs Explorer を選択してプロジェクトの Cloud Logging にアクセスし、クエリ INVALID_JSON を実行して関連するイベントログを取得します。最新のエラーログを見つける必要があります。

エラーログはスマートホームイベントであり、エラーの詳細は次のように示されます。

実行されたユーザーアクションは、最近失敗した音声コマンドに対応する "resuming washer" ( actionType: "STARTSTOP_UNPAUSE" ) です。
関連するデバッグメッセージは、 "JSON response does not include device." です。

デバッグメッセージに基づいて、洗濯機アプリが EXECUTE 応答に正しいデバイスを含めない理由を確認する必要があります。

エラーの根本原因を特定する

functions/index.js で、各コマンドのステータスと新しいデバイスの状態を返す EXECUTE ハンドラー (onExecute 配列内) を見つけます。 EXECUTE 応答へのデバイス ID の挿入は、 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 関数がウォッシャーで一時停止/再開を処理する方法をさらに確認すると、 pause / resume コマンドに一致する文字列が正しくないことがわかります。

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

次の音声コマンドを再試行すると、洗濯機を一時停止/再開したときにアシスタントが正しく応答することがわかります。

"Hey Google, pause my washer."

"Sure, pausing the washer."

"Hey Google, resume my washer."

"Got it, resuming the washer."

You can also test the current state of your washer by asking questions.

"Hey Google, is my washer on?"

"Hey Google, is my washer running?"

"Hey Google, what cycle is my washer on?"

手動でのテストに加えて、スマートホーム向けのテストスイートを使用して、アクションに関連付けられたデバイスタイプとトレイトに基づいてユースケースを検証できます。テストスイートは一連のテストを実行してアクションの問題を検出し、失敗したテストケースの情報メッセージを表示して、イベントログに飛び込む前にデバッグを促進します。

スマートホーム向けテストスイートを実行する

テストスイートによるスマートホームアクションのテストは、これらの指示に従います。

Web ブラウザーで、 Test Suite for smart home を開きます。
右上隅にあるボタンを使用して Google にログインします。これにより、テストスイートはコマンドを Google アシスタントに直接送信できます。
Project ID フィールドに、スマートホームアクションのプロジェクト ID を入力します。そして、 NEXT をクリックして次に進みます。
Test Settings ステップでは、テストスイートに洗濯機のデバイスタイプと特性が一覧表示されます。
サンプルウォッシャーアプリには、ウォッシャーを追加/削除/名前変更する UI がないため、 Test Request Sync オプションを無効にします。実稼働システムでは、ユーザーがデバイスを追加/削除/名前変更するたびに、 Request Sync をトリガーする必要があります。
NEXT をクリックして、テストの実行を開始します。

テストスイートの実行が完了したら、テストケースの結果を表示します。失敗した 2 つのテストケースがそれぞれのエラーメッセージでキャッチされていることに気付くでしょう。

エラーのスマートホームアクションをデバッグするには、最初にエラーメッセージを分析して、エラーの根本原因を特定する必要があります。

エラーメッセージを分析する

開発者が根本原因を特定できるようにするために、Test Suite は失敗した各テストケースのエラーメッセージを表示し、失敗の理由を示します。

上記の最初の失敗したテストケースでは、

エラーメッセージは、テストスイートがスマートホームアクションから報告された状態で "isPause": true を期待していることを示していますが、実際の状態には "isPause": false のみが含まれます。

さらに、2 番目に失敗したテストケースのエラーメッセージは、スマートホームアクションからの QUERY 応答の状態が "isPause": true であることを示しています。これは、スマートホームアクションから報告された状態の "isPause": false とは異なります。

両方のエラーメッセージに従って、アクションが isPaused の状態が正しい値で報告されているかどうかを確認する必要があります。

エラーの根本原因を特定する

functions/index.js を開きます。この関数には、レポートの状態を介して状態の変更をホームグラフに送信する reportstate 関数が含まれています。 Report State ペイロードを調べると、ペイロードに 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 状態を Report State ペイロードに追加して 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

スマートホームのテストスイートを再実行すると、すべてのテストケースに合格したことがわかります。

おめでとう！テストスイートを介してスマートホームアクションの問題をトラブルシューティングする方法を学習しました。

もっと学習する

この Codelab を構築して、次の演習を試して、追加のリソースを調べてください。

デバイスにもっと supported traits を追加して、Test Suite を使ってそれらをテストします。
dashboards を作成して、 alerts をセットアップし、アクションについて有益な使用メトリクスを得るために、 access metrics data programmatically にアクセスします。
スマートホーム向けの local fulfillment を調査します。
より探求するために、 GitHub sample をチェックします。

また、アクションをユーザーに公開するための認証プロセスなど、レビューのためにアクションをテストして提出する方法についても学ぶことができます。