對 Matter 整合作業進行偵錯

1. 事前準備

Matter 為使用者提供流暢的跨平台裝置設定和操控體驗。這主要是取決於多個生態系統元件在幕後搭配運作。這類疑難排解系統對新手開發人員來說往往會相當困難,因此開發了一系列的工具和技術,希望身為支援 Matter 的 Matter 開發人員,你的生活更加便利。

本程式碼研究室涵蓋三個主要的 Matter 元件。針對下列各個系統,Google 為從手機和中樞裝置的開發人員提供了一系列疑難排解分析服務:

執行調試、執行、OTA 更新

對開發人員而言,在裝置開發週期期間,您必須設法減少遇到的問題,因此非常重要。啟動專案後,您需要匯總在現場監控裝置的問題趨勢,並透過軟體更新修正相關問題。本程式碼研究室將介紹這兩種用途的技巧。

必要條件

  • 完成「開始使用 Matter」指南,瞭解能正常運作的 Matter 專案和裝置設定
  • 備妥可連接至工作站的 Android 手機 (針對 ADB 記錄檔)

課程內容

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

2. 查看 Google Home 數據分析

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

存取專案指標

  • 如要存取 Google Home 資訊主頁,請先登入 Google Cloud 控制台,然後依序前往「作業」>「監控」>「資訊主頁」

您的專案有數種可用的資訊主頁 (包括其他 GCP 產品)。智慧型住宅提供的資訊主頁會有「Google Home Analytics (分析)」前置字串。

Google Home 數據分析資訊主頁

我們目前有一個涵蓋整個專案的一般資訊主頁,以及特定整合 (雲端、本機、Matter) 或裝置類型 (攝影機) 的資訊主頁。只有在您整合了對應類型,以及可執行要求的專案時,這些資訊主頁才會包含資料。

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

成功率、延遲時間和裝置類型細目

Google Home 資訊主頁包含各種圖表,可顯示專案相關事件的詳細資料。每個整合資訊主頁中,都會有一張圖表顯示專案處理的要求總數、顯示該整合類型的成功率圖表,以及數個圖表,顯示相關裝置類型和特徵。此外,Matter 還提供一組圖表來追蹤佣金成功與裝置上的更新推出情況。

請注意,Google Home 數據分析資訊主頁的預設檢視畫面,只是我們使用智慧型住宅指標資料為專案建立的資料檢視。您也可以使用 Metrics Explorer 根據相同的基礎指標自行建立圖表,並儲存至自訂資訊主頁。

存取錯誤記錄檔

記錄檔探索工具是一組工具,可用於處理專案上產生的事件記錄檔。如要查看這項功能,請前往 Google Cloud 控制台,然後依序點選「作業」>「記錄」>「記錄檔探索工具」

開啟記錄檔探索工具後,您會看到如下所示的檢視畫面:

記錄檔探索工具

「 Explorer」視窗包含各種工具,讓您查看、篩選、查詢及分析記錄檔。根據預設,這個檢視畫面會顯示專案所有可用系統產生的記錄,包括智慧型住宅以外產生的記錄。因此,只要篩選要偵錯的事件,才能使用這些記錄。我們會在「偵錯」部分中詳細說明。

3. 偵錯調試問題

我們將介紹的第一種指標與 Matter 調試事件。調試是指使用者首次設定 Matter 裝置所需的一系列步驟。

在裝置委任期間,Matter 裝置、Google Home 應用程式和 Matter 織布之間會進行一組互動。下圖說明其中部分事件:

Matter 調試事件

您可以查看 Matter Primer 的參與流程頁面,進一步瞭解每個步驟。本節將說明進行調試問題的工具和技巧。

使用 Google Home 數據分析

我們為您建立了一組指標,方便您追蹤事件並瞭解可能發生的錯誤階段,以便調查調試問題。您可以在 Matter 整合資訊主頁中找到這些資訊,如上一節所述。

