トラブルシューティング

サンプルアプリ

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 ハブのデバイスログを表示する方法は次のとおりです。

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 が 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

トレイト ID は 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 APIs では、アプリに権限を付与できるユーザー数が 100 人に制限されています。この制限は、Developer Console の登録が完了すると解除されます。

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

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

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