تصحيح أخطاء عمليات دمج المسألة القانونية

1. قبل البدء

يوفّر معيار Matter للمستخدمين النهائيين تجربة سلسة في ما يتعلّق بإعداد الأجهزة والتحكّم فيها من عدّة منصات. ويعود السبب الرئيسي في ذلك إلى المكونات المتعددة للمنظومة المتكاملة التي تعمل معًا في الخلفية. غالبًا ما تكون أنظمة تحديد المشاكل وحلّها هذه صعبة على المطوّرين الجدد، لذا طوّرنا سلسلة من الأدوات والأساليب لتسهيل حياتك كمطوّر Matter باستخدام Google Home.

هناك ثلاثة مكوّنات رئيسية في Matter يتم تناولها في هذا الدليل التعليمي حول الرموز البرمجية. بالنسبة إلى كل نظام من هذه الأنظمة، تقدّم Google للمطوّرين مجموعة من الإحصاءات لتحديد المشاكل وحلّها يتم جمعها من الهواتف والمراكز:

التفعيل والتنفيذ والتحديث عبر الهواء

بصفتك مطوّرًا، من المهم أن تتمكّن من الحدّ من المشاكل التي تواجهها خلال دورة تطوير الجهاز. بمجرد إطلاق مشروعك، تحتاج إلى مراقبة اتجاهات المشكلة للأجهزة في المجال بطريقة مجمّعة، وإصلاحها من خلال تحديثات البرامج. يتناول هذا الدليل التدريبي حول رموز البرامج الأساليب التي يمكنك استخدامها لتحقيق هذين الغرضَين.

المتطلبات الأساسية

  • إكمال دليل بدء استخدام Matter من خلال إنشاء مشروع Matter وإعداد الجهاز
  • هاتف Android يمكنك توصيله بجهاز الكمبيوتر (لعرض سجلات ADB)

ما ستتعرّف عليه

  • كيفية استخدام أدوات الإحصاءات في المنزل المزوّد بأجهزة ذكية لمراقبة مشاكل Matter على نطاق واسع
  • كيفية تحديد أولوية الأخطاء من خلال الوصول إلى سجلات الأخطاء وجمع المعلومات
  • كيفية الوصول إلى مستندات Matter وموارد الدعم للحصول على المساعدة

2. الاطّلاع على إحصاءات Google Home

إنّ مراقبة الأداء أمر مهم لدمج التطبيق بنجاح مع منظومة Google Home المتكاملة. نوفّر مجموعة من أدوات المراقبة لمطوّري الأجهزة المنزلية الذكية على Google Cloud Platform. يمكنك استخدام هذه الأدوات للحصول على مقياس لأداء مشروعك.

الوصول إلى مقاييس المشروع

  • الخطوة الأولى للوصول إلى بياناتك هي الاطّلاع على لوحات بيانات Google Home من خلال تسجيل الدخول إلى Google Cloud Console والانتقال إلى العمليات > المراقبة > لوحات البيانات.

تتوفّر لديك عدة لوحات بيانات لمشروعك (بما في ذلك منتجات GCP الأخرى). تتضمّن لوحات البيانات المقدَّمة للمنزل الذكي بادئة "إحصاءات Google Home".

لوحات بيانات "إحصاءات Google" الرئيسية

لدينا حاليًا لوحة بيانات عامة تغطي مشروعك بالكامل، بالإضافة إلى لوحات بيانات لدمج ميزات معيّنة (مثل السحابة الإلكترونية أو المحتوى على الجهاز أو Matter) أو أنواع أجهزة معيّنة (مثل الكاميرات). لا تحتوي لوحات المعلومات هذه على بيانات إلا إذا كان لديك دمج من النوع المقابل، مع مشروع فعال يفي بالطلبات.

عند فتح إحدى لوحات البيانات هذه، ستظهر لك سلسلة من الرسوم البيانية التي تتشابه مع ما يلي:

تفاصيل معدل النجاح ووقت الاستجابة ونوع الجهاز

