ZCL Advanced Platform (ZAP)

ZCL Advanced Platform (ZAP) הוא מנוע תבנית שלNode.js שמבוסס על Matter אשכולות.

ZAP מספקת את התכונות הבאות עבור Matter אפליקציות וגם ערכות SDK:

  • הגדרת Matter נקודות קצה, אשכולות, מאפיינים ו תכונות אחרות של המכשיר מממשק GUI.
  • ליצור תבניות שיוצרות באופן אוטומטי הגדרות של מודל נתונים, קריאות חוזרות (callback) וקוד מקור אחר של 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), מריצים את סקריפט ה-wrapper run_zaptool.sh, ומעבירים אותו את הנתיב לקובץ .zap.

לדוגמה:

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

הגדרה

ב- הגדרות אפשר לקבוע דרך ממשק המשתמש של ZAP, כולל עיצוב בהיר או כהה שבחרתם, הפעלה או השבתה של הכלים למפתחים.

לחיצה על אפשרויות מאפשרת לבחור את המוצר היצרן, מדיניות ברירת המחדל לתגובה, והפעלה או השבתה של פקודות גילוי.

אפשרויות גלובליות של ZAP

לוחצים על תוספים כדי להוסיף תוספים בהתאמה אישית. אשכולות או פקודות של ZCL ל-Zigbee Clusters Configurator.

שימוש

נקודות קצה (endpoints)

הקובץ lighting-app.zap מוגדר מראש באמצעות Matter צומת Root (נקודת קצה (endpoint) – 0) ונורה עם עמעום של Matter (נקודת קצה – 1).

Endpoint - 0 כולל אשכולות כלליים רלוונטיות לכל הצומת, לדוגמה Networking, Commissioning, Descriptor, פרטי כניסה תפעוליים ואשכולות OTA.

נקודת קצה (endpoint) של ZAP 0

בשלבים הבאים תוכלו לבדוק ולהגדיר את נקודת קצה (endpoint) – 1 Matter תאורה ניתנת לעמעום מהדוגמה lighting-app.

  1. מהמאגר connectedhomeip של Matter, מריצים את ZAP.

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

  2. לוחצים על נקודת קצה – 1, ואז עריכה.

  3. אופציונלי: Matter תומך בסוגים שונים של מכשירים. לחשבון בתפריט הנפתח מכשיר, מתחילים להקליד matter כדי לשנות את המכשיר, ולאחר מכן לוחצים על שמירה.

    מכשיר ZAP Select

מידע נוסף זמין במאמר הבא: מכשירים ו נקודות קצה (endpoints) פריימר Matter.

אשכולות

אשכולות, מאפיינים ואפשרויות דיווח מוגדרים מראש מופעלות ב- נקודת קצה (endpoint) – 1 כברירת מחדל.

כדי להציג רק אשכולות שהופעלו, לוחצים על נקודת קצה - 1 ובוחרים Enabled Clusters מההצגה תפריט אפשר גם לחפש אשכולות לפי שם, לדוגמה on.

אשכולות שמופעלת ב-ZAP

כדי להפעיל כל אשכול בתור Client, Server או Client & שרת, משתמשים בתפריט הנפתח Enable. אפשר גם לבחור באפשרות לא מופעל כדי להשבית אשכול מוגדר מראש שלא רלוונטי לסוג המכשיר שלכם.

השבתת אשכול של ZAP

מידע נוסף זמין במאמר הבא: אשכולות בכתבה של Matter.

מאפיינים ופקודות

כדי להגדיר מאפיינים ופקודות, מבצעים את השלבים הבאים:

  1. מאתרים את האשכול On/Off.

  2. באותה שורה, לוחצים על הסמל 'הגדרה'.

    הגדרת ZAP

כאן ניתן להפעיל או להשבית מאפיינים, להגדיר אפשרויות שונות של מאפיינים, מאפייני חיפוש לפי שם.

מאפייני ZAP

לוחצים על Commands כדי להגדיר פעולות לאשכול הזה. עבור לדוגמה, אשכול הפעלה/כיבוי של נורה יכלול את האפשרויות מופעל, כבוי, ו-Toggle. כמה אשכולות, כמו יכול להיות שלאשכול Temperature Measurement לא משויכות פקודות.

פקודות ZAP

מידע נוסף זמין במאמר הבא: מאפיינים ופקודות בכתבה של 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. לוחצים על יצירה.
  2. צריך לבחור תיקייה כדי לשמור את פלט ה-ZAP. לדוגמה, עוברים אל connectedhomeip/zzz_generated/lighting-app/zap-generated ל- lighting-app.
  3. אופציונלי. פותחים את הקבצים בסביבת הפיתוח המשולבת (IDE) המועדפת.

ZAP יוצרת הגדרות, פונקציות וקוד מקור אחר שמותאם אישית סוג המכשיר ותצורת 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) ב-GitHub.