ZCL Advanced Platform (ZAP) یک موتور الگوی node.js است که براساس Matter Clusters است.
ZAP ویژگی‌های زیر را برای برنامه‌ها و کیت‌های توسعه نرم‌افزار Matter ارائه می‌دهد:
- Matter «نقطه‌های پایانی»، «خوشه‌ها»، «مشخصه‌ها»، و دیگر ویژگی‌های دستگاه را از میانای GUI پیکربندی کنید.
- الگوهایی ایجاد کنید که به‌طور خودکار تعاریف مدل داده، فراخوانی‌های برگشتی، و دیگر کدهای منبع Matter را تولید می‌کنند.
- فایل‌های ZAP ازپیش‌پیکربندی‌شده را برای گنجاندن در کیت‌های توسعه نرم‌افزارتان ایجاد و استفاده کنید.
نصب
به صفحه نسخه‌های پخش ZAP بروید.
به‌دنبال نسخه‌ای بگردید که برچسب «Latest» (جدیدترین) دارد (اکثر نسخه‌ها برچسب «Pre-release» (پیش‌انتشار) دارند).
در این نسخه، در زیر عنوان دارایی‌ها، بسته‌ای را که برای سیستم‌عامل شما تعیین شده است انتخاب و بارگیری کنید.
در دستگاهی که 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. این نمونه خوبی برای کاوش پیکربندی‌های مختلف «خوشه» است.
اجرا کردن
- فایل ZAP را از یکی از Matter مثال انتخاب کنید.
- از دایرکتوری ریشه مخزن Matter (
connectedhomeip)، اسکریپت پوشانندهrun_zaptool.shرا اجرا کنید و مسیر فایل.zapرا به آن بدهید.
برای مثال:
./scripts/tools/zap/run_zaptool.sh ./examples/lighting-app/lighting-common/lighting-app.zapتنظیم کردن
در تنظیمات می‌توانید میانای کاربر ZAP را پیکربندی کنید، ازجمله انتخاب طرح زمینه روشن یا تیره، و فعال یا غیرفعال کردن ابزارهای توسعه‌دهنده.
با کلیک کردن روی گزینه‌ها می‌توانید سازنده محصول، خط‌مشی پاسخ پیش‌فرض را انتخاب کنید و «کاوش فرمان» را فعال یا غیرفعال کنید.
روی افزونه‌ها کلیک کنید تا خوشه‌ها یا فرمان‌های ZCL سفارشی را به «پیکربندی‌ساز خوشه‌های Zigbee» اضافه کنید.
استفاده کردن
نقاط پایانی
فایل lighting-app.zap ازقبل با یک Matter
«گره ریشه» (نقطه پایانی - ۰) و یک Matter «چراغ با نور کاهنده»
(نقطه پایانی - ۱) پیکربندی شده است.
نقطه پایانی - ۰ شامل «خوشه‌های» عمومی است که به کل گره مربوط می‌شوند، برای مثال «خوشه‌های» «شبکه‌سازی»، «راه‌اندازی»، «توصیف‌گر»، «اعتبارنامه‌های عملیاتی»، و OTA.
در مراحل بعدی، نقطه پایانی - ۱
Matter چراغ با نور قابل‌تنظیم از نمونه lighting-app را مرور و پیکربندی خواهید کرد.
از مخزن Matter
connectedhomeip، ZAP را اجرا کنید.scripts/tools/zap/run_zaptool.sh \ examples/lighting-app/lighting-common/lighting-app.zapروی نقطه پایانی - ۱، سپس ویرایش کلیک کنید.
اختیاری: Matter از انواع مختلف دستگاه پشتیبانی می‌کند. در منو کرکره‌ای دستگاه، شروع به تایپ کردن
matterکنید تا دستگاهتان را تغییر دهید، سپس روی ذخیره کلیک کنید.
برای کسب اطلاعات بیشتر، به دستگاه‌ها و نقاط پایانی در Matter Primer مراجعه کنید.
دسته‌ها
گزینه‌های «خوشه‌ها»، «مشخصه‌ها»، و «گزارش‌دهی» ازپیش‌تعریف‌شده به‌طور پیش‌فرض در پایانه - ۱ فعال هستند.
برای نمایش فقط «خوشه‌های» فعال‌شده، روی نقطه پایانی - ۱ کلیک کنید و
خوشه‌های فعال‌شده را از منو نمایش
انتخاب کنید. همچنین می‌توانید خوشه‌های را براساس نام جستجو کنید، برای مثال on.
برای فعال کردن هر «خوشه» به‌عنوان کارخواه، سرور، یا کارخواه و سرور، از منو کرکره‌ای فعال کردن استفاده کنید. همچنین می‌توانید فعال نیست را انتخاب کنید تا «خوشه» ازپیش پیکربندی‌شده‌ای را که برای نوع دستگاهتان کاربرد ندارد غیرفعال کنید.
برای کسب اطلاعات بیشتر، به خوشه‌ها در «کتاب راهنمای» Matter مراجعه کنید.
مشخصه‌ها و فرمان‌ها
برای پیکربندی «مشخصه‌ها» و «فرمان‌ها»، مراحل زیر را تکمیل کنید:
- خوشه
On/Offرا پیدا کنید. در همان ردیف، روی نماد «پیکربندی» کلیک کنید.
در اینجا می‌توانید «مشخصه‌ها» را فعال یا غیرفعال کنید، گزینه‌های مختلف «مشخصه» را تنظیم کنید، و مشخصه‌ها را براساس نام جستجو کنید .
برای پیکربندی کنش‌های این «خوشه»، روی فرمان‌ها کلیک کنید. برای
مثال، «خوشه» روشن/خاموش برای چراغ شامل فرمان‌های روشن، خاموش،
و تغییر وضعیت خواهد بود. برخی‌از «خوشه‌ها»، مثل
«خوشه» 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>
پس‌از پیکربندی «نقاط پایانی»، می‌توانید فایل‌های منبع را برای ادغام در پروژه‌تان تولید کنید.
- روی تولید کلیک کنید.
- پوشه‌ای را برای ذخیره کردن برونداد ZAP انتخاب کنید. برای مثال، به
connectedhomeip/zzz_generated/lighting-app/zap-generatedبرایlighting-appبروید. - اختیاری. فایل‌ها را در 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/، می‌توان برای
دریافت و تنظیم «مشخصه‌های» نوع دستگاه استفاده کرد:
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، به
مخزن ZAP
(zap)
در GitHub مراجعه کنید.