ZCL Advanced Platform (ZAP)

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

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

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

تثبيت

  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

إعداد

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

يتيح لك النقر على الخيارات اختيار الشركة المصنّعة للمنتج وسياسة الرد التلقائي وتفعيل ميزة "اكتشاف الأوامر" أو إيقافها.

ZAP Global Options

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

استخدام

نقاط النهاية

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

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

ZAP Endpoint 0

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

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

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

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

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

    ZAP Select Device

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

المجموعات

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

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

المجموعات التي تم تفعيل ZAP فيها

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

ZAP Disable Cluster

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

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

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

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

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

    إعداد ZAP

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

سمات ZAP

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

أوامر ZAP

لمزيد من المعلومات، يُرجى الرجوع إلى السمات والأوامر في 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. انقر على إنشاء.
  2. اختَر مجلدًا لحفظ نتائج ZAP. على سبيل المثال، انتقِل إلى connectedhomeip/zzz_generated/lighting-app/zap-generated للحصول على lighting-app.
  3. Optional. افتح الملفات في بيئة التطوير المتكاملة (IDE) المفضّلة لديك.

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

الملفات التي تم إنشاؤها باستخدام ZAP

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

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/، للحصول على سمات نوع الجهاز وضبطها:

Attributes.h

namespace DeviceTemperatureConfiguration {
  namespace Attributes {

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

  ...

  } // namespace Attributes
} // namespace DeviceTemperatureConfiguration

main.cpp

#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 (zap) على GitHub.