ZCL Advanced Platform (ZAP)

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

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

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

تثبيت

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

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

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

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).

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

في الخطوات التالية، ستراجع وتعدّل نقطة النهاية 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 Primer.

المجموعات

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

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

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

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

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

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

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

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

   

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

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

لمزيد من المعلومات، يُرجى الرجوع إلى السمات والأوامر في دليل Matter المبتدئين.

إنشاء ملفات مصدر 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 من نماذج 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:

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

الموارد

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