پلتفرم پیشرفته ZCL (ZAP) یک موتور قالب node.js است که بر اساس Matter Clusters ساخته شده است.
ZAP ویژگی‌های زیر را برای برنامه‌ها و SDKهای Matter ارائه می‌دهد:
- نقاط پایانی، خوشه‌ها، ویژگی‌ها و سایر ویژگی‌های دستگاه Matter را از یک رابط کاربری گرافیکی پیکربندی کنید.
- قالب‌هایی ایجاد کنید که به طور خودکار تعاریف مدل داده، فراخوانی‌های مجدد و سایر کد منبع Matter را تولید کنند.
- فایل‌های ZAP از پیش پیکربندی‌شده را ایجاد و استفاده کنید تا به SDKهای خود اضافه کنید.
نصب
به صفحه انتشار ZAP بروید.
به دنبال نسخه‌ای با برچسب «آخرین» باشید (بیشتر نسخه‌ها با برچسب «پیش از انتشار» مشخص شده‌اند).
در این نسخه، زیر عنوان Assets ، بسته‌ای را که برای سیستم عامل شما تعیین شده است انتخاب کرده و آن را دانلود کنید.
روی دستگاهی که دبیان یا اوبونتو را اجرا می‌کند، ZAP را با اجرای دستور زیر نصب کنید:
sudo dpkg -i path/to/zap_installation_package
در لینوکس دبیان یا اوبونتو، فایل باینری 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 یافت می‌شود، از پیش با Common Matter Clusters و سه Endpoint، از جمله Matter Secondary Network Commissioning Device Type، پیکربندی شده است. این مثال خوبی برای بررسی پیکربندی‌های مختلف Cluster است.
اجرا کنید
- یک فایل ZAP را از یکی از مثال‌های Matter انتخاب کنید.
- از دایرکتوری ریشه مخزن Matter (
connectedhomeip)، اسکریپت wrapper مربوطrun_zaptool.shرا اجرا کنید و مسیر فایل.zapرا به آن بدهید.
برای مثال:
./scripts/tools/zap/run_zaptool.sh ./examples/lighting-app/lighting-common/lighting-app.zapتنظیم کنید
در ، می‌توانید رابط کاربری ZAP، از جمله انتخاب تم روشن یا تیره، و فعال یا غیرفعال کردن ابزارهای توسعه‌دهنده را پیکربندی کنید.
با کلیک روی Options می‌توانید تولیدکننده محصول ، سیاست پاسخ پیش‌فرض و فعال یا غیرفعال کردن کشف فرمان را انتخاب کنید.
برای افزودن خوشه‌ها یا دستورات ZCL سفارشی به پیکربندی خوشه‌های Zigbee، روی Extensions کلیک کنید.
استفاده کنید
نقاط پایانی
فایل lighting-app.zap از پیش با یک گره ریشه Matter ( نقطه پایانی - 0 ) و یک چراغ Dimmable Matter ( نقطه پایانی - 1 ) پیکربندی شده است.
نقطه پایانی - 0 شامل خوشه‌های عمومی است که به کل گره مربوط می‌شوند، به عنوان مثال خوشه‌های شبکه، راه‌اندازی، توصیفگر، اعتبارنامه‌های عملیاتی و OTA.
در مراحل بعدی، Endpoint - 1 Matter Dimmable Light را از نمونه lighting-app بررسی و پیکربندی خواهید کرد.
از مخزن Matter
connectedhomeip، دستور ZAP را اجرا کنید.scripts/tools/zap/run_zaptool.sh \ examples/lighting-app/lighting-common/lighting-app.zapروی Endpoint-1 کلیک کنید، سپس EDIT را .
اختیاری: Matter از انواع مختلف دستگاه پشتیبانی می‌کند. در منوی کشویی Device ، برای تغییر دستگاه خود، شروع به تایپ
matterکنید، سپس روی SAVE کلیک کنید.
برای کسب اطلاعات بیشتر، به بخش «دستگاه‌ها و نقاط پایانی» در فصل مقدماتی Matter مراجعه کنید.
خوشه‌ها
گزینه‌های از پیش تعریف‌شده‌ی کلاسترها، ویژگی‌ها و گزارش‌گیری به طور پیش‌فرض در Endpoint - 1 فعال هستند.
برای نمایش فقط خوشه‌های فعال، روی Endpoint - 1 کلیک کنید و از منوی Show ، خوشه‌های فعال را انتخاب کنید. همچنین می‌توانید خوشه‌های را بر اساس نام، مثلاً on ، جستجو کنید.
برای فعال کردن هر کلاستر به عنوان کلاینت ، سرور یا کلاینت و سرور ، از منوی کشویی Enable استفاده کنید. همچنین می‌توانید برای غیرفعال کردن یک کلاستر از پیش پیکربندی شده که به نوع دستگاه شما مربوط نمی‌شود، گزینه Not Enabled را انتخاب کنید.
برای کسب اطلاعات بیشتر، به کتاب « خوشه‌ها در Matter » مراجعه کنید.
ویژگی‌ها و دستورات
برای پیکربندی ویژگی‌ها و دستورات، مراحل زیر را انجام دهید:
- خوشه
On/Offرا پیدا کنید. در همان ردیف، روی «پیکربندی آیکون» کلیک کنید.
در اینجا می‌توانید ویژگی‌ها را فعال یا غیرفعال کنید، گزینه‌های مختلف ویژگی را تنظیم کنید و ویژگی‌ها را بر اساس نام جستجو .
برای پیکربندی اقدامات این خوشه، روی «دستورات» کلیک کنید. برای مثال، خوشه روشن/خاموش برای یک چراغ شامل دستورات روشن ، خاموش و تغییر وضعیت خواهد بود. برخی از خوشه‌ها، مانند خوشه 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>
پس از پیکربندی Endpointها، می‌توانید فایل‌های منبع را برای ادغام در پروژه خود ایجاد کنید.
- روی کلیک کنید تا تولید شود .
- یک پوشه برای ذخیره خروجی ZAP انتخاب کنید. برای مثال، برای
lighting-appبهconnectedhomeip/zzz_generated/lighting-app/zap-generatedبروید. - اختیاری . فایل‌ها را در IDE دلخواه خود باز کنید.
ZAP تعاریف، توابع و سایر کدهای منبع را متناسب با نوع دستگاه و پیکربندی ZAP شما تولید می‌کند.
برای مثال، callback-stub.cpp شامل یک متد فراخوانی Cluster است که فقط شامل 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/ ، می‌توانند برای دریافت و تنظیم ویژگی‌های نوع دستگاه استفاده شوند:
ویژگی‌ها.h
namespace DeviceTemperatureConfiguration {
namespace Attributes {
namespace CurrentTemperature {
static constexpr AttributeId Id = 0x00000000;
} // namespace CurrentTemperature
...
} // namespace Attributes
} // namespace DeviceTemperatureConfiguration
اصلی.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 را در SDK خود ادغام کنید .
منابع
برای منابع بیشتر ZAP، به مخزن ZAP ( zap ) در GitHub مراجعه کنید.