Khắc phục sự cố

Ứng dụng mẫu

Nếu gặp vấn đề khi sử dụng API Home, bạn có thể thu thập nhật ký để gỡ lỗi thêm. Để thu thập nhật ký từ thiết bị di động, bạn cần có Cầu gỡ lỗi Android (adb). Nếu bạn cần Google hỗ trợ, hãy thu thập nhật ký từ cả thiết bị Android và trung tâm điều khiển, sau đó mở một phiếu yêu cầu hỗ trợ trong trình theo dõi lỗi kèm theo thông tin và nhật ký liên quan.

Thu thập nhật ký Android

Thiết bị di động của bạn phải được kết nối với máy cục bộ cho tất cả các bước liên quan đến adb.

Cài đặt adb

Thiết lập Cầu gỡ lỗi Android trên máy cục bộ nếu bạn chưa thiết lập:

  1. Cài đặt "adb" trên máy tính.
  2. Bật Tuỳ chọn cho nhà phát triển và tính năng Gỡ lỗi qua USB trên điện thoại Android.

Trình bổ trợ Google Home cho Android Studio

Google Home Plugin for Android Studio là một công cụ hữu ích để thu thập và phân tích nhật ký, đồng thời được tạo riêng cho các nhà phát triển Google Home platform. Trình bổ trợ này cho phép bạn truy cập vào Google Assistant Simulator, Cloud Logging và các công cụ khác để đơn giản hoá quy trình phát triển smart home.

Sử dụng công cụ này cùng với adb để phân tích thêm các nhật ký thiết bị Matter.

Để tìm hiểu thêm và tải công cụ này, hãy xem phần Google Home Plugin for Android Studio.

Thông tin phiên bản

Bạn nên thu thập tất cả thông tin phiên bản liên quan đến chế độ thiết lập của mình bất cứ khi nào bạn quyết định thu thập nhật ký. Đây là yêu cầu bắt buộc nếu bạn cần chia sẻ vấn đề với Google.

  1. Lấy mã thiết bị di động:
    adb devices
    List of devices attached
    device-id    device
  2. Lưu trữ giá trị này trong một biến có tên là phoneid:
    phoneid=device-id
  3. Lưu nhiều thông tin về thiết bị vào các biến:
    containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep "versionName" || true);
    homemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home " || true);
    optionalhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.optional_home " || true);
    policyhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.policy_home" || true);
    threadinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork" || true);
    ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep versionName || true);
    enabledfeatures=$((adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "Enabled features" | grep -i "home") || true);
    androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true);
    androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true)
  4. Lưu tất cả biến vào một tệp có tên là _versions.txt:

    Mở rộng để hiển thị các lệnh lưu biến vào tệp

    Bạn có thể sao chép và dán toàn bộ khối vào một thiết bị đầu cuối cùng một lúc.

    versionfile=$logtimestamp"_versions.txt"
    echo "Saving version info to $versionfile"
    
    echo "Container version:" >> $versionfile
    echo $containerinfo >> $versionfile
    echo "" >> $versionfile
    
    echo "Home Module version:" >> $versionfile
    echo $homemoduleinfo >> $versionfile
    echo "" >> $versionfile
    
    echo "Optional Home Module version:" >> $versionfile
    echo $optionalhomemoduleinfo >> $versionfile
    echo "" >> $versionfile
    
    echo "Policy Home Module version:" >> $versionfile
    echo $policyhomemoduleinfo >> $versionfile
    echo "" >> $versionfile
    
    echo "Thread Module version:" >> $versionfile
    echo $threadinfo >> $versionfile
    echo "" >> $versionfile
    
    echo "GHA version:" >> $versionfile
    echo $ghainfo >> $versionfile
    echo "" >> $versionfile
    
    echo "Android version: " >> $versionfile
    echo $androidversion >> $versionfile
    echo "" >> $versionfile
    
    echo "Android API version: " >> $versionfile
    echo $androidapiversion >> $versionfile
    echo "" >> $versionfile
    
    echo "Found enabled features (blank if missing):" >> $versionfile
    echo $enabledfeatures >> $versionfile
    echo "" >> $versionfile
  5. Xác minh nội dung của _versions.txt:
    cat _versions.txt

    Mở rộng để hiển thị kết quả tệp mẫu

    Container version:
    versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)
    
    Home Module version:
    com.google.android.gms.home [v230508900]
    
    Optional Home Module version:
    
    
    Policy Home Module version:
    com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]
    
    Thread Module version:
    com.google.android.gms.threadnetwork [v231912000]
    
    GHA version:
    versionName=3.2.32.1
    
    Android version:
    13
    
    Android API version:
    33
    
    Found enabled features (blank if missing):
    Giờ đây, bạn có thể cung cấp tệp này cho Google nếu cần để khắc phục sự cố.

Thu thập nhật ký

