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

‫1. قبل البدء

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

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

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

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

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

أهداف الدورة التعليمية

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

‫2. عرض إحصاءات Google Home

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

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

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

تتوفّر عدة لوحات بيانات لمشروعك (بما في ذلك منتجات GCP الأخرى). تتضمّن لوحات البيانات المتوفّرة للمنزل المزوّد بأجهزة ذكية البادئة Google Home Analytics.

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

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

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

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

الوصول إلى سجلّات الأخطاء

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

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

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

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

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

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

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

استخدام "إحصاءات 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 كجزء من أدوات النظام الأساسي لحزمة تطوير البرامج (SDK) لنظام التشغيل Android، والتي يمكن تثبيتها باستخدام استوديو Android أو من خلال أداة سطر الأوامر sdkmanager.

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

$ adb -- version

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

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

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

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

يسمح ذلك لأداة تصحيح أخطاء Android بالوصول إلى السجلّات التي تنشئها التطبيقات التي يتم تشغيلها حاليًا على الجهاز.

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

1. شغِّل خادم ADB باستخدام الأمر التالي:

$ adb start-server

2. وصِّل هاتفك بالكمبيوتر الذي يشغّل خادم ADB.

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

3. إذا تلقّيت رسالة التحذير هذه، انقر على السماح.
4. أدخِل أمرًا لإدراج الأجهزة من الوحدة الطرفية لمعرفة ما إذا كان بإمكان جهاز الكمبيوتر الوصول إلى الهاتف من خلال ADB، وذلك باستخدام الأمر التالي:

$ adb devices

من المفترض أن يظهر ردّ مشابه لما يلي:

List of devices attached
<phone-id>    device

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

5. تذكَّر قيمة <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"

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

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

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

6. طلب الدعم

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

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

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

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

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

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

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

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

7. تهانينا

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

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

جرِّب التمارين التالية واطّلِع على مراجع إضافية:

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