Gỡ lỗi tích hợp vấn đề

1. Trước khi bắt đầu

Matter mang đến trải nghiệm điều khiển và thiết lập thiết bị đa nền tảng liền mạch cho người dùng cuối. Điều này chủ yếu là do nhiều thành phần của hệ sinh thái hoạt động cùng lúc với nhau. Thông thường, các nhà phát triển mới có thể gặp nhiều khó khăn khi khắc phục sự cố, vì vậy, chúng tôi đã phát triển một loạt các công cụ và kỹ thuật để giúp bạn trở nên dễ dàng hơn trong vai trò nhà phát triển Matter bằng Google Home.

Có 3 thành phần chính cho Matter được đề cập trong lớp học lập trình này. Đối với mỗi hệ thống trong số này, Google cung cấp một bộ số liệu phân tích khắc phục sự cố cho các nhà phát triển được thu thập từ điện thoại và trung tâm:

Cập nhật, thực thi, vận hành và OTA

Là nhà phát triển, điều quan trọng là bạn phải có thể giảm thiểu vấn đề mà bạn gặp phải trong suốt quá trình phát triển thiết bị. Sau khi khởi chạy dự án, bạn cần theo dõi xu hướng sự cố của các thiết bị trong lĩnh vực này một cách tổng hợp và khắc phục chúng thông qua các bản cập nhật phần mềm. Lớp học lập trình này bao gồm các kỹ thuật 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 cách thiết lập thiết bị và dự án theo chuẩn Matter đang hoạt động
  • Có điện thoại Android mà bạn có thể kết nối với máy trạm của mình (đối với 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 đề trên thiết bị theo chuẩn Matter.
  • 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 theo chuẩn Matter và các tài nguyên hỗ trợ để được trợ giúp.

2. Xem Google Home Analytics

Việc giám sát hiệu suất là yếu tố rấ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 các chỉ số của 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 Google Home, bằng cách đăng nhập vào Google Cloud Console và chuyển đến Hoạt động > Giám sát > 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). Trang tổng quan dành cho nhà thông minh có tiền tố Google Home Analytics.

Trang tổng quan Google Home Analytics

Hiện tại, chúng tôi có trang tổng quan chung cho toàn bộ dự án của bạn, cũng như các trang tổng quan cho tích hợp cụ thể (Cloud, Cục bộ, Vấn đề) 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 có tích hợp loại tương ứng, cùng với dự án đang hoạt động để hoàn thành 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 các biểu đồ như sau:

Phân tích tỷ lệ thành công, thời gian chờ và loại thiết bị

Trang tổng quan chính của Google chứa nhiều biểu đồ hiển thị 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 tích hợp, bạn sẽ thấy một biểu đồ cho thấy tổng số yêu cầu được dự án của bạn xử lý, một biểu đồ cho thấy tỷ lệ thành công cho loại tích hợp đó và một số biểu đồ cho thấy các loại thiết bị và đặc điểm liên quan. Ngoài ra, với ứng dụng Matter, bạn còn có các biểu đồ theo dõi mức độ thành công của việc vận hành, cũng như các đợt cập nhật thiết bị.

Xin lưu ý rằng chế độ xem mặc định với các biểu đồ bạn thấy trong trang tổng quan Google Home Analytics chỉ là 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 các biểu đồ đó trong trang tổng quan tùy chỉnh của bạn.

Nhật ký lỗi truy cập

Trình khám phá nhật ký là một tập hợp các công cụ để làm việc với nhật ký sự kiện được tạo trên dự án. Bạn có thể truy cập công cụ này trong Google Cloud Console bằng cách chuyển đến Hoạt động > Ghi nhật ký > Trình khám phá nhật ký.

Sau khi mở Trình khám phá nhật ký, bạn sẽ thấy một chế độ xem như sau:

Trình khám phá nhật ký

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 sẽ hiển thị các nhật ký được tạo từ tất cả hệ thống có sẵn cho dự án của bạn, bao gồm cả các nhật ký được tạo bên ngoài Nhà thông minh. Đó là lý do tại sao bạn cần 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 nhiều hơn về điều này trong phần gỡ lỗi.

3. Gỡ lỗi ủy quyền

