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

1. قبل البدء

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

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

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

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

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

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

المعلومات التي ستطّلع عليها

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

2. الاطّلاع على إحصاءات صفحة Google الرئيسية

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

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

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

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

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

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

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

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

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

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

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

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

بمجرد فتح مستكشف السجلات، تحصل على طريقة عرض تبدو كما يلي:

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

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

3- تصحيح أخطاء التكليف

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

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

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

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

استخدام إحصاءات صفحة Google الرئيسية

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

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

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

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

يتوفّر ADB كجزء من أدوات Android SDK Platform التي يمكن تثبيتها من خلال استوديو Android أو من خلال أداة سطر أوامر sdkmanager.

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

$ adb -- version

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

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

الخطوة التالية هي تفعيل تصحيح أخطاء USB على جهاز Android.

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

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

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

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

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

طلب تصحيح أخطاء USB

  1. إذا تلقيت رسالة التحذير هذه، انقر على السماح.
  2. أصدر أمر قائمة بالأجهزة من الوحدة الطرفية لمعرفة ما إذا كان يمكن للكمبيوتر الوصول إلى الهاتف من خلال 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، يمكنك أيضًا البحث عن الأخطاء التي أنشأها النظام الفرعي لسلسلة المحادثات من خلال الأمر التالي:
$ 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 Hub تعتمد على معيار 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 المتكاملة للمنازل الذكية.

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

7. تهانينا

Google Home

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

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

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

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