トラブルシューティング

サンプルアプリ

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

Android ログを収集する

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

adb をインストールする

まだ設定していない場合は、ローカルマシンに Android Debug Bridge を設定します。

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

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

ローカルログの取得用に Cast ハブを有効にするには:

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 の List 関数を呼び出すと、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 がディスカバリ候補のトレイトを使用しようとしているが、初期化中にトレイトが登録されていないため、成功しないことを意味します。次に例を示します。

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 をテストできます。

Home API のテストと使用に Google Home Developer Console 登録は必要ありません。ただし、別のインテグレーションで 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.