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 Datenmodelldefinitionen, Rückrufe und anderer Matter-Quellcode generiert werden.
  • Erstellen und verwenden Sie vorkonfigurierte ZAP-Dateien, die in Ihre SDKs eingebunden werden sollen.
ZAP-Tool

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 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 das Binärprogramm zap in /usr/bin/ installiert. Unter anderen Betriebssystemen ist 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, sogenannte ZAP-Dateien. 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, die sich in connectedhomeip/examples/all-clusters-app/all-clusters-common befindet, ist mit gängigen Matter-Clustern und drei Endpunkten vorkonfiguriert, darunter ein Matter-Sekundärnetzwerk-Inbetriebnahmegerätetyp. Dies ist ein gutes Beispiel, um verschiedene Clusterkonfigurationen auszuprobieren.

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 ihm den Pfad zur Datei .zap.

Beispiel:

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

Einrichten

In den Einstellungen können Sie die ZAP-Benutzeroberfläche konfigurieren, z. B. das helle oder dunkle Design auswählen und die Entwicklertools aktivieren oder deaktivieren.

Wenn Sie auf  Optionen klicken, können Sie den Produkthersteller und die Standardrichtlinie für Antworten auswählen sowie die Befehlserkennung aktivieren oder deaktivieren.

Globale ZAP-Optionen

Klicken Sie auf  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 (Endpoint – 0) und einem Matter-dimmbaren Licht (Endpoint – 1) vorkonfiguriert.

Endpunkt – 0 umfasst allgemeine Cluster, die für den gesamten Knoten relevant sind, z. B. Netzwerk-, Inbetriebnahmen-, Deskriptor-, Betriebsidentifikationsdaten- und OTA-Cluster.

ZAP-Endpunkt 0

In den nächsten Schritten sehen Sie sich Endpoint – 1 Matter Dimmable Light aus dem Beispiel lighting-app an und konfigurieren es.

  1. Führen Sie ZAP im 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 BEARBEITEN.

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

    ZAP – Gerät auswählen

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

Cluster

Vordefinierte Cluster, Attribute und Berichtsoptionen sind in Endpoint – 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 -Clustern suchen, z. B. nach on.

Für ZAP aktivierte Cluster

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

ZAP Disable Cluster

Weitere Informationen finden Sie im Matter-Primer unter Cluster.

Attribute und Befehle

Führen Sie die folgenden Schritte aus, um Attribute und Befehle zu konfigurieren:

  1. Suchen Sie den On/Off-Cluster.

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

    ZAP konfigurieren

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

ZAP-Attribute

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

ZAP-Befehle

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

ZAP-Quelldateien generieren

In den Matter-Beispielen wird von ZAP generierter Quellcode verwendet, 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>

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

  1. Klicken Sie auf Erstellen.
  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 für Ihren Gerätetyp und Ihre ZAP-Konfiguration angepasst ist.

Von ZAP generierte Dateien

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

Mit allgemeinen ZAP-Quelldateien, z. B. Attributes.h in zzz_generated/app-common/app-common/zap-generated/ids/, können Sie Attribute des Gerätetyps abrufen und festlegen:

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

Wenn Sie wissen, wie ZAP-Dateien im Matter-Quellcode verwendet werden können, haben Sie mehrere Möglichkeiten, ZAP zu integrieren:

  • 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 Schritte ausführen:

Ressourcen

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