A partire dal 2026, tutti i test e l'integrazione di Matter richiederanno l'Interop Test dell'alleanza. Per ulteriori informazioni, consulta la pagina di transizione del laboratorio di test di interoperabilità di Alliance.

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

Vai alla pagina delle release di ZAP.
Cerca la release con il tag "Latest" (la maggior parte avrà il tag "Pre-release").
In questa release, sotto l'intestazione Asset, seleziona il pacchetto designato 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 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

Scegli un file ZAP da uno degli esempi Matter.
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 impostazioni 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 Opzioni puoi selezionare il produttore del prodotto, le norme di risposta predefinite e attivare o disattivare la rilevamento dei comandi.

Fai clic su Estensioni per aggiungere cluster o comandi ZCL personalizzati al configuratore dei 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 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.

Dal Matter repo connectedhomeip, esegui ZAP.

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

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

Per saperne di più, consulta Dispositivi ed endpoint nella Matter guida introduttiva.

Cluster

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

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

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

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

Attributi e comandi

Per configurare attributi e comandi:

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

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. For example, the On/off Cluster for a light will include On, Off, and Toggle commands. Alcuni cluster, come il cluster Temperature Measurement, potrebbero non avere comandi associati.

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

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.

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 il lighting-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 ZAP.

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

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