Questa pagina è stata tradotta dall'API Cloud Translation.

Piattaforma avanzata ZCL (ZAP)

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

ZAP fornisce 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 del modello dei dati, callback e altro codice sorgente di Matter.
Crea e utilizza file ZAP preconfigurati da includere con i tuoi SDK.

Installa

Vai alla pagina Release di ZAP.
Cerca l'uscita con il tag "Più recente" (la maggior parte sarà contrassegnata con il tag "Pre-release").
In questa release, sotto l'intestazione Asset, seleziona il pacchetto specifico per il tuo sistema operativo e scaricalo.
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, assicurati che la posizione dell'eseguibile sia presente 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, presente in connectedhomeip/examples/all-clusters-app/all-clusters-common, è preconfigurato con cluster Matter comuni e tre endpoint, incluso un tipo di dispositivo per la messa in servizio della rete secondaria Matter. Questo è un buon esempio per esplorare varie configurazioni di cluster.

Esegui

Scegli un file ZAP da uno degli esempi di Matter.
Dalla directory root del repository Matter (connectedhomeip), esegui lo script wrapper run_zaptool.sh, passando il percorso al file .zap.

Ad esempio:

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

Configura

Nelle Impostazioni di puoi configurare l'interfaccia utente di ZAP, inclusa la scelta del tema chiaro o del tema scuro e l'attivazione o la disattivazione degli strumenti per sviluppatori.

Se fai clic su Opzioni, puoi selezionare il produttore del prodotto, il Criterio di risposta predefinito e abilitare o disabilitare il rilevamento di Command Discovery.

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

Utilizzo

Endpoint

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

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

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

Esegui ZAP dal repository Matter connectedhomeip.

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

Fai clic su Endpoint - 1, quindi su MODIFICA.
Facoltativo:Matter supporta diversi tipi di dispositivi. Nel menu a discesa Dispositivo, inizia a digitare matter per cambiare dispositivo, quindi fai clic su SALVA.

Per ulteriori informazioni, consulta la sezione Dispositivi ed endpoint in Matter Primer.

Cluster

Le opzioni di cluster, attributi e generazione di report predefiniti sono abilitate 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 cluster per nome, ad esempio on.

Per abilitare qualsiasi cluster come Cliente, Server o Cliente e server, utilizza il menu a discesa Abilita. Puoi anche selezionare Non abilitato per disabilitare un cluster preconfigurato che non si applica al tuo tipo di dispositivo.

Per saperne di più, consulta la sezione sui cluster nella guida introduttiva di Matter.

Attributi e comandi

Per configurare attributi e comandi, completa i seguenti passaggi:

Individua il cluster On/Off.
Nella stessa riga, fai clic sull'icona Configura .

Qui puoi attivare o disattivare gli attributi, impostare varie opzioni degli attributi e Cerca attributi 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 Toggle. 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.

Generare 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 dell'app, mentre altri file ZAP generici vengono raggruppati in app-common.

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

Dopo aver configurato gli endpoint, puoi generare i file di origine da integrare nel progetto.

Fai clic su Genera.
Seleziona una cartella in cui salvare l'output ZAP. Ad esempio, vai a connectedhomeip/zzz_generated/lighting-app/zap-generated per lighting-app.
(Facoltativo) Apri i file nel tuo IDE preferito.

ZAP genera definizioni, funzioni e altro codice sorgente personalizzato in base al tipo di dispositivo e alla configurazione ZAP.

Ad esempio, callback-stub.cpp include un metodo di callback 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;
     ...
    }
}

Utilizzare 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 dei tipi di dispositivi:

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

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

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

Personalizza

I file ZAP vengono generati a partire da modelli ZAP. Quando utilizzi run_zaptool.sh per avviare ZAP, questo script passa nei 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 utilizzi ZAP:

Crea modelli ZAP.
Integra ZAP nel tuo SDK.

Risorse

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