請注意!我們即將推出新的開發人員預覽版計畫。歡迎在此申請,率先體驗新工具並提供意見回饋。

對 Matter 整合進行偵錯

1. 事前準備

Matter 提供流暢的跨平台裝置設定和使用者體驗,為使用者提供流暢的體驗。這可能是由於多個生態系統元件在背景中共同運作的要素。這類的疑難排解系統往往相當艱鉅,對新開發人員來說並不容易,因此我們開發了一套工具和技術,讓 Matter 開發人員能夠透過 Google Home 輕鬆完成生活大小事。

在本程式碼研究室中會說明 Matter 的三個主要元件。針對這些系統,Google 提供了一組疑難排解分析,適用於開發人員從手機和中樞裝置收集到的資訊:

佣金、執行、OTA 更新

開發人員必須設法在裝置開發週期內解決各種問題,啟動專案後,您需要以匯總方式監控實際裝置上的問題趨勢,並透過軟體更新修正裝置。本程式碼研究室將介紹兩種用途的技巧。

必要條件

  • 完成 Matter 專案和裝置設定作業的「開始使用 Matter」指南
  • 具備可連線至工作站的 Android 手機 (用於 ADB 記錄檔)

課程內容

  • 如何運用智慧型數據分析工具,大規模監控 Matter 問題。
  • 如何存取錯誤記錄並收集資訊,將錯誤分類。
  • 如何存取 Matter 說明文件和支援資源以尋求協助。

2. 查看 Google Home Analytics (分析)

監控效能是成功與 Google Home 生態系統成功整合的關鍵。我們在 Google Cloud Platform 上為智慧型住宅開發人員提供一套監控工具。您可以使用這些工具來評估專案效能。

存取專案指標

  • 如要存取資料,第一步是查看 Google Home 資訊主頁,方法是登入 Google Cloud Console 並前往「作業」>「監控」>「資訊主頁」

您的專案提供許多資訊主頁 (包括其他 GCP 產品),您可以在智慧家庭資訊主頁中找到資訊主頁,以及 Google Home Analytics (分析) 前置字元。

Google Home 數據分析資訊主頁

我們目前提供了一個通用資訊主頁,可涵蓋您的整個專案,以及特定整合項目 (Cloud、Local、Matter) 或裝置類型 (相機) 的資訊主頁。只有在您對應相應類型時,以及可正常運作的專案執行要求時,資訊主頁才會顯示資料。

開啟其中一個資訊主頁後,您會看到如下圖所示:

成功率、延遲時間和裝置類型詳細資料

Google Home 資訊主頁包含多種圖表,其中顯示與您專案相關事件的詳細資料。每個整合資訊主頁都會顯示一張圖表,顯示專案處理的要求總數、顯示整合類型成功率的圖表,以及顯示裝置類型和特性的多項圖表。此外,Matter 也提供一系列圖表,可追蹤佣金提交成功情形,以及裝置更新項目的推出情形。

請注意,Google Home Analytics (分析) 資訊主頁中顯示的圖表預設檢視畫面,就是使用智慧住宅指標資料所建立的專案資料檢視。您也可以使用 Metrics Explorer,根據相同的基礎指標建立自己的圖表,並儲存至自訂資訊主頁。

存取錯誤記錄檔

「記錄檔探索工具」是一組工具,用於處理針對專案產生的事件記錄檔。在 Google Cloud Console 中依序前往「作業」>「記錄」>「記錄檔探索工具」,即可找到這項工具。

開啟「記錄檔探索工具」後,您會看到像這樣的檢視畫面:

記錄檔探索工具

Explorer 視窗會顯示多項工具,方便您查看、篩選、查詢及分析記錄檔。根據預設,這個檢視畫面會顯示專案可用的所有系統產生的記錄檔,包括在 Smart Home 以外產生的記錄檔。因此,如要篩選這類記錄,您必須篩選要偵錯的事件。我們會在「偵錯」一節中詳細說明。

3. 偵錯佣金問題

首先,我們要探討 Matter 佣金事件。「佣金」是指使用者首次設定 Matter 裝置所需的步驟組合。

在裝置佣金計算過程中,系統會在 Matter 裝置、Google Home 應用程式和 Matter 織布之間進行一組互動。下圖說明其中幾個事件:

Matter 佣金事件

您可以參閱 Matter Primer 的佣金頁面,進一步瞭解每個步驟。在本節中,我們將介紹用來排解佣金問題的工具和技術。

使用 Google Home 數據分析

我們建立了一組指標,方便您追蹤事件並瞭解可能發生的階段,藉此調查佣金問題。您可在上一節的 Matter 整合資訊主頁中找到這些 ID。

這個資訊主頁中的圖表會提供裝置委託資料:

裝置佣金指標

裝置數量圖表會顯示指定日期的使用者佣金嘗試次數。成功率會顯示 Google 端為這類事件認定到的成功率。每個佣金嘗試都會產生一組含有相關狀態的事件。處於任一狀態發生錯誤時,系統也會在錯誤細目圖表中擷取該錯誤。

