ZCL Advanced Platform (ZAP)

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

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

• Configura Matter Endpoints, Clusters, Attributes y otras funciones del dispositivo desde una interfaz de GUI.
• Crea plantillas que generen automáticamente definiciones de modelos de datos, devoluciones de llamada y otro Matter código fuente.
• Crea y usa archivos ZAP preconfigurados para incluirlos en tus SDK.

Instalar

1. Ve a la página de versiones de ZAP.

2. Busca la versión etiquetada como "Latest" (la mayoría se etiquetará como "Pre-release").

3. En esta versión, en el encabezado Assets, selecciona el paquete designado para tu sistema operativo y descárgalo.

4. En una máquina que ejecute Debian o Ubuntu, instala ZAP ejecutando lo siguiente:

   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, el objeto binario se puede instalar en otro lugar. En cualquier caso, verifica que la ubicación del ejecutable esté en tu variable de entorno PATH.

Archivos ZAP

ZAP usa archivos de plantilla llamados archivos ZAP. Un archivo ZAP es un archivo JSON que define Endpoints, Commands, Attributes 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 Matter Clusters comunes y tres Endpoints, incluido un tipo de dispositivo de puesta en marcha de red secundaria de Matter. Este es un buen ejemplo para explorar varias configuraciones de clústeres.

Ejecutar

1. Elige un archivo ZAP de uno de los Matter ejemplos.
2. Desde el directorio raíz del repositorio de Matter (connectedhomeip), ejecuta la secuencia de comandos de 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 settings Settings puedes configurar la interfaz de usuario de ZAP, incluida la elección del tema claro u oscuro, y habilitar o inhabilitar las herramientas para desarrolladores.

Si haces clic en tune Options, puedes seleccionar el Product Manufacturer, la Default Response Policy y habilitar o inhabilitar Command Discovery.

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

Usar

Extremos

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

Endpoint - 0 incluye clústeres generales que son relevantes para todo el nodo, por ejemplo, clústeres de redes, puesta en marcha, descriptor, credenciales operativas y OTA.

En los siguientes pasos, revisarás y configurarás la luz regulable Endpoint - 1 Matter del ejemplo lighting-app.

1. Desde el Matter repo connectedhomeip, ejecuta ZAP.

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

2. Haz clic en Endpoint - 1 y, luego, en edit EDIT.

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

   

Para obtener más información, consulta Dispositivos y extremos en la Matter Guía.

Clústeres

Las opciones de clústeres, atributos y generación de informes predefinidas 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 search clústeres por nombre, por ejemplo on.

Para habilitar cualquier clúster como Client, Server o Client & Server, usa el menú desplegable Enable. También puedes seleccionar Not Enabled 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 la Matter Guía.

Atributos y comandos

Para configurar atributos y comandos, completa los siguientes pasos:

1. Ubica el clúster On/Off.

2. En la misma fila, haz clic en el ícono de configuración settings.

   

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

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

Para obtener más información, consulta Atributos y comandos en la Matter Guía.

Genera archivos fuente ZAP

En los ejemplos de Matter, se usa el código fuente generado por ZAP, que está 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 tus extremos, podrás generar archivos fuente para integrarlos en tu proyecto.

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

ZAP genera definiciones, funciones y otro código fuente que es 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 incluye solo los clústeres que habilitaste:

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

Usa archivos fuente ZAP

Los archivos fuente ZAP comunes, por ejemplo, Attributes.h en zzz_generated/app-common/app-common/zap-generated/ids/, se pueden usar para obtener y configurar atributos de tipo de dispositivo:

namespace DeviceTemperatureConfiguration {
  namespace Attributes {

  namespace CurrentTemperature {
    static constexpr AttributeId Id = 0x00000000;
    } // namespace CurrentTemperature

  ...

  } // namespace Attributes
} // namespace DeviceTemperatureConfiguration

#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 Matter código fuente, existen varias formas de integrar ZAP:

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

Personalizar

Los archivos ZAP se generan a partir de plantillas 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 Matter.

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

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

• Crea plantillas ZAP.
• Integra ZAP en tu SDK.

Recursos

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