۱. قبل از شروع
Matter یک تجربه یکپارچه و چند پلتفرمی برای راهاندازی و کنترل دستگاه به کاربران نهایی ارائه میدهد. این امر عمدتاً به دلیل اجزای متعدد اکوسیستم که در پشت صحنه با یکدیگر کار میکنند، امکانپذیر است. سیستمهای عیبیابی مانند این اغلب میتواند برای توسعهدهندگان جدید دلهرهآور باشد، بنابراین ما مجموعهای از ابزارها و تکنیکها را توسعه دادهایم تا زندگی شما را به عنوان یک توسعهدهنده Matter با Google Home آسانتر کنیم.
سه جزء اصلی برای Matter وجود دارد که در این آزمایشگاه کد پوشش داده شدهاند. برای هر یک از این سیستمها، گوگل مجموعهای از تجزیه و تحلیلهای عیبیابی را برای توسعهدهندگان ارائه میدهد که از تلفنها و هابها جمعآوری شدهاند:

به عنوان یک توسعهدهنده، بسیار مهم است که بتوانید مشکلاتی را که در طول چرخه توسعه دستگاه با آنها مواجه میشوید، کاهش دهید. پس از راهاندازی پروژه، باید روند مشکلات دستگاههای موجود در میدان را به صورت کلی رصد کنید و آنها را از طریق بهروزرسانیهای نرمافزاری برطرف کنید. این آزمایشگاه کد، تکنیکهایی را که میتوانید برای هر دو هدف استفاده کنید، پوشش میدهد.
پیشنیازها
- راهنمای کامل شروع به کار با Matter را با یک پروژه Matter کاربردی و راهاندازی دستگاه تکمیل کنید.
- یک تلفن اندروید داشته باشید که بتوانید آن را به ایستگاه کاری خود متصل کنید (برای گزارشهای ADB)
آنچه یاد خواهید گرفت
- نحوه استفاده از ابزارهای تحلیلی برای خانه هوشمند برای نظارت بر مسائل مربوط به ماده در مقیاس بزرگ.
- چگونه با دسترسی به گزارشهای خطا و جمعآوری اطلاعات، خطاها را اولویتبندی کنیم.
- نحوه دسترسی به اسناد و منابع پشتیبانی Matter برای درخواست کمک.
۲. مشاهدهی گوگل هوم آنالیتیکس
نظارت بر عملکرد برای ادغام موفقیتآمیز با اکوسیستم گوگل هوم بسیار مهم است. ما مجموعهای از ابزارهای نظارتی را برای توسعهدهندگان خانه هوشمند در پلتفرم گوگل کلود ارائه میدهیم. میتوانید از این ابزارها برای سنجش عملکرد پروژه خود استفاده کنید.
دسترسی به معیارهای پروژه
- اولین قدم برای دسترسی به دادههایتان، بررسی داشبوردهای گوگل هوم است، برای این کار وارد کنسول ابری گوگل شوید و به مسیر Operations > Monitoring > Dashboards بروید.
تعدادی داشبورد برای پروژه شما (از جمله سایر محصولات GCP) در دسترس است. داشبوردهای ارائه شده برای خانه هوشمند با پیشوند Google Home Analytics ارائه میشوند.

ما در حال حاضر یک داشبورد عمومی داریم که کل پروژه شما را پوشش میدهد، و همچنین داشبوردهایی برای یکپارچهسازیهای خاص (ابری، محلی، مادهای) یا انواع دستگاهها (دوربینها). این داشبوردها فقط در صورتی حاوی دادهها هستند که شما یکپارچهسازی از نوع مربوطه را به همراه یک پروژه عملیاتی که درخواستها را برآورده میکند، داشته باشید.
وقتی یکی از این داشبوردها را باز میکنید، مجموعهای از نمودارها را مشاهده خواهید کرد که شبیه نمودار زیر هستند:

