疑難排解

範例應用程式

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

收集 Android 日誌

在涉及 adb 的所有步驟中，行動裝置都必須連線至本機。

安裝 adb

如果您尚未在本機電腦上設定 Android 偵錯橋 (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 即可停止指令碼。

指令碼會產生含有所有相關資訊的記錄檔 (附有時間戳記)。如果遇到錯誤，請將這些檔案附加到錯誤報告。

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。

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

請注意下列事項：

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

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

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

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