Cette page a été traduite par l'API Cloud Translation.

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 Matter, les clusters, les attributs et d'autres fonctionnalités de l'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 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 taguée "Dernière" (la plupart sont taguées "Version préliminaire").
Sous cette version, sous l'en-tête Assets (Composants), sélectionnez le package destiné à 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 modèles 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 fichiers ZAP ont des noms se terminant 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 du réseau secondaire Matter. C'est un bon exemple pour explorer différentes configurations de cluster.

Exécuter

Choisissez un fichier ZAP parmi les 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 le thème clair ou sombre de votre choix, et activer ou désactiver les outils pour les développeurs.

En cliquant sur Options, vous pouvez sélectionner le fabricant du produit, la règle de réponse par défaut et activer ou désactiver la découverte des 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).

Point de terminaison 0 : inclut les clusters généraux qui sont 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 Endpoint 1 Matter Dimmable Light à partir 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 modifier votre appareil, puis cliquez sur ENREGISTRER.

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

Clusters

Les options prédéfinies de clusters, d'attributs et de rapports sont activées par défaut dans Point de terminaison 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 Matter.

Attributs et commandes

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

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

Vous pouvez y activer ou désactiver des attributs, définir diverses options d'attributs et rechercher des attributs par nom.

Cliquez sur Commandes pour configurer les actions de ce cluster. Par exemple, le cluster On/off pour une lumière inclura les commandes On, Off et Toggle. Il est possible que certains clusters, comme le cluster Temperature Measurement, n'aient aucune commande associée.

Pour en savoir plus, consultez Attributs et commandes dans le guide 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 à 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 dans votre projet.

Cliquez sur Générer.
Sélectionnez un dossier pour enregistrer le résultat 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 pour votre type d'appareil et 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 les 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 les fichiers ZAP peuvent être utilisés 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 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 supplémentaires lorsque vous travaillez avec ZAP :

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

Ressources

Pour obtenir d'autres ressources ZAP, consultez le dépôt ZAP (zap) sur GitHub.