Questa pagina è stata tradotta dall'API Cloud Translation.

Piattaforma avanzata ZCL (ZAP)

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

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

Configura endpoint, cluster, attributi, e altre funzionalità del dispositivo Matter 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

Vai alla pagina Release di ZAP.
Cerca la release con il tag "Più recente" (la maggior parte sarà contrassegnata con "Pre-release").
In questa release, sotto l'intestazione Asset, seleziona il pacchetto desiderato per il tuo sistema operativo e scaricalo.
Su una macchina che esegue Debian o Ubuntu, installa ZAP eseguendo questo comando:
```
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 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 per la messa in servizio della rete secondaria Matter. Questo è un buon esempio di esplorazione di varie configurazioni di cluster.

Esegui

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

Configurazione

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

Fai clic su Opzioni per selezionare il produttore del prodotto, Criterio di risposta predefinita e attivare o disattivare il rilevamento dei comandi.

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

Utilizzo

Endpoint

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

Endpoint - 0 include cluster generali pertinenti per l'intero nodo, ad esempio networking, messa in servizio, descrittore, 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 vari tipi di dispositivi. Nel menu a discesa Dispositivo, inizia a digitare matter per cambiare il dispositivo, quindi fai clic su SALVA.

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

Cluster

Le opzioni Cluster, Attributi e 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 client, server o client 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 Cluster in Matter Primer.

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 Attributi, impostare varie opzioni degli attributi e Attributi di ricerca per nome.

Fai clic su Comandi per configurare le azioni per questo cluster. Ad esempio, il cluster On/off di una luce includerà i comandi On, Off e Attiva/disattiva. Ad alcuni cluster, ad esempio il cluster Temperature Measurement, potrebbe non essere associato alcun comando.

Per scoprire di più, consulta la sezione Attributi e comandi in Matter Primer.

Genera file di origine ZAP

Gli esempi 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>

Dopo aver configurato gli endpoint, puoi generare 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 nell'IDE preferito.

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 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 ottenere e impostare gli attributi del tipo di dispositivo:

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

Dopo aver compreso come i file ZAP possono essere utilizzati 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 dispositivo.
Crea file .zap personalizzati per i tuoi progetti.

Personalizza

I file ZAP vengono generati da modelli ZAP. Quando utilizzi run_zaptool.sh per avviare ZAP, questo script trasmette 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 utilizzati negli esempi Matter.

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

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

Creare modelli ZAP.
Integra ZAP nel tuo SDK.

Risorse

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