委託委員會:

  • 開始宣傳
  • 新手上路
  • LOCAL_DISCOVERY_SUCCESSFUL
  • PAPA_CONNECTION_SUCCESSFUL
  • NOC_ADDED_SUCCESSFULLY
  • 通訊內容完成

如要查看這些事件的詳細版本,請前往「作業」>「記錄」>「記錄檔探索工具」。如要篩選佣金錯誤,請在查詢欄位中搜尋「clientUpdateLog」以及「severity>=ERROR」。

Matter 的佣金錯誤記錄如下所示:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "clientUpdateLog": {
      "MatterUpdate": {
        "reportedProductId": 55,
        "sessionId": "1584879052892229997",
        "reportedVendorId": 4800,
        "commissioningState": "GENERIC_COMMISSIONING_ERROR",
        "status": "GENERIC_ERROR"
      }
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T07:09:55.216425297Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}

除了佣金狀態和狀態碼外,錯誤記錄也會顯示已擷取錯誤的時間戳記,以及可用來找出產生錯誤的產品的 Matter 產品 ID。相同佣金嘗試產生的記錄集會共用 sessionId

使用 Google Home Analytics (分析) 的指標可讓您初步瞭解問題出在哪個階段。為了找出裝置佣金錯誤的根本原因,您可能需要使用佣金程序內行動裝置產生的記錄進行額外的偵錯。您必須使用 Android Debug Bridge。

使用 Android Debug Bridge (ADB)

另一種排解佣金問題時,您也可以使用 Android Debug Bridge (ADB) 指令列工具。由於佣金是主要在行動裝置和 Matter 裝置之間進行處理,因此使用 ADB 工具時,您可以執行 Google Home 應用程式在整個佣金期間產生的記錄檔。

安裝平台工具

ADB 是 Android SDK Platform Tools 的一部分,您可以透過 Android Studiosdkmanager 指令列工具安裝。

在系統上成功安裝平台工具後,請使用下列指令檢查終端機的版本號碼,藉此驗證 ADB:

$ adb -- version

畫面上應該會顯示已安裝 ADB 公用程式的版本號碼,且沒有任何錯誤。

啟用 USB 偵錯功能

接著,在 Android 裝置上啟用 USB 偵錯功能。

請先按照裝置上的步驟啟用開發人員選項,再啟用 USB 偵錯功能

這可讓 ADB 存取裝置上正在執行的應用程式產生的記錄檔。

擷取裝置 ID

  1. 使用下列指令執行 ADB 伺服器:
$ adb start-server
  1. 將手機連接至執行 ADB 伺服器的電腦。

您的手機可能會收到 USB 偵錯警告訊息,詢問您是否允許電腦存取手機資訊:

USB 偵錯提示

  1. 如果看到這則錯誤訊息,請按一下「允許」
  2. 從終端機發出清單裝置指令,確認您的電腦是否可以透過 ADB 存取手機:
$ adb devices

畫面會顯示類似以下的回應:

List of devices attached
<phone-id>    device

<phone-id> 是一組英數字元,用來識別裝置。

  1. 請記得將 <phone-id> 值用於後續步驟。

收集系統資訊

接著,請查看應用程式的版本資訊和裝置上的系統。

  • 如何查看 Android 作業系統版本:
$ adb -s <phone-id> shell getprop ro.build.version.release
  • 如何查看 Google Home 應用程式版本:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
  • 如何查看 Google Play 服務版本:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
  • 如何透過 Play 服務檢查您是否擁有「住家 / 案件」控制項模組:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

請確保我們的生態系統支援這些傳回值。無法取得佣金問題的相關協助時,一律會在支援單中加入系統資訊。

收集錯誤記錄檔

接下來,請啟動記錄收集程序,然後按照佣金步驟產生您要偵錯的錯誤事件。

  1. 提供 <phone-id><file-name>,儲存在電腦上的記錄檔 (例如debug_file.txt)。
$ adb -s <phone-id> logcat > <file-name>

系統會隨即開始記錄程序。如果檔案不存在,系統會建立指定名稱的檔案,並在每個事件結束後從手機新增記錄檔。

開始透過 Matter 裝置執行佣金步驟。

  1. 進入要偵錯的錯誤後,請在執行中的終端機視窗中按下 Control+C 來停止記錄。

您的記錄檔現在應該儲存在 <file-name> 記錄檔案中。由於這項程序會記錄裝置所追蹤的所有執行程序,因此這個檔案中有許多記錄檔。因此,建議您一律透過搜尋所需項目來尋找這類記錄。

分析錯誤記錄檔

佣金程序會透過名為 MatterCommissioner 的子系統在 GHA 中進行處理。

  1. 分析分析錯誤的主要策略後,請執行以下指令,找出 MatterCommissioner 子系統產生的錯誤:
