ZCL Advanced Platform (ZAP)

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

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

  • הגדרת Matter נקודות קצה, אשכולות, מאפיינים ותכונות אחרות של המכשיר מממשק משתמש גרפי.
  • יצירת תבניות שיוצרות באופן אוטומטי הגדרות של מודל נתונים, קריאות חוזרות (callback) וקוד מקור אחר של 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 Dimmable Light (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.

יצירת קובצי מקור של 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.