À partir de 2026, toutes les intégrations et tous les tests Matter nécessiteront l'Interop Test de l'Alliance. Pour en savoir plus, consultez la page de transition de l'Alliance Interop Test Lab.

ZCL Advanced Platform (ZAP)

ZCL Advanced Platform (ZAP) est un moteur de modèle node.js basé sur les Matter clusters.

ZAP fournit les fonctionnalités suivantes pour les applications Matter et les SDK :

Configurez les points de terminaison Matter, les clusters, les attributs et d'autres fonctionnalités d'appareil à partir d'une interface graphique.
Créez des modèles qui génèrent automatiquement des définitions de modèle de données, des rappels et d'autres Matter codes sources.
Créez et utilisez des fichiers ZAP préconfigurés à inclure dans vos SDK.

Installer

Accédez à la page des versions de ZAP.
Recherchez la version taguée "Latest" (la plupart seront taguées "Pre-release").
Sous cette version, sous l'en-tête Assets (Actifs), sélectionnez le package conçu pour votre système d'exploitation et téléchargez-le.
Sur une machine exécutant Debian ou Ubuntu, installez ZAP en exécutant la commande suivante :
```
sudo dpkg -i path/to/zap_installation_package
```

Sous Debian ou Ubuntu Linux, le binaire zap est installé dans /usr/bin/. Sur d'autres systèmes d'exploitation, le binaire peut être installé ailleurs. Dans tous les cas, vérifiez que l'emplacement de l'exécutable se trouve dans votre variable d'environnement PATH.

Fichiers ZAP

ZAP utilise des fichiers de modèle appelés fichiers ZAP. Un fichier ZAP est un fichier JSON qui définit les points de terminaison, les commandes, les attributs et d'autres fonctionnalités de l'appareil. Les noms des fichiers ZAP se terminent par .zap. Par exemple, lighting-app.zap dans connectedhomeip/examples/lighting-app/lighting-common.

Le fichier all-clusters-app.zap, qui se trouve dans connectedhomeip/examples/all-clusters-app/all-clusters-common, est préconfiguré avec des clusters Matter courants et trois points de terminaison, y compris un type d'appareil de mise en service de réseau secondaire Matter. Il s'agit d'un bon exemple pour explorer différentes configurations de cluster.

Exécuter

Choisissez un fichier ZAP dans l'un des exemples Matter.
À partir du répertoire racine du dépôt Matter (connectedhomeip), exécutez le script wrapper run_zaptool.sh, en lui transmettant le chemin d'accès au fichier .zap.

Exemple :

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

Configurer

Dans les Settings (Paramètres), vous pouvez configurer l'interface utilisateur ZAP, y compris le thème clair ou sombre de votre choix, et activer ou désactiver les outils de développement.

Cliquez sur Options (Options) pour sélectionner votre Product Manufacturer (Fabricant du produit), votre Default Response Policy (Règle de réponse par défaut) et activer ou désactiver la découverte de commandes.

Cliquez sur Extensions pour ajouter des clusters ou des commandes ZCL personnalisés au configurateur de clusters Zigbee.

Utiliser

Points de terminaison

Le fichier lighting-app.zap est préconfiguré avec un Matter nœud racine (Endpoint - 0) et une Matter lumière à intensité variable (Endpoint - 1).

Endpoint - 0 inclut des clusters généraux qui concernent l'ensemble du nœud, par exemple les clusters Networking, Commissioning, Descriptor, Operational Credentials et OTA.

Au cours des étapes suivantes, vous allez examiner et configurer Endpoint - 1 Matter lumière à intensité variable à partir de l'exemple lighting-app.

À partir du Matter dépôt connectedhomeip, exécutez ZAP.

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

Cliquez sur Endpoint - 1, puis sur EDIT (Modifier).
Facultatif : Matter est compatible avec différents types d'appareils. Dans le menu déroulant Device (Appareil), commencez à saisir matter pour modifier votre appareil, puis cliquez sur SAVE (Enregistrer).

Pour en savoir plus, consultez Appareils et points de terminaison dans le Matter guide de démarrage.

Clusters

Les options prédéfinies Clusters, Attributes et Reporting sont activées dans Endpoint - 1 par défaut.

Pour n'afficher que les clusters activés, cliquez sur Endpoint - 1 , puis sélectionnez Enabled Clusters (Clusters activés) dans le menu Show (Afficher). Vous pouvez également rechercher clusters par nom, par exemple on.

Pour activer un cluster en tant que Client, Server ou Client & Server, utilisez le menu déroulant Enable (Activer). Vous pouvez également sélectionner Not Enabled (Non activé) pour désactiver un cluster préconfiguré qui ne s'applique pas à votre type d'appareil.

Pour en savoir plus, consultez Clusters dans le Matter guide de démarrage.

Attributs et commandes

Pour configurer les attributs et les commandes, procédez comme suit :

Recherchez le cluster On/Off.
Sur la même ligne, cliquez sur l'icône de configuration .

Vous pouvez activer ou désactiver des attributs, définir différentes options d'attribut et Search attributes (Recherche d'attributs) par nom.

Cliquez sur Commands (Commandes) pour configurer les actions de ce cluster. Par exemple, le cluster On/off (Activé/Désactivé) d'une lumière inclut les commandes On (Activé), Off (Désactivé) et Toggle (Basculer). Certains clusters, comme le cluster Temperature Measurement (Mesure de la température), peuvent ne pas avoir de commandes associées.

Pour en savoir plus, consultez Attributs et commandes dans le Matter guide de démarrage.

Générer des fichiers sources ZAP

Matter exemples utilisent le code source généré par ZAP, disponible dans le connectedhomeip/zzz_generated répertoire. Certains fichiers sont spécifiques à une application, tandis que d'autres fichiers ZAP génériques sont regroupés dans app-common.

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

Une fois vos points de terminaison configurés, vous pouvez générer des fichiers sources à intégrer à votre projet.

Cliquez sur Generate (Générer).
Sélectionnez un dossier pour enregistrer la sortie ZAP. Par exemple, accédez à connectedhomeip/zzz_generated/lighting-app/zap-generated pour le lighting-app.
Facultatif. Ouvrez les fichiers dans l'IDE de votre choix.

ZAP génère des définitions, des fonctions et d'autres codes sources personnalisés pour votre type d'appareil et votre configuration ZAP.

Par exemple, callback-stub.cpp inclut une méthode de rappel de cluster qui ne comprend que les clusters que vous avez activés :

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

Utiliser des fichiers sources ZAP

Les fichiers sources ZAP courants, par exemple Attributes.h dans zzz_generated/app-common/app-common/zap-generated/ids/, peuvent être utilisés pour obtenir et définir des attributs de type d'appareil :

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

Une fois que vous avez compris comment les fichiers ZAP peuvent être utilisés dans le Matter code source, vous pouvez intégrer ZAP de plusieurs manières :

Utilisez les fichiers zzz_generated existants pour créer des exemples propres à vos types d'appareils.
Créez des fichiers .zap personnalisés pour vos projets.

Personnaliser

Les fichiers ZAP sont générés à partir de modèles ZAP. Lorsque vous utilisez run_zaptool.sh pour lancer ZAP, ce script transmet les modèles suivants :

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 définit le nom du modèle Matter et le fichier de sortie correspondant utilisé dans les exemples Matter.

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

Pour personnaliser vos solutions Matter, vous pouvez suivre plusieurs étapes lorsque vous utilisez ZAP :

Créez des modèles ZAP.
Intégrez ZAP à votre SDK.

Ressources

Pour obtenir des ressources ZAP supplémentaires, consultez le dépôt ZAP (zap) sur GitHub.