對 Matter 整合作業進行偵錯

1. 事前準備

Matter 可為使用者提供順暢的跨平台裝置設定和控制體驗。這主要是因為多個生態系統元件在幕後相互配合運作。對新開發人員來說，這類系統的疑難排解工作往往令人望而生畏，因此我們開發了一系列工具和技術，協助您輕鬆使用 Google Home 開發 Matter 裝置。

本程式碼研究室涵蓋 Matter 的三個主要元件。針對這些系統，Google 會提供一組從手機和中樞裝置收集的開發人員疑難排解分析資料：

身為開發人員，您必須能夠在裝置開發週期內，減輕所遇到的問題。專案推出後，您需要以匯總方式監控現場裝置的問題趨勢，並透過軟體更新修正問題。本程式碼研究室將介紹這兩種用途的技巧。

必要條件

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

課程內容

• 如何使用智慧住宅的分析工具，大規模監控 Matter 問題。
• 如何存取錯誤記錄並收集資訊，以排解錯誤。
• 如何存取 Matter 說明文件和支援資源以尋求協助。

2. 查看 Google Home Analytics

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

存取專案指標

• 如要存取資料，請先登入 Google Cloud 控制台，然後依序前往「Operations」>「Monitoring」>「Dashboards」，查看 Google Home 資訊主頁。

專案可使用多個資訊主頁 (包括其他 GCP 產品)。智慧住宅專用的資訊主頁會加上「Google Home Analytics」前置字元。

我們目前提供涵蓋整個專案的一般資訊主頁，以及特定整合 (Cloud、Local、Matter) 或裝置類型 (攝影機) 的資訊主頁。只有在整合相應類型的服務，且專案運作正常並能滿足要求時，這些資訊主頁才會顯示資料。

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

Google Home 資訊主頁包含各種圖表，顯示與專案相關聯的事件詳細資料。每個整合資訊主頁都會顯示圖表，說明專案處理的要求總數、該整合類型的成功率，以及涉及的裝置類型和特徵。此外，您還能透過 Matter 取得一系列圖表，追蹤裝置的委派成功率和更新推出情況。

請注意，Google Home Analytics 資訊主頁中顯示圖表的預設檢視畫面，是我們使用智慧住宅指標資料為專案建立的檢視畫面。您也可以使用指標探索工具，從相同的基礎指標建立自己的圖表，並儲存至自訂資訊主頁。

存取錯誤記錄檔

記錄檔瀏覽器是一系列工具，可處理專案產生的事件記錄。如要存取，請前往 Google Cloud 控制台，然後依序選取「Operations」>「Logging」>「Logs Explorer」。

開啟記錄檔探索工具後，您會看到類似下方的畫面：

探索視窗包含各種工具，可用於查看、篩選、查詢及分析記錄。根據預設，這個檢視畫面會顯示專案可用的所有系統產生的記錄，包括智慧住宅以外產生的記錄。因此，請務必篩選要偵錯的事件，並使用這些記錄。我們會在偵錯章節中進一步說明這點。

3. 偵錯委任問題

首先要介紹的指標類型是 Matter 委派事件。委派是指使用者首次設定 Matter 裝置時所需的一系列步驟。

在裝置委派程序中，Matter 裝置、Google Home 應用程式和 Matter 網狀架構之間會進行一連串的互動。下圖顯示部分事件：

如要進一步瞭解各個步驟，請參閱 Matter 基礎入門課程的委任頁面。本節將介紹用於偵錯委派問題的工具和技術。

使用 Google Home Analytics

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

這個資訊主頁中的圖表會提供裝置委派相關資料：

裝置計數圖表會顯示特定日期使用者嘗試委派裝置的次數。成功率會顯示 Google 端對這些事件的預估成功率。每次嘗試委派都會產生一組事件，並附帶相關聯的狀態。如果這些狀態發生錯誤，也會顯示在錯誤細目圖表中。

調試狀態：

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

如要查看這些事件的詳細版本，請依序前往「Operations」>「Logging」>「Logs Explorer」。如要篩選委任錯誤，可以在查詢欄位中搜尋「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 偵錯橋接器。

