ZCL Advanced Platform (ZAP)

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

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

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

התקנה

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

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

אפשרויות גלובליות של ZAP

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

שימוש

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

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

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

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

בשלבים הבאים צריך לבדוק ולהגדיר את נקודת קצה (endpoint) – 1 Matter ניתן לכבות את התאורה מהדוגמה lighting-app.

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

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

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

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

    מכשיר ZAP Select

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

אשכולות

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

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

אשכולות שמופעלת ב-ZAP

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

השבתת אשכול של ZAP

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

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

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

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

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

    הגדרת ZAP

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

מאפייני ZAP

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

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.