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 Apps und SDKs:

• Konfigurieren Sie Matter Endpunkte, Cluster, Attribute und andere Gerätefunktionen über eine grafische Benutzeroberfläche.
• Erstellen Sie Vorlagen, mit denen automatisch Definitionen für das Datenmodell, Callbacks und anderer Matter Quellcode generiert werden.
• Erstellen und verwenden Sie vorkonfigurierte ZAP-Dateien, die Sie in Ihre SDKs einbinden können.

Installieren

1. Rufen Sie die ZAP-Releases Seite auf.

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

3. Wählen Sie unter diesem Release unter der Überschrift Assets das Paket für Ihr Betriebssystem 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 zap-Binärdatei in /usr/bin/ installiert. Bei anderen Betriebssystemen wird die Binärdatei möglicherweise an einem anderen Ort installiert. 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, einschließlich eines sekundären Matter Gerätetyps für die Inbetriebnahme. Dies ist ein gutes Beispiel, um verschiedene Clusterkonfigurationen zu testen.

Ausführen

1. Wählen Sie 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 .zap-Datei.

Beispiel:

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

Einrichten

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

Wenn Sie auf tune Optionen klicken, können Sie den Produkthersteller und die Standardrichtlinie für Antworten 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 Root-Knoten (Endpunkt – 0) und einer Matter dimmbaren Lampe (Endpunkt – 1) vorkonfiguriert.

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

In den nächsten Schritten überprüfen und konfigurieren Sie die dimmbare Lampe Endpunkt – 1 Matter aus dem Beispiel lighting-app.

1. Führen Sie ZAP aus dem Matter Repository connectedhomeip 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 im Matter Primer unter Geräte und Endpunkte.

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 search Clustern nach Namen suchen, z. B. on.

Verwenden Sie das Drop-down-Menü Aktivieren, um einen Cluster als Client, Server oder Client & Server zu aktivieren. Sie können auch Nicht aktiviert auswählen, um einen vorkonfigurierten Cluster zu deaktivieren, der nicht für Ihren Gerätetyp gilt.

Weitere Informationen finden Sie im Matter Primer unter Cluster.

Attribute und Befehle

So konfigurieren Sie 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 mit Attribute suchen search nach Namen suchen.

Klicken Sie auf Befehle , um Aktionen für diesen Cluster zu konfigurieren. For example, the On/off Cluster for a light will include On, Off, and Toggle commands. Einige Cluster wie der Cluster Temperature Measurement haben möglicherweise keine zugehörigen Befehle.

Weitere Informationen finden Sie im Matter Primer unter Attribute und Befehle.

ZAP-Quelldateien generieren

Matter Beispiele verwenden ZAP-generierten Quellcode, verfügbar im Verzeichnis connectedhomeip/zzz_generated. Einige Dateien sind appspezifisch, 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 Ihre Endpunkte konfiguriert haben, können Sie Quelldateien generieren, die Sie in Ihr Projekt einbinden können.

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

ZAP generiert Definitionen, Funktionen und anderen Quellcode, der für Ihren Gerätetyp und Ihre ZAP-Konfiguration spezifisch 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 wie Attributes.h in zzz_generated/app-common/app-common/zap-generated/ids/ können verwendet werden, um Attribute des Gerätetyps 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");
    }
}

Sobald Sie wissen, 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 Matter Vorlagennamen 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 mehrere nächste Schritte ausführen:

• ZAP-Vorlagen erstellen
• ZAP in Ihr SDK einbinden.

Ressourcen

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