ZCL Advanced Platform (ZAP)

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

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

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

تثبيت

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

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

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

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

   sudo dpkg -i path/to/zap_installation_package

على نظام التشغيل Debian أو Ubuntu Linux، يتم تثبيت الملف الثنائي 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 الخيارات إلى تحديد الشركة المصنّعة للمنتج وسياسة الاستجابة التلقائية وتفعيل ميزة "اكتشاف الأوامر" أو إيقافها.

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

استخدام

نقاط النهاية

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

نقطة النهاية 0 تتضمّن مجموعات عامة تتعلّق بالعقدة بأكملها، مثل مجموعات الشبكات والتشغيل والواصف وبيانات الاعتماد التشغيلية والتحديث عبر الهواء.

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

1. من مستودع Matter connectedhomeip، شغِّل ZAP.

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

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

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

   

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

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

يتم تفعيل خيارات "المجموعات" و"السمات" و"إعداد التقارير" المحدّدة مسبقًا في Endpoint - 1 تلقائيًا.

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على المجموعات في دليل Matter التمهيدي.

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

لضبط "السمات" و"الأوامر"، يُرجى إكمال الخطوات التالية:

1. ابحث عن مجموعة "On/Off".

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

   

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على السمات والأوامر في دليل Matter التمهيدي.

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

Matter examples use ZAP generated source code, available in the connectedhomeip/zzz_generated directory. بعض الملفات خاصة بالتطبيق، بينما يتم تجميع ملفات 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 من نماذج ZAP. عند استخدام 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.