ZCL Advanced Platform (ZAP)

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

توفر 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).

تتضمّن نقطة النهاية - 0 مجموعات عامة ذات صلة بالعقدة بأكملها، مثل مجموعات Networking وCommissioning وDescriptor وOperational Credentials وOTA.

في الخطوات التالية، ستراجع نقطة النهاية - 1 Matter ومصباح 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 Primer.

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

لضبط السمات والأوامر، يُرجى اتّباع الخطوات التالية:

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

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

   

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

انقر على الأوامر لضبط الإجراءات لهذه المجموعة. على سبيل المثال، ستتضمّن مجموعة On/off لمصباح الأوامر On وOff، وToggle. قد لا تتضمّن بعض المجموعات، مثل مجموعة 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. اختياري. افتح الملفات في بيئة التطوير المتكاملة المفضّلة لديك.

تنشئ 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.