ZCL Advanced Platform (ZAP)

ZCL Advanced Platform (ZAP) هو محرك نموذج لـNode.js يستند إلى مجموعات Matter.

يوفّر ZAP الميزات التالية لتطبيقات وحِزم تطوير البرامج (SDK) لـ Matter:

• يمكنك ضبط نقاط النهاية والمجموعات والسمات في Matter وميزات الجهاز الأخرى من واجهة واجهة المستخدم الرسومية.
• يمكنك إنشاء نماذج تنشئ تلقائيًا تعريفات نماذج البيانات وطلبات استدعاء الإجراءات ورموز مصدر Matter أخرى.
• يمكنك إنشاء ملفات ZAP المُعدّة مسبقًا واستخدامها لتضمينها مع حِزم تطوير البرامج (SDK).

تثبيت

1. انتقِل إلى صفحة إصدارات ZAP.

2. ابحث عن الإصدار الذي تم وضع علامة "الأحدث" عليه (سيتم وضع علامة على معظمه "ما قبل الإصدار").

3. ضمن هذا الإصدار، ضمن العنوان مواد العرض، حدد الحزمة المخصصة لنظام التشغيل الذي تستخدمه ونزِّله.

4. على جهاز يعمل بنظام Debian أو Ubuntu، ثبِّت ZAP عن طريق تشغيل:

   sudo dpkg -i path/to/zap_installation_package
   

في نظام التشغيل Debian أو Ubuntu، يتمّ تثبيت البرنامج الثنائي zap في /usr/bin/. وقد يتم تثبيت البرنامج الثنائي على أنظمة تشغيل أخرى في مكان آخر. على أي حال، عليك التحقق للتأكد من أنّ موقع الملف التنفيذي موجود في متغيّر بيئة PATH.

ملفات ZAP

يستخدم ZAP ملفات نماذج تسمى ملفات ZAP. ملف ZAP هو ملف JSON يحدد نقاط النهاية والأوامر والسمات وغيرها من ميزات الجهاز. ملفات ZAP لها أسماء تنتهي بـ .zap. على سبيل المثال، lighting-app.zap في connectedhomeip/examples/lighting-app/lighting-common.

ملف all-clusters-app.zap المتوفّر في connectedhomeip/examples/all-clusters-app/all-clusters-common تم ضبطه مسبقًا باستخدام مجموعات Matter الشائعة وثلاث نقاط نهاية، بما في ذلك نوع الجهاز الذي يعمل بتفويض الشبكة الثانوية، وهو Matter. وهذا مثال جيد لاستكشاف تكوينات المجموعة المختلفة.

تنفيذ

1. اختَر ملف ZAP من أحد أمثلة Matter.
2. من الدليل الجذر لمستودع Matter (connectedhomeip)، شغِّل النص البرمجي لبرنامج تضمين run_zaptool.sh ونقله المسار إلى ملف .zap.

مثلاً:

./scripts/tools/zap/run_zaptool.sh ./examples/lighting-app/lighting-common/lighting-app.zap

إعداد

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

يؤدي النقر على tune الخيارات إلى اختيار Product Manufacturer وسياسة الاستجابة التلقائية وتفعيل Command Discovery أو إيقافه.

انقر على extension الإضافات لإضافة مجموعات أو أوامر ZCL مخصّصة إلى أداة Zigbee Clusters Configurator.

استخدام

نقاط النهاية

يتم ضبط الملف lighting-app.zap مسبقًا باستخدام عقدة جذرية Matter (نقطة نهاية - 0) ومصباح إضاءة قابلة للتعتيم Matter (نقطة النهاية - 1).

تتضمن نقطة النهاية - 0 المجموعات العامة ذات الصلة بالعقدة بأكملها، على سبيل المثال: الشبكات، والإعداد، والواصف، وبيانات الاعتماد التشغيلية، ومجموعات عبر الهواء.

في الخطوات التالية، عليك مراجعة وضبط نقطة النهاية - 1 Matter الإضاءة الخافتة من المثال lighting-app.

1. من Matter repo connectedhomeip، شغِّل ZAP.

   scripts/tools/zap/run_zaptool.sh \
   examples/lighting-app/lighting-common/lighting-app.zap
   

2. انقر على نقطة النهاية - 1، ثم على تعديل edit.

3. اختياري: يتوافق Matter مع العديد من أنواع الأجهزة. في القائمة المنسدلة الجهاز، ابدأ كتابة matter لتغيير جهازك، ثم انقر على حفظ.

   

لمعرفة المزيد، راجع الأجهزة ونقاط النهاية في Matter Primer.

المجموعات العنقودية

يتم تفعيل خيارات المجموعات والسمات وإعداد التقارير المحدَّدة مسبقًا في نقطة النهاية - 1 بشكل تلقائي.

لعرض المجموعات المفعّلة فقط، انقر على نقطة النهاية - 1 واختر المجموعات المفعّلة من القائمة عرض. يمكنك أيضًا البحث في مجموعات search حسب الاسم، على سبيل المثال on.

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

لمعرفة المزيد من المعلومات، راجع المجموعات في Matter Primer.

السمات والأوامر

لضبط "السمات" و"الأوامر"، أكمِل الخطوات التالية:

