疑難排解

範例應用程式

如果使用 Google Home API 時遇到任何問題，可以收集記錄以進行進一步偵錯。如要從行動裝置收集記錄，必須使用 Android Debug Bridge (adb)。如果需要 Google 協助，請從 Android 裝置和中樞裝置收集記錄，並在問題追蹤器中開啟支援單，附上相關資訊和記錄。

收集 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 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 錯誤報告收集 Android 記錄

如要分享涵蓋系統層級問題、當機傾印或低層級網路和藍牙偵錯的詳細診斷資訊，請擷取完整的 Android 錯誤報告：

  • Matter BLE 委派：回報有關 BLE 的 Matter 委派問題時，請先在「開發人員選項」中啟用「藍牙 HCI 窺探記錄」(依序前往「設定」 >「開發人員選項」 >「啟用藍牙 HCI 窺探記錄」)，再重現問題。
  • 測試前設定：執行測試前，請按照「啟用詳細偵錯標記」一節中的步驟，在裝置上啟用詳細偵錯屬性。
  • 擷取錯誤報告：執行測試並重現問題後，請執行下列指令，產生完整的錯誤報告封存檔： 
    adb -s $phoneid bugreport ./android-bugreport_$(date +%Y%m%d%H%M%S).zip
  • 進階偵錯資訊：產生的 android-bugreport_YYYYMMDDmmss.zip 檔案包含完整的系統層級診斷資料，包括完整系統傾印、記憶體統計資料、電池診斷和低階子系統追蹤記錄，可提供更進階的偵錯資訊。

Cast 中樞裝置記錄

你可以使用這個方法查看 Google Nest Hub 的裝置記錄，支援的機型如下：

  • Google Home
  • Google Nest Audio
  • Google Nest Hub
  • Google Nest Mini

如要啟用 Cast 中樞裝置，以便擷取本機記錄，請按照下列步驟操作：

  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。

如要測試及使用 Home API，不需要進行 Google Home Developer Console 註冊。 不過，即使您有來自其他整合服務的已驗證 OAuth 用戶端，仍須通過Developer Console核准才能發布應用程式。

注意事項如下：

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

  • Developer Console 註冊 準備透過 OAuth 限制裝置類型授權，並更新應用程式以使用 Home API 時，應送交註冊以供核准。

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

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