ZCL Advanced Platform (ZAP)

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

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

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

התקנה

1. נכנסים לדף גרסאות של ZAP.

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

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 נפוצים ושלוש נקודות קצה (endpoint), כולל Matter Secondary Networking Device Type. זוהי דוגמה טובה לבדיקה של ההגדרות השונות של Cluster.

ריצה

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

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

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

שימוש

נקודות קצה

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

בשדה endpoint - 0 נכללים אשכולות כלליים שרלוונטיים לצומת כולו, לדוגמה Networking, Commissioning, Descriptor, Operational Credentials ו-OTA.

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

1. ממאגר Matterconnectedhomeip, מריצים את 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 Primer.

אשכולות

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

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

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

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

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

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

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

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

   

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

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

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

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

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.