Matter 統合のデバッグ

1. 始める前に

Matter は、シームレスなクロス プラットフォーム デバイス セットアップと操作エクスペリエンスをエンドユーザーに提供します。これが主に可能なのは、バックグラウンドで相互に連携する複数のエコシステム コンポーネントにあります。このようなシステムのトラブルシューティングは、初めて利用するデベロッパーにとっては面倒な作業になりがちです。そこで、Google Home を使用する Matter デベロッパーの作業を容易にする一連のツールと手法を開発しました。

この Codelab では、Matter の 3 つの主要コンポーネントについて説明します。Google はこれらのシステムごとに、スマートフォンやハブから収集したデベロッパー向けのトラブルシューティング分析を提供します。

コミッショニング、実行、OTA アップデート

デバイスの開発サイクル全体を通じて、デベロッパーが直面する問題を軽減することは非常に重要です。プロジェクトを開始したら、フィールドで発生しているデバイスの問題の傾向を集約してモニタリングし、ソフトウェア アップデートによって修正する必要があります。この Codelab では、この両方の目的に使用できる手法について説明します。

前提条件

  • 作業中の Matter プロジェクトとデバイスのセットアップで、Matter のスタートガイドを完了していること
  • ワークステーションに接続できる Android スマートフォンを用意する（ADB ログ用）

学習内容

  • スマートホームの分析ツールを使用して、Matter の問題を大規模にモニタリングする方法
  • エラーログにアクセスして情報を収集し、エラーをトリアージする方法。
  • Matter のドキュメントやサポート リソースにアクセスしてサポートを求める方法

2. Google Home アナリティクスを表示する

Google Home エコシステムとの統合を成功させるには、パフォーマンスのモニタリングが不可欠です。Google は、Google Cloud Platform 上でスマートホーム デベロッパー向けに一連のモニタリング ツールを提供しています。これらのツールを使用して、プロジェクトのパフォーマンスの測定値を取得できます。

プロジェクトの指標にアクセスする

  • データにアクセスする最初のステップは、Google Home ダッシュボードを確認することです。Google Cloud コンソールにログインして、[オペレーション] > [モニタリング] > [ダッシュボード] の順に移動します。

プロジェクトでは多数のダッシュボードを利用できます（他の GCP プロダクトを含む）。スマートホーム用に提供されるダッシュボードには、接頭辞 Google Home Analytics が付いています。

Google Home Analytics ダッシュボード

現在、プロジェクト全体を網羅する一般的なダッシュボードと、特定のインテグレーション（クラウド、ローカル、Matter）やデバイスタイプ（カメラ）向けのダッシュボードがあります。これらのダッシュボードには、対応するタイプのインテグレーションと、リクエストを処理する機能するプロジェクトがある場合のみ、データが含まれます。

これらのダッシュボードのいずれかを開くと、次のような一連のグラフが表示されます。

成功率、レイテンシ、デバイスタイプの内訳

Google Home ダッシュボードには、プロジェクトに関連付けられたイベントの詳細を示すさまざまなグラフが表示されます。各統合ダッシュボードには、プロジェクトで処理されたリクエストの合計数を示すグラフ、その統合タイプの成功率を示すグラフ、関係するデバイスの種類とトレイトを示す複数のグラフが表示されます。さらに、Matter によって、コミッショニングの成功状況と、デバイスへの更新のロールアウトを追跡した一連のグラフを利用できます。

なお、Google Home Analytics ダッシュボードに表示されるグラフのデフォルト ビューは、スマートホームの指標データを使用してプロジェクト用に作成されたビューです。また、Metrics Explorer を使用して、基盤となる同じ指標から独自のグラフを作成し、カスタム ダッシュボードに保存することもできます。

エラーログにアクセスする

ログ エクスプローラは、プロジェクトで生成されたイベントログを操作するためのツールのコレクションです。ログ エクスプローラにアクセスするには、Google Cloud コンソールで [オペレーション] > [ロギング] > [ログ エクスプローラ] に移動します。

ログ エクスプローラを開くと、次のようなビューが表示されます。

ログ エクスプローラ

エクスプローラ ウィンドウには、ログの表示、フィルタ、クエリ、分析を行うためのさまざまなツールが用意されています。デフォルトでは、プロジェクトで利用可能なすべてのシステムから生成されたログ（スマートホームの外部で生成されたログを含む）が表示されます。そのため、デバッグするイベントをフィルタして、これらのログを使用することが重要です。これについてはデバッグのセクションで詳しく説明します。

3. コミッショニングの問題をデバッグする

最初に確認するのは、Matter のコミッショニング イベントに関する指標です。コミッショニングとは、ユーザーが Matter デバイスを初めてセットアップするために必要な一連の手順を指します。

デバイスのコミッショニング中は、Matter デバイス、Google Home アプリ、Matter ファブリック間で一連のやり取りが行われます。次の図は、これらのイベントの一部を示しています。

Matter コミッショニング イベント

それぞれのステップの詳細については、Matter Primer のコミッショニング ページをご覧ください。このセクションでは、コミッショニングの問題をデバッグするためのツールと手法について説明します。

Google Home アナリティクス を使用する

イベントを追跡し、エラーがどの段階で発生するかを把握することで、コミッショニングの問題を調査するための一連の指標を作成しました。これらは、前のセクションで説明したように、Matter 統合ダッシュボードで確認できます。

このダッシュボードのグラフは、デバイスのコミッショニングに関するデータを提供します。

デバイスのコミッショニングの指標

デバイス数のグラフには、特定の日付にユーザーが試したコミッショニングの試行回数が表示されます。成功率は、Google 側でこれらのイベントについて認識された成功率を示します。コミッショニングが試行されるたびに、状態が関連付けられた一連のイベントが生成されます。これらのステータスのいずれかでエラーが発生すると、エラーの内訳グラフにも記録されます。

コミッショニング状態:

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

これらのイベントの詳細バージョンを表示するには、[オペレーション] > [ロギング] > [ログ エクスプローラ] に移動します。コミッション エラーをフィルタするには、クエリ フィールドで「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"
}

エラーログには、コミッショニングの状態とステータス コードに加えて、キャプチャされたエラーのタイムスタンプと、エラーを引き起こしたプロダクトを特定できる Matter プロダクト ID が含まれます。同じコミッショニングの試行で生成された一連のログは sessionId を共有します。

Google ホーム アナリティクスの指標を見ると、どの段階で問題が発生するかがまずわかります。デバイスのコミッショニング エラーの根本原因を見つけるには、場合によっては、コミッショニング プロセスで使用されたモバイル デバイスによって生成されたログを使用して追加のデバッグを行う必要があります。そのためには Android Debug Bridge が必要です。

Android Debug Bridge（ADB）を使用する

コミッショニングに関する問題のトラブルシューティングには、Android Debug Bridge（ADB）コマンドライン ツールを使用するという方法もあります。コミッショニングは主にモバイル デバイスと Matter デバイスの間で処理されるため、ADB ツールを使用して、コミッショニングの間、Google Home アプリで生成されたログにアクセスできます。

プラットフォーム ツールをインストールする

ADB は Android SDK Platform Tools の一部として提供されており、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 開発者サービスに Google Home / Matter コントロール モジュールがあるかどうかを確認するには:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

これらの戻り値が Google のエコシステムでサポートされていることを確認してください。コミッショニングの失敗についてサポートに問い合わせる場合は、常にシステム情報をサポート チケットに含めてください。

エラーログを収集する

次に、ログの収集プロセスを開始し、コミッショニングの手順に従って、デバッグするエラーイベントを生成します。

  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, リビングの電気をつけて」）、または Google Home アプリまたは Google Nest ディスプレイ デバイスの UI を使用して、音声コマンドでコマンドを実行できます。

エンドデバイスと Google Hub の間の制御仕様は Matter によって仲介されるため、デバイス操作側でのエラーが減少することが予想されます。ともかく、Google はこうした問題のデバッグに役立つ指標とログを提供しています。

指標を使用する

Matter 統合ダッシュボードには、デバイス コントロールに関する指標がいくつか表示されます。現場のデバイスのパフォーマンスを評価するには、次の 3 つのグラフが必要です。

成功、レイテンシ、エラーの内訳のグラフ

コントロールの問題では、一般的に成功率に下降傾向が、エラー内訳グラフに上昇傾向が見られます。エラーの内訳のグラフには、デバイス操作が失敗した理由に関して Google Nest Hub でキャプチャされたエラーが表示されます。

ログを使用する

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 が発行する Matter デバイスの無線（OTA）アップデートのリリース状況を追跡するために、Google は、販売中のデバイスのハードウェア バージョンとソフトウェア バージョンを示す一連の指標を提供しています。

コンソールからアップデートを発行したら、次の指標を確認します。

ソフトウェアとハードウェアの故障

リリースの数日後には、OTA ソフトウェア リリースに関連付けられた新しいソフトウェア バージョンを入手できるデバイスがますます増えていきます。

6. サポートを求める

Google は Matter の問題をデバッグするためのツールとドキュメントを提供していますが、Matter エコシステムは新しいため、これらのリソースでカバーされていない問題があります。このような場合は、いつでも Google またはコミュニティに連絡してサポートを受けることができます。

デベロッパー チャンネルを見る

Google では次の 3 つのデベロッパー チャネルが活発にモニタリングされています。

Stack Overflow、Issue Tracker、デベロッパー フォーラム

各チャネルは、同じチームが定期的にモニタリングしていますが、どのチャネルをどのタイミングで使用すべきかに関して重要な違いがいくつかあります。

  • Stack Overflow: 実装に関する質問やガイダンスが必要な場合は、Google およびスマートホーム デベロッパー コミュニティにお問い合わせください。このチャンネルは、問題のトラブルシューティング方法や特定の機能の実装方法について質問する場合に最適です。
  • Issue Tracker: Google が運営する公式の Issue Tracker システムです。外部のユーザーがエコシステムに関するエラーを報告できます。必要に応じて、ファイルを添付したり機密情報を共有したりするためのウェブツールが提供されます。エコシステムに関する問題の報告や機能リクエストの共有には、Issue Tracker の使用をおすすめします。
  • デベロッパー フォーラム: Google Nest デベロッパー フォーラムでは、Google の公式サポートやコミュニティ エキスパートからアドバイスを受けることができます。このフォーラムは、開発に関する公式のガイダンスを得るのに最適です。

デベロッパー ニュースレターに登録

また、デベロッパー チャネルを通じて質問をいただくほかに、新機能や Google スマートホーム エコシステムの現状を伝えるニュースレターを年 4 回発行しています。

デベロッパー ニュースレターを受け取るには、登録フォームをご利用ください。

7. 完了

Google Home

お疲れさまでした。おすすめのツールと手法を使用して Matter 統合をデバッグする方法を学びました。Matter と Google Home との統合をぜひご検討ください。

次のステップ

次の演習を行い、参考情報をご確認ください。

  • アナリティクスを利用して問題のトラブルシューティングを行うほかに、テストスイートを使用して潜在的な問題に対して統合をテストすることもできます。
  • 統合を世界に公開する準備が整ったら、次のステップとして、プロジェクトの Works with Google Home 認定を取得します。認定資格ページの手順に沿って進めることができます。