トラブルシューティング

サンプルアプリ

Home API の使用中に問題が発生した場合は、ログを収集してさらにデバッグできます。モバイル デバイスからログを収集するには、Android Debug Bridge（adb）が必要です。Google のサポートが必要な場合は、Android デバイスとハブの両方からログを収集し、関連情報とログを添付して問題トラッカーでチケットを開いてください。

Android ログを収集する

`adb` を使用するすべての手順で、モバイル デバイスをローカルマシンに接続する必要があります。 adb

adb をインストールする

まだインストールしていない場合は、ローカルマシンに Android Debug Bridge をセットアップします。

1. パソコンに「adb」をインストールします 。
2. Android スマートフォンで開発者向けオプションと USB デバッグ を有効にします。Android

Android Studio 用 Google Home プラグイン

Google Home Plugin for Android Studio は、ログの収集と分析に役立つツールで、Google Home platform デベロッパー向けに作成されました。この 拡張機能を使用すると、Google Assistant Simulatorや Cloud Logging といった ツールにアクセスし、smart homeの開発プロセスを簡素化できます。

このツールを adb と組み合わせて使用すると、 Matter デバイスのログをさらに分析できます。

詳細とツールの入手方法については、 Google Home Plugin for Android Studioをご覧ください。

バージョン情報

ログを収集する場合は、セットアップに関連するすべてのバージョン情報を収集することをおすすめします。Google と問題を共有する必要がある場合は、これが必要です。

1. モバイル デバイスの ID を取得します。

   adb devices

   List of devices attached
   device-id    device

2. この値を phoneid という変数に保存します。

   phoneid=device-id

3. さまざまなデバイス情報を変数に保存します。

   containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep "versionName" || true);
   homemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home " || true);
   optionalhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.optional_home " || true);
   policyhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.policy_home" || true);
   threadinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork" || true);
   ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep versionName || true);
   enabledfeatures=$((adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "Enabled features" | grep -i "home") || true);
   androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true);
   androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true)

4. すべての変数を _versions.txt というファイルに保存します。

   開いて、変数をファイルに保存するコマンドを表示する

   ブロック全体をコピーして、ターミナルに一度に貼り付けることができます。

   versionfile=$logtimestamp"_versions.txt"
   echo "Saving version info to $versionfile"
   
   echo "Container version:" >> $versionfile
   echo $containerinfo >> $versionfile
   echo "" >> $versionfile
   
   echo "Home Module version:" >> $versionfile
   echo $homemoduleinfo >> $versionfile
   echo "" >> $versionfile
   
   echo "Optional Home Module version:" >> $versionfile
   echo $optionalhomemoduleinfo >> $versionfile
   echo "" >> $versionfile
   
   echo "Policy Home Module version:" >> $versionfile
   echo $policyhomemoduleinfo >> $versionfile
   echo "" >> $versionfile
   
   echo "Thread Module version:" >> $versionfile
   echo $threadinfo >> $versionfile
   echo "" >> $versionfile
   
   echo "GHA version:" >> $versionfile
   echo $ghainfo >> $versionfile
   echo "" >> $versionfile
   
   echo "Android version: " >> $versionfile
   echo $androidversion >> $versionfile
   echo "" >> $versionfile
   
   echo "Android API version: " >> $versionfile
   echo $androidapiversion >> $versionfile
   echo "" >> $versionfile
   
   echo "Found enabled features (blank if missing):" >> $versionfile
   echo $enabledfeatures >> $versionfile
   echo "" >> $versionfile

5. _versions.txt の内容を確認します。

   cat _versions.txt

   開いて、サンプル ファイルの出力を表示する

   Container version:
   versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)
   
   Home Module version:
   com.google.android.gms.home [v230508900]
   
   Optional Home Module version:
   
   
   Policy Home Module version:
   com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]
   
   Thread Module version:
   com.google.android.gms.threadnetwork [v231912000]
   
   GHA version:
   versionName=3.2.32.1
   
   Android version:
   13
   
   Android API version:
   33
   
   Found enabled features (blank if missing):

   このファイルは、トラブルシューティングが必要な場合に Google に提供できます。

