Khắc phục sự cố

Ứng dụng mẫu

Nếu gặp vấn đề khi sử dụng Home API, 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 cần Google trợ giúp, hãy thu thập nhật ký từ cả thiết bị Android và trung tâm, đồng thời mở một phiếu yêu cầu trong trình theo dõi vấn đề 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

Nếu bạn chưa thực hiện, hãy thiết lập Android Debug Bridge trên máy cục bộ:

1. Cài đặt "adb" trên máy tính.
2. Bật Tuỳ chọn cho nhà phát triển và 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 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.

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

Để tìm hiểu thêm và tải công cụ này, hãy xem 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 về 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ý. Bạn phải cung cấp thông tin này nếu cần chia sẻ vấn đề với Google.

1. Lấy mã nhận dạng của 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ả các biến vào một tệp có tên là _versions.txt:

   Mở rộng để hiện 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 đầu ra của 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 khi 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

   Để cửa sổ dòng lệnh 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ả cá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 một tệp có tên _logs.txt.

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

Tập lệnh nhật ký

Để thuận tiện cho bạn, Ứng dụng mẫu cung cấp các tập lệnh để lấy 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 để Google dễ dàng 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 của Ứng dụng mẫu. Thực hiện các bước sau đây từ thư mục gốc của dự án:

1. Lấy mã nhận dạng của 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 kịch bản.

Tập lệnh này 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 những thông tin này vào mọi báo cáo về 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 Google Nest Hub bằng phương thức này. Phương thức này được hỗ trợ cho các mẫu sau:

• Google Home
• Google Nest Audio
• Google Nest Hub
• Google Nest Mini

Cách bật một trung tâm truyền để truy xuất nhật ký cục bộ:

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 (nếu trung tâm 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 settings
     3. Tìm địa chỉ IP của thiết bị: Trên Nest Hub (2nd gen), hãy chuyển đến phầ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 settings để mở trang cài đặt
     3. Tìm địa chỉ IP của thiết bị: chuyển đến phần Thông tin thiết bị > Thông tin kỹ thuật > Địa chỉ IP

3. Trên máy tính kết nối với cùng mạng Wi-Fi như thiết bị:

     adb connect ip-address
     adb logcat
   

4. Để cung cấp nhật ký cho người khác, hãy thực hiện thao tác không thành công và chuyển hướng đầu ra đến 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

Các quy trình tự động hoá trong hệ sinh thái Google Home có tính năng phát hiện cạnh. Đây là logic xác minh rằng một điều kiện bắt đầu chỉ kích hoạt khi có thay đổi trạng thái thực tế, thay vì bản 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 điều kiện bắt đầu, thì tính năng phát hiện cạnh sẽ xác minh rằng điều kiện bắt đầu 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).

Tính năng tự động hoá không hoạt động như mong đợi

Sau khi tính đến việc 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 thiết bị hoạt động đúng cách mà không phụ thuộc vào hệ thống tự động hoá.

2. 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á của bạn để phát hiện mọi giả định có thể không chính xác về phía bạn.

3. Theo dõi 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ị mà quy trình tự động hoá tham chiếu đều có trong cấu trúc mà bạn muốn. Việc xoá một thiết bị mà một quy trình tự động hoá phụ thuộc vào có thể gây ra những hậu quả không mong muốn. Xem phần Ảnh hưởng của việc xoá thiết bị đối với các hoạt động 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 hoá chạy khi không nên, hãy xem xét các tiêu chí bắt đầu. Bạn có thể cần thêm logic bổ sung để đả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 quy tắc tự động một lần.

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

Đảm bảo ứng dụng của bạn chứa tất cả các nội dung 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 khác nhau cũng như các đặc điểm mà bạn đang tham chiếu.

Quy trình tự động hoá không vượt qua được bước xác thực

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 thông báo cảnh báo hoặc lỗi sẽ cung cấp thông tin về vấn đề. Để biết thêm thông tin, hãy tham khảo ValidationIssueType.

Hàm List sẽ gửi các ngoại lệ

Khi gọi hàm Automation API List, các 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. Kiểm tra để đả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 tự động hoá bằng mã nhận dạng của quy tắc tự động hoá:

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

Discovery API ghi lại cảnh báo khi một đặc điểm bị huỷ đăng ký

Nếu Discovery API ghi nhật ký cảnh báo cho Trait not found, điều này có nghĩa là API đang cố gắng sử dụng đặc điểm này cho các đề xuất trên Discovery, nhưng sẽ không thành công vì đặc điểm này chưa được đăng ký trong quá trình khởi tạo. 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 tạo ứ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 OAuth hiện có

Nếu đã có một ứng dụng OAuth được xác minh cho một ứng dụng đã xuất bản, bạn có thể dùng ứng dụng OAuth hiện có để kiểm thử Home API.

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

Bạn cần cân nhắc những điểm sau:

• Bạn chỉ được phép có tối đa 100 người dùng khi sử dụng một ứng dụng OAuth hiện có. Để biết thông tin về cách thêm người dùng kiểm thử, hãy tham khảo phầnThiết lập màn hình đồng ý OAuth. Ngoài quy trình xác minh OAuth, Home API còn áp đặt giới hạn 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 quy trình đăng ký Developer Console.

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

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

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