2026 年より、すべての Matter の統合とテストで Alliance Interop Test が必要になります。詳しくは、Allliance Interop Test Lab の移行ページをご覧ください。

Matter 統合のデバッグ

1. 始める前に

Matter は、エンドユーザーにシームレスなクロスプラットフォームのデバイス設定と制御のエクスペリエンスを提供します。これは主に、バックグラウンドで連携して動作する複数のエコシステムコンポーネントによって実現されています。このようなシステムのトラブルシューティングは、新しいデベロッパーにとって難しいことが多いため、Google Home で Matter デベロッパーとして作業しやすくするためのツールと手法を開発しました。

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

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

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

前提条件

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

学習内容

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

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

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

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

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

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

Google Home Analytics ダッシュボード

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

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

成功率、レイテンシ、デバイスの種類の内訳

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

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

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

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

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

ログエクスプローラ

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

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

これらのイベントの詳細なバージョンを表示するには、[オペレーション] > [ロギング] > [ログエクスプローラ] に移動します。コミッショニングエラーをフィルタするには、クエリフィールドで「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 Analytics の指標を使用すると、問題が発生する可能性のある段階を把握できます。デバイスのコミッショニングエラーの根本原因を特定するには、コミッショニングプロセスで使用されたモバイルデバイスで生成されたログを使用して、追加のデバッグが必要になることがあります。これらの操作には、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 デバッグのプロンプト

この警告メッセージが表示されたら、[許可] をクリックします。
ターミナルからデバイスリストコマンドを発行して、次のコマンドを使用して、パソコンが 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 開発者サービスでスマートホーム / Matter 制御モジュールがインストールされているかどうかを確認するには:

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

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

エラーログを収集する

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

次のコマンドを実行します。<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 アプリや 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）アップデートのリリースを追跡するために、フィールド内のデバイスのハードウェアバージョンとソフトウェアバージョンを示す一連の指標を提供しています。

コンソールから更新を発行したら、次の指標を監視します。

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

リリース後、フィールド内のデバイスで OTA ソフトウェアリリースに関連付けられた新しいソフトウェアバージョンが取得されるようになります。

6. サポートを求める

Google は Matter の問題をデバッグするためのツールとドキュメントを提供していますが、Matter エコシステムは新しいものであるため、これらのリソースで対応できない問題も発生します。このような場合は、いつでも Google またはコミュニティにお問い合わせください。

デベロッパーチャンネルにアクセスする

Google 内でアクティブにモニタリングされているデベロッパーチャネルは 3 つあります。

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

これらのチャネルはすべて同じチームによって定期的にモニタリングされますが、どのチャネルをいつ使用するかについては、いくつかの重要な違いがあります。

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

質問についてはデベロッパーチャンネルをご利用いただくほか、四半期ごとにニュースレターをリリースして、新機能や Google スマートホームエコシステムの最新情報をお届けしています。

デベロッパーニュースレターは、登録フォームからお申し込みいただけます。

7. 完了

Google Home

おめでとうございます！推奨するツールと手法を使用して Matter 統合をデバッグする方法を学習しました。Google Home との Matter 統合を構築する際に、このガイドがお役に立てば幸いです。

次のステップ

以下の演習に挑戦し、追加リソースを参照してみましょう。

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

Matter 統合のデバッグ コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。