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 SDK de Matter:
- Configura extremos, clústeres, atributos y otras funciones del dispositivo de Matter desde una interfaz GUI.
- Crea plantillas que generen automáticamente definiciones de modelos de datos, devoluciones de llamada y otro código fuente de Matter.
- Crea y usa archivos ZAP preconfigurados para incluirlos con tus SDK.
Instalar
Ve a la página Versiones de ZAP.
Busca la versión con la etiqueta "Más reciente" (la mayoría se etiquetará como "Previo al lanzamiento").
En esta versión, en el encabezado Recursos, selecciona el paquete designado para tu sistema operativo y descárgalo.
En una máquina que ejecuta Debian o Ubuntu, ejecuta el siguiente comando para instalar ZAP:
sudo dpkg -i path/to/zap_installation_package
En Debian o Ubuntu Linux, el objeto binario zap
está instalado en /usr/bin/
. En otros sistemas operativos, el objeto binario puede estar instalado en otro lugar. En cualquier caso, asegúrate de que la ubicación del archivo ejecutable esté en la variable de entorno PATH
.
Archivos ZAP
ZAP utiliza archivos de plantilla llamados archivos ZAP. Un archivo ZAP es un archivo JSON que define extremos, comandos, atributos y otras características 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 opciones de configuración del clúster.
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 wrapperrun_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, lo que incluye el tema oscuro o claro, y la habilitación o inhabilitación de las herramientas para desarrolladores.Si haces clic en
Options, podrás seleccionar el Product Manufacturer y la Default Response Policy, como también habilitar o inhabilitar Command Discovery.Haz clic en
Extensiones para agregar clústeres o comandos de ZCL personalizados a Zigbee Clusters Configurator.Usa
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, Herramientas de redes, comisionado, descriptor, credenciales operativas y clústeres inalámbricos.
En los próximos pasos, revisarás y configurarás Endpoint - 1
Matter (con luz regulable) del ejemplo lighting-app
.
Desde el repositorio de 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 habilitados en Extremo 1 de forma predeterminada.
Para mostrar solo los clústeres habilitados, haz clic en Endpoint - 1 y selecciona Clústeres habilitados en el menú Mostrar. También puedes buscar clústeres de 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:
- Ubica el clúster
On/Off
. En la misma fila, haz clic en el ícono Configurar
.
Aquí puedes habilitar o inhabilitar los atributos, establecer varias opciones de atributos y establecer Buscar atributos
por nombre.Haz clic en Comandos para configurar las acciones de 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 Temperature Measurement
, no tengan comandos asociados.
Para obtener más información, consulta Atributos y comandos en el Primer de Matter.
Genera archivos de origen ZAP
Los ejemplos de Matter usan 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>
Cuando los extremos estén configurados, puedes generar archivos de origen para integrarlos a 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 lalighting-app
. - Opcional: Abre los archivos en tu IDE preferido.
ZAP genera definiciones, funciones y otros códigos fuente personalizados para tu tipo de dispositivo y la configuración de ZAP.
Por ejemplo, callback-stub.cpp
incluye un método de devolución de llamada Cluster 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 de origen ZAP
Los archivos de origen de 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:
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 Matter, puedes integrar ZAP de varias maneras:
- Usa los archivos
zzz_generated
existentes para crear ejemplos nuevos que sean exclusivos de tus tipos de dispositivos. - Crea archivos
.zap
personalizados para tus proyectos.
Personalizar
Los archivos ZAP se generan a partir de plantillas ZAP.
Cuando utilizas 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, puedes seguir varios pasos a continuación cuando trabajas con ZAP:
Recursos
Para obtener recursos de ZAP adicionales, consulta el repositorio de ZAP (zap
) en GitHub.