對 Matter 整合作業進行偵錯

1. 事前準備

Matter 可為使用者提供順暢的跨平台裝置設定和控制體驗。這主要是因為多個生態系統元件會在幕後相互搭配運作。對於新手開發人員而言，這類系統的疑難排解作業通常相當棘手，因此我們開發了一系列工具和技巧，讓您在使用 Google Home 時，能更輕鬆地當個 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 Analytics 資訊主頁

我們目前提供涵蓋整個專案的一般資訊主頁，以及針對特定整合 (雲端、本機、Matter) 或裝置類型 (攝影機) 的資訊主頁。只有在您整合了對應類型的服務，且有可滿足要求的運作專案時，這些資訊主頁才會顯示資料。

開啟其中一個資訊主頁時，您會看到一系列類似下方的圖表：

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

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

請注意，Google Home Analytics 資訊主頁中顯示的圖表預設檢視畫面，只是我們根據智慧型家居指標資料為專案建立的檢視畫面。您也可以使用 Metrics Explorer，根據相同的基礎指標建立自訂圖表，並儲存在自訂資訊主頁中。

存取錯誤記錄檔

Logs Explorer 是一組工具，可用於處理專案產生的事件記錄。如要存取這項服務，請前往 Google Cloud 控制台，依序前往「Operations」>「Logging」>「Logs Explorer」。

開啟「Logs Explorer」後，您會看到類似下圖的檢視畫面：

Logs Explorer

探索器視窗包含各種工具，可用於查看、篩選、查詢及分析記錄。根據預設，這個檢視畫面會顯示專案可用的所有系統產生的記錄檔，包括智慧家庭以外產生的記錄檔。因此，您必須篩選要偵錯的事件，才能有效運用這些記錄。我們會在偵錯部分進一步說明這項功能。

3. 啟用偵錯問題

我們將首先查看 Matter 啟用事件的相關指標。調試是指使用者首次設定 Matter 裝置時，所需的一系列步驟。

在裝置委派期間，Matter 裝置、Google Home 應用程式和 Matter 架構之間會發生一連串互動。下圖顯示部分事件：

Matter 調試事件

你可以參閱 Matter 入門指南的調試頁面，進一步瞭解這些步驟。本節將介紹用於偵錯委派問題的工具和技巧。

使用 Google Home Analytics

我們已建立一組指標，讓您追蹤事件，並瞭解可能發生錯誤的階段，以便調查啟用問題。如先前所述，您可以在 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 Analytics 的指標，就能初步判斷問題可能發生在哪個階段。為了找出裝置委派錯誤的根本原因，您可能需要使用委派程序中使用的行動裝置產生的記錄，進行額外的偵錯作業。如要執行這些操作，您需要使用 Android Debug Bridge。

使用 Android Debug Bridge (ADB)

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

安裝平台工具

ADB 是 Android SDK 平台工具的一部分，可透過 Android Studio 或 sdkmanager 指令列工具安裝。

在系統上成功安裝平台工具後，請使用下列指令在終端機中查看版本號碼，確認 ADB 是否正常運作：

$ adb -- version

這應該會顯示已安裝 ADB 公用程式的版本號碼，且不會出現任何錯誤。

啟用 USB 偵錯功能

接下來，請在 Android 裝置上啟用 USB 偵錯功能。

請先按照這篇文章的步驟在裝置上啟用開發人員選項，然後啟用 USB 偵錯功能。

這樣一來，ADB 就能存取目前在裝置上執行的應用程式產生的記錄檔。

擷取裝置 ID

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

手機可能會顯示 USB 偵錯警告訊息，詢問您是否要允許電腦存取手機中的資訊：

USB 偵錯提示

  1. 如果您看到這則警告訊息，請按一下「允許」。
  2. 請從終端機發出「list devices」指令，看看電腦是否可以透過 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 服務檢查是否有 Home / 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 開發人員論壇。這個論壇最適合取得官方開發指南。

訂閱開發人員電子報

除了前往開發人員管道尋求協助，我們每季也會發布電子報，介紹新功能，並提供 Google 智慧型住宅生態系統的最新消息。

您可以使用訂閱表單訂閱開發人員電子報。

7. 恭喜

Google Home

恭喜！您已成功瞭解如何使用我們推薦的工具和技巧，偵錯 Matter 整合。祝您建構 Matter 與 Google Home 的整合作業順利。

後續步驟

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

  • 除了使用數據分析排解問題，您也可以使用測試套件，測試整合是否有任何潛在問題。
  • 整合完成後，您就可以向全世界分享成果，接下來就是讓專案取得 WWGH 認證。如要進行這項操作，請按照「認證」頁面中的步驟操作。