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“ getaggt).

3. Wählen Sie unter diesem Release unter der Überschrift Assets das Paket aus, das für Ihr Betriebssystem bestimmt ist, 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. 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 all-clusters-app.zap Datei in connectedhomeip/examples/all-clusters-app/all-clusters-common ist mit allgemeinen Matter Clustern und drei Endpunkten vorkonfiguriert, einschließlich eines sekundären Matter Netzwerk Inbetriebnahme-Gerätetyps. 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 Datei .zap.

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“ Options klicken, können Sie den Product Manufacturer (Produkthersteller) und die Default Response Policy (Standardrichtlinie für Antworten) auswählen sowie die Befehlserkennung (Command Discovery) aktivieren oder deaktivieren.

Klicken Sie auf extension Extensions , 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 (Endpoint - 0) und einer Matter dimmbaren Lampe (Endpoint - 1) vorkonfiguriert.

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

In den nächsten Schritten überprüfen und konfigurieren Sie die dimmbare Lampe Endpoint - 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 Endpoint - 1 und dann auf edit EDIT.

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

   

Weitere Informationen finden Sie unter Geräte und Endpunkte im Matter Leitfaden.

Cluster

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

Wenn Sie nur aktivierte Cluster anzeigen möchten, klicken Sie auf Endpoint - 1 und wählen Sie im Menü Show die Option Enabled Clusters aus. Sie können auch nach search Clustern nach Namen suchen, z. B. on.

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

Weitere Informationen finden Sie unter Cluster im Matter Leitfaden.

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 „Configure“ settings.

   

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

Klicken Sie auf Commands , 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 unter Attribute und Befehle im Matter Leitfaden.

ZAP-Quelldateien generieren

In den Matter Beispielen wird ZAP-generierter Quellcode verwendet, der im connectedhomeip/zzz_generated Verzeichnis verfügbar ist. 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>

Sobald Ihre Endpunkte konfiguriert sind, können Sie Quelldateien generieren, die Sie in Ihr Projekt einbinden können.

1. Klicken Sie auf video_settings Generate.
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, werden die folgenden Vorlagen übergeben:

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.