使用 Android Debug Bridge (ADB)

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

安裝平台工具

ADB 隨附於 Android SDK Platform Tools，可透過 Android Studio 或 sdkmanager 指令列工具安裝。

在系統上成功安裝平台工具後，請在終端機中執行下列指令，檢查版本號碼來驗證 ADB：

$ adb -- version

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

啟用 USB 偵錯功能

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

首先，請按照步驟在裝置上啟用開發人員選項，然後啟用 USB 偵錯。

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

擷取裝置 ID

1. 使用下列指令執行 ADB 伺服器：

$ adb start-server

2. 將手機連線至執行 ADB 伺服器的電腦。

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

3. 如果看到這則警告訊息，請按一下「允許」。
4. 從終端機發出列出裝置的指令，確認電腦是否能透過 ADB 存取手機，請使用下列指令：

$ adb devices

這時應該會收到類似以下的回覆：

List of devices attached
<phone-id>    device

<phone-id> 是由英數字元組成的字串，可做為裝置的專屬 ID。

5. 請記住 <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"

請確認這些傳回值受到我們生態系統支援。如要回報委任失敗問題，請務必在支援單中附上系統資訊。

收集錯誤記錄

接著啟動記錄收集程序，然後完成委派步驟，產生要偵錯的錯誤事件。

1. 提供 <phone-id> 並執行下列指令，以及在電腦中儲存記錄的 <file-name> (例如 debug_file.txt)。

$ adb -s <phone-id> logcat > <file-name>

系統會立即開始記錄程序。如果檔案不存在，系統會建立檔案，並在每個事件發生後將手機記錄新增至檔案。

繼續使用 Matter 裝置完成委派步驟。

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

記錄檔現在應該會儲存在 <file-name> 記錄檔中。由於這項程序會記錄裝置中追蹤的每個執行程序，因此這個檔案中會有大量記錄。因此，您應一律搜尋所需項目，藉此運用這些記錄。

分析錯誤記錄

調試程序是由 GHA 內的 MatterCommissioner 子系統處理。

1. 按照分析委派錯誤時使用的主要策略，使用下列指令尋找 MatterCommissioner 子系統產生的錯誤：

$ grep "MatterCommissioner" <file-name>

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

2. 如果 Matter 裝置使用 Thread，您也可以透過下列指令，查看 Thread 子系統產生的錯誤：

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

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

3. 使用下列指令搜尋委派失敗訊息：

$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. 偵錯裝置控制問題

使用者在 Google Home 生態系統中設定及啟用 Matter 裝置後，就能透過 Google 助理發出語音指令 (例如「Ok Google，開啟客廳的燈」)，或使用 Google Home 應用程式或 Google Nest 螢幕裝置上的使用者介面發出指令。

由於終端裝置和 Google Hub 之間的控制規格是由 Matter 仲介，因此裝置控制端預期會減少錯誤。無論如何，我們都會提供指標和記錄，協助您偵錯這類問題。

使用指標

在 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：這是 Google 官方經營的問題追蹤系統，外部對象可以在這裡回報生態系統的錯誤。並提供網頁工具，方便您視需要附加檔案及分享機密資訊。如要回報生態系統問題或分享功能要求，建議使用 Issue Tracker。
• 開發人員論壇：如要向 Google 官方支援團隊和社群專家尋求指引，請前往 Nest 開發人員論壇。這個論壇最適合取得開發的官方指引。

訂閱開發人員電子報

除了透過開發人員管道提問外，我們每季也會發布電子報，重點介紹新功能，並提供 Google 智慧型住宅生態系統的最新消息。

如要訂閱開發人員電子報，請填寫註冊表單。

7. 恭喜

恭喜！您已成功學會如何使用我們建議的工具和技術，對 Matter 整合進行偵錯。祝您順利完成 Google Home 的 Matter 整合。

後續步驟

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

• 除了使用 Analytics 進行疑難排解，您也可以使用測試套件測試整合功能，找出任何潛在問題。
• 整合完成後，下一步就是取得 WWGH 認證。如要進行這項操作，請按照「認證」頁面的步驟操作。