Piattaforma avanzata ZCL (ZAP)

ZCL Advanced Platform (ZAP) è un motore di template node.js basato sui cluster Matter.

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

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

Installa

1. Vai alla pagina 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 Asset, 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 programma binario zap è installato in /usr/bin/. Su altri sistemi operativi, il programma binario potrebbe essere installato altrove. In ogni caso, verifica che la posizione dell'eseguibile sia nella variabile di ambiente PATH.

File ZAP

ZAP utilizza file modello 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 cluster Matter comuni e tre endpoint, tra cui un tipo di dispositivo di messa in servizio della rete secondaria Matter. Questo è un buon esempio per esplorare varie configurazioni di cluster.

Esegui

1. Scegli un file ZAP da uno degli esempi di Matter.
2. Dalla directory root 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

In 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.

Se fai clic su tune Opzioni, puoi selezionare il produttore del prodotto, la policy di risposta predefinita e attivare o disattivare il rilevamento dei comandi.

Fai clic su extension Estensioni per aggiungere cluster o comandi ZCL personalizzati a Zigbee Clusters Configurator.

Utilizza

Endpoint

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

Endpoint - 0 include i cluster generali pertinenti per l'intero nodo, ad esempio i cluster Networking, Commissioning, Descriptor, Operational Credentials e OTA.

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

1. Dal repository Matter connectedhomeip, esegui ZAP.

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

2. Fai clic su Endpoint - 1, quindi su edit MODIFICA.

3. (Facoltativo) Matter supporta vari tipi di dispositivi. Nel menu a discesa Dispositivo, inizia a digitare matter per cambiare il dispositivo, quindi fai clic su SALVA.

   

Per scoprire di più, consulta Dispositivi ed endpoint nella guida di base di Matter.

Cluster

I cluster, gli attributi e le opzioni di reporting predefiniti sono abilitati in Endpoint - 1 per impostazione predefinita.

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

Per attivare un cluster come Client, Server o Client e server, utilizza il menu a discesa Attiva. Puoi anche selezionare Non attivato per disattivare un cluster preconfigurato non applicabile al tuo tipo di dispositivo.

Per saperne di più, consulta Cluster nella guida introduttiva di Matter.

Attributi e comandi

Per configurare attributi e comandi, completa i seguenti passaggi:

1. Individua il cluster On/Off.

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

   

Qui puoi attivare o disattivare gli attributi, impostare varie opzioni degli attributi e cercare gli attributi search per nome.

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

Per saperne di più, consulta Attributi e comandi nella guida introduttiva di Matter.

Genera file di origine ZAP

Gli esempi di Matter utilizzano il codice sorgente generato da ZAP, disponibile nella directory connectedhomeip/zzz_generated. Alcuni file sono specifici per l'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 file di origine da integrare nel tuo progetto.

1. Fai clic su video_settings Genera.
2. Seleziona una cartella in cui salvare l'output di ZAP. Ad esempio, vai a connectedhomeip/zzz_generated/lighting-app/zap-generated per 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 Cluster che include solo i cluster che hai attivato:

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

Utilizza i file di origine ZAP

I file di origine ZAP comuni, ad esempio Attributes.h in zzz_generated/app-common/app-common/zap-generated/ids/, possono essere utilizzati per recuperare 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 utilizzare i file ZAP nel codice sorgente di Matter, esistono diversi modi per integrare ZAP:

• Utilizza i file zzz_generated esistenti per creare nuovi esempi, unici per i tuoi tipi di dispositivi.
• 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 template:

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 template Matter e il file di output corrispondente utilizzato negli esempi di Matter.

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

Per personalizzare le tue soluzioni Matter, ecco alcuni passaggi successivi che puoi seguire quando lavori con ZAP:

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

Risorse

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