داشبوردهای گوگل هوم شامل نمودارهای مختلفی هستند که جزئیات رویدادهای مرتبط با پروژه شما را نشان میدهند. با هر داشبورد ادغام، نموداری را مشاهده میکنید که تعداد کل درخواستهای رسیدگی شده توسط پروژه شما، نموداری که میزان موفقیت برای آن نوع ادغام را نشان میدهد و چندین نمودار که انواع دستگاهها و ویژگیهای مربوط به آنها را نشان میدهد. علاوه بر این، با Matter مجموعهای از نمودارها را دارید که موفقیت راهاندازی و همچنین بهروزرسانیهای دستگاههای شما را پیگیری میکنند.
توجه داشته باشید که نمای پیشفرض با نمودارهایی که در داشبوردهای Google Home Analytics مشاهده میکنید، فقط نمایی است که ما برای پروژه شما با استفاده از دادههای معیارهای خانه هوشمند ایجاد کردهایم. همچنین میتوانید از Metrics Explorer برای ایجاد نمودارهای خود از همان معیارهای اساسی استفاده کنید و آنها را در داشبوردهای سفارشی خود ذخیره کنید.
دسترسی به گزارشهای خطا
Logs Explorer مجموعهای از ابزارها برای کار با گزارشهای رویداد تولید شده در یک پروژه است. این ابزار در کنسول Google Cloud با رفتن به Operations > Logging > Logs Explorer قابل دسترسی است.
وقتی Logs Explorer را باز میکنید، نمایی مانند تصویر زیر خواهید داشت:

پنجره اکسپلورر شامل ابزارهای مختلفی برای مشاهده، فیلتر کردن، پرس و جو و تجزیه و تحلیل لاگها است. به طور پیشفرض، این نما لاگهای تولید شده از تمام سیستمهای موجود در پروژه شما، از جمله لاگهایی که خارج از خانه هوشمند تولید میشوند را نشان میدهد. به همین دلیل است که استفاده از این لاگها با فیلتر کردن رویدادهایی که میخواهید اشکالزدایی کنید، کلیدی است. در بخشهای اشکالزدایی بیشتر در مورد این موضوع صحبت خواهیم کرد.
۳. رفع اشکال مشکلات راهاندازی
اولین نوع معیاری که به آن خواهیم پرداخت، مربوط به رویدادهای راهاندازی Matter است. راهاندازی به مجموعهای از مراحل مورد نیاز برای راهاندازی دستگاه Matter توسط کاربر برای اولین بار اشاره دارد.
در طول راهاندازی دستگاه، مجموعهای از تعاملات بین دستگاه Matter، برنامه Google Home و Matter fabric رخ میدهد. تصویر زیر برخی از این رویدادها را نشان میدهد:

برای کسب اطلاعات بیشتر در مورد هر یک از این مراحل، میتوانید صفحه راهاندازی را از Matter Primer بررسی کنید. در این بخش، ابزارها و تکنیکهایی را برای اشکالزدایی مشکلات راهاندازی پوشش خواهیم داد.
از گوگل هوم آنالیتیکس استفاده کنید
ما مجموعهای از معیارها را برای شما ایجاد کردهایم تا با ردیابی رویدادها و درک اینکه خطاها در کدام مرحله ممکن است رخ دهند، مشکلات راهاندازی را بررسی کنید. همانطور که در بخش قبلی به آن پرداختیم، میتوانید این موارد را در داشبورد Matter Integration بیابید.
نمودارهای موجود در این داشبورد، دادههای مربوط به راهاندازی دستگاه را ارائه میدهند:

