1. 事前準備
Matter 提供順暢的跨平台裝置設定及控管體驗，讓使用者能輕鬆使用。這主要是因為在幕後運作的多個生態系統元件會彼此搭配運作。對於新開發的開發人員來說，這類疑難排解系統常常令人感到困惑，因此開發了一系列工具與技術，為支援 Google Home 的 Matter 開發人員減輕了負擔。
本程式碼研究室涵蓋了 Matter 的三個主要元件。針對上述各個系統，Google 都為從手機和中心收集的開發人員提供一系列的疑難排解分析：
開發人員十分重視在裝置開發週期中遭遇的問題。專案推出後，您需要以匯總方式監控現場裝置的問題趨勢，並透過軟體更新修正這些問題。本程式碼研究室將介紹可用於上述兩種用途的技術。
必要條件
- 完成「開始使用 Matter」指南，提供正在運作的 Matter 專案和裝置設定
- 擁有可連線至工作站的 Android 手機 (用於儲存 ADB 記錄)
課程內容
- 如何使用智慧型住宅的數據分析工具大規模監控 Matter 問題。
- 如何透過存取錯誤記錄檔和收集資訊，將錯誤分類。
- 如何存取 Matter 說明文件和支援資源，以便尋求協助。
2. 查看 Google Home Analytics
監控效能是與 Google Home 生態系統成功整合的關鍵。我們在 Google Cloud Platform 上為智慧型住宅開發人員提供一組監控工具。你可以使用這些工具評估專案成效。
存取專案指標
- 存取資料的第一步是查看 Google Home 資訊主頁，方法是登入 Google Cloud 控制台，然後前往「作業」>監控 >資訊主頁。
您的專案有很多可用的資訊主頁，包括其他 GCP 產品。智慧型住宅的資訊主頁會加上 Google Home 數據分析前置字元。
我們目前使用的一般資訊主頁涵蓋整個專案，以及特定整合 (雲端、本機、Matter) 或裝置類型 (攝影機) 的資訊主頁。這些資訊主頁只會在有對應類型，以及可執行要求的專案中執行要求時，才會包含資料。
開啟上述任一資訊主頁時，您會看到一系列類似下方的圖表：
Google Home 資訊主頁含有各種圖表，會顯示專案相關事件的詳細資料。每個整合資訊主頁都會提供一張圖表，呈現專案處理的要求總數、呈現該整合類型的成功率圖表，以及多個圖表，顯示涉及的裝置類型和特徵。此外，Matter 可透過一組圖表追蹤調用成功，以及裝置上的更新推出情形。
請注意，Google Home Analytics 資訊主頁中的圖表預設顯示檢視畫面，只是我們使用智慧型住宅指標資料為專案建立的資料檢視。您也可以使用 Metrics Explorer，運用相同的基礎指標自行建立圖表，並儲存至自訂資訊主頁。
存取錯誤記錄
記錄檔探索工具提供一系列工具，用於處理專案產生的事件記錄。只要前往 Google Cloud 控制台、作業 > 即可存取。記錄 >記錄檔探索工具。
開啟記錄檔探索工具後，您會看到如下的檢視畫面：
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 偵錯的警告訊息，詢問您是否要允許電腦存取手機中的資訊：
- 如果收到這則警告訊息，請按一下「允許」。
- 使用以下指令從終端機發出列出裝置指令，看看電腦是否可以透過 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 服務提供的住家 / Matter 控制模組：
$ 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> 記錄檔中。這個程序會記錄裝置所追蹤每個執行程序的記錄，因此這個檔案中有許多記錄。因此，建議您一律透過搜尋所需項目來運用這些記錄。
分析錯誤記錄
調試程序是透過 GHA 中的 Matter 子系統處理。
- 按照主要策略分析調用錯誤時，請使用下列指令找出 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 顯示裝置上的 UI 下達指令。
由於 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 整合。
後續步驟
請嘗試下列練習，並探索其他資源：