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

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

نموذج التطبيق

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

جمع سجلّات Android

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

تثبيت أداة adb

إذا لم يسبق لك إعداد Android Debug Bridge على جهازك، يمكنك اتّباع الخطوات التالية:

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

الحصول على رقم تعريف الجهاز الجوّال

احصل على رقم تعريف جهازك الجوّال:

adb devices

List of devices attached
device-id    device

يجب تخزين هذه القيمة في متغيّر باسم phoneid:
```
phoneid=device-id
```

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

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

حفظ معلومات الجهاز المختلفة في المتغيّرات:

containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep -m 1 "versionName" || true); ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep -m 1 "versionName" || true); androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true); androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true); chimeradump=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider || true); homemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.home" || true); optionalhomemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.optional_home" || true); threadinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.threadnetwork" || true); enabledfeatures=$(echo "$chimeradump" | grep "Enabled features" | grep -i "home" | sort -u || true)

احفظ جميع المتغيّرات في ملف باسم _versions.txt:

توسيع لعرض أوامر حفظ المتغيرات في ملف

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

versionfile="_versions.txt"
echo "Saving version info to $versionfile"
echo "Container version: $containerinfo" > $versionfile
echo "Home Module version: $homemoduleinfo" >> $versionfile
echo "Optional Home Module version: $optionalhomemoduleinfo" >> $versionfile
echo "Thread Module version: $threadinfo" >> $versionfile
echo "GHA version: $ghainfo" >> $versionfile
echo "Android version: $androidversion" >> $versionfile
echo "Android API version: $androidapiversion" >> $versionfile
echo "Found enabled features: $enabledfeatures" >> $versionfile

تحقَّق من محتوى _versions.txt:

cat _versions.txt

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

Container version:     versionName=26.26.34 (190400-945364269)
Home Module version:             com.google.android.gms.home [v262634001]
Optional Home Module version:         com.google.android.gms.optional_home [262634025] ...
Thread Module version:             com.google.android.gms.threadnetwork [v262634001]
GHA version:     versionName=4.22.28.0
Android version: 14
Android API version: 34
Found enabled features:             Enabled features: appsearch_impl, brella_dynamite, dck_management...

يمكن الآن تقديم هذا الملف إلى Google حسب الحاجة لتحديد المشاكل وحلّها.

تفعيل علامات تصحيح الأخطاء المطوَّلة

قبل جمع سجلّات أجهزة Android أو إنشاء تقرير خطأ، يجب ضبط حجم ذاكرة التخزين المؤقت للمسجِّل وتفعيل علامات تصحيح الأخطاء المطوَّلة لمكوّنات Google Home وخدمات Google للأجهزة الجوّالة:

# Clear existing device logs and expand logger buffer size
adb -s $phoneid logcat -b all -c
adb -s $phoneid logcat -G 8M

# Enable displaying seconds on the screen
adb -s $phoneid shell settings put secure clock_seconds 1

# Enable GMS Service ID verbose flags
adb -s $phoneid shell setprop log.tag.gms_svc_id:168 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:304 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:305 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:319 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:336 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:360 VERBOSE

# Enable GHP and Matter log tags
adb -s $phoneid shell setprop log.tag.CameraCommissioningPlugin VERBOSE
adb -s $phoneid shell setprop log.tag.HomeSdk VERBOSE
adb -s $phoneid shell setprop log.tag.HomeClient VERBOSE
adb -s $phoneid shell setprop log.tag.InteractionApiChimeraService VERBOSE
adb -s $phoneid shell setprop log.tag.MatterCommissioner VERBOSE
adb -s $phoneid shell setprop log.tag.SampleApp VERBOSE

جمع سجلّات Android باستخدام النصوص البرمجية

لتسجيل سجلّات أجهزة Android مباشرةً أثناء جلسة تصحيح الأخطاء، اتّبِع الخطوات التالية:

اتّبِع التعليمات الواردة في مقالة تفعيل علامات تصحيح الأخطاء المطوّلة لمحو السجلّات الحالية وتوسيع حجم ذاكرة التخزين المؤقت وضبط علامات التسجيل المطوّل.
أغلِق جميع التطبيقات قيد التشغيل على الجهاز الجوّال.
امسح بيانات التشويش الحالية في مخزن السجلّ المؤقت قبل بدء الاختبار:
```
adb -s $phoneid logcat -c
```
ابدأ عملية جمع السجلّات في نافذة المحطة الطرفية:
```
adb -s $phoneid logcat | tee android-logs_$(date +%Y%m%d%H%M%S).txt
```
اترك نافذة المحطة الطرفية هذه مفتوحة. سيؤدي ذلك إلى تسجيل السجلّات من جهازك طوال مدة تشغيل العملية.
شغِّل تطبيقك ونفِّذ جميع إجراءات واجهة المستخدم اللازمة لإعادة إنتاج المشكلة.
بعد الانتهاء، أوقِف عملية logcat في الوحدة الطرفية من خلال الضغط على Ctrl+C (أو Cmd+C على أجهزة Mac).
يتم حفظ السجلّات من هذه الجلسة في android-logs_YYYYMMDDmmss.txt. أرفِق كلاً من android-logs_YYYYMMDDmmss.txt و_versions.txt بأي تقارير أخطاء.

جمع سجلّات Android باستخدام تقرير الأخطاء في adb

