ZCL Advanced Platform (ZAP) è un motore di template Node.js basato su Matter Cluster.
ZAP fornisce le seguenti funzionalità per le app e gli SDK Matter:
- Configura Matter endpoint, cluster, attributi e altre funzionalità dei dispositivi 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 Uscite ZAP.
Cerca la release con il tag "Ultima" (la maggior parte avrà il tag "Pre-release").
In questa release, nella sezione Asset, seleziona il pacchetto designato per il tuo sistema operativo e scaricalo.
Su una macchina con 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,
verifica che la posizione dell'eseguibile sia nella variabile di ambiente PATH
.
File ZAP
ZAP utilizza file modello denominati 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 commissioning della reteMatter secondaria. Questo è un buon esempio per esplorare varie configurazioni del cluster.
Esegui
- Scegli un file ZAP da uno degli esempi Matter.
- Dalla directory principale del repository Matter (
connectedhomeip
), esegui lo script wrapperrun_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
Impostazioni puoi configurare l'interfaccia utente di ZAP, inclusa la scelta del tema chiaro o scuro, nonché attivare o disattivare gli strumenti per sviluppatori.Se fai clic su
Opzioni, puoi selezionare il Produttore del prodotto, le Norme di risposta predefinite e attivare o disattivare la funzionalità di Rilevamento comandi.
Fai clic su
Estensioni per aggiungere comandi o cluster ZCL personalizzati al configuratore di cluster Zigbee.Utilizza
Endpoint
Il file lighting-app.zap
è preconfigurato con un Matter
Nodo principale (Endpoint - 0) e una Matter Luce dimmerabile
(Endpoint - 1).
Endpoint - 0 include cluster generali pertinenti all'intero nodo, ad esempio Networking, Commissioning, Descriptor, Credenziali di servizio e cluster OTA.

Nei passaggi successivi, esaminerai e configurerai Endpoint - 1
Matter Luce dimmerabile dall'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 dispositivo, quindi fai clic su SALVA.
Per saperne di più, consulta la sezione Dispositivi e endpoint nel MatterPrimer.
Cluster
I cluster, gli attributi e le opzioni di generazione di report 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 on
.

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

Per saperne di più, consulta la sezione Cluster nel Matter Primer.
Attributi e comandi
Per configurare gli attributi e i 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 cercare gli 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 On/off. Alcuni cluster, come il cluster Temperature Measurement
, potrebbero non avere comandi associati.

Per saperne di più, consulta Attributi e comandi nel MatterPrimer.
Genera i 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>
Una volta configurati gli endpoint, puoi generare i file di origine da integrare nel progetto.
- Fai clic su Genera.
- Seleziona una cartella in cui salvare l'output di ZAP. Ad esempio, vai a
connectedhomeip/zzz_generated/lighting-app/zap-generated
per illighting-app
. - 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 di 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;
...
}
}
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 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");
}
}
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, specifici 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
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 corrispondente file di output utilizzato 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, puoi seguire diversi passaggi aggiuntivi quando utilizzi ZAP:
Risorse
Per ulteriori risorse ZAP, consulta il
repository ZAP
(zap
)
su GitHub.