نمونه برنامه
اگر هنگام استفاده از APIهای Home با مشکلی مواجه شدید، میتوانید برای اشکالزدایی بیشتر، لاگها را جمعآوری کنید. جمعآوری لاگها از دستگاه تلفن همراه به Android Debug Bridge ( adb ) نیاز دارد. اگر به کمک گوگل نیاز دارید، لاگها را هم از دستگاههای اندروید و هم از هاب جمعآوری کنید و یک تیکت در ردیاب مشکل با اطلاعات و لاگهای مرتبط با آن باز کنید.
جمعآوری گزارشهای اندروید
برای تمام مراحل مربوط به adb دستگاه همراه شما باید به دستگاه محلی شما متصل باشد.
نصب adb
اگر هنوز Android Debug Bridge را روی دستگاه محلی خود راهاندازی نکردهاید، مراحل زیر را دنبال کنید:
- "adb" را روی رایانه خود نصب کنید .
- گزینههای توسعهدهنده (Developer Options) و اشکالزدایی USB را در گوشی Android خود فعال کنید .
دریافت شناسه دستگاه تلفن همراه
- شناسه دستگاه تلفن همراه خود را دریافت کنید:
adb devicesList of devices attached device-id device
- این مقدار را در متغیری به نام
phoneidذخیره کنید:phoneid=device-id
اطلاعات نسخه
توصیه میکنیم هر زمان که تصمیم به جمعآوری گزارشها گرفتید، تمام اطلاعات نسخه مربوط به تنظیمات خود را جمعآوری کنید. این کار در صورتی که نیاز به اشتراکگذاری مشکلات با گوگل داشته باشید، ضروری است.
- ذخیره اطلاعات مختلف دستگاه در متغیرها:
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 Home و GMS فعال کنید:
# Clear existing device logs and expand logger buffer size
adb -s $phoneid logcat -b all -c
adb -s $phoneid logcat -G 8M
# 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جمعآوری لاگهای اندروید بر اساس اسکریپتها
برای ثبت گزارشهای زنده دستگاه اندروید در طول یک جلسه اشکالزدایی:
- برای پاک کردن گزارشهای موجود، افزایش اندازه بافر و تنظیم برچسبهای گزارشگیری مفصل، دستورالعملهای موجود در بخش «فعال کردن پرچمهای اشکالزدایی مفصل» را دنبال کنید.
- تمام برنامههای در حال اجرا روی دستگاه تلفن همراه را ببندید.
- قبل از شروع آزمایش، نویز بافر لاگ موجود را پاک کنید:
adb -s $phoneid logcat -c - فرآیند جمعآوری گزارشها را در یک پنجره ترمینال شروع کنید:
adb -s $phoneid logcat | tee android-logs_$(date +%Y%m%d%H%M%S).txt - برنامه خود را اجرا کنید و تمام اقدامات رابط کاربری مورد نیاز برای رفع مشکل را انجام دهید.
- پس از اتمام، با فشار دادن Ctrl+C (یا Cmd+C در مک) فرآیند
logcatرا در ترمینال متوقف کنید. - گزارشهای این جلسه در
android-logs_YYYYMMDDmmss.txtذخیره میشوند. فایلandroid-logs_YYYYMMDDmmss.txtو_versions.txtرا به هر گزارش اشکالی پیوست کنید.
جمعآوری لاگهای اندروید توسط adb bugreport
وقتی نیاز به اشتراکگذاری اطلاعات تشخیصی دقیقی در مورد مشکلات سطح سیستم، گزارش خرابیها یا اشکالزدایی سطح پایین شبکه و بلوتوث دارید، یک گزارش کامل از اشکالات اندروید تهیه کنید:
- راهاندازی Matter BLE: هنگام گزارش مشکل راهاندازی Matter در رابطه با BLE، قبل از تکرار مشکل، ورود به سیستم Bluetooth HCI snoop را در گزینههای توسعهدهندگان ( تنظیمات > گزینههای توسعهدهندگان > فعال کردن ورود به سیستم Bluetooth HCI snoop ) فعال کنید.
- تنظیمات پیش از آزمون: قبل از اجرای آزمون، مراحل موجود در «فعال کردن پرچمهای اشکالزدایی مفصل» را دنبال کنید تا ویژگیهای اشکالزدایی مفصل را در دستگاه خود فعال کنید.
- ثبت گزارش اشکال: پس از اجرای تست و ایجاد مجدد مشکل، دستور زیر را برای ایجاد یک آرشیو کامل گزارش اشکال اجرا کنید:
adb -s $phoneid bugreport ./android-bugreport_$(date +%Y%m%d%H%M%S).zip - اطلاعات اشکالزدایی پیشرفته: فایل
android-bugreport_YYYYMMDDmmss.zipتولید شده حاوی دادههای جامع تشخیصی در سطح سیستم - از جمله دادههای کامل سیستم، آمار حافظه، تشخیص باتری و ردیابیهای زیرسیستم سطح پایین - است که اطلاعات پیشرفتهتری را برای اشکالزدایی ارائه میدهد.
گزارشهای دستگاه هاب کست
میتوانید گزارشهای دستگاه را برای هاب Google Nest خود با استفاده از این روش مشاهده کنید، که برای مدلهای زیر پشتیبانی میشود:
- Google Home
- Google Nest Audio
- Google Nest Hub
- Google Nest Mini
برای فعال کردن یک هاب Cast برای بازیابی گزارشهای محلی:
- پل اشکالزدایی اندروید را راهاندازی کنید .
آدرس IP هاب خود را دریافت کنید:
- از هاب، اگر صفحه نمایش داشته باشد:
- از بالای صفحه به پایین بکشید
- روی تنظیمات ضربه بزنید.
- پیدا کردن آدرس IP دستگاه: در Nest Hub (2nd gen) ، به اطلاعات دستگاه > اطلاعات فنی > آدرس IP بروید
- از GHA روی گوشی شما:
- برای نمایش صفحه جزئیات دستگاه، روی دستگاه ضربه بزنید
- برای نمایش صفحه تنظیمات، روی تنظیمات ضربه بزنید.
- آدرس IP دستگاه را پیدا کنید: به اطلاعات دستگاه > اطلاعات فنی > آدرس IP بروید
- از هاب، اگر صفحه نمایش داشته باشد:
روی کامپیوتری که به همان شبکه وایفای دستگاه متصل است:
adb connect ip-addressadb logcatبرای ارائه گزارشها به کسی، عملیاتی را که با شکست مواجه شده است انجام دهید و خروجی را به یک فایل متنی ارسال کنید:
adb logcat -d > platform-logs.txt
اتوماسیونها
تشخیص لبه
اتوماسیونهای موجود در اکوسیستم گوگل هوم دارای قابلیت تشخیص لبه هستند، که منطقی است که تأیید میکند یک استارتر فقط زمانی فعال میشود که یک تغییر وضعیت واقعی رخ دهد، برخلاف بهروزرسانی وضعیت که صرفاً وضعیت قبلی دستگاه را تکرار میکند.
برای مثال، اگر روشن کردن یک چراغ با استارت زدن باشد، تشخیص لبه تأیید میکند که استارت فقط در صورتی فعال میشود که آن دستگاه چراغ از حالت خاموش به روشن تغییر کند، نه اینکه از حالت روشن به روشن تغییر کند (بدون تغییر).
اتوماسیون آنطور که انتظار میرود رفتار نمیکند
پس از در نظر گرفتن تشخیص لبه، اگر اتوماسیون مطابق انتظار رفتار نکند:
هر دستگاه را بررسی کنید تا مطمئن شوید که مستقل از اتوماسیون شما به درستی کار میکند.
به نمودار اتوماسیون برای اتوماسیون خود نگاهی بیندازید و آن را با DSL اتوماسیون خود مقایسه کنید تا هرگونه فرض نادرست احتمالی از جانب شما آشکار شود.
در طول اجرای اتوماسیون، وضعیت دستگاه را در برنامه Google Home مشاهده کنید.
بررسی کنید تا مطمئن شوید که تمام دستگاههایی که اتوماسیون به آنها ارجاع میدهد، در ساختاری که انتظار دارید، وجود دارند. حذف دستگاهی که اتوماسیون به آن وابسته است، میتواند عواقب ناخواستهای داشته باشد. به تأثیر حذف دستگاه بر اتوماسیونها مراجعه کنید.
اتوماسیون زمانی اجرا میشود که نباید
اگر اتوماسیون شما زمانی که نباید اجرا میشود، معیارهای شروع را بررسی کنید. ممکن است لازم باشد منطق اضافی اضافه کنید تا مطمئن شوید که تغییر در وضعیت فقط یک بار ثبت میشود و فقط یک بار اتوماسیون را فعال میکند.
اتوماسیون کامپایل نمیشود
مطمئن شوید که برنامه شما شامل تمام ایمپورتهای لازم، از جمله هر کلاس مربوط به انواع مختلف گره و همچنین ویژگیهایی که به آنها ارجاع میدهید، میشود.
اعتبارسنجی ایجاد خودکار با شکست مواجه میشود
اگر ایجاد اتوماسیون از اعتبارسنجی عبور نکند، یک پیام هشدار یا خطا اطلاعاتی در مورد مشکل ارائه میدهد. برای اطلاعات بیشتر، به مرجع ValidationIssueType مراجعه کنید.
تابع لیست، استثنائات را ایجاد میکند
هنگام فراخوانی تابع Automation API List، ممکن است به دلیل فقدان ویژگیهای API، کنترلکنندههای خواندن، استثناهایی ایجاد کنند. برای کاهش این مشکل، اتوماسیون آسیبدیده را حذف کنید.
برای انجام این کار:
- بررسی کنید که آیا
adbinstalled نصب شده است یا خیر. به نصب 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.