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

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 والانتقال إلى العمليات > المراقبة > لوحات البيانات.

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

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

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

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

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

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

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

بمجرد فتح مستكشف السجلات يظهر لك عرض يشبه ما يلي:

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

3. تصحيح أخطاء التفويض

إنّ النوع الأول من المقاييس الذي سنلقي نظرة عليه يتعلّق بأحداث تفويض المسألة القانونية. يشير التفويض إلى مجموعة الخطوات التي يجب أن يتّبعها المستخدم لإعداد جهاز 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.

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

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

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

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

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

$ adb -- version

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

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

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

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

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

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

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 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: يمكنك التواصل معنا ومع منتدى مطوّري أجهزة Smart Home لطرح أسئلة عن التنفيذ أو طلب الإرشادات. هذه القناة هي الأنسب للسؤال عن كيفية تحديد المشاكل وحلّها أو تنفيذ ميزة معيّنة.
• أداة تتبُّع المشاكل: هذا هو نظام تتبُّع المشاكل الرسمي الذي تديره Google، حيث يمكن للجماهير الخارجية الإبلاغ عن الأخطاء في المنظومة المتكاملة. وهو يوفر أدوات ويب لإرفاق الملفات ومشاركة المعلومات الحساسة عند الحاجة. ويعتبر استخدام أداة "تتبُّع المشاكل" الطريقة الأفضل للإبلاغ عن مشاكل المنظومة المتكاملة أو مشاركة طلبات الميزات.
• منتدى المطوّرين: للحصول على إرشادات من فريق الدعم الرسمي في Google وخبراء المنتدى، يمكنك التواصل من خلال منتدى مطوّري برامج Nest. هذا المنتدى هو الخيار الأفضل للحصول على إرشادات رسمية للتطوير.

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

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

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

7. تهانينا

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

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

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

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