1. 事前準備
Matter 提供流暢的跨平台裝置設定和使用者體驗，為使用者提供流暢的體驗。這可能是由於多個生態系統元件在背景中共同運作的要素。這類的疑難排解系統往往相當艱鉅，對新開發人員來說並不容易，因此我們開發了一套工具和技術，讓 Matter 開發人員能夠透過 Google Home 輕鬆完成生活大小事。
在本程式碼研究室中會說明 Matter 的三個主要元件。針對這些系統，Google 提供了一組疑難排解分析，適用於開發人員從手機和中樞裝置收集到的資訊：
開發人員必須設法在裝置開發週期內解決各種問題，啟動專案後，您需要以匯總方式監控實際裝置上的問題趨勢，並透過軟體更新修正裝置。本程式碼研究室將介紹兩種用途的技巧。
必要條件
- 完成 Matter 專案和裝置設定作業的「開始使用 Matter」指南
- 具備可連線至工作站的 Android 手機 (用於 ADB 記錄檔)
課程內容
- 如何運用智慧型數據分析工具，大規模監控 Matter 問題。
- 如何存取錯誤記錄並收集資訊，將錯誤分類。
- 如何存取 Matter 說明文件和支援資源以尋求協助。
2. 查看 Google Home Analytics (分析)
監控效能是成功與 Google Home 生態系統成功整合的關鍵。我們在 Google Cloud Platform 上為智慧型住宅開發人員提供一套監控工具。您可以使用這些工具來評估專案效能。
存取專案指標
- 如要存取資料，第一步是查看 Google Home 資訊主頁，方法是登入 Google Cloud Console 並前往「作業」>「監控」>「資訊主頁」。
您的專案提供許多資訊主頁 (包括其他 GCP 產品)，您可以在智慧家庭資訊主頁中找到資訊主頁，以及 Google Home Analytics (分析) 前置字元。
我們目前提供了一個通用資訊主頁，可涵蓋您的整個專案，以及特定整合項目 (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 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 Studio 或 sdkmanager 指令列工具安裝。
在系統上成功安裝平台工具後，請使用下列指令檢查終端機的版本號碼，藉此驗證 ADB：
$ adb -- version
畫面上應該會顯示已安裝 ADB 公用程式的版本號碼，且沒有任何錯誤。
啟用 USB 偵錯功能
接著，在 Android 裝置上啟用 USB 偵錯功能。
請先按照裝置上的步驟啟用開發人員選項，再啟用 USB 偵錯功能。
這可讓 ADB 存取裝置上正在執行的應用程式產生的記錄檔。
擷取裝置 ID
- 使用下列指令執行 ADB 伺服器：
$ adb start-server
- 將手機連接至執行 ADB 伺服器的電腦。
您的手機可能會收到 USB 偵錯警告訊息，詢問您是否允許電腦存取手機資訊：
- 如果看到這則錯誤訊息，請按一下「允許」。
- 從終端機發出清單裝置指令，確認您的電腦是否可以透過 ADB 存取手機：
$ adb devices
畫面會顯示類似以下的回應：
List of devices attached <phone-id> device
<phone-id> 是一組英數字元，用來識別裝置。
- 請記得將
<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"
請確保我們的生態系統支援這些傳回值。無法取得佣金問題的相關協助時，一律會在支援單中加入系統資訊。
收集錯誤記錄檔
接下來，請啟動記錄收集程序，然後按照佣金步驟產生您要偵錯的錯誤事件。
- 提供
<phone-id>和<file-name>，儲存在電腦上的記錄檔 (例如debug_file.txt)。
$ adb -s <phone-id> logcat > <file-name>
系統會隨即開始記錄程序。如果檔案不存在，系統會建立指定名稱的檔案，並在每個事件結束後從手機新增記錄檔。
開始透過 Matter 裝置執行佣金步驟。
- 進入要偵錯的錯誤後，請在執行中的終端機視窗中按下
Control+C來停止記錄。
您的記錄檔現在應該儲存在 <file-name> 記錄檔案中。由於這項程序會記錄裝置所追蹤的所有執行程序，因此這個檔案中有許多記錄檔。因此，建議您一律透過搜尋所需項目來尋找這類記錄。
分析錯誤記錄檔
佣金程序會透過名為 MatterCommissioner 的子系統在 GHA 中進行處理。
- 分析分析錯誤的主要策略後，請執行以下指令，找出 MatterCommissioner 子系統產生的錯誤：
$ grep "MatterCommissioner" <file-name>
這會產生包含佣金程序事件的輸出內容。
- 如果您的 Matter 裝置使用 Thread，您也可以透過下列指令查詢 Thread 子系統產生的錯誤：
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
在分析 ADB 偵錯程序產生的記錄檔時，請一併尋找特定模式。許多錯誤訊息中都含有「commissioning failure」字串，
- 使用下列指令搜尋佣金失敗訊息：
$ 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：這是 Google 官方提供的 Issue Tracker 系統，外部目標對象可回報生態系統中的錯誤。Chrome 提供網站工具，方便您附加檔案及分享機密資訊。如要回報生態系統問題或分享功能要求，使用 Issue Tracker。
- 開發人員論壇：如要向 Google 官方支援團隊和社群專家尋求協助，請前往 Nest 開發人員論壇。這個論壇最適合用於取得官方開發指南。
訂閱開發人員電子報
除了在開發人員管道上查詢問題外，我們也每季都會發布電子報，提供各項新功能並介紹 Google 智慧型住宅生態系統的狀態。
您可以使用申請表單接收開發人員電子報。
7. 恭喜
恭喜！您已經瞭解如何根據我們建議的工具和技術對 Matter 整合作業進行偵錯。我們希望你能準備整合 Matter 與 Google Home。
後續步驟
請嘗試下列練習並探索其他資源：