1. 事前準備
Matter 可為使用者提供順暢的跨平台裝置設定和控制體驗。這主要是因為多個生態系統元件會在幕後相互搭配運作。對於新手開發人員而言，這類系統的疑難排解作業通常相當棘手，因此我們開發了一系列工具和技巧，讓您在使用 Google Home 時，能更輕鬆地當個 Matter 開發人員。
本程式碼研究室涵蓋了 Matter 的三個主要元件。針對每個系統，Google 都會為開發人員提供一組從手機和中樞收集的疑難排解分析資料：
開發人員必須能夠在裝置開發週期中減輕遇到的問題。專案啟動後，您需要以匯總方式監控現場裝置的問題趨勢，並透過軟體更新進行修正。本程式碼研究室將介紹可用於這兩種用途的技術。
必要條件
- 完成Matter 入門指南，並設定可運作的 Matter 專案和裝置
- 擁有可連結至工作站的 Android 手機 (用於 ADB 記錄)
課程內容
- 如何使用智慧型住宅數據分析工具，大規模監控 Matter 問題。
- 如何存取錯誤記錄並收集資訊，以便分類處理錯誤。
- 如何存取 Matter 說明文件和支援資源，以便尋求協助。
2. 查看 Google Home 數據分析
監控效能是成功與 Google Home 生態系統整合的關鍵。我們在 Google Cloud Platform 上為智慧住宅開發人員提供一套監控工具。您可以使用這些工具評估專案的效能。
存取專案指標
- 如要存取資料，第一步是檢查 Google Home 資訊主頁。請登入 Google Cloud 控制台，然後依序前往「作業」>「監控」>「資訊主頁」。
專案可用的資訊主頁很多，包括其他 GCP 產品 。專為智慧型住宅提供的資訊主頁會附上 Google Home Analytics 前置字元。
我們目前使用的一般資訊主頁涵蓋整個專案，以及特定整合 (雲端、本機、Matter) 或裝置類型 (攝影機) 的資訊主頁。只有在您整合了對應類型的服務，且有可滿足要求的運作專案時，這些資訊主頁才會顯示資料。
開啟其中一個資訊主頁時，您會看到一系列類似下方的圖表：
Google Home 資訊主頁包含各種圖表，顯示與專案相關聯的事件詳細資料。每個整合資訊主頁都會顯示一張圖表，顯示專案處理的要求總數、該整合類型的成功率，以及幾張圖表，顯示相關的裝置類型和特徵。此外，Matter 還提供一組圖表，可追蹤委派成功與裝置更新的推出情形。
請注意，Google Home Analytics 資訊主頁中的圖表預設顯示檢視畫面，只是我們使用智慧型住宅指標資料為專案建立的資料檢視。您也可以使用 Metrics Explorer，根據相同的基礎指標建立自訂圖表，並儲存在自訂資訊主頁中。
存取錯誤記錄
Logs Explorer 是一組工具，可用於處理專案產生的事件記錄。如要存取這項功能，請前往 Google Cloud 控制台，依序前往「Operations」>「Logging」>「Logs Explorer」。
開啟「Logs Explorer」後，您會看到類似下圖的檢視畫面：
探索器視窗包含各種工具，可用於查看、篩選、查詢及分析記錄。根據預設，這個檢視畫面會顯示專案可用的所有系統產生的記錄檔，包括智慧家庭以外產生的記錄檔。因此，使用這些記錄時，請務必篩選要偵錯的事件。我們會在偵錯部分進一步說明這項功能。
3. 啟用偵錯問題
我們將首先查看 Matter 啟用事件的相關指標。調試是指使用者首次設定 Matter 裝置時，需要完成的一系列步驟。
在裝置委派期間，Matter 裝置、Google Home 應用程式和 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 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
- 使用下列指令執行 ADB 伺服器：
$ adb start-server
- 將手機連接至執行 ADB 伺服器的電腦。
手機可能會顯示 USB 偵錯警告訊息，詢問您是否要允許電腦存取手機中的資訊：
- 如果您看到這則警告訊息，請按一下「允許」。
- 請從終端機發出「list devices」指令，看看電腦是否可以透過 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 服務檢查是否有 Home/Matter 控制模組，請按照下列步驟操作：
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
請確認這些傳回值受 Google 生態系統支援。如需針對啟用失敗問題尋求支援，請務必在支援單中加入系統資訊。
收集錯誤記錄檔
接著，請啟動記錄收集程序，然後完成調試步驟，產生要偵錯的錯誤事件。
- 執行下列指令，並提供您的
<phone-id>，以及將記錄儲存在電腦中的<file-name>(例如debug_file.txt)。
$ adb -s <phone-id> logcat > <file-name>
這會立即啟動記錄程序。如果檔案尚未存在，系統會建立檔案並命名為您提供的名稱，並在每次事件發生後將手機的記錄新增至檔案。
請直接執行 Matter 裝置的調試步驟。
- 看到要偵錯的錯誤後，請在執行中的終端機視窗中按下
Control+C來停止記錄。
記錄現在應儲存在 <file-name> 記錄檔案中。這個程序會記錄裝置所追蹤每個執行程序的記錄，因此這個檔案中有許多記錄。因此，您應該一律透過搜尋所需的項目來使用這些記錄。
分析錯誤記錄
調試程序會透過 GHA 中名為 MatterCommissioner 的子系統處理。
- 按照主要策略分析調用錯誤時，請使用下列指令找出 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. 偵錯裝置控制問題
使用者在 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：這是 Google 推出的官方 Issue Tracker 系統，外部目標對象可回報生態系統中的錯誤。這項服務提供附加檔案及視需要分享機密資訊的網路工具。如要回報生態系統問題或分享功能要求，使用 Issue Tracker 是最佳選擇。
- 開發人員論壇：如要向 Google 官方支援團隊和社群專家尋求指引，請前往 Nest 開發人員論壇。這個論壇最適合取得官方開發指南。
訂閱開發人員電子報
除了前往開發人員管道尋求協助，我們每季也會發布電子報，介紹新功能，並提供 Google 智慧型住宅生態系統的最新消息。
您可以使用訂閱表單訂閱開發人員電子報。
7. 恭喜
恭喜！您已成功瞭解如何使用我們推薦的工具和技巧，偵錯 Matter 整合。我們希望你能花點時間將 Matter 與 Google Home 整合。
後續步驟
請嘗試下列練習，並探索其他資源：