トラブルシューティング

サンプルアプリ

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

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. サンプル アプリを実行し、すべてのユーザー インターフェイス アクションをキャプチャします。終わったら、logcat端末上で実行中のプロセスは、 Ctrl+C （またはコマンド+C (Mac の場合)
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 が 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 をテストできます。

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

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

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

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

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

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