ZCL Advanced Platform (ZAP)

ZCL Advanced Platform (ZAP) ist eine Node.js-Vorlagen-Engine, die auf Matter-Clustern basiert.

ZAP bietet die folgenden Funktionen für Matter-Anwendungen und SDKs:

• Konfigurieren Sie Matter-Endpunkte, -Cluster, -Attribute und andere Gerätefunktionen über eine GUI-Oberfläche.
• Vorlagen erstellen, die automatisch Datenmodelldefinitionen, Callbacks und anderen Matter-Quellcode generieren.
• Erstellen und verwenden Sie vorkonfigurierte ZAP-Dateien, die Sie in Ihre SDKs einbinden können.

Installieren

1. Rufen Sie die Seite ZAP-Releases auf.

2. Suchen Sie nach dem Release mit dem Tag „Latest“ (die meisten haben das Tag „Pre-release“).

3. Wählen Sie unter diesem Release unter der Überschrift Assets das für Ihr Betriebssystem vorgesehene Paket aus und laden Sie es herunter.

4. Installieren Sie ZAP auf einem Computer mit Debian oder Ubuntu, indem Sie Folgendes ausführen:

   sudo dpkg -i path/to/zap_installation_package

Unter Debian oder Ubuntu Linux wird die Binärdatei zap in /usr/bin/ installiert. Auf anderen Betriebssystemen kann die Binärdatei an anderer Stelle installiert sein. Prüfen Sie in jedem Fall, ob sich der Speicherort der ausführbaren Datei in der Umgebungsvariable PATH befindet.

ZAP-Dateien

ZAP verwendet Vorlagendateien, die als ZAP-Dateien bezeichnet werden. Eine ZAP-Datei ist eine JSON-Datei, in der Endpunkte, Befehle, Attribute und andere Gerätefunktionen definiert sind. ZAP-Dateien haben Namen, die auf .zap enden. Beispiel: lighting-app.zap in connectedhomeip/examples/lighting-app/lighting-common.

Die Datei all-clusters-app.zap in connectedhomeip/examples/all-clusters-app/all-clusters-common ist mit gängigen Matter-Clustern und drei Endpunkten vorkonfiguriert, darunter ein Matter-Gerätetyp für die Inbetriebnahme eines sekundären Netzwerks. Dies ist ein gutes Beispiel für die Erkundung verschiedener Clusterkonfigurationen.

Ausführen

1. Wähle eine ZAP-Datei aus einem der Matter-Beispiele aus.
2. Führen Sie im Stammverzeichnis des Matter-Repositorys (connectedhomeip) das Wrapper-Skript run_zaptool.sh aus und übergeben Sie den Pfad zur Datei .zap.

Beispiel:

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

Einrichten

In den settings-Einstellungen können Sie die ZAP-Benutzeroberfläche konfigurieren, einschließlich der Auswahl des hellen oder dunklen Designs und der Aktivierung oder Deaktivierung der Entwicklertools.

Wenn Sie auf tune Optionen klicken, können Sie den Produkthersteller und die Standardantwortrichtlinie auswählen sowie die Befehlserkennung aktivieren oder deaktivieren.

Klicken Sie auf extension Erweiterungen, um dem Zigbee Clusters Configurator benutzerdefinierte ZCL-Cluster oder ‑Befehle hinzuzufügen.

Verwenden

Endpunkte

Die Datei lighting-app.zap ist mit einem Matter-Stammknoten (Endpunkt 0) und einer dimmbaren Matter-Leuchte (Endpunkt 1) vorkonfiguriert.

Endpunkt 0 enthält allgemeine Cluster, die für den gesamten Knoten relevant sind, z. B. Netzwerk, Inbetriebnahme, Deskriptor, Betriebsanmeldedaten und OTA-Cluster.

In den nächsten Schritten überprüfst und konfigurierst du Endpunkt 1 Matter Dimmbare Lampe aus dem Beispiel lighting-app.

1. Führen Sie ZAP im Repository connectedhomeip Matter aus.

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

2. Klicken Sie auf Endpunkt – 1 und dann auf edit BEARBEITEN.

3. Optional: Matter unterstützt verschiedene Gerätetypen. Geben Sie im Drop-down-Menü Gerät matter ein, um das Gerät zu ändern, und klicken Sie dann auf SPEICHERN.

   

Weitere Informationen finden Sie unter Geräte und Endpunkte in der Einführung zu Matter.