這個資訊主頁中的圖表提供裝置佣金的資料:

裝置調試指標

裝置數量圖表會顯示指定日期內使用者的委託嘗試次數。「成功率」會顯示 Google 端活動感知到的成功率。每次執行佣金嘗試都會產生一組具有相關狀態的事件。當上述任何狀態發生錯誤時,錯誤分析圖表也會擷取這個錯誤。

調試狀態:

  • COMMISSIONING_STARTED
  • ONBOARDING_PAYLOAD_GENERATED
  • LOCAL_DISCOVERY_SUCCESSFUL
  • PASE_CONNECTION_SUCCESSFUL
  • NOC_ADDED_SUCCESSFULLY
  • COMMISSIONING_COMPLETE

如要查看這些事件的詳細版本,請依序前往「作業」>「記錄」>「記錄檔探索工具」。如要篩選佣金錯誤,請在查詢欄位中搜尋「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 數據分析中的指標,有助於初步瞭解問題發生在哪個階段。如要找出導致裝置執行錯誤的根本原因,有時您可能需要使用行動裝置在調試程序中所使用的行動裝置產生的記錄,進行額外的偵錯作業。如要進行這類操作,您必須使用 Android Debug Bridge。

使用 Android Debug Bridge (ADB)

另一個排解調試問題的方法是使用 Android Debug Bridge (ADB) 指令列工具。由於調試程序主要在行動裝置和 Matter 裝置之間進行,因此在調解期間,您可以使用 ADB 工具存取 Google Home 應用程式產生的記錄。

安裝平台工具

Android SDK Platform Tools 則包含 ADB,您可以透過 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 服務確認是否已有主畫面 / Matter 控制模組,請按照下列步驟操作:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

請確保這些傳回值受到 Google 生態系統支援。諮詢佣金失敗相關支援時,請務必在支援單中附上系統資訊。

收集錯誤記錄檔

接著,啟動記錄檔收集程序,然後按照調試步驟產生要偵錯的錯誤事件。

  1. 請提供您的 <phone-id>,以及將記錄儲存在電腦的 <file-name> (例如debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>

系統會立即啟動記錄程序。如果檔案不存在,系統會建立一個使用指定名稱的檔案,並在每個事件之後,將電話的記錄新增到檔案中。

為 Matter 裝置執行調試步驟。

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

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

分析錯誤記錄檔

調試程序會透過 GHA 中名為 MatterCommissioner 的子系統進行處理。

  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. 對裝置控制問題進行偵錯

使用者在 Google Home 生態系統中設定 Matter 裝置並委任後,就能透過 Google 助理 (例如「Ok Google,打開客廳的燈」) 或使用 Google Home 應用程式或 Google Nest 螢幕裝置上的使用者介面下達指令。

由於 Matter 會協調最終裝置和 Google 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 系統,可供外部目標對象回報生態系統的錯誤。並提供網頁工具,方便您附加檔案及分享機密資訊。如要回報生態系統問題或分享功能要求,使用 Issue Tracker 是最佳方法。
  • 開發人員論壇:如要向 Google 官方支援和社群專家尋求指引,可以前往 Nest Developer 論壇。這個論壇最適合用於取得開發官方指南

訂閱開發人員電子報

除了造訪開發人員管道尋求協助外,我們也發布每季發行的電子報,說明新功能並提供 Google 智慧型住宅生態系統的最新狀況。

你可以使用註冊表單來接收開發人員電子報。

7. 恭喜

Google Home

恭喜!您已順利學會如何使用我們建議的工具和技巧,對 Matter 整合作業進行偵錯。希望你能抽空將 Matter 與 Google Home 整合。

後續步驟

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

  • 除了使用數據分析排解問題之外,您也可以利用測試套件來測試整合作業,瞭解任何潛在問題。
  • 準備好向全世界分享整合後,下一步就是將專案通過「WWGH 認證」。您也可以按照「認證」頁面的步驟操作。