Khắc phục sự cố

Ứng dụng mẫu

Nếu bạn gặp bất kỳ sự cố nào khi sử dụng API Trang chủ, 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, rồ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ộ của bạn:

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 ra dành 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 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

   Để nguyên terminal này mở. Thao tác này sẽ thu thập nhật ký từ thiết bị của bạn trong suốt quá trình.
3. Chạy ứng dụng mẫu và ghi lại mọi hành động trên giao diện người dùng. Khi hoàn tất, hãy dừng tiến trình logcat đang chạy trên thiết bị đầu cuối bằng cách nhấn Ctrl+C (hoặc Cmd+C trên máy Mac).
4. Nhật ký từ 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 trong tệp này theo nhiều cách khác nhau, bao gồm tìm kiếm các từ khóa 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ý có liên quan và biên dịch chúng thành tệp văn bản. Để cung cấp trải nghiệm gỡ lỗi tốt nhất, các nhật ký này phải được đính kèm vào bất kỳ lỗi nào được báo cáo để Google có thể 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 hiện các bước sau từ thư mục gốc của dự án:

1. Lấy ID của thiết bị di động của bạn:

   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 có liên quan. Đính kèm những thông tin này vào bất kỳ báo cáo nà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 đầu ra vào một tệp văn bản:

     adb logcat -d > platform-logs.txt
   

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 quy trình tự động hoá 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 khởi động, phát hiện cạnh sẽ xác minh rằng khởi động chỉ được kích hoạt nếu thiết bị đèn đó chuyển từ tắt sang bật, thay vì từ bật sang bật (không 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 quy trình 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á để phát hiện mọi giả định có thể không chính xác về phí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 hiện tự động hóa.

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 Tác độ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

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.

Tự động hóa 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 danh sách ném ngoại lệ

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

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

1. Kiểm tra để đảm bảo adb đã được cài đặt. Xem 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

   Ví dụ về nhật ký:

   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 xóa nhiều ID tự động hóa, bạn có thể sử dụng trình nhắn tin đầu cuối để kiểm soát đầu ra:

   adb logcat -s GhpNative level:debug | less

3. Xóa tự động hóa bằng cách sử dụng ID của tự động hóa:

   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 lại 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 cho các ứng viên Discovery, nhưng sẽ không thành công vì đặc điểm 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

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

Từ ví dụ này, RelativeHumidityControl cần được đăng ký trong quá trình khởi tạo ứng dụng. Tham khảo Đăng ký đặc điểm để thêm đặc điểm của bạn vào sổ đăng ký.

OAuth

Nếu bạn có một ứng dụng khách OAuth hiện có

Nếu bạn đã có ứng dụng khách OAuth được xác minh cho ứ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 tra API Trang chủ.

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 dỡ 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.