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

1- قبل البدء

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

يتضمّن هذا الدرس التطبيقي ثلاثة مكوّنات رئيسية لمعيار 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".

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

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

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

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

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

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

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

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

3. تصحيح أخطاء تكليف العملاء

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

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

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

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

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

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

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

حالات العمولات:

• عمولة
• ONBOARDING_PAYLOAD_GENERATED
• نجاح_الأماكن المحلية
• نجاح في عملية الربط
• NOC_ADDED_SUCCESSfullY
• عمولة مكتملة

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

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

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

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

يتوفّر التطبيق ADB كجزء من أدوات Android Platform 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 يستخدم سلسلة محادثات، يمكنك أيضًا البحث عن الأخطاء التي أنشأها النظام الفرعي لسلسلة المحادثات من خلال الأمر التالي:

$ 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، أريد إضاءة المصابيح في غرفة المعيشة") أو باستخدام واجهة المستخدم في تطبيق Google Home أو على أجهزة عرض Google Nest.

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

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

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

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

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

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

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

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

6- طلب الدعم

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

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

هناك ثلاث قنوات مطوّري البرامج خاضعة للرقابة النشطة لدى Google:

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

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

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

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

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

7- تهانينا

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

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

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

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