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

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 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 アナリティクスを使用する

Google では、イベントを追跡してエラーが発生する可能性があるステージを把握することで、試運転に関する問題を調査するための一連の指標を作成しました。これらは、前のセクションで説明したように、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 Product 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"

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 ハブの間の制御仕様は 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 に関するデバイスのコミッショニングと操作に関する問題を処理する方法について学習しました。このエコシステムには他にも、質の高い統合を実現するために Google が推奨する手法を使用できる機能があります。

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 スマートホームエコシステムの現状に関するニュースを四半期ごとに発行するニュースレターも発行しています。

デベロッパーニュースレターを受け取るには、登録フォームを使用します。

7. 完了

Google Home

これで、おすすめのツールと手法を使用して Matter の統合をデバッグする方法を学びました。Matter と Google Home の統合がうまくいくことを願っています。

次のステップ

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

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