Cluster

Vordefinierte Cluster, Attribute und Berichtsoptionen sind in Endpunkt 1 standardmäßig aktiviert.

Wenn Sie nur aktivierte Cluster anzeigen möchten, klicken Sie auf Endpunkt – 1 und wählen Sie im Menü Anzeigen die Option Aktivierte Cluster aus. Sie können auch nach dem Namen von search-Clustern suchen, z. B. on.

Wenn Sie einen Cluster als Client, Server oder Client und Server aktivieren möchten, verwenden Sie das Drop-down-Menü Aktivieren. Du kannst auch Nicht aktiviert auswählen, um einen vorkonfigurierten Cluster zu deaktivieren, der nicht für deinen Gerätetyp gilt.

Weitere Informationen finden Sie unter Cluster in der Einführung zu Matter.

Attribute und Befehle

So konfigurierst du Attribute und Befehle:

1. Suchen Sie den Cluster On/Off.

2. Klicken Sie in derselben Zeile auf das Symbol „Konfigurieren“ settings.

   

Hier können Sie Attribute aktivieren oder deaktivieren, verschiedene Attributoptionen festlegen und Attribute nach Namen suchen search.

Klicken Sie auf Befehle, um Aktionen für diesen Cluster zu konfigurieren. Beispielsweise enthält der Cluster Ein/Aus für eine Lampe die Befehle Ein, Aus und Umschalten. Einige Cluster, z. B. der Temperature Measurement-Cluster, haben möglicherweise keine zugehörigen Befehle.

Weitere Informationen findest du unter Attribute und Befehle in der Matter-Einführung.

ZAP-Quelldateien generieren

Matter-Beispiele verwenden von ZAP generierten Quellcode, der im Verzeichnis connectedhomeip/zzz_generated verfügbar ist. Einige Dateien sind App-spezifisch, während andere generische ZAP-Dateien in app-common gruppiert sind.

#include <app-common/zap-generated/ids/Attributes.h>
#include <app-common/zap-generated/ids/Clusters.h>

Nachdem Sie die Endpunkte konfiguriert haben, können Sie Quelldateien generieren, die Sie in Ihr Projekt einbinden können.

1. Klicken Sie auf video_settingsErstellen.
2. Wählen Sie einen Ordner aus, in dem die ZAP-Ausgabe gespeichert werden soll. Rufen Sie beispielsweise connectedhomeip/zzz_generated/lighting-app/zap-generated für lighting-app auf.
3. Optional: Öffnen Sie die Dateien in Ihrer bevorzugten IDE.

ZAP generiert Definitionen, Funktionen und anderen Quellcode, der auf Ihren Gerätetyp und Ihre ZAP-Konfiguration zugeschnitten ist.

callback-stub.cpp enthält beispielsweise eine Cluster-Callback-Methode, die nur die von Ihnen aktivierten Cluster enthält:

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

ZAP-Quelldateien verwenden

Allgemeine ZAP-Quelldateien, z. B. Attributes.h in zzz_generated/app-common/app-common/zap-generated/ids/, können verwendet werden, um Gerätetypattribute abzurufen und festzulegen:

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");
    }
}

Wenn Sie verstanden haben, wie ZAP-Dateien im Matter-Quellcode verwendet werden können, gibt es mehrere Möglichkeiten, ZAP einzubinden:

• Verwenden Sie die vorhandenen zzz_generated-Dateien, um neue Beispiele zu erstellen, die für Ihre Gerätetypen spezifisch sind.
• Erstellen Sie benutzerdefinierte .zap-Dateien für Ihre Projekte.

Anpassen

ZAP-Dateien werden aus ZAP-Vorlagen generiert. Wenn Sie ZAP mit run_zaptool.sh starten, übergibt dieses Skript die folgenden Vorlagen:

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 definiert den Vorlagennamen Matter und die entsprechende Ausgabedatei, die in Matter-Beispielen verwendet wird.

{
    "path": "templates/app/callback-stub-src.zapt",
    "name": "ZCL callback-stub source",
    "output": "callback-stub.cpp"
}

Wenn Sie Ihre Matter-Lösungen anpassen möchten, können Sie bei der Arbeit mit ZAP die folgenden Schritte ausführen:

• ZAP-Vorlagen erstellen
• ZAP in Ihr SDK einbinden

Ressourcen

Weitere ZAP-Ressourcen finden Sie im ZAP-Repository (zap) auf GitHub.