ログを収集する

ログを収集するには、モバイル デバイスで実行されているすべてのアプリを閉じます。以下の手順を行います。

1. ターミナル ウィンドウを開き、既存のデバイスログをクリアします。

   adb logcat -b all -c

2. ログ収集プロセスを開始します。

   adb logcat >> _logs.txt

   このターミナルは開いたままにしておきます。プロセスが実行されている限り、デバイスからログが収集されます。
3. サンプルアプリを実行し、すべてのユーザー インターフェース アクションをキャプチャします。完了したら、Ctrl+C （Mac の場合は Cmd+C ）を押して、ターミナルで実行されている logcat プロセスを停止します。
4. このセッションのログは、_logs.txt というファイルに保存されます。

このファイルの情報は、error、exception、crash などのキーワードを検索するなど、さまざまな方法で分析できます。

ログスクリプト

便宜上、サンプルアプリには、関連するログを取得してテキスト ファイルにコンパイルするスクリプトが用意されています。デバッグを最適に行うため、これらのログは、Google による根本原因分析を容易にするために、報告されたバグに添付する必要があります。

これらのログは、サンプルアプリのソースツリーの scripts ディレクトリにあります。 プロジェクトのルート ディレクトリから次の手順を実行します。

1. モバイル デバイスの ID を取得します。

   adb devices -l

   List of devices attached
   device-id device

2. get_logs.sh スクリプトを実行します。

    ./scripts/get_logs.sh device-id

   Cleared previous logs from device.
   Saving version information to home_api_sample_logs_20240605233243.txt...
   Saving logs to home_api_sample_logs_20240605233243.txt...
   (Press CTRL+C to stop the script)

3. 問題を再現します。
4. CTRL+C を押してスクリプトを停止します。

スクリプトは、関連するすべての情報を含むタイムスタンプ付きのログファイルを生成します。発生したバグのレポートに添付してください。

キャスト ハブ デバイスのログ

この方法を使用すると、Google Nest Hub のデバイスログを表示できます。この方法は、次のモデルでサポートされています。

• Google Home
• Google Nest Audio
• Google Nest Hub
• Google Nest Mini

ローカルログの取得用にキャスト ハブを有効にするには:

1. Android Debug Bridge をセットアップします。

2. ハブの IP アドレスを取得します。

   • 画面付きのハブから:
     1. 画面を上から下にスワイプします。
     2. 設定アイコン settings をタップします。
     3. デバイスの IP アドレスを確認します。Nest Hub (2nd gen) の場合は、 [デバイス情報] > [技術情報] > [IP アドレス] に移動します。
   • スマートフォンの GHA から:
     1. デバイスをタップして、デバイスの詳細ページを開きます。
     2. 設定アイコン settings をタップして、設定ページを開きます。
     3. デバイスの IP アドレスを確認します。[デバイス情報] > [技術情報] > [IP アドレス] に移動します。

3. デバイスと同じ Wi-Fi ネットワーク上のパソコンで:

     adb connect ip-address
     adb logcat
   

4. ログを他のユーザーに提供するには、失敗しているオペレーションを実行し、出力をテキスト ファイルにパイプします。

     adb logcat -d > platform-logs.txt
   

自動化

エッジ検出

Google Home エコシステムの自動化には、エッジ検出というロジックが搭載されています。これは、開始条件がデバイスの以前の状態を繰り返すだけの状態更新ではなく、実際の 状態変化があった場合にのみ有効になることを確認するロジックです。

たとえば、照明をオンにすることが開始条件の場合、エッジ検出では、照明デバイスがオフからオンに変わった場合にのみ開始条件が有効になり、オンからオンに変わった場合（変化なし）は有効にならないことを確認します。

自動化が想定どおりに動作しない

