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

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

ZCL Advanced Platform (ZAP)

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

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

Configurez les points de terminaison, les clusters, les attributs et d'autres fonctionnalités des appareils Matter à partir d'une interface utilisateur 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 codes sources Matter.
Créez et utilisez des fichiers ZAP préconfigurés à inclure dans vos SDK.

Installer

Accédez à la page Versions de ZAP.
Recherchez la version portant le tag "Latest" (la plupart portent le tag "Pre-release").
Sous cette version, sous l'en-tête Assets, sélectionnez le package désigné 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
```

Sur 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. C'est 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 Paramètres, vous pouvez configurer l'interface utilisateur de ZAP, y compris choisir un thème clair ou sombre, et activer ou désactiver les outils pour les développeurs.

Cliquez sur Options pour sélectionner le fabricant du produit, la stratégie 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 nœud racine Matter (Endpoint - 0) et une lumière à intensité variable Matter (Endpoint - 1).

Le point de terminaison 0 inclut des clusters généraux pertinents pour l'ensemble du nœud, par exemple les clusters Networking, Commissioning, Descriptor, Operational Credentials et OTA.

Dans les étapes suivantes, vous allez examiner et configurer le point de terminaison 1 Matter "Dimmable Light" (Lumière à intensité variable) de l'exemple lighting-app.

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

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

Cliquez sur Point de terminaison - 1, puis sur MODIFIER.
Facultatif : Matter est compatible avec différents types d'appareils. Dans le menu déroulant Appareil, commencez à saisir matter pour changer d'appareil, puis cliquez sur ENREGISTRER.

Pour en savoir plus, consultez Appareils et points de terminaison dans le guide d'initiation à Matter.

Clusters

Les options de clusters, d'attributs et de rapports prédéfinis sont activées par défaut dans Endpoint - 1.

Pour n'afficher que les clusters activés, cliquez sur Point de terminaison - 1, puis sélectionnez Clusters activés dans le menu Afficher. Vous pouvez également rechercher des clusters par nom, par exemple on.

Pour activer un cluster en tant que Client, Serveur ou Client et serveur, utilisez le menu déroulant Activer. Vous pouvez également sélectionner 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 guide de démarrage de Matter.

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

Ici, vous pouvez activer ou désactiver des attributs, définir différentes options d'attributs et rechercher des attributs par nom.

Cliquez sur Commandes pour configurer des actions pour ce cluster. Par exemple, le cluster On/off (Marche/Arrêt) d'une ampoule inclut les commandes On (Allumer), Off (Éteindre) et Toggle (Activer/Désactiver). Certains clusters, comme le cluster Temperature Measurement, peuvent ne pas avoir de commandes associées.

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

Générer des fichiers sources ZAP

Les exemples Matter utilisent le code source généré par ZAP, disponible dans le répertoire connectedhomeip/zzz_generated. Certains fichiers sont spécifiques à l'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 Générer.
Sélectionnez un dossier pour enregistrer la sortie ZAP. Par exemple, accédez à connectedhomeip/zzz_generated/lighting-app/zap-generated pour 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 en fonction de votre type d'appareil et de votre configuration ZAP.

Par exemple, callback-stub.cpp inclut une méthode de rappel de cluster qui n'inclut 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 les 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 utiliser les fichiers ZAP dans le code source Matter, vous pouvez intégrer ZAP de plusieurs manières :

Utilisez les fichiers zzz_generated existants pour créer des exemples uniques pour 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.