عیب یابی

نمونه برنامه

اگر هنگام استفاده از APIهای Home با مشکلی مواجه شدید، می‌توانید گزارش‌ها را برای اشکال‌زدایی بیشتر جمع‌آوری کنید. جمع‌آوری گزارش‌ها از دستگاه تلفن همراه به پل اشکال‌زدایی Android ( adb ) نیاز دارد. اگر به کمک Google نیاز دارید، گزارش‌ها را هم از دستگاه‌های Android و هم از هاب جمع‌آوری کنید و بلیتی را با اطلاعات مربوطه و گزارش‌های مرتبط با آن در ردیاب مشکل باز کنید.

لاگ های اندروید را جمع آوری کنید

دستگاه همراه شما باید برای تمام مراحل مربوط به adb به دستگاه محلی شما متصل باشد.

adb رو نصب کن

اگر قبلاً این کار را نکرده اید، Android Debug Bridge را در دستگاه محلی خود راه اندازی کنید:

  1. "adb" را روی رایانه خود نصب کنید .
  2. Developer Options و USB Debugging را در گوشی Android خود روشن کنید .

افزونه Google Home برای اندروید استودیو

Google Home Plugin for Android Studio ابزاری مفید برای جمع آوری و تجزیه و تحلیل گزارش ها است و به طور خاص برای توسعه دهندگان Google Home platform ایجاد شده است. این افزونه به شما امکان دسترسی به Google Assistant Simulator ، Cloud Logging و سایر ابزارها را می دهد تا فرآیند توسعه 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):
    اکنون می توان این فایل را در صورت نیاز برای عیب یابی در اختیار گوگل قرار داد.

سیاهههای مربوط را جمع آوری کنید

برای جمع‌آوری گزارش‌ها، همه برنامه‌هایی را که در دستگاه تلفن همراه در حال اجرا هستند، ببندید. سپس:

  1. یک پنجره ترمینال را باز کنید و سیاهه های موجود دستگاه را پاک کنید: 
    adb logcat -b all -c
  2. فرآیند جمع آوری گزارش را شروع کنید:
    adb logcat >> _logs.txt
     این ترمینال را باز بگذارید. تا زمانی که این فرآیند در حال اجرا باشد، گزارش‌ها را از دستگاه شما جمع‌آوری می‌کند.
  3. برنامه نمونه را اجرا کنید و تمام اقدامات رابط کاربری را ضبط کنید. پس از اتمام کار، با فشردن کلیدهای Ctrl+C (یا Cmd+C در مک)، فرآیند logcat در حال اجرا در ترمینال را متوقف کنید.
  4. گزارش‌های این جلسه در فایلی با نام _logs.txt ذخیره می‌شوند.

می‌توانید اطلاعات این فایل را با روش‌های مختلف، از جمله جستجوی کلمات کلیدی مانند error ، exception یا crash تجزیه و تحلیل کنید.

اسکریپت های لاگ

برای راحتی شما، برنامه نمونه اسکریپت هایی را برای به دست آوردن گزارش های مربوطه ارائه می دهد و آنها را در یک فایل متنی کامپایل می کند. برای ارائه بهترین تجربه اشکال‌زدایی، این گزارش‌ها باید به هر گونه اشکال گزارش شده پیوست شوند تا تجزیه و تحلیل علت اصلی توسط 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 را فشار دهید تا اسکریپت متوقف شود.

اسکریپت یک فایل log مهر زمانی ایجاد می کند که حاوی تمام اطلاعات مربوطه است. این موارد را به گزارشات مربوط به اشکالاتی که با آنها برخورد می کنید، پیوست کنید.

گزارش‌های دستگاه مرکز ارسال

با انجام کارهای زیر می توانید گزارش های دستگاه را برای هاب 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 مراجعه کنید.

تابع لیست استثناها را پرتاب می کند

هنگام فراخوانی تابع فهرست API اتوماسیون، کنترل کننده های خواندن ممکن است به دلیل از دست دادن ویژگی های API استثناهایی ایجاد کنند. برای کاهش این موضوع، اتوماسیون آسیب دیده را حذف کنید.

برای انجام این کار:

  1. مطمئن شوید که adb نصب کرده اید. به نصب adb مراجعه کنید.

  2. شناسه اتوماسیون را از لاگ های اندروید با فراخوانی بازیابی کنید: 

    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 ثبت کند، به این معنی است که API سعی می‌کند از این ویژگی برای کاندیدهای Discovery استفاده کند، اما موفق نمی‌شود زیرا این ویژگی در طول اولیه‌سازی ثبت نشده است. به عنوان مثال: 

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 موجود خود برای آزمایش API های Home استفاده کنید.

ثبت نام Google Home Developer Console برای آزمایش و استفاده از APIهای Home لازم نیست. با این حال، حتی اگر یک سرویس گیرنده OAuth تأیید شده از ادغام دیگری داشته باشید، همچنان برای انتشار برنامه خود به ثبت نام Developer Console تأیید شده نیاز دارید.

ملاحظات زیر اعمال می شود:

  • هنگام استفاده از یک سرویس گیرنده OAuth موجود، یک محدودیت 100 کاربر وجود دارد. برای اطلاعات در مورد افزودن کاربران آزمایشی، به تنظیم صفحه رضایت OAuth مراجعه کنید. مستقل از تأیید OAuth، محدودیت 100 کاربر توسط Home API تحمیل شده است که می توانند به برنامه شما مجوز دهند. این محدودیت با تکمیل ثبت نام Developer Console برداشته می شود.

  • ثبت نام Developer Console باید زمانی برای تأیید ارسال شود که برای آماده‌سازی برای به‌روزرسانی برنامه خود با APIهای Home آماده باشید تا کمک هزینه‌های نوع دستگاه را از طریق OAuth محدود کنید.

برای برنامه‌های Google Cloud که هنوز در انتظار تأیید OAuth هستند، کاربران نمی‌توانند جریان OAuth را تکمیل کنند تا اینکه تأیید کامل شود. تلاش برای اعطای مجوز با خطای زیر ناموفق خواهد بود: 

Access blocked: <Project Name> has not completed the Google verification process.
قبلی
API مجوزها
بعدی
راه اندازی API