エッジ検出を考慮しても、自動化が想定どおりに動作しない場合は、次のことを確認してください。

1. 各デバイスが自動化とは関係なく正常に機能していることを確認します。

2. 自動化の自動化グラフを確認し、自動化 DSL と比較して、誤った想定がないか確認します。

3. 自動化の実行中に Google Home アプリでデバイスの状態を確認します。

4. 自動化で参照されているすべてのデバイスが、想定される構造に存在していることを確認します。自動化が依存しているデバイスを削除すると、意図しない結果が生じる可能性があります。デバイスの削除が自動化に与える影響をご覧ください。

自動化が実行されるべきでないときに実行される

自動化が実行されるべきでないときに実行される場合は、開始条件を確認します。 状態の変化が 1 回だけキャプチャされ、自動化が 1 回だけトリガーされるように、追加のロジックが必要になることがあります。

自動化がコンパイルされない

アプリに、さまざまなノードタイプに対応する各クラスや参照している特性など、必要なインポートがすべて含まれていることを確認してください。

自動化の作成が検証に失敗する

自動化の作成が検証に合格しない場合は、警告またはエラー メッセージで問題に関する情報が提供されます。詳細については、 ValidationIssueType リファレンスをご覧ください。

リスト関数が例外をスローする

Automation API のリスト関数を呼び出すと、API 機能が不足しているため、読み取りハンドラが例外をスローすることがあります。この問題を軽減するには、影響を受ける自動化を削除します。

手順は次のとおりです。

1. adb がインストールされていることを確認します。 adb をインストールするをご覧ください。

2. 次のコマンドを呼び出して、Android ログから自動化の ID を取得します。

   adb logcat -s GhpNative

   ログの例:

   adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse
   
   INTERACTION RESPONSE -> SendCommandsResponse:
   1 {
   1: "automation@global"
   3 {
     1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
     2:
     5 {
       1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
       1 {
           1: "1111-2222-3333-44444-55555" // Automation ID to delete
           2: "structure@2222-3333-4444-5555-6666"
   ...

   複数の自動化 ID を削除する必要がある場合は、ターミナル ページャを使用して出力を制御できます。

   adb logcat -s GhpNative level:debug | less

3. 自動化の ID を使用して自動化を削除します。

   structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))
   

特性が登録解除されると、Discovery API が警告を記録する

Discovery API が Trait not found の警告を記録している場合、API は Discovery 候補に特性を使用しようとしていますが、初期化時に特性が登録されていないため、成功しません。次に例を示します。

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

特性識別子は home.matter.6006.clusters.fc43 で、RelativeHumidityControl に対応します。ID から特性名を判断するには、 特性インデックスをご覧ください。

この例では、アプリの初期化時に RelativeHumidityControl を登録する必要があります。特性を登録して、特性をレジストリに追加するをご覧ください。

OAuth

既存の OAuth クライアントがある場合

公開済みアプリの検証済み OAuth クライアントがすでにある場合は、既存の OAuth クライアントを使用して Home API をテストできます。

Google Home Developer Console のテストと使用に Home API の登録は必要ありません。 ただし、他の統合から 検証済みの OAuth クライアントがある場合でも、アプリを公開するには、承認済みの Developer Console登録が必要です。

次のことに注意してください。

• 既存の OAuth クライアントを使用する場合、ユーザー数の上限は 100 人です。テストユーザーの追加については、 OAuth 同意画面をセットアップします。 OAuth 検証とは別に、Home API では、アプリケーションに権限を付与できるユーザー数が 100 人に制限されています。 この制限は、 登録が完了すると解除されます。Developer Console

• Developer Console 登録 は、Home API でアプリを更新する準備として、OAuth を介してデバイスタイプの付与を制限する準備ができたら、承認のために送信する必要があります。

OAuth 検証が保留中の Google Cloud アプリの場合、 検証が完了するまで OAuth フローを完了できません。権限を付与しようとすると、次のエラーが発生します。

Access blocked: <Project Name> has not completed the Google verification process.