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。
後續步驟
請嘗試下列練習並探索其他資源: