疑難排解

範例應用程式

如果您在使用 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. 執行範例應用程式，並擷取所有使用者介面動作。完成後，請按下 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. 輕觸「設定」圖示
      3. 找出裝置 IP 位址：在 Nest Hub (2nd gen) 上依序前往「裝置資訊」>「技術資訊」>「IP 位址」
    • 在手機的 GHA 中：
      1. 輕觸裝置，開啟裝置詳細資料頁面
      2. 輕觸「設定」圖示 ，即可開啟設定頁面
      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. 請確認自動化動作參照的所有裝置都位於預期的結構中。刪除自動動作所依賴的裝置可能會造成意想不到的後果。請參閱刪除裝置對自動化動作的影響。

自動化動作在不適當的情況下執行

如果自動化動作在不適當的時間執行，請檢查啟動條件。您可能需要新增額外的邏輯，確保系統只擷取一次狀態變更，並只觸發一次自動化動作。

自動化功能無法編譯

請確認應用程式包含所有必要的匯入項目，包括與不同節點類型相對應的每個類別，以及您要參照的特徵。

建立自動化動作時驗證失敗

如果自動化動作建立作業未通過驗證，系統會顯示警告或錯誤訊息，提供相關問題的相關資訊。詳情請參閱 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。

Google Home Developer Console 註冊不必使用 Home API 進行測試。不過，即使您已透過其他整合服務取得已驗證的 OAuth 用戶端，仍需要經過核准的 Developer Console 註冊才能發布應用程式。

請考量以下因素：

  • 使用現有 OAuth 用戶端時，使用者人數上限為 100 位。如要瞭解如何新增測試使用者，請參閱「設定 OAuth 同意畫面」。除了 OAuth 驗證外，Google Home API 還會限制最多 100 位使用者可授予應用程式權限。完成 Developer Console 註冊後，這項限制就會解除。

  • Developer Console註冊 ：當您準備好透過 OAuth 限制裝置類型授權，以便使用 Google Home API 更新應用程式時，請將註冊資訊送交審查。

如果 Google Cloud 應用程式仍在等待 OAuth 驗證，使用者必須等到驗證完成後，才能完成 OAuth 流程。授予權限的嘗試會失敗，並顯示以下錯誤：

Access blocked: <Project Name> has not completed the Google verification process.
上一頁
錯誤處理
下一頁
Commissioning API