ZCL Advanced Platform (ZAP)

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

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

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

התקנה

1. נכנסים לדף ZAP releases.

2. מחפשים את הגרסה שמתויגת בתור Latest (רוב הגרסאות יתויגו בתור Pre-release).

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

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

הגדרה

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

לחיצה על tune Options מאפשרת לבחור את Product Manufacturer, את Default Response Policy, ולהפעיל או להשבית את Command Discovery.

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

שימוש

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

הקובץ lighting-app.zap מוגדר מראש עם צומת בסיס (Matter) (נקודת קצה – 0) ועם Matter Dimmable Light (נקודת קצה – 1).

נקודת קצה – 0 כוללת אשכולות כלליים שרלוונטיים לכל הצומת, למשל אשכולות של רשתות, הפעלה, מתאר, פרטי כניסה תפעוליים ו-OTA.

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

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

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

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

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

   

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

אשכולות

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

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

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

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

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

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

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

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

   

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

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

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.