1. Trước khi bắt đầu
Matter mang đến trải nghiệm thiết lập và kiểm soát thiết bị liền mạch, đa nền tảng cho người dùng cuối. Điều này chủ yếu có thể xảy ra là do nhiều thành phần của hệ sinh thái hoạt động kết hợp với nhau trong nền. Việc khắc phục sự cố cho các hệ thống như vậy thường khiến các nhà phát triển mới gặp khó khăn. Vì vậy, chúng tôi đã phát triển một loạt công cụ và kỹ thuật để giúp bạn dễ dàng hơn khi làm nhà phát triển Matter với Google Home.
Có 3 thành phần chính của Matter được đề cập trong lớp học lập trình này. Đối với mỗi hệ thống này, Google cung cấp một bộ số liệu phân tích khắc phục sự cố cho nhà phát triển được thu thập từ điện thoại và trung tâm:
Là nhà phát triển, bạn cần phải có khả năng giảm thiểu các vấn đề gặp phải trong suốt chu trình phát triển thiết bị. Sau khi triển khai dự án, bạn cần theo dõi xu hướng vấn đề cho các thiết bị đang hoạt động trên thực tế theo cách tổng hợp và khắc phục các vấn đề đó thông qua bản cập nhật phần mềm. Lớp học lập trình này đề cập đến các kỹ thuật mà bạn có thể sử dụng cho cả hai mục đích này.
Điều kiện tiên quyết
- Hoàn thành hướng dẫn Bắt đầu sử dụng Matter bằng một dự án Matter đang hoạt động và thiết lập thiết bị
- Có một điện thoại Android mà bạn có thể kết nối với máy trạm (dành cho nhật ký ADB)
Kiến thức bạn sẽ học được
- Cách sử dụng các công cụ phân tích dành cho Nhà thông minh để theo dõi các vấn đề Matter trên quy mô lớn.
- Cách phân loại lỗi bằng cách truy cập vào nhật ký lỗi và thu thập thông tin.
- Cách truy cập vào tài liệu về Matter và tài nguyên hỗ trợ để yêu cầu trợ giúp.
2. Xem Google Home Analytics
Việc theo dõi hiệu suất là yếu tố quan trọng để tích hợp thành công với hệ sinh thái Google Home. Chúng tôi cung cấp một bộ công cụ giám sát cho các nhà phát triển nhà thông minh trên Google Cloud Platform. Bạn có thể sử dụng các công cụ này để đo lường hiệu suất của dự án.
Truy cập vào chỉ số dự án
- Bước đầu tiên để truy cập vào dữ liệu của bạn là kiểm tra trang tổng quan của Google Home bằng cách đăng nhập vào Google Cloud Console rồi chuyển đến phần Operations (Hoạt động) > Monitoring (Theo dõi) > Dashboards (Trang tổng quan).
Có một số trang tổng quan dành cho dự án của bạn (bao gồm cả các sản phẩm khác của GCP). Các trang tổng quan được cung cấp cho nhà thông minh có tiền tố là Google Home Analytics.
Chúng tôi hiện có một trang tổng quan chung bao gồm toàn bộ dự án của bạn, cũng như các trang tổng quan dành cho việc tích hợp cụ thể (Đám mây, Cục bộ, Matter) hoặc các loại thiết bị (Máy ảnh). Các trang tổng quan này chỉ chứa dữ liệu nếu bạn đã tích hợp loại tương ứng, cùng với một dự án đang hoạt động để thực hiện các yêu cầu.
Khi mở một trong các trang tổng quan này, bạn sẽ thấy một loạt biểu đồ như sau:
Trang tổng quan Google Home có nhiều biểu đồ cho biết thông tin chi tiết về các sự kiện liên quan đến dự án của bạn. Với mỗi trang tổng quan về chế độ tích hợp, bạn sẽ thấy một biểu đồ cho biết tổng số yêu cầu mà dự án của bạn xử lý, một biểu đồ cho biết tỷ lệ thành công của loại chế độ tích hợp đó và một số biểu đồ cho biết các loại thiết bị và đặc điểm liên quan. Ngoài ra, với Matter, bạn có một bộ biểu đồ theo dõi quá trình triển khai thành công cũng như việc triển khai bản cập nhật trên thiết bị.
Xin lưu ý rằng chế độ xem mặc định có các biểu đồ mà bạn thấy trong trang tổng quan của Google Home Analytics chỉ là một chế độ xem mà chúng tôi đã tạo cho dự án của bạn bằng dữ liệu chỉ số nhà thông minh. Bạn cũng có thể sử dụng Trình khám phá chỉ số để tạo biểu đồ của riêng mình từ cùng các chỉ số cơ bản và lưu chúng vào trang tổng quan tuỳ chỉnh.
Truy cập nhật ký lỗi
Trình khám phá nhật ký là một tập hợp các công cụ giúp bạn làm việc với nhật ký sự kiện được tạo trong một dự án. Bạn có thể truy cập vào công cụ này trong Google Cloud Console bằng cách chuyển đến phần Operations (Thao tác) > Logging (Ghi nhật ký) > Logs Explorer (Trình khám phá nhật ký).
Sau khi mở Logs Explorer (Trình khám phá nhật ký), bạn sẽ thấy chế độ xem như sau:
Cửa sổ trình khám phá chứa nhiều công cụ để xem, lọc, truy vấn và phân tích nhật ký. Theo mặc định, chế độ xem này hiển thị nhật ký được tạo từ tất cả các hệ thống có sẵn cho dự án của bạn, bao gồm cả nhật ký được tạo bên ngoài Nhà thông minh. Đó là lý do quan trọng để sử dụng các nhật ký này bằng cách lọc các sự kiện mà bạn muốn gỡ lỗi. Chúng tôi sẽ nói thêm về vấn đề này trong các phần gỡ lỗi.
3. Khắc phục vấn đề về việc uỷ quyền
Loại chỉ số đầu tiên mà chúng ta sẽ xem xét là về các sự kiện uỷ quyền Matter. Ủy quyền là tập hợp các bước cần thiết để người dùng thiết lập thiết bị theo chuẩn Matter lần đầu tiên.
Trong quá trình vận hành thiết bị, một tập hợp các hoạt động tương tác diễn ra giữa thiết bị Matter, ứng dụng Google Home và vải Matter. Hình ảnh sau đây minh hoạ một số sự kiện này:
Bạn có thể xem trang về phí hoa hồng của Matter cùng để tìm hiểu thêm về từng bước trong số này. Trong phần này, chúng ta sẽ tìm hiểu về các công cụ và kỹ thuật khắc phục vấn đề trong quá trình vận hành.
Sử dụng Google Home Analytics
Chúng tôi đã tạo một bộ chỉ số để bạn điều tra các vấn đề liên quan đến việc uỷ quyền, bằng cách theo dõi các sự kiện và tìm hiểu xem lỗi có thể xảy ra ở giai đoạn nào. Bạn có thể tìm thấy các chế độ này trong Trang tổng quan về tích hợp Matter, như đã đề cập trong phần trước.
Các biểu đồ trong trang tổng quan này cung cấp dữ liệu về quá trình vận hành thiết bị:
Biểu đồ số lượng thiết bị cho biết số lần người dùng thử nghiệm vào một ngày cụ thể. Tỷ lệ thành công cho biết tỷ lệ thành công được nhận thấy đối với những sự kiện này từ phía Google. Mỗi lần vận hành sẽ tạo một nhóm sự kiện với các trạng thái tương ứng. Khi lỗi xảy ra ở bất kỳ trạng thái nào trong số này, lỗi đó cũng được ghi lại trong biểu đồ phân tích lỗi.
Trạng thái uỷ quyền:
- COMMISSIONING_STARTED
- ONBOARDING_PAYLOAD_GENERATED
- LOCAL_DISCOVERY_SUCCESSFUL
- PASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY
- COMMISSIONING_COMPLETE
Để xem phiên bản chi tiết của những sự kiện này, hãy chuyển đến Thao tác > Ghi nhật ký > Trình khám phá nhật ký. Để lọc lỗi uỷ quyền, bạn có thể tìm kiếm "clientUpdateLog" cùng với "severity>=ERROR" trong trường truy vấn.
Nhật ký lỗi khi bắt đầu sử dụng Matter có dạng như sau:
{
"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"
}
Ngoài trạng thái vận hành và mã trạng thái, nhật ký lỗi còn chứa dấu thời gian của lỗi đã ghi lại, cũng như Mã sản phẩm Matter để bạn xác định sản phẩm nào gây ra lỗi. Tập hợp nhật ký được tạo từ cùng một lần thử nghiệm uỷ quyền sẽ chia sẻ một sessionId.
Việc sử dụng các chỉ số từ Google Home Analytics sẽ giúp bạn có ý tưởng ban đầu về giai đoạn có thể xảy ra vấn đề. Để tìm nguyên nhân gốc rễ của lỗi trong quá trình uỷ quyền thiết bị, đôi khi bạn có thể cần phải gỡ lỗi bổ sung bằng cách sử dụng nhật ký do thiết bị di động dùng trong quá trình uỷ quyền tạo ra. Đối với những trường hợp này, bạn cần có Cầu gỡ lỗi Android.
Sử dụng Cầu gỡ lỗi Android (ADB)
Một cách khác để khắc phục sự cố vận hành là sử dụng công cụ dòng lệnh Cầu gỡ lỗi Android (ADB). Vì việc uỷ quyền chủ yếu được xử lý giữa thiết bị di động và thiết bị Matter, nên bạn có thể sử dụng công cụ ADB để truy cập vào nhật ký do ứng dụng Google Home tạo ra trong suốt quá trình uỷ quyền.
Cài đặt các công cụ của nền tảng
ADB là một phần trong Công cụ nền tảng SDK Android, có thể được cài đặt bằng Android Studio hoặc thông qua công cụ dòng lệnh sdkmanager.
Sau khi cài đặt thành công các công cụ nền tảng trên hệ thống, hãy xác minh ADB bằng cách kiểm tra số phiên bản từ dòng lệnh bằng lệnh sau:
$ adb -- version
Thao tác này sẽ hiển thị số phiên bản của tiện ích ADB đã cài đặt mà không gặp lỗi nào.
Bật tính năng gỡ lỗi qua USB
Tiếp theo, hãy bật tính năng gỡ lỗi qua USB trên thiết bị Android.
Trước tiên, hãy làm theo các bước để bật tuỳ chọn cho nhà phát triển trên thiết bị của bạn, sau đó bật tính năng gỡ lỗi qua USB.
Điều này cho phép ADB truy cập vào nhật ký do các ứng dụng đang chạy trên thiết bị tạo ra.
Truy xuất mã thiết bị
- Chạy máy chủ ADB bằng lệnh sau:
$ adb start-server
- Kết nối điện thoại với máy tính đang chạy máy chủ ADB.
Bạn có thể nhận được một thông báo cảnh báo trên điện thoại về tính năng gỡ lỗi qua USB, hỏi xem bạn có muốn cho phép máy tính truy cập vào thông tin trên điện thoại hay không:
- Nếu bạn nhận được thông báo cảnh báo này, hãy nhấp vào Cho phép.
- Hãy đưa ra lệnh list devices (liệt kê thiết bị) từ dòng lệnh để xem máy tính của bạn có thể truy cập vào điện thoại thông qua ADB hay không bằng lệnh sau:
$ adb devices
Thao tác này sẽ trả về phản hồi tương tự như sau:
List of devices attached <phone-id> device
<phone-id> là chuỗi chữ và số nhận dạng duy nhất thiết bị của bạn.
- Hãy nhớ giá trị
<phone-id>để sử dụng trong các bước tiếp theo.
Thu thập thông tin hệ thống
Tiếp theo, hãy kiểm tra thông tin phiên bản của ứng dụng và hệ thống trên thiết bị.
- Cách kiểm tra phiên bản hệ điều hành Android:
$ adb -s <phone-id> shell getprop ro.build.version.release
- Cách kiểm tra phiên bản ứng dụng Google Home:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
- Cách kiểm tra phiên bản Dịch vụ Google Play:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- Cách kiểm tra xem bạn có các mô-đun kiểm soát Trang chủ / Vấn đề thông qua Dịch vụ Play hay không:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
Đảm bảo các giá trị trả về này được hệ sinh thái của chúng tôi hỗ trợ. Khi liên hệ để được hỗ trợ về các lỗi trong quá trình vận hành, vui lòng luôn cung cấp thông tin hệ thống trong phiếu yêu cầu hỗ trợ của bạn.
Thu thập nhật ký lỗi
Tiếp theo, hãy bắt đầu quy trình thu thập nhật ký, sau đó thực hiện các bước uỷ quyền để tạo các sự kiện lỗi mà bạn muốn gỡ lỗi.
- Chạy lệnh sau bằng cách cung cấp
<phone-id>cũng như<file-name>nơi nhật ký sẽ được lưu trong máy tính của bạn (ví dụ:debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
Thao tác này sẽ ngay lập tức bắt đầu quá trình ghi nhật ký. Tệp có tên được cung cấp sẽ được tạo nếu chưa có và nhật ký từ điện thoại sẽ được thêm vào tệp sau mỗi sự kiện.
Tiếp tục các bước uỷ quyền với thiết bị Matter.
- Khi bạn gặp lỗi muốn gỡ lỗi, hãy dừng ghi nhật ký bằng cách nhấn
Control+Ctrong cửa sổ dòng lệnh đang chạy.
Giờ đây, nhật ký của bạn sẽ được lưu trữ trong tệp nhật ký <file-name>. Vì quá trình này ghi lại nhật ký từ mọi quy trình đang chạy được theo dõi trong thiết bị nên sẽ có nhiều nhật ký trong tệp này. Đó là lý do bạn phải luôn sử dụng các nhật ký này bằng cách tìm kiếm các mục bạn cần.
Phân tích nhật ký lỗi
Các quy trình uỷ quyền được xử lý thông qua một hệ thống con có tên là MatterCommissioner trong GHA.
- Theo chiến lược chính được sử dụng khi phân tích lỗi uỷ quyền, hãy tìm lỗi do hệ thống con MatterCommissioner tạo ra bằng lệnh sau:
$ grep "MatterCommissioner" <file-name>
Thao tác này sẽ tạo ra một kết quả chứa các sự kiện từ quy trình uỷ quyền.
- Nếu thiết bị Matter của bạn đang sử dụng Thread, bạn cũng có thể tìm lỗi do hệ thống con Thread tạo ra thông qua lệnh sau:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
Khi phân tích tệp nhật ký do quá trình gỡ lỗi ADB tạo ra, hãy tìm một số mẫu nhất định. Nhiều lỗi uỷ quyền có chuỗi "commissioning failure" trong thông báo lỗi.
- Tìm thông báo lỗi khi uỷ quyền bằng lệnh sau:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Gỡ lỗi sự cố điều khiển thiết bị
Sau khi thiết lập và uỷ quyền cho các thiết bị Matter trong hệ sinh thái Google Home, người dùng có thể đưa ra lệnh bằng giọng nói thông qua Trợ lý Google (ví dụ: "Ok Google, bật đèn trong phòng khách") hoặc bằng cách sử dụng giao diện người dùng trên Ứng dụng Home hoặc các thiết bị màn hình Google Nest.
Vì thông số kỹ thuật điều khiển giữa thiết bị cuối và Google Hub được Matter dàn xếp, nên dự kiến sẽ có ít lỗi hơn ở phía điều khiển thiết bị. Mặc dù vậy, chúng tôi cũng cung cấp các chỉ số và nhật ký để bạn gỡ lỗi những loại vấn đề này.
Sử dụng chỉ số
Trong Trang tổng quan về tích hợp Matter, bạn sẽ thấy một số chỉ số liên quan đến việc kiểm soát thiết bị. Có ba biểu đồ quan trọng để đánh giá hiệu suất của thiết bị trong trường:
Trong các vấn đề về quyền kiểm soát, bạn thường thấy xu hướng giảm về tỷ lệ thành công và xu hướng tăng về biểu đồ phân tích lỗi. Biểu đồ chi tiết lỗi cho bạn biết các lỗi mà Google Nest Hub ghi lại được về lý do khiến thao tác điều khiển thiết bị không thành công.
Sử dụng nhật ký
Mỗi vấn đề về việc điều khiển thiết bị Matter cũng tạo ra một nhật ký lỗi trong hệ thống. Bạn có thể lọc các lỗi này khỏi Trình khám phá nhật ký bằng cách tìm kiếm "executionLog".
Nhật ký lỗi điều khiển thiết bị Matter có dạng như sau:
{
"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"
}
Mỗi nhật ký lỗi chứa dấu thời gian, loại thiết bị và đặc điểm, cũng như lỗi liên quan đến yêu cầu kiểm soát trong statusType. Nhiều lỗi điều khiển cũng bao gồm externalDebugString, một thông báo lỗi ngắn giải thích về lỗi đó.
5. Gỡ lỗi các tính năng khác
Đến đây, bạn đã tìm hiểu cách xử lý các vấn đề về việc kiểm soát và uỷ quyền thiết bị cho Matter. Ngoài ra, trong hệ sinh thái này, bạn cũng có thể sử dụng các kỹ thuật mà chúng tôi đề xuất để đảm bảo việc tích hợp có chất lượng cao.
Theo dõi bản cập nhật OTA
Để theo dõi các bản phát hành cho bản cập nhật Qua mạng không dây (OTA) cho các thiết bị Matter do Google Home phát hành, chúng tôi cung cấp một bộ chỉ số cho biết phiên bản phần cứng và phần mềm cho các thiết bị đang hoạt động trên thực tế.
Sau khi bạn phát hành bản cập nhật từ bảng điều khiển, hãy theo dõi các chỉ số sau:
Bạn sẽ thấy rằng trong những ngày sau khi phát hành, ngày càng có nhiều thiết bị trên thực tế nhận được phiên bản phần mềm mới liên kết với bản phát hành phần mềm OTA của bạn.
6. Tìm sự hỗ trợ
Google cung cấp các công cụ và tài liệu để bạn gỡ lỗi các vấn đề về Matter. Tuy nhiên, vì hệ sinh thái Matter còn mới, nên sẽ có những vấn đề mà các tài nguyên này không đề cập đến. Trong những trường hợp như vậy, bạn luôn có thể liên hệ với chúng tôi hoặc cộng đồng để được hỗ trợ.
Truy cập vào các kênh dành cho nhà phát triển
Có 3 kênh dành cho nhà phát triển được Google giám sát tích cực:
Mặc dù mỗi kênh trong số này được cùng một nhóm giám sát theo định kỳ, nhưng có một số điểm khác biệt chính về thời điểm sử dụng kênh nào.
- Stack Overflow: Bạn có thể liên hệ với chúng tôi và cộng đồng nhà phát triển Nhà thông minh để hỏi về cách triển khai hoặc để được hướng dẫn. Kênh này phù hợp nhất để hỏi cách khắc phục sự cố hoặc triển khai một tính năng nhất định.
- Công cụ theo dõi lỗi: Đây là hệ thống công cụ theo dõi lỗi chính thức do Google điều hành, nơi khán giả bên ngoài có thể báo cáo lỗi trên hệ sinh thái. Ứng dụng này cung cấp các công cụ web để đính kèm tệp và chia sẻ thông tin nhạy cảm khi cần. Bạn nên sử dụng Công cụ theo dõi lỗi để báo cáo các vấn đề về hệ sinh thái hoặc chia sẻ yêu cầu về tính năng.
- Diễn đàn nhà phát triển: Để được hướng dẫn của nhóm hỗ trợ chính thức của Google và các chuyên gia trong cộng đồng, bạn có thể liên hệ thông qua Diễn đàn nhà phát triển Nest. Đây là diễn đàn phù hợp nhất để nhận hướng dẫn chính thức về hoạt động phát triển.
Đăng ký nhận bản tin dành cho nhà phát triển
Ngoài việc truy cập vào các kênh dành cho nhà phát triển để giải đáp thắc mắc, chúng tôi cũng phát hành bản tin hằng quý để giới thiệu các tính năng mới và thông tin về trạng thái của hệ sinh thái Nhà thông minh của Google.
Bạn có thể dùng biểu mẫu đăng ký để nhận bản tin dành cho nhà phát triển.
7. Xin chúc mừng
Xin chúc mừng! Bạn đã tìm hiểu thành công cách gỡ lỗi các hoạt động tích hợp Matter bằng các công cụ và kỹ thuật mà chúng tôi đề xuất. Chúc bạn có nhiều niềm vui khi tích hợp Matter với Google Home.
Các bước tiếp theo
Hãy thử các bài tập sau và khám phá các tài nguyên khác:
- Ngoài việc sử dụng số liệu phân tích để khắc phục sự cố, bạn cũng có thể sử dụng Bộ kiểm thử để kiểm tra phương thức tích hợp của mình trước mọi vấn đề tiềm ẩn.
- Sau khi bạn đã sẵn sàng chia sẻ giải pháp tích hợp của mình với thế giới, bước tiếp theo là chứng nhận dự án của bạn theo WWGH. Để làm việc này, bạn có thể làm theo các bước trong trang Chứng chỉ.