このページは Cloud Translation API によって翻訳されました。

Matter 統合のデバッグ

1. 始める前に

Matter は、シームレスなクロスプラットフォームのデバイスセットアップとコントロールエクスペリエンスをエンドユーザーに提供します。これは主に、複数のエコシステムコンポーネントがバックグラウンドで連携して動作しているためです。このようなシステムのトラブルシューティングは、新しいデベロッパーにとって負担になることがあります。そこで Google は、Google Home を Matter デベロッパーとして簡単に使用できるように、一連のツールと手法を開発しました。

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

コミッショニング、実行、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 アナリティクスのダッシュボード

現在、プロジェクト全体をカバーする一般的なダッシュボードと、特定の統合（クラウド、ローカル、Matter）またはデバイスタイプ（カメラ）のダッシュボードがあります。これらのダッシュボードにデータが表示されるのは、対応するタイプの統合と、リクエストを処理する機能するプロジェクトが存在する場合のみです。

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

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

Google Home ダッシュボードには、プロジェクトに関連付けられたイベントの詳細を示すさまざまなグラフが表示されます。各統合ダッシュボードには、プロジェクトで処理されたリクエストの合計数を示すグラフ、その統合タイプの成功率を示すグラフ、関連するデバイスタイプと特性を示すグラフがいくつか表示されます。また、Matter では、デバイスのセットアップの成功とデバイスへのアップデートのロールアウトを追跡する一連のグラフも利用できます。

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

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

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

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

ログエクスプローラ

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

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

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

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

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

各ステップの詳細については、Matter の概要の設置ページをご覧ください。このセクションでは、構成の問題をデバッグするためのツールと手法について説明します。

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 Home アナリティクスの指標を使用すると、問題が発生している段階を把握できます。デバイスのコミッショニングエラーの根本原因を見つけるには、コミッショニングプロセスでモバイルデバイスが生成したログを使用して、追加のデバッグが必要になることがあります。そのためには、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 を取得する

次のコマンドを使用して ADB サーバーを実行します。

$ adb start-server

ADB サーバーを実行しているパソコンにスマートフォンを接続します。

スマートフォンに USB デバッグに関する警告メッセージが表示され、パソコンがスマートフォンの情報にアクセスすることを許可するかどうかを尋ねられることがあります。

USB デバッグプロンプト

この警告メッセージが表示された場合は、[許可] をクリックしてください。
ターミナルから list devices コマンドを実行し、次のコマンドを使用して、コンピュータが ADB 経由でスマートフォンにアクセスできるかどうかを確認します。

$ adb devices

次のようなレスポンスが返されます。

List of devices attached
<phone-id>    device

<phone-id> は、デバイスを一意に識別する英数字の文字列です。

次のステップで使用する <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"

Google Play 開発者サービス経由で Home / Matter コントロールモジュールがインストールされているかどうかを確認するには:

$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

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

エラーログを収集する

次に、ログ収集プロセスを開始し、構成手順に沿ってデバッグするエラーイベントを生成します。

<phone-id> と、ログを保存するパソコンの <file-name>（例: debug_file.txt）を指定できます。

$ adb -s <phone-id> logcat > <file-name>

これにより、ロギングプロセスが直ちに開始されます。指定した名前のファイルがまだ存在しない場合は作成され、各イベントの後にスマートフォンのログがファイルに追加されます。

Matter デバイスで設定手順を進めます。

デバッグするエラーに到達したら、実行中のターミナルウィンドウで Control+C を押してロギングを停止します。

これで、ログが <file-name> ロギングファイルに保存されるようになります。このプロセスは、デバイスで追跡されているすべての実行中のプロセスからログを記録するため、このファイルには多くのログが含まれます。そのため、必要なエントリを検索して、これらのログを常に活用する必要があります。

エラーログを分析する

コミッショニングプロセスは、GHA 内の MatterCommissioner というサブシステムによって処理されます。

構成エラーの分析に使用される主な戦略に沿って、次のコマンドを使用して MatterCommissioner サブシステムによって生成されたエラーを探します。

$ grep "MatterCommissioner" <file-name>

これにより、コミッショニングプロセスのイベントを含む出力が生成されます。

Matter デバイスが Thread を使用している場合は、次のコマンドを使用して Thread サブシステムによって生成されたエラーを探すこともできます。

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

ADB デバッグプロセスで生成されたログファイルを分析するときに、特定のパターンも探してください。コミッショニングエラーの多くは、エラーメッセージに「commissioning failure」という文字列が含まれています。

次のコマンドを使用して、構成の失敗メッセージを検索します。

$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. デバイスの制御に関する問題をデバッグする

Matter デバイスをセットアップして Google Home エコシステムに組み込むと、Google アシスタントを使って音声コマンド（「OK Google, リビングの照明をつけて」など）や、Google Home アプリの UI や Google Nest ディスプレイデバイスの UI を使ってコマンドを発行できるようになります。

エンドデバイスと Google Hub 間の制御仕様は Matter によって仲介されるため、デバイス制御側のエラーが減少することが期待されます。いずれにしても、この種の問題をデバッグするための指標とログが用意されています。

指標を使用する

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 の公式サポートとコミュニティのエキスパートからアドバイスを得るには、Google Nest デベロッパーフォーラムからお問い合わせください。このフォーラムは、開発に関する公式ガイダンスを入手するのに最適です。

デベロッパーチャンネルで質問を投稿する以外にも、Google では新しい機能のハイライトや Google スマートホームエコシステムの最新情報を掲載したニュースレターを四半期ごとにリリースしています。

デベロッパー向けニュースレターは、登録フォームからご利用いただけます。

7. 完了

Google Home

これで、推奨されるツールと手法を使用して Matter の統合をデバッグする方法について学習しました。Google Home と Matter の統合をぜひご活用ください。

次のステップ

以下の演習や参考情報をお試しください。

アナリティクスを使用して問題のトラブルシューティングを行うだけでなく、テストスイートを使用して、統合に潜在的な問題がないかどうかをテストすることもできます。
統合を公開する準備ができたら、次はプロジェクトの WWGH 認定を取得します。詳しくは、認定ページの手順をご覧ください。