$ grep "MatterCommissioner" <file-name>

這會產生包含佣金程序事件的輸出內容。

  1. 如果您的 Matter 裝置使用 Thread,您也可以透過下列指令查詢 Thread 子系統產生的錯誤:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

在分析 ADB 偵錯程序產生的記錄檔時,請一併尋找特定模式。許多錯誤訊息中都含有「commissioning failure」字串,

  1. 使用下列指令搜尋佣金失敗訊息:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. 偵錯裝置控制問題

使用者設定 Matter 裝置並列入 Google Home 生態系統後,即可使用 Google 助理下達語音指令 (例如「Ok Google,打開客廳的燈」),或使用 Google Home 應用程式或 Google Nest 顯示裝置上的 UI。

由於 Matter 的裝置和 Google Nest Hub 皆設有控管規格,因此裝置控管方面應顯示較少錯誤。儘管如此,我們還是提供相關指標和記錄檔,方便您對這些類型的問題進行偵錯。

使用指標

在 Matter 整合資訊主頁中,您會看到多個與裝置控制項相關的指標。評估裝置效能時,分為三個圖表:

成功、延遲時間和錯誤細目圖表

進行控管時,您通常會看到成功百分比的下降趨勢,以及錯誤細目圖的升幅。錯誤詳細資料圖表會顯示 Google Nest Hub 擷取的錯誤,以及裝置控制失敗的原因。

使用記錄檔

每個 Matter 裝置控制問題都會在系統中產生錯誤記錄。您可在記錄檔探索工具中搜尋「executionLog」篩選這些錯誤。

Matter 裝置控制錯誤記錄如下所示:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "executionLog": {
      "executionResults": [
        {
          "executionType": "MATTER",
          "latencyMsec": "6000",
          "actionResults": [
            {
              "action": {
                "actionType": "ONOFF_OFF",
                "trait": "TRAIT_ON_OFF"
              },
              "status": {
                "externalDebugString": "No message was received before the deadline.",
                "statusType": "RESPONSE_TIMEOUT",
                "fallbackToCloud": false,
                "isSuccess": false
              },
              "device": {
                "deviceType": "OUTLET"
              }
            }
          ],
          "requestId": "1487232799486580805"
        }
      ]
    },
    "locale": "en-US"
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T15:47:27.311673018Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}

每個錯誤記錄都包含時間戳記、裝置類型和特性,以及 statusType 中的控制要求相關錯誤。許多控制錯誤也包含 externalDebugString,這個錯誤訊息會說明錯誤發生原因。

5. 對其他功能進行偵錯

到目前為止,您已瞭解如何處理裝置佣金和控制 Matter 的問題。您也可以運用我們推薦的技巧,確保品質良好整合。

追蹤 OTA 更新

為追蹤 Google Home 核發的 Matter 裝置所發布的無線更新 (OTA) 版本,我們針對一組裝置提供一組指標,當中會顯示裝置的硬體和軟體版本。

透過控制台發出更新後,請留意下列指標:

軟體與硬體細目

您會發現在推出幾天後,欄位內的裝置數量越來越多,與 OTA 軟體相關。

6. 尋求支援

Google 提供工具與說明文件,協助您對 Matter 問題進行偵錯,但由於 Matter 是全新的技術,因此不會包含這些資源的問題。在這種情況下,你隨時可以與我們聯絡,或洽詢社群尋求支援。

前往開發人員頻道

Google 會主動監控三個開發人員頻道:

Stack Overflow、Issue Tracker、開發人員論壇

雖然這些管道都會由同一個團隊定期監控,但兩者之間有一些重要差異。

  • Stack Overflow:您可以向我們和智慧型住宅開發人員社群提出導入問題或尋求指引。這個版本最適合詢問如何排解問題或實作特定功能
  • Issue Tracker:這是 Google 官方提供的 Issue Tracker 系統,外部目標對象可回報生態系統中的錯誤。Chrome 提供網站工具,方便您附加檔案及分享機密資訊。如要回報生態系統問題或分享功能要求,使用 Issue Tracker。
  • 開發人員論壇:如要向 Google 官方支援團隊和社群專家尋求協助,請前往 Nest 開發人員論壇。這個論壇最適合用於取得官方開發指南

訂閱開發人員電子報

除了在開發人員管道上查詢問題外,我們也每季都會發布電子報,提供各項新功能並介紹 Google 智慧型住宅生態系統的狀態。

您可以使用申請表單接收開發人員電子報。

7. 恭喜

Google Home

恭喜!您已經瞭解如何根據我們建議的工具和技術對 Matter 整合作業進行偵錯。我們希望你能準備整合 Matter 與 Google Home。

後續步驟

請嘗試下列練習並探索其他資源:

  • 除了使用數據分析來解決問題,您也可以使用測試套件測試整合作業是否有任何問題。
  • 整合作業可與全世界分享後,下一步就是取得專案 WWGH 認證。您可以按照「認證」頁面中的步驟操作。