اشکال زدایی ادغام های ماده، اشکال زدایی ادغام های ماده

1. قبل از شروع

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

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

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

پیش نیازها

• راهنمای شروع با Matter را با یک پروژه کارکرد Matter و راه اندازی دستگاه کامل کنید
• یک تلفن اندرویدی داشته باشید که بتوانید آن را به ایستگاه کاری خود متصل کنید (برای گزارش های ADB)

چیزی که یاد خواهید گرفت

• نحوه استفاده از ابزارهای تحلیلی برای خانه هوشمند برای نظارت بر مسائل Matter در مقیاس.
• نحوه تریاژ خطاها با دسترسی به گزارش های خطا و جمع آوری اطلاعات.
• نحوه دسترسی به اسناد و منابع پشتیبانی Matter برای جستجوی کمک.

2. Google Home Analytics را مشاهده کنید

نظارت بر عملکرد برای ادغام موفقیت آمیز با اکوسیستم Google Home حیاتی است. ما مجموعه ای از ابزارهای نظارتی را برای توسعه دهندگان خانه هوشمند در پلتفرم Google Cloud ارائه می دهیم. شما می توانید از این ابزارها برای اندازه گیری عملکرد پروژه خود استفاده کنید.

دسترسی به معیارهای پروژه

• اولین گام برای دسترسی به داده‌های خود، بررسی داشبوردهای Google Home، با ورود به Google Cloud Console و پیمایش به Operations > Monitoring > Dashboards است.

تعدادی داشبورد برای پروژه شما موجود است (از جمله سایر محصولات GCP). داشبوردهای ارائه شده برای خانه هوشمند با پیشوند Google Home Analytics عرضه می شوند.

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

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

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

توجه داشته باشید که نمای پیش‌فرض با نمودارهایی که در داشبورد Google Home Analytics می‌بینید، فقط نمایی است که ما برای پروژه شما با استفاده از داده‌های معیارهای خانه هوشمند ایجاد کرده‌ایم. همچنین می توانید از Metrics Explorer برای ایجاد نمودارهای خود از همان معیارهای اساسی استفاده کنید و آنها را در داشبوردهای سفارشی خود ذخیره کنید.

دسترسی به گزارش های خطا

Logs Explorer مجموعه ای از ابزارها برای کار با گزارش رویدادهای تولید شده در یک پروژه است. در Google Cloud Console با پیمایش به Operations > Logging > Logs Explorer قابل دسترسی است.

هنگامی که Logs Explorer را باز می کنید، نمایی به شکل زیر دریافت می کنید:

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

3. مسائل مربوط به راه اندازی اشکال زدایی

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

در طول راه اندازی دستگاه، مجموعه ای از تعاملات بین دستگاه Matter، برنامه Google Home و پارچه Matter انجام می شود. تصویر زیر برخی از این رویدادها را نشان می دهد:

برای کسب اطلاعات بیشتر در مورد هر یک از این مراحل، می توانید صفحه راه اندازی را از Matter Primer بررسی کنید. در این بخش به ابزارها و تکنیک‌های رفع اشکال مشکلات راه‌اندازی می‌پردازیم.

از Google Home Analytics استفاده کنید

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

نمودارهای موجود در این داشبورد اطلاعاتی را در مورد راه اندازی دستگاه ارائه می دهند:

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

کشورهای راه اندازی:

• COMMISSIONING_STARTED
• ONBOARDING_PAYLOAD_GENERATED
• LOCAL_DISCOVERY_SUCCESSFUL
• PASE_CONNECTION_SUCCESSFUL
• NOC_ADDED_SUCCESSFULLY
• COMMISSIONING_COMPLETE

برای مشاهده نسخه دقیق این رویدادها، به 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"
}

علاوه بر وضعیت راه اندازی و کد وضعیت، یک گزارش خطا حاوی مهرهای زمانی برای خطای ثبت شده و همچنین شناسه محصول Matter است که به شما امکان می دهد تشخیص دهید کدام یک از محصولات شما باعث خطا شده است. مجموعه گزارش‌های تولید شده از همان تلاش راه‌اندازی یک sessionId به اشتراک می‌گذارد.

استفاده از معیارهای Google Home Analytics به شما یک ایده اولیه می دهد که در چه مرحله ای ممکن است مشکل رخ دهد. برای یافتن علت اصلی خطاهای راه اندازی دستگاه، گاهی اوقات ممکن است نیاز باشد که با استفاده از گزارش های تولید شده توسط دستگاه تلفن همراه مورد استفاده در فرآیند راه اندازی، اشکال زدایی بیشتری انجام دهید. برای این موارد، به پل اشکال زدایی اندروید نیاز دارید.

از پل اشکال زدایی اندروید (ADB) استفاده کنید