1. حدِّد موقع المجموعة On/Off.

2. في الصف نفسه، انقر على رمز الضبط settings.

   

يمكنك هنا تفعيل السمات أو إيقافها، وضبط خيارات السمات المختلفة، وسمات البحث search حسب الاسم.

انقر على الأوامر لضبط الإجراءات لهذه المجموعة. على سبيل المثال، تتضمن مجموعة تشغيل/إيقاف المصباح أوامر تشغيل وإيقاف وتبديل. قد لا تحتوي بعض المجموعات، مثل المجموعة Temperature Measurement، على أي أوامر مرتبطة.

لمعرفة المزيد، راجع السمات والأوامر في Matter Primer.

إنشاء ملفات مصدر ZAP

تستخدم أمثلة Matter رمز المصدر الذي أنشأه ZAP، والمتاح في دليل connectedhomeip/zzz_generated. تكون بعض الملفات خاصة بالتطبيقات، بينما يتم تجميع ملفات ZAP العامة الأخرى في app-common.

#include <app-common/zap-generated/ids/Attributes.h>
#include <app-common/zap-generated/ids/Clusters.h>

بعد ضبط نقاط النهاية، يمكنك إنشاء ملفات مصدر لدمجها في مشروعك.

1. انقر على video_settings إنشاء.
2. حدد مجلدًا لحفظ إخراج ZAP. على سبيل المثال، انتقِل إلى connectedhomeip/zzz_generated/lighting-app/zap-generated للوصول إلى lighting-app.
3. Optional. افتح الملفات في بيئة التطوير المتكاملة (IDE) التي تفضّلها.

ينشئ ZAP التعريفات والدوال بالإضافة إلى رمز مصدر آخر مخصّص لنوع جهازك وإعدادات ZAP.

على سبيل المثال، تتضمن السمة callback-stub.cpp طريقة استدعاء المجموعة التي تتضمّن فقط المجموعة التي فعّلتها:

void emberAfClusterInitCallback(EndpointId endpoint, ClusterId clusterId)
{
    switch (clusterId)
    {
     ...
     case ZCL_ON_OFF_CLUSTER_ID :
        emberAfOnOffClusterInitCallback(endpoint);
        break;
     ...
    }
}

استخدام الملفات المصدر لبرنامج ZAP

يمكن استخدام ملفات مصدر ZAP الشائعة، على سبيل المثال Attributes.h في zzz_generated/app-common/app-common/zap-generated/ids/، للحصول على سمات نوع الجهاز وإعدادها:

namespace DeviceTemperatureConfiguration {
  namespace Attributes {

  namespace CurrentTemperature {
    static constexpr AttributeId Id = 0x00000000;
    } // namespace CurrentTemperature

  ...

  } // namespace Attributes
} // namespace DeviceTemperatureConfiguration

#include <app-common/zap-generated/att-storage.h>
#include <app-common/zap-generated/attribute-id.h>
#include <app-common/zap-generated/attribute-type.h>
#include <app-common/zap-generated/attributes/Accessors.h>
#include <app-common/zap-generated/callback.h>
#include <app-common/zap-generated/cluster-id.h>
#include <app-common/zap-generated/cluster-objects.h>
#include <app-common/zap-generated/command-id.h>

using namespace ::chip;
using namespace ::chip::app::Clusters;

static void InitServer(intptr_t context)
{
    ...

    // Sets temperature to 20C
    int16_t temperature = 2000;
    auto status         = DeviceTemperatureConfiguration::Attributes::CurrentTemperature::Set(1, temperature);
    if (status != EMBER_ZCL_STATUS_SUCCESS)
    {
        ChipLogError(Shell, "Temp measurement set failed");
    }
}

بعد فهم طريقة استخدام ملفات ZAP في رمز المصدر Matter، هناك عدة طرق يمكنك من خلالها دمج ZAP:

• يمكنك استخدام ملفات zzz_generated الحالية لإنشاء أمثلة جديدة وفريدة لأنواع أجهزتك.
• يمكنك إنشاء ملفات .zap مخصّصة لمشاريعك.

تخصيص

يتم إنشاء ملفات ZAP من نماذج ZaAP. عند استخدام run_zaptool.sh لتشغيل ZAP، يتم تمرير هذا النص البرمجي في النماذج التالية:

node src-script/zap-start.js --logToStdout \
    --gen "$CHIP_ROOT/src/app/zap-templates/app-templates.json" \
    --zcl "$CHIP_ROOT/src/app/zap-templates/zcl/zcl.json" \
    "${ZAP_ARGS[@]}"

تحدد templates.json اسم النموذج Matter وملف الإخراج المناظر المستخدم في أمثلة Matter.

{
    "path": "templates/app/callback-stub-src.zapt",
    "name": "ZCL callback-stub source",
    "output": "callback-stub.cpp"
}

لتخصيص حلول Matter، هناك العديد من الخطوات التي يمكنك اتّخاذها عند استخدام ZAP:

• أنشِئ نماذج ZAP.
• دمج ZAP في حزمة تطوير البرامج (SDK)

المراجِع

للاطّلاع على موارد إضافية عن ZAP، يُرجى الرجوع إلى مستودع ZAP (zap) على GitHub.