トラブルシューティング

サンプルアプリ

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

Android のログを収集する

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

adb をインストールする

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

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

モバイル デバイス ID を取得する

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

   adb devices

   List of devices attached
   device-id    device

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

   phoneid=device-id

バージョン情報

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

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

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

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

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

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

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

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

   cat _versions.txt

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

   Container version:     versionName=26.26.34 (190400-945364269)
   Home Module version:             com.google.android.gms.home [v262634001]
   Optional Home Module version:         com.google.android.gms.optional_home [262634025] ...
   Thread Module version:             com.google.android.gms.threadnetwork [v262634001]
   GHA version:     versionName=4.22.28.0
   Android version: 14
   Android API version: 34
   Found enabled features:             Enabled features: appsearch_impl, brella_dynamite, dck_management...

   このファイルは、トラブルシューティングのために必要に応じて Google に提供できます。

詳細なデバッグフラグを有効にする

Android デバイスのデバイスログを収集したり、バグレポートを実行したりする前に、ロガーのバッファサイズを設定し、Google Home と GMS コンポーネントの詳細なデバッグタグを有効にします。

# Clear existing device logs and expand logger buffer size
adb -s $phoneid logcat -b all -c
adb -s $phoneid logcat -G 8M

# Enable displaying seconds on the screen
adb -s $phoneid shell settings put secure clock_seconds 1

# Enable GMS Service ID verbose flags
adb -s $phoneid shell setprop log.tag.gms_svc_id:168 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:304 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:305 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:319 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:336 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:360 VERBOSE

# Enable GHP and Matter log tags
adb -s $phoneid shell setprop log.tag.CameraCommissioningPlugin VERBOSE
adb -s $phoneid shell setprop log.tag.HomeSdk VERBOSE
adb -s $phoneid shell setprop log.tag.HomeClient VERBOSE
adb -s $phoneid shell setprop log.tag.InteractionApiChimeraService VERBOSE
adb -s $phoneid shell setprop log.tag.MatterCommissioner VERBOSE
adb -s $phoneid shell setprop log.tag.SampleApp VERBOSE

スクリプトを使用して Android ログを収集する

デバッグ セッション中に Android デバイスのデバイスログをキャプチャするには:

1. 詳細なデバッグフラグを有効にするの手順に沿って、既存のログを消去し、バッファサイズを拡張して、詳細なロギングタグを設定します。
2. モバイル デバイスで実行されているすべてのアプリケーションを閉じます。
3. テストを開始する前に、既存のログバッファ ノイズを消去します。

   adb -s $phoneid logcat -c

4. ターミナル ウィンドウでログ収集プロセスを開始します。

   adb -s $phoneid logcat | tee android-logs_$(date +%Y%m%d%H%M%S).txt

   このターミナル ウィンドウは開いたままにしておきます。これにより、プロセスが実行されている間、デバイスからログがキャプチャされます。
5. アプリを実行し、問題を再現するために必要なすべてのユーザー インターフェース操作を行います。
6. 完了したら、ターミナルで Ctrl+C キー（Mac の場合は Cmd+C キー）を押して logcat プロセスを停止します。
7. このセッションのログは android-logs_YYYYMMDDmmss.txt に保存されます。android-logs_YYYYMMDDmmss.txt と _versions.txt の両方をバグレポートに添付します。

adb bugreport で Android ログを収集する

システムレベルの問題、クラッシュ ダンプ、低レベルのネットワークや Bluetooth のデバッグなど、詳細な診断情報を共有する必要がある場合は、完全な Android バグレポートをキャプチャします。

• Matter BLE のコミッショニング: BLE に関する Matter のコミッショニングの問題を報告する場合は、問題を再現する前に、開発者向けオプション（[設定] > [開発者向けオプション] > [Bluetooth HCI スヌープログ]）で [Bluetooth HCI スヌープログ] を有効にします。
• テスト前の設定: テストを実行する前に、詳細デバッグフラグを有効にするの手順に沿って、デバイスの詳細デバッグ プロパティを有効にします。
• バグレポートをキャプチャする: テストを実行して問題を再現したら、次のコマンドを実行して、完全なバグレポート アーカイブを生成します。

  adb -s $phoneid bugreport ./android-bugreport_$(date +%Y%m%d%H%M%S).zip

• 高度なデバッグ情報: 生成された android-bugreport_YYYYMMDDmmss.zip ファイルには、システムレベルの包括的な診断データ（完全なシステムダンプ、メモリ統計、バッテリー診断、低レベルのサブシステム トレースなど）が含まれており、デバッグに役立つ高度な情報が提供されます。

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

この方法で 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 の確認とは別に、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.