تحديد المشاكل وحلّها

نموذج تطبيق

إذا واجهت أي مشاكل عند استخدام Home APIs، يمكنك جمع السجلات لإجراء المزيد من عمليات تصحيح الأخطاء. يتطلب جمع السجلات من الجهاز الجوّال استخدام أداة Android Debug Bridge (adb). إذا كنت بحاجة إلى مساعدة من Google، يمكنك جمع السجلات من أجهزة Android والمركز وفتح طلب دعم في أداة تتبُّع المشاكل مع تحديد المعلومات ذات الصلة والسجلّات المرتبطة بها.

جمع سجلات Android

يجب أن يكون جهازك الجوّال متصلاً بجهاز الكمبيوتر لتنفيذ جميع الخطوات التي تتضمّن adb.

تثبيت adb

عليك إعداد Android Debug Bridge على جهازك إذا لم يسبق لك إجراء ذلك:

  1. ثبِّت "adb" على جهاز الكمبيوتر.
  2. فعِّل خيار "خيارات المطوّرين" وميزة "تصحيح أخطاء الجهاز عبر USB" على هاتف Android.

المكوّن الإضافي Google Home لـ "استوديو Android"

‫Google Home Plugin for Android Studio هي أداة مفيدة لجمع السجلّات وتحليلها، وقد تم إنشاؤها خصيصًا لمطوّري Google Home platform. يتيح لك هذا الإضافة الوصول إلى Google Assistant Simulator و"تسجيل في السحابة الإلكترونية" وغيرها من الأدوات لتوفير عملية تطوير smart home.

استخدِم هذه الأداة مع adb لتحليل سجلات جهاز Matter بشكل أكبر.

لمزيد من المعلومات والحصول على الأداة، يُرجى الاطّلاع على Google Home Plugin for Android Studio.

معلومات الإصدار

ننصحك بجمع كل معلومات الإصدار ذات الصلة بالإعدادات كلما قرّرت جمع السجلات. هذا الإجراء مطلوب إذا كنت بحاجة إلى مشاركة المشاكل مع Google.

  1. الحصول على رقم تعريف جهازك الجوّال: 
    adb devices
     
    List of devices attached
device-id    device
  2. تخزين هذه القيمة في متغيّر يُسمى phoneid: 
    phoneid=device-id
  3. حفظ معلومات الجهاز المختلفة في المتغيّرات: 
    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. احفظ جميع المتغيّرات في ملف باسم _versions.txt:

    يُرجى النقر هنا لإظهار الأوامر لحفظ المتغيرات في ملف.

    يمكن نسخ الكتلة بأكملها ولصقها في وحدة تحكّم في المحطة الطرفية في آنٍ واحد.

    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. يُرجى التحقّق من محتوى _versions.txt: 
    cat _versions.txt

    توسيع القسم لعرض نموذج إخراج الملف

    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):
    يمكن الآن تقديم هذا الملف إلى Google حسب الحاجة لتحديد المشاكل وحلّها.

جمع السجلات

لجمع السجلات، أغلِق جميع التطبيقات التي تعمل على الجهاز الجوّال. بعد ذلك:

  1. افتح نافذة طرفية وأزِل سجلات الجهاز الحالية: 
    adb logcat -b all -c
  2. ابدأ عملية جمع السجلّات: 
    adb logcat >> _logs.txt
     اترك هذه المحطة الطرفية مفتوحة. سيؤدي ذلك إلى جمع السجلات من جهازك ما دامت العملية قيد التنفيذ.
  3. شغِّل نموذج التطبيق وسجِّل جميع إجراءات واجهة المستخدم. بعد الانتهاء، يمكنك إيقاف عملية logcat التي تعمل على وحدة التحكّم عن بُعد من خلال الضغط على Ctrl+C (أو Cmd+C على نظام التشغيل Mac).
  4. يتم حفظ السجلات من هذه الجلسة في ملف باسم _logs.txt.

يمكنك تحليل المعلومات الواردة في هذا الملف بطرق مختلفة، بما في ذلك البحث عن كلمات رئيسية مثل error أو exception أو crash.

النصوص البرمجية لتسجيل الأحداث

لتسهيل الأمر عليك، يقدّم نموذج التطبيق نصوصًا برمجية للحصول على ملفّات log ذات الصلة وتجميعها في ملف نصي. لتقديم أفضل تجربة تصحيح أخطاء، يجب إرفاق هذه السجلّات بأي أخطاء تم الإبلاغ عنها لتسهيل تحليل Google للسبب الأساسي.