Để thu thập nhật ký, hãy đóng tất cả ứng dụng đang chạy trên thiết bị di động. Sau đó:

  1. Mở cửa sổ dòng lệnh và xoá nhật ký thiết bị hiện có:
    adb logcat -b all -c
  2. Bắt đầu quy trình thu thập nhật ký:
    adb logcat >> _logs.txt
    Để thiết bị đầu cuối này mở. Thao tác này sẽ thu thập nhật ký từ thiết bị của bạn miễn là quá trình này đang chạy.
  3. Chạy ứng dụng mẫu và ghi lại tất cả thao tác trên giao diện người dùng. Sau khi hoàn tất, hãy dừng quy trình logcat đang chạy trên thiết bị đầu cuối bằng cách nhấn tổ hợp phím Ctrl+C (hoặc Cmd+C trên máy Mac).
  4. Nhật ký của phiên này được lưu trong tệp có tên _logs.txt.

Bạn có thể phân tích thông tin trên tệp này theo nhiều cách, bao gồm cả việc tìm kiếm từ khoá như error, exception hoặc crash.

Nhật ký tập lệnh

Để thuận tiện cho bạn, ứng dụng mẫu cung cấp các tập lệnh để lấy các nhật ký liên quan và biên dịch các nhật ký đó thành một tệp văn bản. Để mang lại trải nghiệm gỡ lỗi tốt nhất, bạn nên đính kèm những nhật ký này vào mọi lỗi được báo cáo để tạo điều kiện cho Google phân tích nguyên nhân gốc rễ.

Các nhật ký này nằm trong thư mục scripts trong cây nguồn ứng dụng mẫu. Để thực thi các lệnh này, hãy làm theo các bước dưới đây từ thư mục gốc của dự án:

  1. Lấy mã thiết bị di động:
    adb devices -l
    List of devices attached
    device-id device
  2. Chạy tập lệnh get_logs.sh:
     ./scripts/get_logs.sh device-id
    Cleared previous logs from device.
    Saving version information to home_api_sample_logs_20240605233243.txt...
    Saving logs to home_api_sample_logs_20240605233243.txt...
    (Press CTRL+C to stop the script)
  3. Tái hiện vấn đề.
  4. Nhấn CTRL+C để dừng tập lệnh.

Tập lệnh sẽ tạo một tệp nhật ký có dấu thời gian chứa tất cả thông tin liên quan. Đính kèm các tệp này vào mọi báo cáo lỗi mà bạn gặp phải.

Nhật ký thiết bị trung tâm truyền

Bạn có thể xem nhật ký thiết bị cho trung tâm nhà thông minh của Google bằng cách làm như sau:

  1. Thiết lập Cầu gỡ lỗi Android.
  2. Lấy địa chỉ IP của trung tâm:

    • Trên trung tâm điều khiển (nếu có màn hình):
      1. Vuốt xuống từ đầu màn hình
      2. Nhấn vào biểu tượng Cài đặt
      3. Tìm địa chỉ IP của thiết bị: Trên Nest Hub (2nd gen), hãy chuyển đến Thông tin thiết bị > Thông tin kỹ thuật > Địa chỉ IP
    • Từ GHA trên điện thoại:
      1. Nhấn vào thiết bị để mở trang chi tiết về thiết bị
      2. Nhấn vào biểu tượng Cài đặt để mở trang cài đặt
      3. Tìm địa chỉ IP của thiết bị: chuyển đến Thông tin thiết bị > Thông tin kỹ thuật > Địa chỉ IP
  3. Trên máy tính sử dụng cùng một mạng Wi-Fi với thiết bị:

      adb connect ip-address
      adb logcat
    

  4. Để cung cấp nhật ký cho một người nào đó, hãy thực hiện thao tác không thành công và chuyển đầu ra sang một tệp văn bản:

      adb logcat -d > platform-logs.txt
    

Chế độ tự động hoá

Phát hiện đường viền

Tính năng tự động hoá trong hệ sinh thái Google Home có tính năng phát hiện cạnh. Đây là logic đảm bảo rằng trình khởi động chỉ kích hoạt khi có thay đổi trạng thái thực tế, thay vì cập nhật trạng thái chỉ lặp lại trạng thái trước đó của thiết bị.

Ví dụ: nếu bật đèn là một trình khởi động, thì tính năng phát hiện cạnh sẽ đảm bảo rằng trình khởi động chỉ kích hoạt nếu thiết bị đèn đó chuyển từ trạng thái tắt sang bật, thay vì từ trạng thái bật sang bật (không có thay đổi).

Quy trình tự động hoá không hoạt động như mong đợi

Sau khi tính đến tính năng phát hiện cạnh, nếu một quy trình tự động hoá không hoạt động như mong đợi:

  1. Kiểm tra từng thiết bị để đảm bảo rằng thiết bị đó hoạt động đúng cách, độc lập với tính năng tự động hoá của bạn.

  2. Hãy xem biểu đồ tự động hoá cho quy trình tự động hoá của bạn, so sánh biểu đồ đó với DSL tự động hoá để tiết lộ mọi giả định có thể không chính xác của bạn.

  3. Quan sát trạng thái thiết bị trong ứng dụng Google Home trong quá trình thực thi quy trình tự động hoá.

  4. Kiểm tra để đảm bảo rằng tất cả các thiết bị được tham chiếu bởi tính năng tự động hoá đều có trong cấu trúc mà bạn mong đợi. Việc xoá một thiết bị mà quy trình tự động hoá phụ thuộc vào đó có thể gây ra những hậu quả ngoài mong muốn. Xem bài viết Tác động của việc xoá thiết bị đối với quy trình tự động hoá.

