ZCL Advanced Platform (ZAP)

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

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

• הגדרת נקודות קצה, אשכולות, מאפיינים ותכונות אחרות של מכשיר Matter דרך ממשק משתמש גרפי.
• יצירת תבניות שיוצרות באופן אוטומטי הגדרות של מודל נתונים, קריאות חזרה (callbacks) וקוד מקור אחר של Matter.
• יצירת קובצי ZAP מוגדרים מראש לשימוש עם ערכות ה-SDK.

התקנה

1. עוברים לדף ZAP releases.

2. מחפשים את הגרסה המתויגת בתווית 'הגרסה העדכנית ביותר' (רוב הגרסאות יסומנו בתווית 'גרסה מוקדמת').

3. בקטע הזה, בקטע נכסים, בוחרים את החבילה שמיועדת למערכת ההפעלה שלכם ומורידים אותה.

4. במכונה עם Debian או Ubuntu, מריצים את הפקודה הבאה כדי להתקין את ZAP:

   sudo dpkg -i path/to/zap_installation_package

ב-Debian או ב-Ubuntu Linux, קובץ ה-binary של 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 אפשרויות מאפשרת לכם לבחור את יצרן המוצר, את מדיניות התשובה שמוגדרת כברירת מחדל ולהפעיל או להשבית את Command Discovery.

לוחצים על extension Extensions כדי להוסיף לאפליקציית ההגדרה של אשכולות Zigbee אשכולות או פקודות ZCL בהתאמה אישית.

שימוש

נקודות קצה

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

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

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

1. מתוך המאגר Matter connectedhomeip, מריצים את ZAP.

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

2. לוחצים על Endpoint - 1 ואז על edit EDIT.

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

   

למידע נוסף, ראו מכשירים ונקודות קצה במאמר Matter.

אשכולות

כברירת מחדל, אפשרויות של אשכול, מאפיין ודוחות מוגדרים מראש מופעלות ב-Endpoint – 1.

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

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

למידע נוסף, קראו את המאמר אשכולות במדריך למתחילים בנושא Matter.

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

כדי להגדיר מאפיינים ופקודות:

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

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

   

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

לוחצים על Commands כדי להגדיר פעולות לאשכולות. לדוגמה, האשכולות On/off (הפעלה/כיבוי) של תאורה יכללו את הפקודות On (הפעלה), Off (כיבוי) ו-Toggle (החלפת מצב). יכול להיות שלאשכולות מסוימים, כמו אשכול 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>

אחרי שמגדירים את נקודות הקצה, אפשר ליצור קובצי מקור כדי לשלב אותם בפרויקט.

1. לוחצים על video_settings יצירה.
2. בוחרים תיקייה לשמירת הפלט של ZAP. לדוגמה, עוברים אל connectedhomeip/zzz_generated/lighting-app/zap-generated עבור lighting-app.
3. אופציונלי. פותחים את הקבצים בסביבת הפיתוח המשולבת (IDE) המועדפת.

ZAP יוצר הגדרות, פונקציות וקוד מקור נוסף בהתאמה אישית לסוג המכשיר ולהגדרות ZAP.

לדוגמה, callback-stub.cpp כולל שיטת קריאה חוזרת (callback) של אשכולות שכוללת רק את האשכולות שהפעלתם:

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.