Se usó la API de Cloud Translation para traducir esta página.

ZCL Advanced Platform (ZAP)

ZCL Advanced Platform (ZAP) es un motor de plantillas de node.js que se basa en clústeres Matter.

ZAP proporciona las siguientes funciones para las apps y los SDKs de Matter:

Configura los extremos, los clústeres, los atributos y otras funciones del dispositivo de Matter desde una interfaz de GUI.
Crea plantillas que generen automáticamente definiciones de modelos de datos, callbacks y otro código fuente de Matter.
Crea y usa archivos ZAP preconfigurados para incluirlos en tus SDKs.

Instalar

Ve a la página ZAP releases.
Busca la versión etiquetada como "Más reciente" (la mayoría estará etiquetada como "Versión preliminar").
En esta versión, en el encabezado Recursos, selecciona el paquete designado para tu sistema operativo y descárgalo.
En una máquina que ejecute Debian o Ubuntu, instala ZAP con el siguiente comando:
```
sudo dpkg -i path/to/zap_installation_package
```

En Debian o Ubuntu Linux, el objeto binario zap se instala en /usr/bin/. En otros sistemas operativos, es posible que el objeto binario se instale en otro lugar. En cualquier caso, asegúrate de que la ubicación del ejecutable esté en tu variable de entorno PATH.

Archivos ZAP

ZAP usa archivos de plantillas llamados archivos ZAP. Un archivo ZAP es un archivo JSON que define extremos, comandos, atributos y otras funciones del dispositivo. Los archivos ZAP tienen nombres que terminan en .zap. Por ejemplo, lighting-app.zap en connectedhomeip/examples/lighting-app/lighting-common.

El archivo all-clusters-app.zap, que se encuentra en connectedhomeip/examples/all-clusters-app/all-clusters-common, está preconfigurado con clústeres Matter comunes y tres extremos, incluido un tipo de dispositivo de comisión de red secundaria Matter. Este es un buen ejemplo para explorar varias configuraciones de clústeres.

Ejecutar

Elige un archivo ZAP de uno de los ejemplos de Matter.
Desde el directorio raíz del repositorio de Matter (connectedhomeip), ejecuta la secuencia de comandos del wrapper run_zaptool.sh y pásale la ruta de acceso al archivo .zap.

Por ejemplo:

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

Configurar

En Configuración, puedes configurar la interfaz de usuario de ZAP, incluida la elección del tema oscuro o claro, y habilitar o inhabilitar las herramientas para desarrolladores.

Si haces clic en Opciones, puedes seleccionar el Fabricante del producto, la Política de respuesta predeterminada y habilitar o inhabilitar el descubrimiento de comandos.

Haz clic en Extensiones para agregar clústeres o comandos ZCL personalizados al configurador de clústeres Zigbee.

Usar

Extremos

El archivo lighting-app.zap está preconfigurado con un nodo raíz Matter (extremo - 0) y una luz regulable Matter (extremo - 1).

Extremo - 0 incluye clústeres generales que son relevantes para todo el nodo, por ejemplo, Networking, Commissioning, Descriptor, Operational Credentials y OTA Clusters.

En los próximos pasos, revisarás y configurarás el extremo - 1 Matter Luz regulable del ejemplo lighting-app.

Desde el repositorio Matter connectedhomeip, ejecuta ZAP.

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

Haz clic en Extremo - 1 y, luego, en EDITAR.
Opcional: Matter admite varios tipos de dispositivos. En el menú desplegable Device, comienza a escribir matter para cambiar el dispositivo y, luego, haz clic en SAVE.

Para obtener más información, consulta Dispositivos y extremos en el primer de Matter.

Clústeres

Las opciones de informes, atributos y clústeres predefinidos están habilitadas en Endpoint - 1 de forma predeterminada.

Para mostrar solo los clústeres habilitados, haz clic en Endpoint - 1 y selecciona Enabled Clusters en el menú Show. También puedes buscar clústeres de por nombre, por ejemplo, on.

Para habilitar cualquier clúster como Cliente, Servidor o Cliente y servidor, usa el menú desplegable Habilitar. También puedes seleccionar No habilitado para inhabilitar un clúster preconfigurado que no se aplique a tu tipo de dispositivo.

Para obtener más información, consulta Clústeres en el Primer de Matter.

Atributos y comandos

Para configurar los atributos y los comandos, completa los siguientes pasos:

Busca el clúster On/Off.
En la misma fila, haz clic en el ícono de configuración .

Aquí puedes habilitar o inhabilitar los atributos, establecer varias opciones de atributos y buscar atributos por nombre.

Haz clic en Comandos para configurar acciones para este clúster. Por ejemplo, el clúster On/off de una luz incluirá los comandos On, Off y Toggle. Es posible que algunos clústeres, como el clúster Temperature Measurement, no tengan comandos asociados.

Para obtener más información, consulta Atributos y comandos en el Primer de Matter.

Genera archivos fuente de ZAP

Los ejemplos de Matter usan el código fuente generado por ZAP, disponible en el directorio connectedhomeip/zzz_generated. Algunos archivos son específicos de la app, mientras que otros archivos ZAP genéricos se agrupan en app-common.

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

Una vez que se configuren los extremos, podrás generar archivos de origen para integrarlos en tu proyecto.

Haz clic en Generar.
Selecciona una carpeta para guardar el resultado de ZAP. Por ejemplo, navega a connectedhomeip/zzz_generated/lighting-app/zap-generated para lighting-app.
Opcional. Abre los archivos en tu IDE preferido.

ZAP genera definiciones, funciones y otro código fuente personalizado para tu tipo de dispositivo y configuración de ZAP.

Por ejemplo, callback-stub.cpp incluye un método de devolución de llamada de clúster que solo incluye los clústeres que habilitaste:

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

Usa archivos de origen de ZAP

Los archivos de origen comunes de ZAP, por ejemplo, Attributes.h en zzz_generated/app-common/app-common/zap-generated/ids/, se pueden usar para obtener y establecer atributos de tipo de 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 vez que comprendas cómo se pueden usar los archivos ZAP en el código fuente de Matter, existen varias formas de integrar ZAP:

Usa los archivos zzz_generated existentes para crear ejemplos nuevos, únicos para tus tipos de dispositivos.
Crea archivos .zap personalizados para tus proyectos.

Personalizar

Los archivos ZAP se generan a partir de plantillas de ZAP. Cuando usas run_zaptool.sh para iniciar ZAP, esta secuencia de comandos pasa las siguientes plantillas:

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 define el nombre de la plantilla Matter y el archivo de salida correspondiente que se usa en los ejemplos de Matter.

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

Para personalizar tus soluciones de Matter, hay varios pasos que puedes seguir cuando trabajas con ZAP:

Crea plantillas de ZAP.
Integra ZAP en tu SDK.

Recursos

Para obtener recursos adicionales de ZAP, consulta el repositorio de ZAP (zap) en GitHub.