Quy trình tự động hoá chạy khi không nên chạy

Nếu quy trình tự động chạy khi không nên chạy, hãy kiểm tra các tiêu chí khởi động. Bạn có thể cần thêm logic để đảm bảo rằng một thay đổi về trạng thái chỉ được ghi lại một lần và chỉ kích hoạt quá trình tự động hoá một lần.

Quy trình tự động hoá không biên dịch

Đảm bảo rằng ứng dụng của bạn chứa tất cả các tệp nhập cần thiết, bao gồm cả từng lớp tương ứng với các loại nút cũng như các đặc điểm mà bạn đang tham chiếu.

Không xác thực được quá trình tạo quy trình tự động

Nếu quá trình tạo quy trình tự động hoá không vượt qua quy trình xác thực, thì một cảnh báo hoặc thông báo lỗi sẽ cung cấp thông tin về vấn đề. Để biết thêm thông tin, hãy tham khảo tài liệu tham khảo về ValidationIssueType.

Hàm List gửi ngoại lệ

Khi gọi hàm Danh sách API tự động hoá, trình xử lý đọc có thể gửi ngoại lệ do thiếu các tính năng API. Để giảm thiểu vấn đề này, hãy xoá quy trình tự động hoá bị ảnh hưởng.

Để thực hiện việc này:

  1. Đảm bảo bạn đã cài đặt adb. Xem phần Cài đặt adb.
  2. Truy xuất mã nhận dạng của quy trình tự động hoá từ nhật ký Android bằng cách gọi:

    adb logcat -s GhpNative

    Nhật ký mẫu:

    adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse
    
    INTERACTION RESPONSE -> SendCommandsResponse:
    1 {
    1: "automation@global"
    3 {
      1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
      2:
      5 {
        1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
        1 {
            1: "1111-2222-3333-44444-55555" // Automation ID to delete
            2: "structure@2222-3333-4444-5555-6666"
    ...

    Nếu cần xoá nhiều mã nhận dạng tự động hoá, bạn có thể sử dụng trình phân trang của thiết bị đầu cuối để kiểm soát đầu ra:

    adb logcat -s GhpNative level:debug | less
  3. Xoá quy tắc của thao tác tự động bằng mã của quy tắc đó:

    structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))
    

API Khám phá ghi lại cảnh báo khi một đặc điểm không được đăng ký

Nếu API Khám phá ghi lại cảnh báo cho Trait not found, thì điều này có nghĩa là API đang cố gắng sử dụng đặc điểm cho các đề xuất Khám phá, nhưng sẽ không thành công vì đặc điểm này không được đăng ký trong quá trình khởi chạy. Ví dụ:

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

Giá trị nhận dạng đặc điểm là home.matter.6006.clusters.fc43, tương ứng với RelativeHumidityControl. Để xác định tên đặc điểm từ một mã nhận dạng, hãy xem Chỉ mục đặc điểm.

Trong ví dụ này, bạn cần đăng ký RelativeHumidityControl trong quá trình khởi chạy ứng dụng. Hãy tham khảo phần Đăng ký đặc điểm để thêm đặc điểm vào sổ đăng ký.

OAuth

Nếu bạn đã có ứng dụng khách OAuth

Nếu đã có ứng dụng khách OAuth đã xác minh cho một ứng dụng đã phát hành, bạn có thể sử dụng ứng dụng khách OAuth hiện có để kiểm thử API Home.

Bạn không cần đăng ký Google Home Developer Console để kiểm thử và sử dụng các API Home. Tuy nhiên, bạn vẫn cần có một lượt đăng ký Developer Console đã được phê duyệt để phát hành ứng dụng, ngay cả khi bạn có một ứng dụng khách OAuth đã xác minh từ một công cụ tích hợp khác.

Bạn cần cân nhắc những điều sau:

  • Có giới hạn 100 người dùng khi sử dụng ứng dụng OAuth hiện có. Để biết thông tin về cách thêm người dùng thử nghiệm, hãy tham khảo phần Thiết lập màn hình đồng ý OAuth. Ngoài quy trình xác minh OAuth, API Home còn áp dụng giới hạn là 100 người dùng có thể cấp quyền cho ứng dụng của bạn. Hạn chế này sẽ được gỡ bỏ sau khi bạn hoàn tất việc đăng ký Developer Console.

  • Bạn nên gửiDeveloper Console đăng ký để được phê duyệt khi bạn đã sẵn sàng hạn chế các khoản cấp theo loại thiết bị thông qua OAuth để chuẩn bị cập nhật ứng dụng bằng API Home.

Đối với các ứng dụng Google Cloud vẫn đang chờ xác minh OAuth, người dùng không thể hoàn tất luồng OAuth cho đến khi quá trình xác minh hoàn tất. Bạn sẽ không cấp được quyền với lỗi sau:

Access blocked: <Project Name> has not completed the Google verification process.