Loại chỉ số đầu tiên mà chúng ta sẽ xem xét là về vấn đề ủy quyền vấn đề. Ủ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ị Matter lần đầu tiên.

Trong quá trình vận hành thiết bị, một nhóm các hoạt động tương tác sẽ diễn ra giữa thiết bị Matter, ứng dụng Google Home và vải Matter. Hình ảnh sau đây minh họa một số sự kiện sau:

Sự kiện ủy quyền vấn đề

Bạn có thể xem trang yêu cầu hỗ trợ trên Primer Primer để tìm hiểu thêm về từng bước này. Trong phần này, chúng tôi sẽ đề cập đến các công cụ và kỹ thuật để gỡ lỗi các vấn đề về việc thử nghiệm.

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 đề về phí hoa hồng bằng cách theo dõi các sự kiện và biết được các lỗi có thể xảy ra ở giai đoạn nào. Bạn có thể tìm thấy các mã này trong Trang tổng quan về vấn đề tích hợp, như chúng tôi đã trình bày ở phần trước.

Biểu đồ trong trang tổng quan này cung cấp dữ liệu về quá trình ủy quyền thiết bị:

Chỉ số phí vận chuyển thiết bị

Biểu đồ số lượng thiết bị cho biết số lần thử của người dùng vào một ngày cụ thể. Tỷ lệ thành công cho biết tỷ lệ thành công theo cảm nhận cho những sự kiện này từ phía Google. Mỗi lần thử nghiệm tạo ra một nhóm sự kiện có các trạng thái liên kết. Khi xảy ra lỗi ở bất kỳ trạng thái nào trong số các trạng thái này, lỗi cũng được thể hiện trong biểu đồ phân tích lỗi.

Quốc gia có hoa hồng:

  • COMMISIONING_START ĐƯỢC
  • ONBOARDING_PAYLOAD_GENERATED
  • LOCAL_DISCOVERY_SUCCESSFUL
  • PASE_CONNECTION_SUCCESSFUL
  • NOC_ADDED_SUCCESSFUL
  • COMMISSIONING_HOÀN TẤT

Để xem phiên bản chi tiết của những sự kiện này, hãy chuyển đến phần Hoạt động > Ghi nhật ký > Trình khám phá nhật ký. Để lọc lỗi ủy quyền, bạn có thể tìm "clientUpdateLog" cùng với "severity>=ERROR" trong trường truy vấn.

Nhật ký lỗi ủy quyền cho Matter sẽ 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 được ghi lại, cũng như mã sản phẩm Matter cho phép 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 có chung sessionId.

Việc sử dụng các chỉ số từ Google Home Analytics cung cấp cho bạn ý tưởng ban đầu về giai đoạn xảy ra vấn đề. Để tìm ra nguyên nhân gốc rễ cho các lỗi xảy ra tình trạng thiết bị xảy ra, đôi khi bạn có thể cần gỡ lỗi bổ sung bằng cách sử dụng nhật ký do thiết bị di động tạo ra dùng trong quá trình ủy quyền. Đố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ì quá trình ủy 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ể dùng công cụ ADB để truy cập vào nhật ký do ứng dụng Google Home tạo trong suốt quá trình ủy quyền.

Cài đặt công cụ nền tảng

ADB là một phần của 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 bạn đã cài đặt thành công các công cụ nền tảng trên hệ thống của mình, hãy xác minh ADB bằng cách kiểm tra số phiên bản từ thiết bị đầu cuối 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 có bất kỳ lỗi nào.

Bật tính năng gỡ lỗi qua USB

Tiếp theo là bật tính năng gỡ lỗi USB trên thiết bị Android của bạn.

Trước tiên, hãy làm theo các bước để bật tùy chọn cho nhà phát triển trên thiết bị rồi bật tùy chọn gỡ lỗi USB.

Điều này cho phép ADB truy cập vào các nhật ký do ứng dụng hiện đang chạy trên thiết bị tạo ra.

Truy xuất ID thiết bị

  1. Chạy máy chủ ADB bằng lệnh sau:
$ adb start-server
  1. Kết nối điện thoại với máy tính chạy máy chủ ADB.

Bạn có thể nhận được thông báo cảnh báo trên điện thoại về tính năng gỡ lỗi USB, hỏi xem bạn có muốn cho phép máy tính của mình truy cập thông tin từ điện thoại của bạn không:

