A ZCL Advanced Platform (ZAP) é um mecanismo de modelo do node.js baseado em Matter clusters.
O ZAP fornece os seguintes recursos para apps e SDKs do Matter:
- Configure endpoints, clusters, atributos e outros recursos do dispositivo Matter em uma interface GUI.
- Crie modelos que geram automaticamente definições de modelo de dados, callbacks e outros códigos-fonte de Matter.
- Crie e use arquivos ZAP pré-configurados para incluir nos seus SDKs.
Instalar
Acesse a página Versões de ZAP (em inglês).
Procure a versão marcada como "Mais recente" (a maioria estará marcada como "Pré-lançamento").
Nessa versão, em Recursos, selecione o pacote designado para seu sistema operacional e faça o download dele.
Em uma máquina com Debian ou Ubuntu, instale o ZAP executando:
sudo dpkg -i path/to/zap_installation_package
No Debian ou no Ubuntu Linux, o binário zap
é instalado em /usr/bin/
. Em
outros sistemas operacionais, o binário pode ser instalado em outro lugar. De qualquer forma,
verifique se o local do executável está na sua variável de
ambiente PATH
.
Arquivos ZAP
O ZAP usa arquivos de modelo chamados arquivos ZAP. Um arquivo ZAP é um arquivo JSON que define endpoints, comandos, atributos e outros recursos do dispositivo. Os arquivos ZAP têm nomes terminados em .zap
. Por exemplo,
lighting-app.zap
em connectedhomeip/examples/lighting-app/lighting-common
.
O arquivo all-clusters-app.zap
, encontrado em connectedhomeip/examples/all-clusters-app/all-clusters-common
, é pré-configurado com clusters Matter comuns e três endpoints, incluindo um tipo de dispositivo de comissionamento de rede secundário Matter. Esse é um bom exemplo para explorar várias configurações
de clusters.
Execução
- Escolha um arquivo ZAP de um dos exemplos de Matter.
- No diretório raiz do repositório Matter (
connectedhomeip
), execute o script do wrapperrun_zaptool.sh
, transmitindo o caminho para o arquivo.zap
.
Exemplo:
./scripts/tools/zap/run_zaptool.sh ./examples/lighting-app/lighting-common/lighting-app.zap
Configurar
Em
Settings, é possível definir a interface do usuário do ZAP, incluindo sua escolha de tema claro ou escuro, e ativando ou desativando as ferramentas para desenvolvedores.Clique em
Opções para selecionar o Fabricante do produto, a Política de resposta padrão e ativar ou desativar a descoberta de comando.Clique em
Extensions para adicionar clusters ou comandos personalizados da ZCL ao Zigbee Clusters Configurator.Usar
Endpoints
O arquivo lighting-app.zap
é pré-configurado com um nó raiz Matter (Endpoint - 0) e uma luz regulável Matter
(Endpoint - 1).
Endpoint - 0 inclui clusters gerais relevantes para o nó inteiro, por exemplo, rede, comissionamento, descritor, credenciais operacionais e clusters OTA.
Nas próximas etapas, você vai analisar e configurar Endpoint - 1
Matter "Luz regulável" do exemplo lighting-app
.
No repositório Matter do
connectedhomeip
, execute o ZAP.scripts/tools/zap/run_zaptool.sh \ examples/lighting-app/lighting-common/lighting-app.zap
Clique em Endpoint - 1 e em
EDITAR.Opcional:o Matter oferece suporte a vários tipos de dispositivos. No menu suspenso Dispositivo, comece a digitar
matter
para mudar o dispositivo e clique em SALVAR.
Para saber mais, consulte Dispositivos e endpoints no Matter Primer.
Clusters
As opções de clusters, atributos e relatórios predefinidos estão ativadas em Endpoint - 1 por padrão.
Para exibir apenas os clusters ativados, clique em Endpoint - 1 e selecione
Clusters ativados no menu
Mostrar. Também é possível pesquisar clusters on
.
Para ativar qualquer cluster como Cliente, Servidor ou Cliente e servidor, use o menu suspenso Ativar. Também é possível selecionar Não ativado para desativar um cluster pré-configurado que não se aplica ao seu tipo de dispositivo.
Para saber mais, consulte Clusters no Matter Primer.
Atributos e comandos
Para configurar atributos e comandos, siga estas etapas:
- Localize o cluster
On/Off
. Na mesma linha, clique no ícone de configuração
.
Aqui é possível ativar ou desativar atributos, definir várias opções de atributos e Pesquisar atributos
por nome.Clique em Comandos para configurar ações para esse cluster. Por
exemplo, o cluster On/off de uma luz vai incluir os comandos On, Off
e Toggle. Alguns clusters, como
o cluster Temperature Measurement
, podem não ter comandos associados.
Para saber mais, consulte Atributos e comandos no Matter Primer.
Gerar arquivos de origem ZAP
Os exemplos de Matter usam o código-fonte gerado pelo ZAP, disponível no diretório connectedhomeip/zzz_generated
. Alguns arquivos são específicos do app,
enquanto outros arquivos ZAP genéricos são agrupados em app-common
.
#include <app-common/zap-generated/ids/Attributes.h>
#include <app-common/zap-generated/ids/Clusters.h>
Depois de configurar o Endpoints, é possível gerar arquivos de origem para integrar ao projeto.
- Clique em Gerar.
- Selecione uma pasta para salvar a saída do ZAP. Por exemplo, navegue até
connectedhomeip/zzz_generated/lighting-app/zap-generated
para olighting-app
. - Opcional: Abra os arquivos no seu ambiente de desenvolvimento integrado preferido.
O ZAP gera definições, funções e outros códigos-fonte personalizados para seu tipo de dispositivo e configuração do ZAP.
Por exemplo, callback-stub.cpp
inclui um método de callback de cluster que
inclui apenas os clusters que você ativou:
void emberAfClusterInitCallback(EndpointId endpoint, ClusterId clusterId)
{
switch (clusterId)
{
...
case ZCL_ON_OFF_CLUSTER_ID :
emberAfOnOffClusterInitCallback(endpoint);
break;
...
}
}
Usar arquivos de origem ZAP
Arquivos de origem ZAP comuns, por exemplo, Attributes.h
em
zzz_generated/app-common/app-common/zap-generated/ids/
, podem ser usados para
receber e definir atributos do 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");
}
}
Depois de entender como os arquivos ZAP podem ser usados no código-fonte Matter, há várias maneiras de integrar o ZAP:
- Use os arquivos
zzz_generated
já existentes para criar novos exemplos exclusivos para seus tipos de dispositivos. - Crie arquivos
.zap
personalizados para seus projetos.
Personalizar
Os arquivos ZAP são gerados a partir de modelos ZAP (em inglês).
Quando você usa o run_zaptool.sh
para iniciar o ZAP, esse script transmite os seguintes modelos:
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 o nome do modelo de Matter e
o arquivo de saída correspondente usado nos exemplos de Matter.
{
"path": "templates/app/callback-stub-src.zapt",
"name": "ZCL callback-stub source",
"output": "callback-stub.cpp"
}
Para personalizar suas soluções de Matter, há várias próximas etapas que você pode seguir ao trabalhar com o ZAP:
Recursos
Para conferir outros recursos do ZAP, consulte o
repositório ZAP
(zap
) (link em inglês)
no GitHub.