این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

عیب یابی

نمونه برنامه

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

جمع‌آوری گزارش‌های اندروید

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

نصب adb

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

"adb" را روی رایانه خود نصب کنید .
گزینه‌های توسعه‌دهنده (Developer Options) و اشکال‌زدایی USB را در گوشی Android خود فعال کنید .

افزونه گوگل هوم برای اندروید استودیو

Google Home Plugin for Android Studio ابزاری مفید برای جمع‌آوری و تحلیل لاگ‌ها است و به‌طور خاص برای توسعه‌دهندگان Google Home platform ساخته شده است. این افزونه به شما امکان دسترسی به Google Assistant Simulator ، Cloud Logging و سایر ابزارها را برای ساده‌سازی فرآیند توسعه smart home می‌دهد.

از این ابزار به همراه adb برای تجزیه و تحلیل بیشتر لاگ‌های دستگاه Matter استفاده کنید.

برای کسب اطلاعات بیشتر و دریافت این ابزار، به Google Home Plugin for Android Studio مراجعه کنید.

اطلاعات نسخه

توصیه می‌کنیم هر زمان که تصمیم به جمع‌آوری گزارش‌ها گرفتید، تمام اطلاعات نسخه مربوط به تنظیمات خود را جمع‌آوری کنید. این کار در صورتی که نیاز به اشتراک‌گذاری مشکلات با گوگل داشته باشید، ضروری است.

شناسه دستگاه تلفن همراه خود را دریافت کنید:
```
adb devices
```
```
List of devices attached
device-id    device
```
این مقدار را در متغیری به نام phoneid ذخیره کنید:
```
phoneid=device-id
```

ذخیره اطلاعات مختلف دستگاه در متغیرها:

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)

تمام متغیرها را در فایلی با نام _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

محتوای فایل _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):

اکنون می‌توان این فایل را در صورت نیاز برای عیب‌یابی در اختیار گوگل قرار داد.

جمع‌آوری لاگ‌ها

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

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

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

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

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

این لاگ‌ها در دایرکتوری scripts در درخت سورس Sample App قرار دارند. مراحل زیر را از دایرکتوری ریشه پروژه اجرا کنید:

شناسه دستگاه تلفن همراه خود را دریافت کنید:
```
adb devices -l
```
```
List of devices attached
device-id device
```

اسکریپت 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)

مسئله را بازنشر کنید.
برای متوقف کردن اسکریپت CTRL+C را فشار دهید.

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

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

می‌توانید گزارش‌های دستگاه را برای هاب Google Nest خود با استفاده از این روش مشاهده کنید، که برای مدل‌های زیر پشتیبانی می‌شود:

Google Home
Google Nest Audio
Google Nest Hub
Google Nest Mini

برای فعال کردن یک هاب Cast برای بازیابی گزارش‌های محلی:

پل اشکال‌زدایی اندروید را راه‌اندازی کنید .
آدرس IP هاب خود را دریافت کنید:
- از هاب، اگر صفحه نمایش داشته باشد:
  1. از بالای صفحه به پایین بکشید
  2. روی نماد ضربه بزنید.
  3. پیدا کردن آدرس IP دستگاه: در Nest Hub (2nd gen) ، به اطلاعات دستگاه > اطلاعات فنی > آدرس IP بروید
- از GHA روی گوشی شما:
  1. برای نمایش صفحه جزئیات دستگاه، روی دستگاه ضربه بزنید
  2. برای نمایش صفحه تنظیمات، روی نماد ضربه بزنید.
  3. آدرس IP دستگاه را پیدا کنید: به اطلاعات دستگاه > اطلاعات فنی > آدرس IP بروید
روی کامپیوتری که به همان شبکه وای‌فای دستگاه متصل است:
```
  adb connect ip-address
  adb logcat
```
برای ارائه گزارش‌ها به کسی، عملیاتی را که با شکست مواجه شده است انجام دهید و خروجی را به یک فایل متنی ارسال کنید:
```
  adb logcat -d > platform-logs.txt
```

اتوماسیون‌ها

تشخیص لبه

