ZCL Advanced Platform (ZAP)

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

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

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

התקנה

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

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

ריצה

  1. בוחרים קובץ ZAP מאחת מMatter הדוגמאות.
  2. מהספרייה הראשית של מאגר Matter (connectedhomeip), מריצים את סקריפט העטיפה run_zaptool.sh ומעבירים לו את הנתיב לקובץ .zap.

לדוגמה:

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

הגדרה

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

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

אפשרויות כלליות של ZAP

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

שימוש

נקודות קצה

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

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

ZAP Endpoint 0

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

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

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

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

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

    ZAP Select Device

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

אשכולות

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

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

אשכולות עם הפעלת ZAP

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

ZAP Disable Cluster

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

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

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

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

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

    הגדרת ZAP

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

מאפיינים של ZAP

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

פקודות ZAP

מידע נוסף זמין במאמר מאפיינים ופקודות ב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>

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

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

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

קבצים שנוצרו על ידי ZAP

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

void emberAfClusterInitCallback(EndpointId endpoint, ClusterId clusterId)
{
    switch (clusterId)
    {
     ...
     case ZCL_ON_OFF_CLUSTER_ID :
        emberAfOnOffClusterInitCallback(endpoint);
        break;
     ...
    }
}

שימוש בקובצי מקור של ZAP

אפשר להשתמש בקבצי מקור נפוצים של ZAP, למשל Attributes.h in 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.