Matter 統合のデバッグ

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

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

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

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

Google Home Analytics を使用する

コミッショニング イベントを追跡し、エラーが発生する可能性のあるステージを把握することで、コミッショニングの問題が発生した際の調査に役立つ指標のセットを作成しました。これらは、前のセクションで説明したように、Matter 統合ダッシュボードで確認できます。

このダッシュボードのグラフには、デバイスのコミッショニングに関するデータが示されます。

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

コミッショニング ステータス:

• コミッショニング開始
• 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）を使用する

コミッショニングの問題を解決するもう 1 つの方法は、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

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

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

3. この警告メッセージが表示された場合は、[Allow] をクリックします。
4. ターミナルから list devices コマンドを発行して、パソコンが ADB を介して電話にアクセスできるかどうかを確認します。

$ adb devices

レスポンスは次のようになります。

List of devices attached
<phone-id>    device

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

5. <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 開発者サービスを介してホーム / 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 デバイスを使用したコミッショニングの手順に進みます。

2. デバッグするエラーが表示されたら、実行中のターミナル ウィンドウで Control+C を押してロギングを停止します。

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

エラーログを分析する

コミッショニング プロセスは、GHA 内の MatterCommissioner と呼ばれるサブシステムを通じて処理されます。

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

$ grep "MatterCommissioner" <file-name>

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

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

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

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

3. 次のコマンドを使用して、コミッショニング エラー メッセージを検索します。

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

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

Matter デバイスをセットアップして Google Home エコシステムを試してみると、Google アシスタントを使った音声コマンド（「OK 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 のデバイスのコミッショニングと制御に関する問題を処理する方法について学習しました。このエコシステムには、Google が推奨する手法を使用して高品質の統合を実現できる機能もあります。

OTA アップデートの追跡

Google Home が発行する Matter デバイスに対する無線（OTA）アップデートのリリースをトラッキングするために、Google は、屋外に設置されたデバイスのハードウェアとソフトウェアのバージョンを示す一連の指標を提供しています。

コンソールからアップデートを発行したら、次の指標に注意してください。

リリース後の数日間で、OTA ソフトウェア リリースに関連付けられている新しいソフトウェア バージョンが、さらに多くの現場で実際に使用されていることがわかります。

6. サポートのリクエスト

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

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

Google 社内では、次の 3 つのデベロッパー チャンネルを積極的にモニタリングしています。

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

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

デベロッパー向けニュースレターに登録する

デベロッパー チャネルにアクセスして質問するだけでなく、新機能を取り上げた Google スマートホーム エコシステムの最新情報を提供するニュースレターも年に 4 回発行しています。

登録フォームを使用してデベロッパー向けニュースレターを受け取る。

7. 完了

これで完了です。推奨のツールと手法を使用して、Matter の統合をデバッグする方法を学びました。Matter と Google Home の統合は、どうぞご検討ください。

次のステップ

次の演習を試して、その他のリソースをご確認ください。

• アナリティクスを使用して問題のトラブルシューティングを行う以外に、テストスイートを使用して、潜在的な問題に対する統合をテストすることもできます。
• インテグレーションを世界各地と共有する準備が整ったら、次のステップとしてプロジェクトの WWGH 認定を取得しましょう。詳しくは、認定資格のページに記載されている手順をご覧ください。