تحتوي لوحات بيانات Google Home على رسوم بيانية مختلفة تعرض تفاصيل الأحداث المرتبطة بمشروعك. في كل لوحة بيانات دمج، يظهر لك رسم بياني يعرض العدد الإجمالي للطلبات التي يعالجها مشروعك، ورسم بياني يعرض معدّل النجاح لنوع الدمج هذا، والعديد من الرسوم البيانية التي تعرض أنواع الأجهزة والسمات المعنيّة. بالإضافة إلى ذلك، تتوفّر لك مجموعة من الرسوم البيانية التي تتبّع نجاح عملية الإعداد، بالإضافة إلى عمليات طرح التحديثات على أجهزتك.

يُرجى العِلم أنّ العرض التلقائي الذي يتضمّن الرسوم البيانية التي تظهر في لوحات بيانات "إحصاءات Google Home" هو مجرد عرض أنشأناه لمشروعك باستخدام بيانات مقاييس المنزل الذكي. يمكنك أيضًا استخدام "مستكشف المقاييس" لإنشاء الرسوم البيانية الخاصة بك من المقاييس الأساسية نفسها وحفظها في لوحات البيانات المخصّصة.

سجلات أخطاء الوصول

"مستكشف السجلّات" هو مجموعة من الأدوات للعمل مع سجلّات الأحداث التي يتم إنشاؤها في مشروع معيّن. ويمكن الوصول إليه في Google Cloud Console من خلال الانتقال إلى العمليات > التسجيل > مستكشف السجلات.

بعد فتح "مستكشف السجلّات"، ستظهر لك طريقة عرض تشبه ما يلي:

مستكشف السجلات

تحتوي نافذة المستكشف على أدوات متنوعة لعرض السجلات وتصفيتها والاستعلام عنها وتحليلها. يعرض هذا العرض تلقائيًا السجلات التي تم إنشاؤها من جميع الأنظمة المتاحة لمشروعك، بما في ذلك السجلات التي تم إنشاؤها خارج "المنزل الذكي". لهذا السبب، من المهم استخدام هذه السجلّات من خلال الفلترة للأحداث التي تريد تصحيح أخطاءها. سنتحدث عن ذلك أكثر في أقسام تصحيح الأخطاء.

3- تصحيح أخطاء إعداد الأجهزة

يتعلّق النوع الأول من المقاييس الذي سنلقي نظرة عليه وهو أحداث تكليف Matter. يشير "الإعداد" إلى مجموعة الخطوات اللازمة ليتمكّن المستخدم من إعداد جهاز Matter لأول مرة.

أثناء بدء تشغيل الجهاز، تحدث مجموعة من التفاعلات بين جهاز Matter وتطبيق Google Home وبنية Matter. توضِّح الصورة التالية بعض هذه الأحداث:

أحداث تشغيل المسألة القانونية

يمكنك الاطّلاع على صفحة التفويض من مقالة Matter Primer للتعرّف على المزيد من المعلومات عن كل خطوة من هذه الخطوات. في هذا القسم، سنتناول الأدوات والأساليب اللازمة لتصحيح أخطاء عمليات الإعداد.

استخدام إحصاءات Google Home

لقد أنشأنا مجموعة من المقاييس لتحقّق من مشاكل العمولة عن طريق تتبُّع الأحداث ومعرفة المرحلة التي قد تحدث فيها الأخطاء. يمكنك العثور على هذه الإعدادات في لوحة بيانات "دمج Matter"، كما أوضحنا في القسم السابق.

توفِّر الرسومات البيانية في لوحة البيانات هذه بيانات عن بدء تشغيل الأجهزة:

مقاييس إعداد الأجهزة

يعرض الرسم البياني لعدد الأجهزة عدد محاولات تفعيل المستخدمين في تاريخ معيّن. يعرض معدّل النجاح معدّل النجاح المُلاحظ لهذه الأحداث من جانب Google. تؤدي كل محاولة تفعيل إلى إنشاء مجموعة من الأحداث ذات الحالات المرتبطة. عند حدوث خطأ في أيّ من هذه الحالات، يتم تسجيله أيضًا في الرسم البياني لتقسيم الأخطاء.