تتوفّر هذه السجلات في دليل scripts ضمن شجرة مصدر التطبيق النموذجية. لتنفيذها، اتّبِع الخطوات التالية من الدليل الجذر للمشروع:

  1. الحصول على رقم تعريف جهازك الجوّال: 
    adb devices -l
     
    List of devices attached
device-id device
  2. شغِّل النص البرمجي 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. أعِد إظهار المشكلة.
  4. اضغط على CTRL+C لإيقاف النص البرمجي.

سيُنشئ النص البرمجي ملف سجلّ مزوّدًا بطابع زمني يحتوي على كل المعلومات ذات الصلة. يُرجى إرفاق هذه المعلومات بأي تقارير عن الأخطاء التي تواجهها.

سجلات أجهزة مركز البث

يمكنك الاطّلاع على سجلات الأجهزة لمركز Google من خلال اتّباع الخطوات التالية:

  1. إعداد Android Debug Bridge

  2. الحصول على عنوان IP الخاص بمركز التحكّم:

    • من المحور، إذا كان يحتوي على شاشة:
      1. التمرير سريعًا لأسفل الشاشة من أعلاها
      2. انقر على رمز الإعدادات .
      3. العثور على عنوان IP للجهاز: على Nest Hub (2nd gen)، انتقِل إلى معلومات الجهاز > المعلومات الفنية > عنوان IP.
    • من GHA على هاتفك:
      1. انقر على الجهاز لعرض صفحة تفاصيله.
      2. انقر على رمز الإعدادات لعرض صفحة الإعدادات.
      3. العثور على عنوان IP للجهاز: انتقِل إلى معلومات الجهاز > المعلومات الفنية > عنوان IP.

  3. على جهاز كمبيوتر متصل بشبكة Wi-Fi نفسها التي يتصل بها الجهاز: 

      adb connect ip-address
  adb logcat

  4. لتقديم السجلات لشخص ما، عليك تنفيذ العملية التي تؤدي إلى حدوث خطأ و توجيه الإخراج إلى ملف نصي: 

      adb logcat -d > platform-logs.txt

عمليات التشغيل المبرمَج

رصد الحواف

تتضمن الإجراءات المبرمَجة في المنظومة المتكاملة لأجهزة Google Home ميزة رصد الحدود، وهو منطق يضمن عدم بدء تشغيل الجهاز إلا عند حدوث تغيير فعلي في حالته، بدلاً من تحديث الحالة الذي يكرر ببساطة الحالة السابقة للجهاز.

على سبيل المثال، إذا كان تشغيل الإضاءة هو عنصر بدء، تضمن ميزة رصد الحواف تفعيل العنصر البدء فقط إذا تم تشغيل جهاز الإضاءة من وضع الإيقاف إلى وضع التشغيل، بدلاً من التشغيل من وضع التشغيل إلى وضع التشغيل (بدون تغيير).

لا تعمل ميزة التشغيل الآلي على النحو المتوقّع

بعد مراعاة ميزة رصد الحواف، إذا لم تتصرف إحدى الإجراءات المبرمَجة بالشكل المتوقع:

  1. تحقَّق من كل جهاز للتأكّد من أنّه يعمل بشكل صحيح بغض النظر عن عملية التشغيل الآلي.

  2. اطّلِع على الرسم البياني للتشغيل الآلي لمشروعك، وقارِنه بـ DSL للتشغيل الآلي، وذلك للكشف عن أي افتراضات قد تكون غير صحيحة من جانبك.

  3. راقِب حالة الجهاز في تطبيق Google Home أثناء تنفيذ عملية التشغيل الآلي.

  4. تأكَّد من أنّ جميع الأجهزة التي يشير إليها الإجراء المبرمَج متوفرة في البنية التي تتوقّع أن تكون فيها. قد يؤدي حذف جهاز يعتمد عليه أحد الإجراءات المبرمَجة إلى عواقب غير مقصودة. اطّلِع على تأثير حذف الجهاز على الإجراءات المبرمَجة.

يتم تشغيل ميزة التشغيل الآلي عندما لا يُفترض أن يتم تشغيلها

إذا كان التشغيل التلقائي يتم في وقت غير مناسب، راجِع معايير البدء. قد يكون من الضروري إضافة منطق إضافي لضمان تسجيل أي تغيير في الحالة مرة واحدة فقط وبدء التشغيل الآلي مرة واحدة فقط.

لا يتم تجميع ميزة التشغيل الآلي

