ZCL Advanced Platform (ZAP)

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

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

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

שימוש

נקודות קצה

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

Endpoint - 0 כולל אשכולות כלליים שרלוונטיים לצומת כולו, למשל Networking,‏ Commissioning,‏ Descriptor,‏ Operational Credentials ו-OTA Clusters.

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

בשלבים הבאים בודקים ומגדירים את Endpoint - 1 (נקודת קצה – 1) Matter Dimmable Light מהדוגמה 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 כולל שיטה של קריאה חוזרת מ-Cluster שכוללת רק את ה-Clusters שהפעלתם:

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.