حالات إعداد الجهاز:

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

لعرض نسخة تفصيلية من هذه الأحداث، انتقِل إلى العمليات > التسجيل > مستكشف السجلّات. لفلترة أخطاء العمولات، يمكنك البحث عن "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"، يمكنك الحصول على فكرة أولية عن المرحلة التي قد تحدث فيها المشكلة. للعثور على السبب الأساسي لأخطاء تفعيل الجهاز، قد تحتاج أحيانًا إلى إجراء تصحيح أخطاء إضافي باستخدام السجلات التي أنشأها الجهاز الجوّال المستخدَم في عملية التفعيل. ولإجراء ذلك، تحتاج إلى أداة Android Debug Bridge.

استخدام أداة Android Debug Bridge (ADB)

هناك طريقة أخرى لتحديد مشاكل العمولة وحلّها، وهي استخدام أداة سطر الأوامر Android Debug Bridge (ADB). بما أنّ عملية الإعداد تتم بشكل أساسي بين الجهاز الجوّال وجهاز Matter، من الممكن استخدام أداة ADB للوصول إلى السجلات التي أنشأها تطبيق Google Home أثناء عملية الإعداد.

تثبيت أدوات النظام الأساسي

تأتي أداة ADB كجزء من أدوات نظام التشغيل لـ Android SDK، والتي يمكن تثبيتها باستخدام استوديو Android أو من خلال أداة سطر الأوامر sdkmanager.

بعد تثبيت "أدوات النظام الأساسي" بنجاح على نظامك، تحقّق من أداة ADB من خلال التحقّق من رقم الإصدار من وحدة التحكّم الطرفية باستخدام الأمر التالي:

$ adb -- version

من المفترض أن يعرض هذا الأمر رقم إصدار أداة ADB المثبَّتة بدون أي أخطاء.

تفعيل ميزة "تصحيح أخطاء الجهاز عبر USB"

بعد ذلك، عليك تفعيل ميزة "تصحيح أخطاء USB" على جهاز Android.

اتّبِع أولاً الخطوات لتفعيل خيارات المطوّرين على جهازك، ثم تفعيل تصحيح أخطاء الجهاز عبر USB.

يتيح ذلك لـ ADB الوصول إلى السجلّات التي أنشأتها التطبيقات التي تعمل حاليًا على الجهاز.

استرداد رقم تعريف الجهاز

  1. شغّل خادم ADB باستخدام الأمر التالي:
$ adb start-server
  1. وصِّل هاتفك بالكمبيوتر الذي يعمل بخادم ADB.

قد تظهر لك رسالة تحذير على هاتفك بشأن تصحيح أخطاء USB، وتطلب منك تحديد ما إذا كنت تريد السماح لجهاز الكمبيوتر بالوصول إلى المعلومات من هاتفك:

إشعار تصحيح أخطاء الجهاز عبر USB

  1. إذا تلقيت رسالة التحذير هذه، انقر على السماح.
  2. أدخِل الأمر list devices من وحدة التحكّم الطرفية لمعرفة ما إذا كان بإمكان جهاز الكمبيوتر الوصول إلى الهاتف من خلال ADB، وذلك باستخدام الأمر التالي:
$ adb devices

من المفترض أن يؤدي ذلك إلى ظهور استجابة مشابهة لما يلي:

List of devices attached
<phone-id>    device

<phone-id> هو سلسلة أبجدية رقمية تحدِّد جهازك بشكل فريد.

  1. تذكَّر قيمة <phone-id> لاستخدامها في الخطوات التالية.

جمع معلومات النظام

بعد ذلك، عليك التحقّق من معلومات الإصدار للتطبيقات والنظام على جهازك.

  • للتحقّق من إصدار نظام التشغيل Android:
$ 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
  • للتحقق من إصدار "خدمات 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.

  1. بعد الوصول إلى الخطأ الذي تريد تصحيحه، أوقِف التسجيل من خلال الضغط على Control+C في نافذة وحدة التحكّم الطرفية.