تأكَّد من أنّ تطبيقك يحتوي على جميع عمليات الاستيراد اللازمة، بما في ذلك كل فئة تتوافق مع أنواع العقد المختلفة بالإضافة إلى السمات التي تتم إحالتك إليها.

تعذّر التحقّق من صحة عملية إنشاء التشغيل الآلي

إذا لم يجتَز إنشاء الإجراء المبرمَج عملية التحقّق، ستعرض رسالة تحذير أو خطأ معلومات عن المشكلة. لمزيد من المعلومات، يُرجى الرجوع إلى مرجع ValidationIssueType.

تعرِض دالة القائمة استثناءات

عند استدعاء دالة Automation API List، قد تُلقي معالجات القراءة استثناءات بسبب عدم توفّر ميزات واجهة برمجة التطبيقات. للحدّ من هذا التأثير، عليك حذف الإجراء المبرمَج المتأثّر.

ولإجراء ذلك:

  1. تأكَّد من تثبيت adb. راجِع مقالة تثبيت adb.

  2. استرداد معرّف التشغيل الآلي من سجلات Android من خلال استدعاء:

    adb logcat -s GhpNative

    أمثلة على السجلّات:

    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"
...

    إذا كنت بحاجة إلى حذف أرقام تعريف متعدّدة للتشغيل الآلي، يمكنك استخدام أداة التنقّل في المحطة الطرفية للتحكّم في الإخراج:

    adb logcat -s GhpNative level:debug | less

  3. يمكنك حذف الإجراء المبرمَج باستخدام رقم تعريفه:

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

تسجيل تحذير في Discovery API عند إلغاء تسجيل سمة

إذا سجّلت واجهة برمجة التطبيقات Discovery API تحذيرًا بشأن Trait not found، يعني ذلك أنّ واجهة برمجة التطبيقات تحاول استخدام السمة لمرشحي ميزة "اقتراحات"، ولكن لن يتمكّن الإجراء من التمام لأنّه لم يتم تسجيل السمة أثناء الإعداد. على سبيل المثال:

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

معرّف السمة هو home.matter.6006.clusters.fc43، والذي يتوافق مع RelativeHumidityControl. لتحديد اسم السمة من رقم تعريف، اطّلِع على فهرس السمات.

من هذا المثال، يجب تسجيل RelativeHumidityControl أثناء بدء تشغيل التطبيق. راجِع مقالة تسجيل السمات لإضافة سمتك إلى السجلّ.

OAuth

إذا كان لديك عميل OAuth حالي

إذا كان لديك عميل OAuth تم إثبات ملكيته لتطبيق منشور، يمكنك استخدام عميل OAuth الحالي لاختبار واجهات برمجة تطبيقات Home.

ليس من الضروري تسجيل Google Home Developer Console لاختبار واجهات برمجة التطبيقات Home API واستخدامها. ومع ذلك، سيظلّ عليك الحصول على تسجيل Developer Console تمت الموافقة عليه لنشر تطبيقك، حتى إذا كان لديك ملف تعريف عميل OAuth تم التحقّق منه من عملية دمج أخرى.

تنطبق الاعتبارات التالية:

  • هناك حد أقصى يبلغ 100 مستخدم عند استخدام ملف شخصي حالي لبروتوكول OAuth. للحصول على معلومات عن إضافة مستخدمين تجريبيين، يُرجى الرجوع إلى مقالة إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth. بغض النظر عن عملية إثبات الهوية باستخدام OAuth، هناك حد أقصى لعدد المستخدمين الذين يمكنهم منح أذونات لتطبيقك، وهو 100 مستخدم، وهو الحد الذي تفرضه Home APIs. يتم رفع هذا القيد عند إكمال عملية تسجيل Developer Console.

  • Developer Console تسجيل : يجب إرساله للموافقة عندما تكون مستعدًا لتقييد منح الأذونات لأنواع الأجهزة من خلال OAuth استعدادًا لتعديل تطبيقك باستخدام واجهات برمجة تطبيقات Home.

بالنسبة إلى Google Cloud تطبيقًا لا تزال عملية إثبات الملكية باستخدام OAuth في انتظار المراجعة، لا يمكن للمستخدمين إكمال عملية OAuth إلى أن تكتمل عملية إثبات الملكية. ستتعذّر محاولات منح الأذونات وستظهر رسالة الخطأ التالية:

Access blocked: <Project Name> has not completed the Google verification process.
السابق
خطأ أثناء المعالجة
التالي
واجهة برمجة التطبيقات قيد التشغيل