نمودار تعداد دستگاهها، تعداد تلاشهای راهاندازی توسط کاربران را در یک تاریخ مشخص نشان میدهد. نرخ موفقیت، میزان موفقیت درک شده برای این رویدادها را از طرف گوگل نشان میدهد. هر تلاش راهاندازی، مجموعهای از رویدادها را با حالتهای مرتبط ایجاد میکند. هنگامی که در هر یک از این حالتها خطایی رخ میدهد، در نمودار تجزیه خطا نیز ثبت میشود.
ایالتهای راه اندازی:
- راهاندازی_آغاز شد
- تولید بار عملیاتی در حین سوار شدن
- کشف_موفق_محلی
- اتصال موفقیتآمیز
- NOC_ADDED_SUCCESSFULLY
- تکمیل_راه_اندازی
برای مشاهدهی نسخهی دقیق این رویدادها، به Operations > Logging > Logs Explorer بروید. برای فیلتر کردن خطاهای راهاندازی، میتوانید عبارت " clientUpdateLog " را به همراه " severity>=ERROR " در فیلد جستجو جستجو کنید.
گزارش خطای راهاندازی برای Matter به این شکل است:
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"clientUpdateLog": {
"MatterUpdate": {
"reportedProductId": 55,
"sessionId": "1584879052892229997",
"reportedVendorId": 4800,
"commissioningState": "GENERIC_COMMISSIONING_ERROR",
"status": "GENERIC_ERROR"
}
}
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T07:09:55.216425297Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}
علاوه بر وضعیت راهاندازی و کد وضعیت، یک گزارش خطا شامل مهرهای زمانی برای خطای ثبتشده و همچنین شناسه محصول مهم است که به شما امکان میدهد مشخص کنید کدام یک از محصولات شما باعث خطا شده است. مجموعه گزارشهای تولید شده از همان تلاش برای راهاندازی، یک sessionId مشترک دارند.
استفاده از معیارهای Google Home Analytics به شما ایده اولیهای میدهد که مشکل در کدام مرحله ممکن است رخ دهد. برای یافتن علت اصلی خطاهای راهاندازی دستگاه، گاهی اوقات ممکن است نیاز به اشکالزدایی اضافی با استفاده از گزارشهای تولید شده توسط دستگاه تلفن همراه مورد استفاده در فرآیند راهاندازی داشته باشید. برای این کار، به Android Debug Bridge نیاز دارید.
از پل اشکالزدایی اندروید (ADB) استفاده کنید
راه دیگر برای عیبیابی مشکلات راهاندازی، استفاده از ابزار خط فرمان Android Debug Bridge (ADB) است. از آنجایی که راهاندازی عمدتاً بین دستگاه تلفن همراه و دستگاه Matter انجام میشود، میتوان از ابزار ADB برای دسترسی به گزارشهای تولید شده توسط برنامه Google Home در طول راهاندازی استفاده کرد.
نصب ابزارهای پلتفرم
ADB به عنوان بخشی از ابزارهای پلتفرم SDK اندروید ارائه میشود که میتوان آن را با اندروید استودیو یا از طریق ابزار خط فرمان sdkmanager نصب کرد.
پس از نصب موفقیتآمیز ابزارهای پلتفرم روی سیستم خود، با بررسی شماره نسخه از طریق ترمینال و با استفاده از دستور زیر، ADB را تأیید کنید:
$ adb -- version
این باید شماره نسخه ابزار ADB نصب شده را بدون هیچ خطایی نمایش دهد.
اشکالزدایی USB را فعال کنید
مرحله بعدی فعال کردن اشکالزدایی USB در دستگاه اندروید شماست.
ابتدا مراحل فعال کردن گزینههای توسعهدهنده (Developer Options) را در دستگاه خود دنبال کنید و سپس اشکالزدایی USB را فعال کنید .
این به ADB اجازه میدهد تا به گزارشهای تولید شده توسط برنامههای در حال اجرا روی دستگاه دسترسی پیدا کند.
بازیابی شناسه دستگاه
- سرور ADB را با دستور زیر اجرا کنید:
$ adb start-server
- گوشی خود را به کامپیوتری که سرور ADB روی آن نصب است وصل کنید.
ممکن است در گوشی خود یک پیام هشدار در مورد اشکالزدایی USB دریافت کنید که از شما میپرسد آیا میخواهید به رایانه خود اجازه دهید به اطلاعات گوشی شما دسترسی داشته باشد:

- اگر این پیام هشدار را دریافت کردید، روی «مجاز» کلیک کنید.
- برای بررسی اینکه آیا رایانه شما میتواند از طریق ADB به تلفن دسترسی داشته باشد، با استفاده از دستور زیر، دستور list devices را از ترمینال اجرا کنید:
$ adb devices
این باید پاسخی مشابه این بدهد:
List of devices attached <phone-id> device
<phone-id> شما یک رشته الفبایی-عددی است که به طور منحصر به فرد دستگاه شما را شناسایی میکند.
- مقدار
<phone-id>را برای استفاده در مراحل بعدی به خاطر بسپارید.
جمعآوری اطلاعات سیستم
مرحله بعدی بررسی اطلاعات نسخه برنامهها و سیستم عامل دستگاه شماست.
- برای بررسی نسخه سیستم عامل اندروید:
$ adb -s <phone-id> shell getprop ro.build.version.release
- برای بررسی نسخه برنامه Google Home:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
- برای بررسی نسخه خدمات گوگل پلی:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- برای بررسی اینکه آیا ماژولهای کنترل Home / Matter را از طریق Play Services دارید:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
مطمئن شوید که این مقادیر برگشتی توسط اکوسیستم ما پشتیبانی میشوند. هنگام تماس با پشتیبانی در مورد خرابیهای راهاندازی، لطفاً همیشه اطلاعات سیستم را در تیکتهای پشتیبانی خود وارد کنید.
جمعآوری گزارشهای خطا
در مرحله بعد، فرآیند جمعآوری لاگ را آغاز کنید، سپس مراحل راهاندازی را طی کنید تا رویدادهای خطایی که میخواهید اشکالزدایی کنید، ایجاد شوند.
- دستور زیر را با وارد کردن
<phone-id>خود و همچنین<file-name>که گزارشها در رایانه شما ذخیره میشوند (مثلاًdebug_file.txt) اجرا کنید.
$ adb -s <phone-id> logcat > <file-name>
این بلافاصله فرآیند ثبت وقایع را آغاز میکند. اگر فایلی با نام ارائه شده وجود نداشته باشد، ایجاد میشود و وقایع ثبت شده از تلفن پس از هر رویداد به این فایل اضافه میشوند.
مراحل راهاندازی دستگاه Matter خود را ادامه دهید.
- وقتی به خطایی که میخواهید اشکالزدایی کنید رسیدید، با فشردن
Control+Cدر پنجره ترمینال در حال اجرا، ثبت گزارش را متوقف کنید.
اکنون گزارشهای شما باید در فایل ثبت وقایع <file-name> ذخیره شوند. از آنجایی که این فرآیند، گزارشهای مربوط به هر فرآیند در حال اجرا که در دستگاه ردیابی میشود را ثبت میکند، گزارشهای زیادی در این فایل وجود خواهد داشت. به همین دلیل است که همیشه باید با جستجوی ورودیهای مورد نیاز خود، از این گزارشها استفاده کنید.
تحلیل گزارشهای خطا
فرآیندهای راهاندازی از طریق زیرسیستمی به نام MatterCommissioner در GHA انجام میشود.
- با پیروی از استراتژی اصلی مورد استفاده هنگام تحلیل خطاهای راهاندازی، با دستور زیر به دنبال خطاهای ایجاد شده توسط زیرسیستم MatterCommissioner باشید:
$ grep "MatterCommissioner" <file-name>
این یک خروجی تولید میکند که شامل رویدادهای فرآیند راهاندازی است.
- اگر دستگاه Matter شما از Thread استفاده میکند، میتوانید از طریق دستور زیر خطاهای ایجاد شده توسط زیرسیستم Thread را نیز جستجو کنید:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
همانطور که فایل لاگ تولید شده توسط فرآیند اشکالزدایی ADB را تجزیه و تحلیل میکنید، به دنبال الگوهای خاصی نیز باشید. بسیاری از خطاهای راهاندازی شامل رشته " commissioning failure " در پیام خطای خود هستند.
- با دستور زیر پیام خطای راهاندازی را جستجو کنید:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
۴. رفع اشکال مشکلات کنترل دستگاه
پس از اینکه کاربران دستگاههای Matter را در اکوسیستم Google Home راهاندازی و راهاندازی کردند، میتوانند با استفاده از دستیار گوگل (مثلاً «Ok Google، چراغهای اتاق نشیمن من را روشن کن») یا با استفاده از رابط کاربری در برنامه Home یا دستگاههای نمایشگر Google Nest، دستورات صوتی صادر کنند.
از آنجایی که مشخصات کنترل بین دستگاههای انتهایی و گوگل هابها توسط Matter میانجیگری میشود، انتظار میرود خطاهای کمتری در سمت کنترل دستگاه وجود داشته باشد. صرف نظر از این، ما معیارها و گزارشهایی را برای شما فراهم میکنیم تا این نوع مشکلات را نیز اشکالزدایی کنید.
از معیارها استفاده کنید
در داشبورد Matter Integration، چندین معیار در مورد کنترل دستگاه مشاهده خواهید کرد. سه نمودار برای ارزیابی عملکرد دستگاههای شما در محل بسیار مهم هستند:

در طول مشکلات کنترل، معمولاً روند نزولی در درصد موفقیت و روند صعودی در نمودار تجزیه خطا مشاهده میکنید. نمودار تجزیه خطا، خطاهای ثبت شده توسط Google Nest Hubs را در مورد دلیل شکست تلاش برای کنترل دستگاه به شما نشان میدهد.
از لاگها استفاده کنید
هر مشکل کنترل دستگاه Matter همچنین یک گزارش خطا در سیستم ایجاد میکند. این خطاها را میتوان با جستجوی " executionLog " از Logs Explorer فیلتر کرد.
گزارشهای خطای کنترل دستگاه Matter به شکل زیر هستند:
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"executionLog": {
"executionResults": [
{
"executionType": "MATTER",
"latencyMsec": "6000",
"actionResults": [
{
"action": {
"actionType": "ONOFF_OFF",
"trait": "TRAIT_ON_OFF"
},
"status": {
"externalDebugString": "No message was received before the deadline.",
"statusType": "RESPONSE_TIMEOUT",
"fallbackToCloud": false,
"isSuccess": false
},
"device": {
"deviceType": "OUTLET"
}
}
],
"requestId": "1487232799486580805"
}
]
},
"locale": "en-US"
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T15:47:27.311673018Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}
هر گزارش خطا شامل یک مهر زمانی، نوع دستگاه و ویژگی و همچنین خطای مرتبط با درخواست کنترل در statusType است. بسیاری از خطاهای کنترلی همچنین شامل یک externalDebugString هستند، یک پیام خطای کوتاه که توضیح میدهد خطا مربوط به چیست.
۵. اشکالزدایی سایر ویژگیها
تا اینجا یاد گرفتید که چگونه مشکلات راهاندازی و کنترل دستگاه را برای Matter مدیریت کنید. همچنین ویژگیهای دیگری در اکوسیستم وجود دارد که میتوانید از آنها استفاده کنید یا تکنیکهایی را برای اطمینان از یکپارچهسازی با کیفیت خوب توصیه کنید.
پیگیری بهروزرسانیهای OTA
برای ردیابی انتشار بهروزرسانیهای بیسیم (OTA) برای دستگاههای Matter که توسط Google Home منتشر شدهاند، مجموعهای از معیارها را ارائه میدهیم که نسخههای سختافزاری و نرمافزاری دستگاههای موجود در بازار را نشان میدهد.
پس از انتشار بهروزرسانی از کنسول، به معیارهای زیر توجه داشته باشید:

خواهید دید که در روزهای پس از انتشار، دستگاههای بیشتر و بیشتری نسخه نرمافزاری جدید مرتبط با نسخه نرمافزار OTA شما را دریافت میکنند.
۶. به دنبال پشتیبانی باشید
گوگل ابزارها و مستنداتی را برای رفع مشکلات Matter در اختیار شما قرار میدهد، اما از آنجایی که اکوسیستم Matter جدید است، مشکلاتی وجود خواهد داشت که این منابع آنها را پوشش نمیدهند. برای این موارد، همیشه میتوانید برای دریافت پشتیبانی با ما یا جامعه تماس بگیرید.
از کانالهای توسعهدهندگان دیدن کنید
سه کانال توسعهدهنده بهطور فعال در گوگل رصد میشوند:

اگرچه هر یک از این کانالها به صورت دورهای توسط یک تیم واحد رصد میشوند، اما تفاوتهای کلیدی در مورد زمان استفاده از هر یک وجود دارد.
- Stack Overflow: میتوانید با ما و جامعه توسعهدهندگان خانه هوشمند در مورد پیادهسازی سوالات یا درخواست راهنمایی تماس بگیرید. این کانال برای پرسیدن چگونگی عیبیابی مشکلات یا پیادهسازی یک ویژگی خاص بهترین گزینه است.
- ردیاب مشکلات: این سیستم رسمی ردیاب مشکلات گوگل است که مخاطبان خارجی میتوانند در آن خطاهای موجود در اکوسیستم را گزارش دهند. این سیستم ابزارهای وب را برای پیوست کردن فایلها و به اشتراک گذاشتن اطلاعات حساس در صورت نیاز فراهم میکند. استفاده از ردیاب مشکلات بهترین راه برای گزارش مشکلات اکوسیستم یا به اشتراک گذاشتن درخواستهای مربوط به ویژگیها است.
- انجمن توسعهدهندگان: برای دریافت راهنمایی از پشتیبانی رسمی گوگل و متخصصان جامعه، میتوانید از طریق انجمن توسعهدهندگان Nest با ما در ارتباط باشید. این انجمن بهترین مکان برای دریافت راهنماییهای رسمی برای توسعه است.
در خبرنامه توسعهدهندگان ثبت نام کنید
علاوه بر مراجعه به کانالهای توسعهدهندگان برای پرسیدن سوالات، ما یک خبرنامه فصلی نیز منتشر میکنیم که ویژگیهای جدید را برجسته میکند و اخبار مربوط به وضعیت اکوسیستم خانه هوشمند گوگل را ارائه میدهد.
برای دریافت خبرنامه توسعهدهندگان میتوانید از فرم ثبت نام استفاده کنید.
۷. تبریک

تبریک! شما با موفقیت یاد گرفتید که چگونه با استفاده از ابزارها و تکنیکهایی که توصیه میکنیم، یکپارچهسازیهای Matter را اشکالزدایی کنید. برای شما آرزوی موفقیت در یکپارچهسازیهای Matter با Google Home را داریم.
مراحل بعدی
تمرینهای زیر را امتحان کنید و منابع اضافی را بررسی کنید:
- علاوه بر استفاده از تجزیه و تحلیل برای عیبیابی مشکلات، میتوانید از Test Suite نیز برای آزمایش ادغام خود در برابر هرگونه مشکل بالقوه استفاده کنید.
- پس از آماده شدن ادغام شما برای اشتراکگذاری با جهان، مرحله بعدی دریافت گواهینامه WWGH برای پروژه شماست. برای این کار میتوانید مراحل موجود در صفحه گواهینامه را دنبال کنید.