Lời nhắc gỡ lỗi qua USB

  1. 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.
  2. Ra lệnh thiết bị cho danh sách từ thiết bị đầu cuối để xem máy tính của bạn có thể truy cập điện thoại thông qua ADB hay không bằng cách sử dụng lệnh sau:
$ adb devices

Thao tác này sẽ đưa ra phản hồi tương tự như sau:

List of devices attached
<phone-id>    device

<phone-id> là một chuỗi gồm chữ và số giúp nhận dạng duy nhất thiết bị của bạn.

  1. 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 là 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ủa bạn.

  • 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 của ứ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ụ của Google Play:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
  • Cách kiểm tra xem bạn có mô-đun điều khiển Nhà / 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 đều được hệ sinh thái của chúng tôi hỗ trợ. Khi liên hệ để được hỗ trợ về các vấn đề liên quan đến phí hoa hồng, vui lòng đưa thông tin hệ thống vào phiếu yêu cầu hỗ trợ.

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 ủy quyền để tạo sự kiện lỗi mà bạn muốn gỡ lỗi.

  1. Chạy lệnh sau bằng cách cung cấp <phone-id>, cũng như <file-name> để nhật ký đượ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ẽ bắt đầu quá trình ghi nhật ký ngay lập tức. Tệp có tên được cung cấp sẽ được tạo nếu tệp này chưa tồn tại và nhật ký từ điện thoại được thêm vào tệp sau mỗi sự kiện.

Tiếp tục với các bước ủy quyền bằng thiết bị Matter.

  1. Sau khi gặp lỗi mà bạn muốn gỡ lỗi, hãy dừng quá trình ghi nhật ký bằng cách nhấn Control+C trong cửa sổ dòng lệnh đang chạy.

Nhật ký của bạn hiện sẽ được lưu trữ trong tệp ghi nhật ký <file-name>. Vì quá trình này ghi nhật ký từ mọi quá trình đang chạy được theo dõi trong thiết bị, sẽ có nhiều nhật ký trong tệp này. Đó là lý do tại sao bạn nên luôn sử dụng các nhật ký này bằng cách tìm kiếm các mục nhập bạn cần.

Phân tích nhật ký lỗi

Quá trình ủy quyền được xử lý thông qua một hệ thống con có tên là MatterỦy viên trong GHA.

  1. Sau khi sử dụng chiến lược chính được dùng khi phân tích lỗi uỷ quyền, hãy tìm các lỗi do hệ thống con MatterỦy thác tạo bằng lệnh sau:
$ grep "MatterCommissioner" <file-name>

Thao tác này sẽ tạo một kết quả chứa các sự kiện trong quá trình thử nghiệm.

  1. Nếu thiết bị Matter đang dùng Thread, bạn cũng có thể tìm các lỗi do hệ thống con Thread tạo bằng lệnh sau:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

Khi bạn phân tích tệp nhật ký được tạo bởi quá trình gỡ lỗi ADB, hãy tìm các mẫu nhất định. Rất nhiều lỗi chạy thử bao gồm chuỗi "commissioning failure" trong thông báo lỗi.

  1. Tìm kiếm thông báo lỗi thử nghiệm bằng lệnh sau:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. Gỡ lỗi các vấn đề về điều khiển thiết bị

Sau khi người dùng thiết lập và đưa thiết bị Matter vào hệ sinh thái Google Home, họ có thể dùng lệnh thoại qua Trợ lý Google (ví dụ: "Ok Google, bật đèn trong phòng khách của tôi") hoặc dùng giao diện người dùng trên ứng dụng Home hoặc thiết bị màn hình Google Nest.

Vì thông số kỹ thuật điều khiển giữa các thiết bị cuối và Google Hub do dàn xếp theo Matter được thiết lập nên dự kiến sẽ có ít lỗi hơn ở phía điều khiển thiết bị. Dù vậy, chúng tôi cũng cung cấp số liệu và nhật ký để bạn cũng gỡ lỗi các loại vấn đề này.

Sử dụng chỉ số

