Piattaforma avanzata ZCL (ZAP)

ZCL Advanced Platform (ZAP) è un motore di modelli Node.js basato su Matter Clusters.

ZAP fornisce le seguenti funzionalità per le app Matter e gli SDK:

• Configura Matter endpoint, cluster, attributi e altre funzionalità del dispositivo da un'interfaccia GUI.
• Crea modelli che generano automaticamente definizioni del modello di dati, callback e altro codice sorgente Matter.
• Crea e utilizza file ZAP preconfigurati da includere negli SDK.

Installa

1. Vai alla pagina delle release di ZAP.

2. Cerca la release con il tag "Latest" (la maggior parte avrà il tag "Pre-release").

3. In questa release, sotto l'intestazione Assets, seleziona il pacchetto designato per il tuo sistema operativo e scaricalo.

4. Su una macchina che esegue Debian o Ubuntu, installa ZAP eseguendo:

   sudo dpkg -i path/to/zap_installation_package

Su Debian o Ubuntu Linux, il file binario zap viene installato in /usr/bin/. Su altri sistemi operativi, il file binario potrebbe essere installato altrove. In ogni caso, assicurati che la posizione dell'eseguibile sia nella variabile di ambiente PATH.

File ZAP

ZAP utilizza file di modelli chiamati file ZAP. Un file ZAP è un file JSON che definisce endpoint, comandi, attributi e altre funzionalità del dispositivo. I file ZAP hanno nomi che terminano con .zap. Ad esempio, lighting-app.zap in connectedhomeip/examples/lighting-app/lighting-common.

Il file all-clusters-app.zap, che si trova in connectedhomeip/examples/all-clusters-app/all-clusters-common, è preconfigurato con i cluster Matter comuni e tre endpoint, incluso un tipo di dispositivo di commissioning di rete secondaria Matter. Questo è un buon esempio per esplorare varie configurazioni di cluster.

Esegui

1. Scegli un file ZAP da uno degli esempi Matter.
2. Dalla directory principale del repository Matter (connectedhomeip), esegui lo script wrapper run_zaptool.sh, passandogli il percorso del file .zap.

Ad esempio:

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

Configura

Nelle settings Impostazioni puoi configurare l'interfaccia utente di ZAP, inclusa la scelta del tema chiaro o scuro, e attivare o disattivare gli strumenti per sviluppatori.

Facendo clic su tune Options puoi selezionare Product Manufacturer, Default Response Policy e attivare o disattivare Command Discovery.

Fai clic su extension Extensions per aggiungere cluster o comandi ZCL personalizzati al configuratore dei cluster Zigbee.

Utilizza

Endpoint

Il file lighting-app.zap è preconfigurato con un Matter nodo root (Endpoint - 0) e una Matter luce dimmerabile (Endpoint - 1).

Endpoint - 0 include cluster generali pertinenti all'intero nodo, ad esempio cluster di rete, commissioning, descrittore, credenziali operative e OTA.

Nei passaggi successivi, esaminerai e configurerai la luce dimmerabile Endpoint - 1 Matter dall'esempio lighting-app.

1. Dal Matter repo connectedhomeip, esegui ZAP.

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

2. Fai clic su Endpoint - 1, poi su edit EDIT.

3. Facoltativo: Matter supporta vari tipi di dispositivi. Nel menu a discesa Device, inizia a digitare matter per cambiare dispositivo, poi fai clic su SAVE.

   

Per saperne di più, consulta Dispositivi ed endpoint in Matter Primer.

Cluster

Le opzioni di cluster, attributi e report predefiniti sono attivate in Endpoint - 1 per impostazione predefinita.

Per visualizzare solo i cluster abilitati, fai clic su Endpoint - 1 e seleziona Enabled Clusters dal menu Show. Puoi anche cercare i cluster search per nome, ad esempio on.

Per abilitare qualsiasi cluster come Client, Server o Client & Server, utilizza il menu a discesa Enable. Puoi anche selezionare Not Enabled per disattivare un cluster preconfigurato che non si applica al tipo di dispositivo.

Per saperne di più, consulta Cluster in Matter Primer.

Attributi e comandi

Per configurare attributi e comandi:

1. Individua il cluster On/Off.

2. Nella stessa riga, fai clic sull'icona di configurazione settings.

   

Qui puoi attivare o disattivare gli attributi, impostare varie opzioni di attributo e Search attributes search cercare per nome.

Fai clic su Commands per configurare le azioni per questo cluster. Ad esempio, il cluster On/off per una luce includerà i comandi On, Off, e Toggle. Alcuni cluster, come il cluster Temperature Measurement, potrebbero non avere comandi associati.

Per saperne di più, consulta Attributi e comandi in Matter Primer.

Genera file sorgente ZAP

Matter esempi utilizzano il codice sorgente generato da ZAP, disponibile nella directory connectedhomeip/zzz_generated. Alcuni file sono specifici dell'app, mentre altri file ZAP generici sono raggruppati in app-common.

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

Una volta configurati gli endpoint, puoi generare i file sorgente da integrare nel progetto.

1. Fai clic su video_settings Generate.
2. Seleziona una cartella in cui salvare l'output di ZAP. Ad esempio, vai a connectedhomeip/zzz_generated/lighting-app/zap-generated per il lighting-app.
3. Facoltativo. Apri i file nell'IDE che preferisci.

ZAP genera definizioni, funzioni e altro codice sorgente personalizzato per il tipo di dispositivo e la configurazione ZAP.

Ad esempio, callback-stub.cpp include un metodo di callback del cluster che include solo i cluster che hai abilitato:

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

Utilizza i file sorgente ZAP

I file sorgente ZAP comuni, ad esempio Attributes.h in zzz_generated/app-common/app-common/zap-generated/ids/, possono essere utilizzati per ottenere e impostare gli attributi del tipo di dispositivo:

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

Una volta compreso come i file ZAP possono essere utilizzati nel Matter codice sorgente, esistono diversi modi per integrare ZAP:

• Utilizza i file zzz_generated esistenti per creare nuovi esempi, univoci per i tipi di dispositivo.
• Crea file .zap personalizzati per i tuoi progetti.

Personalizza

I file ZAP vengono generati dai modelli ZAP. Quando utilizzi run_zaptool.sh per avviare ZAP, questo script passa i seguenti modelli:

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 definisce il nome del modello Matter e il file di output corrispondente utilizzato negli esempi Matter.

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

Per personalizzare le soluzioni Matter, puoi eseguire diversi passaggi successivi quando lavori con ZAP:

• Crea modelli ZAP.
• Integra ZAP nel tuo SDK.

Risorse

Per ulteriori risorse ZAP, consulta il repository ZAP (zap) su GitHub.