يمكنك تسجيل تقرير خطأ كامل في Android عندما تحتاج إلى مشاركة معلومات تشخيصية تفصيلية تغطي المشاكل على مستوى النظام أو ملفات الذاكرة عند تعطّل البرنامج أو تصحيح أخطاء الشبكة والبلوتوث على مستوى منخفض:

إعداد Matter BLE: عند الإبلاغ عن مشكلة في إعداد Matter تتعلّق بـ BLE، فعِّل سجلّ التتبع لواجهة تحكم مضيف البلوتوث في "خيارات المطوّرين" (الإعدادات > خيارات المطوّرين > تفعيل سجلّ التتبع لواجهة تحكم مضيف البلوتوث) قبل إعادة إنتاج المشكلة.
الإعداد قبل الاختبار: قبل إجراء الاختبار، اتّبِع الخطوات الواردة في مقالة تفعيل علامات تصحيح الأخطاء المطوَّلة لتفعيل خصائص تصحيح الأخطاء المطوَّلة على جهازك.
تسجيل تقرير الخطأ: بعد إجراء الاختبار وإعادة إنتاج المشكلة، شغِّل الأمر التالي لإنشاء أرشيف كامل لتقرير الخطأ:
```
adb -s $phoneid bugreport ./android-bugreport_$(date +%Y%m%d%H%M%S).zip
```
معلومات تصحيح الأخطاء المتقدّمة: يحتوي ملف android-bugreport_YYYYMMDDmmss.zip الذي تم إنشاؤه على بيانات تشخيصية شاملة على مستوى النظام، بما في ذلك تفريغ كامل للنظام وإحصاءات الذاكرة وتشخيصات البطارية وتتبُّع الأنظمة الفرعية ذات المستوى المنخفض، ما يوفّر معلومات أكثر تقدّمًا لتصحيح الأخطاء.

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

يمكنك الاطّلاع على سجلّات جهاز Google Nest Hub باستخدام هذه الطريقة المتوافقة مع الطُرز التالية:

Google Home
Google Nest Audio
Google Nest Hub
Google Nest Mini

لتفعيل مركز Cast لاسترداد السجلّات المحلية:

إعداد Android Debug Bridge
احصل على عنوان IP الخاص بالموزّع:
- من جهاز Hub، إذا كان مزوّدًا بشاشة:
  1. التمرير سريعًا لأسفل الشاشة من أعلاها
  2. انقر على رمز الإعدادات
  3. للعثور على عنوان IP الخاص بالجهاز: على جهاز Nest Hub (2nd gen)، انتقِل إلى معلومات الجهاز > المعلومات الفنية > عنوان IP
- من تطبيق "GHA" على هاتفك:
  1. انقر على الجهاز لفتح صفحة تفاصيله
  2. انقر على رمز الإعدادات لفتح صفحة الإعدادات
  3. ابحث عن عنوان IP الخاص بالجهاز: انتقِل إلى معلومات الجهاز > المعلومات الفنية > عنوان IP
على جهاز كمبيوتر متصل بشبكة Wi-Fi نفسها التي يتصل بها الجهاز:
```
  adb connect ip-address
  adb logcat
```
لتقديم السجلّات إلى مستخدم، نفِّذ العملية التي يتعذّر إجراؤها وأرسِل الناتج إلى ملف نصي:
```
  adb logcat -d > platform-logs.txt
```

عمليات التشغيل الآلي

رصد الحواف

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

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

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

بعد مراعاة ميزة "رصد الحواف"، إذا لم تعمل عملية التشغيل الآلي على النحو المتوقّع، يُرجى اتّباع الخطوات التالية:

تحقّق من كل جهاز للتأكّد من أنه يعمل بشكل صحيح بشكل مستقل عن التشغيل الآلي.
ألقِ نظرة على الرسم البياني للأتمتة، وقارنه بلغة DSL الخاصة بالأتمتة، للكشف عن أي افتراضات قد تكون غير صحيحة من جانبك.
راقِب حالة الجهاز في تطبيق Google Home أثناء تنفيذ عملية التشغيل الآلي.
يُرجى التأكّد من أنّ جميع الأجهزة التي يشير إليها التشغيل الآلي موجودة في البنية التي تتوقّع أن تكون فيها. قد يؤدي حذف جهاز تعتمد عليه عملية تشغيل آلي إلى عواقب غير مقصودة. راجِع تأثير حذف الجهاز على عمليات التشغيل الآلي.

تبدأ عملية التشغيل الآلي في حالات غير مناسبة

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

لا يمكن تجميع عملية التشغيل الآلي

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

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

إذا لم تنجح عملية إنشاء التشغيل الآلي في اجتياز عملية التحقّق، ستظهر رسالة تحذير أو رسالة خطأ توفّر معلومات عن المشكلة. لمزيد من المعلومات، يُرجى الاطّلاع على مرجع ValidationIssueType.

دالة القائمة تطرح استثناءات

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

ولإجراء ذلك:

يُرجى التأكّد من تثبيت "adb". يُرجى الاطّلاع على تثبيت adb.

استخرِج معرّف عملية التشغيل الآلي من سجلّات 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"
...

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

adb logcat -s GhpNative level:debug | less

احذف قاعدة التشغيل الآلي باستخدام رقم تعريفها:

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

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

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

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

ملاحظة مهمة: لا تتوفّر Google Home Developer Console للتسجيل بعد.

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

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