Trong Trang tổng quan về vấn đề tích hợp, bạn sẽ thấy một vài chỉ số về việc kiểm soát thiết bị. Có 3 biểu đồ quan trọng khi đánh giá hiệu suất của thiết bị ngoài thực tế:

Biểu đồ phân tích mức độ thành công, thời gian chờ và lỗi

Trong quá trình kiểm soát các vấn đề, bạn thường thấy xu hướng giảm trong tỷ lệ phần trăm thành công và xu hướng tăng trong biểu đồ phân tích lỗi. Biểu đồ phân tích lỗi cho bạn biết các lỗi do Google Nest Hub thu thập liên quan đến nguyên nhân khiến bạn không thể kiểm soát thiết bị.

Sử dụng nhật ký

Mỗi vấn đề về điều khiển thiết bị Matter cũng tạo ra 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 kiểm soát thiết bị theo chuẩn 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 nội dung của lỗi đó.

5. Gỡ lỗi các tính năng khác

Cho đến nay, bạn đã tìm hiểu được cách xử lý các vấn đề về việc vận hành thiết bị và điều khiển ứng dụng theo chuẩn Matter. Ngoài ra còn có các tính năng khác trong hệ sinh thái mà bạn có thể sử dụng các kỹ thuật đề xuất để đảm bảo tích hợp chất lượng tốt.

Theo dõi thông tin cập nhật về OTA

Để theo dõi bản phát hành của các 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 nhóm chỉ số cho biết phiên bản phần cứng và phần mềm cho các thiết bị trong thực tế.

Sau khi bạn phát hành bản cập nhật trên bảng điều khiển, hãy theo dõi các chỉ số sau:

Phân tích phần mềm và phần cứng

Bạn sẽ thấy rằng trong những ngày sau khi phát hành, ngày càng nhiều thiết bị trong lĩnh vực này nhận được phiên bản phần mềm mới liên quan đến bản phát hành phần mềm OTA của bạn.

6. Tìm hỗ trợ

Google cung cấp các công cụ và tài liệu giúp bạn khắc phục vấn đề về vấn đề này. Tuy nhiên, khi hệ sinh thái này còn mới, thì sẽ có một số vấn đề không đề cập đến. Trong trường hợp này, bạn luôn có thể liên hệ với chúng tôi hoặc cộng đồng để yêu cầu hỗ trợ.

Truy cập vào kênh của nhà phát triển

Có ba kênh dành cho nhà phát triển được chủ động theo dõi trong Google:

Stack Overflow, Trình theo dõi vấn đề, Diễn đàn dành cho nhà phát triển

Mặc dù mỗi kênh được theo dõi bởi cùng một nhóm theo định kỳ, có một số 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 các nhà phát triển Smart Home để đặt câu hỏi triển khai hoặc yêu cầu 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 theo dõi lỗi chính thức do Google điều hành, trong đó đối tượng bên ngoài có thể báo cáo lỗi trên hệ sinh thái. Dịch vụ 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. Tốt nhất là 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 dành cho nhà phát triển: Để nhận được hướng dẫn từ bộ phận hỗ trợ chính thức của Google và các chuyên gia cộng đồng, bạn có thể liên hệ với chúng tôi qua Diễn đàn dành cho nhà phát triển Nest. Diễn đàn này là phù hợp nhất để \ nhận hướng dẫn chính thức về 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 để tìm câu hỏi, chúng tôi cũng phát hành bản tin hàng quý nêu bật các tính năng mới và cung cấp tin tức về tình trạng hệ sinh thái nhà thông minh của Google.

Bạn có thể sử 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

Google Home

Xin chúc mừng! Bạn đã tìm hiểu cách gỡ lỗi tích hợp vấn đề theo chuẩn Matter bằng các công cụ và kỹ thuật mà chúng tôi đề xuất. Chúng tôi chúc bạn dành thời gian để xây dựng quá trình 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á thêm tài nguyên:

  • 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ộ thử nghiệm để kiểm tra việc tích hợp của bạn với mọi sự cố tiềm ẩn.
  • Sau khi công cụ tích hợp của bạn sẵn sàng chia sẻ với mọi người, bước tiếp theo là chuẩn bị để dự án của bạn được Chứng nhận WWGH. Để thực hiện việc này, bạn có thể làm theo các bước trong trang Giấy chứng nhận.