راه دیگر برای عیب یابی مشکلات راه اندازی، استفاده از ابزار خط فرمان Android Debug Bridge (ADB) است. از آنجایی که راه اندازی عمدتاً بین دستگاه تلفن همراه و دستگاه Matter انجام می شود، می توان از ابزار ADB برای دسترسی به گزارش های تولید شده توسط برنامه Google Home در طول راه اندازی استفاده کرد.

ابزارهای پلتفرم را نصب کنید

ADB به عنوان بخشی از Android SDK Platform Tools است که می تواند با Android Studio یا از طریق ابزار خط فرمان sdkmanager نصب شود.

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

$ adb -- version

این باید شماره نسخه ابزار ADB نصب شده را بدون هیچ خطایی نمایش دهد.

اشکال زدایی USB را فعال کنید

مرحله بعدی فعال کردن اشکال زدایی USB در دستگاه اندرویدی خود است.

ابتدا مراحل را برای فعال کردن گزینه های توسعه دهنده در دستگاه خود دنبال کنید و سپس اشکال زدایی USB را فعال کنید .

این به ADB اجازه می دهد تا به گزارش های تولید شده توسط برنامه هایی که در حال حاضر روی دستگاه اجرا می شوند دسترسی داشته باشد.

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

1. سرور ADB را با دستور زیر اجرا کنید:

$ adb start-server

2. تلفن خود را به رایانه ای که سرور ADB را اجرا می کند وصل کنید.

ممکن است یک پیام هشدار در مورد اشکال زدایی USB بر روی تلفن خود دریافت کنید و از شما بپرسد که آیا می خواهید به رایانه خود اجازه دهید به اطلاعات تلفن شما دسترسی داشته باشد یا خیر:

3. اگر این پیام هشدار را دریافت کردید، روی Allow کلیک کنید.
4. با استفاده از دستور زیر، یک فرمان لیست دستگاه ها را از ترمینال صادر کنید تا ببینید آیا رایانه شما می تواند از طریق ADB به تلفن دسترسی داشته باشد یا خیر:

$ adb devices

این باید پاسخی مشابه این بدهد:

List of devices attached
<phone-id>    device

<phone-id> شما یک رشته الفبایی است که دستگاه شما را به طور منحصربفرد شناسایی می کند.

5. مقدار <phone-id> را برای استفاده در مراحل بعدی به خاطر بسپارید.

جمع آوری اطلاعات سیستم

بعدی این است که اطلاعات نسخه برنامه ها و سیستم موجود در دستگاه خود را بررسی کنید.

• برای بررسی نسخه سیستم عامل اندروید:

$ adb -s <phone-id> shell getprop ro.build.version.release

• برای بررسی نسخه Google Home App:

$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName

• برای بررسی نسخه خدمات Google Play:

$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"

• برای بررسی اینکه آیا ماژول های کنترل Home / Matter را از طریق خدمات Play دارید:

$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

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

گزارش های خطا را جمع آوری کنید

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

1. دستور زیر را با ارائه <phone-id> و همچنین <file-name> که در آن گزارش‌ها در رایانه شما ذخیره می‌شوند (به عنوان مثال debug_file.txt ) اجرا کنید.

$ adb -s <phone-id> logcat > <file-name>

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

مراحل راه اندازی را با دستگاه Matter خود ادامه دهید.

2. پس از رسیدن به خطایی که می‌خواهید اشکال زدایی کنید، با فشار دادن Control+C در پنجره ترمینال در حال اجرا، ثبت‌نام را متوقف کنید.

گزارش های شما اکنون باید در فایل ثبت نام <file-name> ذخیره شوند. از آنجایی که این فرآیند گزارش‌ها را از هر فرآیند در حال اجرا ردیابی شده در دستگاه ثبت می‌کند، گزارش‌های زیادی در این فایل وجود خواهد داشت. به همین دلیل است که همیشه باید از این گزارش‌ها با جستجوی ورودی‌های مورد نیاز خود استفاده کنید.

گزارش های خطا را تجزیه و تحلیل کنید

فرآیندهای راه اندازی از طریق یک سیستم فرعی به نام MatterCommissioner در GHA انجام می شود.

1. با پیروی از استراتژی اصلی مورد استفاده در هنگام تجزیه و تحلیل خطاهای راه اندازی، به دنبال خطاهای ایجاد شده توسط زیرسیستم MatterCommissioner با دستور زیر باشید:

$ grep "MatterCommissioner" <file-name>

این یک خروجی حاوی رویدادهای فرآیند راه اندازی تولید می کند.

2. اگر دستگاه Matter شما از Thread استفاده می کند، می توانید از طریق دستور زیر به دنبال خطاهای ایجاد شده توسط زیرسیستم Thread نیز بگردید:

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

همانطور که فایل گزارش تولید شده توسط فرآیند اشکال زدایی ADB را تجزیه و تحلیل می کنید، به دنبال الگوهای خاصی نیز باشید. بسیاری از خطاهای راه اندازی شامل رشته « commissioning failure » در پیام خطای آن است.

3. با دستور زیر پیغام خرابی راه اندازی را جستجو کنید:

$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. اشکال زدایی مسائل کنترل دستگاه

پس از راه‌اندازی و راه‌اندازی دستگاه‌های Matter در اکوسیستم Google Home، کاربران می‌توانند با استفاده از «دستیار Google» (به‌عنوان مثال، «Ok Google، چراغ‌های اتاق نشیمن من را روشن کن») یا با استفاده از رابط کاربری در برنامه Home دستورات صوتی صادر کنند. یا دستگاه های نمایشگر Google Nest.

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

از معیارها استفاده کنید

در داشبورد Matter Integration چندین معیار در مورد کنترل دستگاه مشاهده خواهید کرد. سه نمودار برای ارزیابی عملکرد دستگاه های شما در این زمینه حیاتی است:

در طول مسائل کنترل معمولاً روندهای نزولی در درصد موفقیت و یک روند صعودی در نمودار شکست خطا مشاهده می کنید. نمودار تفکیک خطا، خطاهایی را که توسط Google Nest Hubs در رابطه با اینکه چرا تلاش کنترل دستگاه شکست خورده است، به شما نشان می دهد.

از لاگ استفاده کنید

هر مشکل مربوط به کنترل دستگاه Matter نیز یک گزارش خطا در سیستم ایجاد می کند. این خطاها را می توان با جستجوی " executionLog " از Logs Explorer فیلتر کرد.

گزارش خطای کنترل دستگاه به شکل زیر است:

{
  "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 هستند، یک پیام خطای کوتاه که توضیح می‌دهد که خطا در مورد چیست.

5. اشکال زدایی سایر ویژگی ها

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

به روز رسانی OTA را ردیابی کنید

برای ردیابی نسخه‌های به‌روزرسانی‌های خارج از هوا (OTA) برای دستگاه‌های Matter که توسط Google Home صادر شده است، مجموعه‌ای از معیارها را ارائه می‌کنیم که نسخه‌های سخت‌افزاری و نرم‌افزاری دستگاه‌ها را در این زمینه نشان می‌دهد.

هنگامی که یک به‌روزرسانی از کنسول صادر می‌کنید، به معیارهای زیر توجه داشته باشید:

خواهید دید که در روزهای پس از انتشار، دستگاه های بیشتری در این زمینه نسخه نرم افزار جدید مرتبط با نسخه OTA را دریافت می کنند.

6. به دنبال پشتیبانی باشید

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

از کانال های توسعه دهنده بازدید کنید

سه کانال توسعه دهنده به طور فعال در Google نظارت می شود:

در حالی که هر یک از این کانال ها توسط یک تیم به صورت دوره ای نظارت می شوند، تفاوت های کلیدی در مورد زمان استفاده از کدام یک وجود دارد.

• Stack Overflow: می توانید با سؤالات پیاده سازی یا جستجوی راهنمایی با ما و جامعه توسعه دهندگان خانه هوشمند تماس بگیرید. این کانال برای پرسیدن نحوه عیب یابی مشکلات یا اجرای یک ویژگی خاص بهترین است.
• ردیاب مشکل: این سیستم رسمی ردیاب مشکل توسط گوگل است که در آن مخاطبان خارجی می توانند خطاهای موجود در اکوسیستم را گزارش کنند. ابزارهای وب را برای پیوست کردن فایل ها و اشتراک گذاری اطلاعات حساس در صورت نیاز فراهم می کند. استفاده از Issue Tracker برای گزارش مشکلات اکوسیستم یا اشتراک‌گذاری درخواست‌های ویژگی بهترین است.
• تالار گفتمان توسعه‌دهنده: برای دریافت راهنمایی از پشتیبانی رسمی Google و کارشناسان انجمن، می‌توانید از طریق تالار گفتمان توسعه‌دهنده Nest با آن تماس بگیرید. این انجمن برای \ دریافت راهنمایی رسمی برای توسعه بهترین است.

در خبرنامه توسعه دهندگان ثبت نام کنید

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

برای دریافت خبرنامه توسعه دهنده می توانید از فرم ثبت نام استفاده کنید.

7. تبریک می گویم

تبریک می گویم! شما با موفقیت یاد گرفتید که چگونه ادغام های Matter را با استفاده از ابزارها و تکنیک هایی که توصیه می کنیم، اشکال زدایی کنید. ما برای شما آرزوی گذراندن زمان خوبی برای ایجاد ادغام Matter با Google Home داریم.

مراحل بعدی

تمرین های زیر را امتحان کنید و منابع اضافی را کشف کنید:

• علاوه بر استفاده از تجزیه و تحلیل برای عیب‌یابی مشکلات، می‌توانید از Test Suite نیز برای آزمایش ادغام خود در برابر هرگونه مشکل احتمالی استفاده کنید.
• هنگامی که ادغام شما برای اشتراک گذاری با جهان آماده شد، گام بعدی دریافت گواهینامه WWGH پروژه شما است. برای این کار می توانید مراحل موجود در صفحه گواهی را دنبال کنید.