من المفترض أن يتم الآن تخزين السجلّات في ملف تسجيل <file-name>. بما أنّ هذه العملية تسجِّل سجلات من كل عملية قيد التشغيل يتم تتبُّعها في الجهاز، سيكون هناك الكثير من السجلات في هذا الملف. وهذا هو السبب في أنه يجب عليك دائمًا استخدام هذه السجلات عن طريق البحث في الإدخالات التي تحتاجها.

تحليل سجلّات الأخطاء

تتم معالجة عمليات التفويض من خلال نظام فرعي يُسمى MatterCommissioner ضمن GHA.

  1. باتّباع الاستراتيجية الرئيسية المستخدَمة عند تحليل أخطاء التفعيل، ابحث عن الأخطاء التي تم إنشاؤها بواسطة النظام الفرعي MatterCommissioner باستخدام الأمر التالي:
$ grep "MatterCommissioner" <file-name>

يؤدي ذلك إلى إنشاء نتيجة تحتوي على الأحداث من عملية التفويض.

  1. إذا كان جهاز Matter يستخدم بروتوكول Thread، يمكنك أيضًا البحث عن الأخطاء التي ينشئها النظام الفرعي Thread من خلال الأمر التالي:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

أثناء تحليل ملف السجلّ الذي تم إنشاؤه من خلال عملية تصحيح أخطاء ADB، ابحث عن أنماط معيّنة أيضًا. تتضمّن الكثير من أخطاء الإعداد سلسلة "commissioning failure" في رسالة الخطأ.

  1. ابحث عن رسالة تشير إلى تعذُّر بدء التشغيل باستخدام الأمر التالي:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. تصحيح أخطاء مشاكل التحكّم في الأجهزة

بعد أن يُعدّ المستخدمون أجهزة Matter ويشغّلونها في منظومة Google Home المتكاملة، يمكنهم إصدار الطلبات عبر الصوت باستخدام "مساعد Google" (على سبيل المثال، "Ok Google، أريد تشغيل الأضواء في غرفة المعيشة") أو باستخدام واجهة المستخدم في تطبيق Home أو أجهزة شاشة Google Nest.

بما أنّ مواصفات التحكّم بين الأجهزة الطرفية وGoogle Hubs تتم من خلال Matter، من المتوقّع حدوث أخطاء أقلّ من جانب التحكّم في الجهاز. مع ذلك، نوفّر لك مقاييس وسجلات لتصحيح أخطاء هذه الأنواع من المشاكل أيضًا.

استخدام المقاييس

في لوحة بيانات دمج Matter، ستظهر لك عدة مقاييس بشأن التحكّم في الجهاز. هناك ثلاثة رسوم بيانية مهمة لتقييم أداء أجهزتك في الميدان:

الرسوم البيانية لتقسيم حالات النجاح ووقت الاستجابة والأخطاء

أثناء حدوث مشاكل في التحكّم، تلاحظ عادةً انخفاضًا في النسبة المئوية للنجاح وارتفاعًا في مخطّط تقسيم الأخطاء. يعرض الرسم البياني لتقسيم الأخطاء الأخطاء التي سجّلتها أجهزة Google Nest Hub بشأن سبب تعذُّر محاولة التحكّم في الجهاز.

استخدام السجلات

تنشئ كل مشكلة متعلّقة بالتحكّم في الجهاز معيار Matter أيضًا سجلّ أخطاء في النظام. يمكن فلترة هذه الأخطاء من "مستكشف السجلّات" عن طريق البحث عن "executionLog".

تبدو سجلّات أخطاء التحكّم في الجهاز ضمن معيار 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، وهو رسالة خطأ قصيرة توضّح سبب الخطأ.

5- تصحيح أخطاء الميزات الأخرى

لقد تعرّفت حتى الآن على كيفية التعامل مع مشاكل تفعيل الجهاز والتحكّم فيه في ما يتعلّق بمعيار Matter. هناك أيضًا ميزات أخرى ضمن المنظومة المتكاملة يمكنك استخدام الأساليب المقترَحة لضمان عملية دمج بجودة عالية.

تتبُّع التحديثات عبر الهواء