اتوماسیون‌های موجود در اکوسیستم گوگل هوم دارای قابلیت تشخیص لبه هستند، که منطقی است که تأیید می‌کند یک استارتر فقط زمانی فعال می‌شود که یک تغییر وضعیت واقعی رخ دهد، برخلاف به‌روزرسانی وضعیت که صرفاً وضعیت قبلی دستگاه را تکرار می‌کند.

برای مثال، اگر روشن کردن یک چراغ با استارت زدن باشد، تشخیص لبه تأیید می‌کند که استارت فقط در صورتی فعال می‌شود که آن دستگاه چراغ از حالت خاموش به روشن تغییر کند، نه اینکه از حالت روشن به روشن تغییر کند (بدون تغییر).

اتوماسیون آنطور که انتظار می‌رود رفتار نمی‌کند

پس از در نظر گرفتن تشخیص لبه، اگر اتوماسیون مطابق انتظار رفتار نکند:

هر دستگاه را بررسی کنید تا مطمئن شوید که مستقل از اتوماسیون شما به درستی کار می‌کند.
به نمودار اتوماسیون برای اتوماسیون خود نگاهی بیندازید و آن را با DSL اتوماسیون خود مقایسه کنید تا هرگونه فرض نادرست احتمالی از جانب شما آشکار شود.
در طول اجرای اتوماسیون، وضعیت دستگاه را در برنامه Google Home مشاهده کنید.
بررسی کنید تا مطمئن شوید که تمام دستگاه‌هایی که اتوماسیون به آنها ارجاع می‌دهد، در ساختاری که انتظار دارید، وجود دارند. حذف دستگاهی که اتوماسیون به آن وابسته است، می‌تواند عواقب ناخواسته‌ای داشته باشد. به تأثیر حذف دستگاه بر اتوماسیون‌ها مراجعه کنید.

اتوماسیون زمانی اجرا می‌شود که نباید

اگر اتوماسیون شما زمانی که نباید اجرا می‌شود، معیارهای شروع را بررسی کنید. ممکن است لازم باشد منطق اضافی اضافه کنید تا مطمئن شوید که تغییر در وضعیت فقط یک بار ثبت می‌شود و فقط یک بار اتوماسیون را فعال می‌کند.

اتوماسیون کامپایل نمی‌شود

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

اعتبارسنجی ایجاد خودکار با شکست مواجه می‌شود

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

تابع لیست، استثنائات را ایجاد می‌کند

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

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

بررسی کنید که آیا adb installed نصب شده است یا خیر. به نصب adb مراجعه کنید.

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

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

اتوماسیون را با استفاده از شناسه اتوماسیون حذف کنید:
```
structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))
```

API دیسکاوری در صورت ثبت نشدن یک ویژگی، هشداری را ثبت می‌کند.

اگر API مربوط به Discovery هشداری برای 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 است. برای تعیین نام ویژگی از روی شناسه، به فهرست ویژگی‌ها (Trait index) مراجعه کنید.

از این مثال، RelativeHumidityControl باید در طول مقداردهی اولیه برنامه ثبت شود. برای افزودن ویژگی خود به رجیستری، به بخش ثبت ویژگی‌ها مراجعه کنید.

اواوت

اگر یک کلاینت OAuth موجود دارید

اگر از قبل یک کلاینت OAuth تأیید شده برای یک برنامه منتشر شده دارید، می‌توانید از کلاینت OAuth موجود خود برای آزمایش APIهای Home استفاده کنید.

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

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

هنگام استفاده از یک کلاینت OAuth موجود، محدودیت ۱۰۰ کاربر وجود دارد. برای اطلاعات بیشتر در مورد افزودن کاربران آزمایشی، بهصفحه رضایت OAuth را تنظیم کنید .مستقل از تأیید OAuth، محدودیت ۱۰۰ کاربر از طرف Home APIs وجود دارد که می‌توانند به برنامه شما مجوز اعطا کنند. این محدودیت پس از تکمیل ثبت نام در Developer Console برداشته می‌شود.
ثبت نام Developer Console باید زمانی که آماده محدود کردن اعطای مجوز به نوع دستگاه از طریق OAuth برای به‌روزرسانی برنامه خود با رابط‌های برنامه‌نویسی کاربردی خانگی هستید، برای تأیید ارسال شود.
مهم: کنسول توسعه‌دهندگان گوگل هوم هنوز برای ثبت‌نام در دسترس نیست.

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

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