لتتبُّع إصدارات التحديثات عبر الهواء (OTA) لأجهزة Matter التي تصدر عن Google Home، نقدّم مجموعة من المقاييس التي تعرض إصدارات الأجهزة والبرامج للأجهزة في الميدان.

بعد إصدار تحديث من وحدة التحكّم، عليك مراقبة المقاييس التالية:

تفاصيل البرامج والأجهزة

ستلاحظ أنّه في الأيام التي تلي الإصدار، سيحصل المزيد والمزيد من الأجهزة في الميدان على إصدار البرنامج الجديد المرتبط بإصدار البرنامج عبر الهواء.

6- طلب الدعم

تقدِّم Google أدوات ومستندات لمساعدتك في تصحيح أخطاء مشاكل Matter، ولكن بما أنّ منظومة Matter المتكاملة جديدة، ستكون هناك مشاكل لا تتناولها هذه المراجع. في هذه الحالات، يمكنك في أي وقت التواصل معنا أو مع أفراد المنتدى لطلب المساعدة.

الانتقال إلى قنوات المطوّرين

هناك ثلاث قنوات للمطوّرين يتمّ تتبّعها بشكلٍ نشط في Google:

Stack Overflow و&quot;أداة تتبُّع المشاكل&quot; و&quot;منتدى المطوّرين&quot;

على الرغم من أنّ الفريق نفسه يرصد كلّ قناة من هذه القنوات بشكل دوري، إلا أنّ هناك بعض الاختلافات الرئيسية في ما يتعلّق بوقت استخدام كلّ قناة.

  • Stack Overflow: يمكنك التواصل معنا ومع منتدى مطوّري الأجهزة المنزلية الذكية لطرح أسئلة حول التنفيذ أو للحصول على إرشادات. هذه القناة هي الأفضل للسؤال عن كيفية تحديد المشاكل وحلّها أو استخدام ميزة معيّنة.
  • نظام تتبُّع المشاكل: هذا هو نظام تتبُّع المشاكل الرسمي الذي تديره Google، حيث يمكن للجمهور الخارجي الإبلاغ عن الأخطاء في المنظومة المتكاملة. وتوفّر أدوات ويب لإرفاق الملفات ومشاركة المعلومات الحسّاسة عند الحاجة. يُعدّ استخدام "أداة تتبُّع المشاكل" هو الخيار الأفضل للإبلاغ عن مشاكل في المنظومة المتكاملة أو مشاركة طلبات الميزات.
  • منتدى المطوّرين: للحصول على إرشادات من فريق الدعم الرسمي في Google وخبراء المنتدى، يمكنك التواصل معنا من خلال منتدى المطوّرين في Nest. هذا المنتدى هو الأفضل للحصول على إرشادات رسمية بشأن التطوير.

الاشتراك في النشرة الإخبارية المخصّصة للمطوّرين

بالإضافة إلى زيارة قنوات المطوّرين لطرح الأسئلة، ننشر أيضًا نشرة إخبارية ربع سنوية تسلط الضوء على الميزات الجديدة وتقدّم آخر الأخبار حول حالة منظومة Google Smart Home المتكاملة.

يمكنك استخدام نموذج الاشتراك لتلقّي النشرة الإخبارية للمطوِّرين.

7- تهانينا

Google Home

تهانينا! لقد تعلّمت بنجاح كيفية تصحيح أخطاء عمليات دمج Matter باستخدام الأدوات والأساليب التي ننصح بها. نتمنى لك وقتًا سعيدًا في إنشاء عمليات دمج معيار Matter مع Google Home.

الخطوات التالية

جرّب التمارين التالية واستكشف موارد إضافية:

  • بالإضافة إلى استخدام الإحصاءات لتحديد المشاكل وحلّها، يمكنك أيضًا استخدام مجموعة الاختبار لاختبار عملية الدمج بحثًا عن أي مشاكل محتملة.
  • بعد أن يصبح الدمج جاهزًا للمشاركة مع العالم، تكون الخطوة التالية هي الحصول على شهادة WWGH لمشروعك. ويمكنك اتّباع الخطوات الواردة في صفحة الاعتماد.