Esta página foi traduzida pela API Cloud Translation.

Plataforma avançada de ZCL (ZAP)

A plataforma avançada ZCL (ZAP) é um mecanismo de modelo node.js baseado em clusters Matter.

O ZAP oferece os seguintes recursos para apps e SDKs Matter:

Configure endpoints, clusters, atributos e outros recursos do dispositivo do Matter em uma interface gráfica.
Crie modelos que geram automaticamente definições de modelo de dados, callbacks e outros códigos-fonte Matter.
Crie e use arquivos ZAP pré-configurados para incluir nos seus SDKs.

Instalar

Acesse a página ZAP releases.
Procure a versão com a tag "Latest" (a maioria terá a tag "Pre-release").
Nessa versão, em Assets, 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 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 variável de ambiente PATH.

Arquivos ZAP

O ZAP usa arquivos de modelo chamados de arquivos ZAP. Um arquivo ZAP é um arquivo JSON que define endpoints, comandos, atributos e outros recursos do dispositivo. Os arquivos ZAP têm nomes que terminam 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, é reconfigurado com clusters Matter comuns e três endpoints, incluindo um tipo de dispositivo de comissionamento de rede secundária Matter. Esse é um bom exemplo para explorar várias configurações de cluster.

Executar

Escolha um arquivo ZAP em um dos exemplos de Matter.
No diretório raiz do repositório do Matter (connectedhomeip), execute o script de wrapper run_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 Configurações, você pode configurar a interface do usuário do ZAP, incluindo a escolha do tema claro ou escuro, e ativar ou desativar 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 detecção de comando.

Clique em Extensões para adicionar clusters ou comandos ZCL personalizados 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 que são relevantes para todo o nó, 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 connectedhomeip, execute o ZAP.

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

Clique em Endpoint - 1 e em EDIT.
Opcional:Matter oferece suporte a vários tipos de dispositivos. No menu suspenso Device, comece a digitar matter para mudar o dispositivo e clique em SAVE.

Para saber mais, consulte Dispositivos e endpoints no manual introdutório Matter.

Clusters

Os clusters predefinidos, os atributos e as opções de relatórios são ativados em Endpoint - 1 por padrão.

Para mostrar apenas clusters ativados, clique em Endpoint - 1 e selecione Clusters ativados no menu Mostrar. Também é possível pesquisar clusters por nome, por exemplo, on.

Para ativar qualquer cluster como Cliente, Servidor ou Cliente e servidor, use o menu suspenso Ativar. Você também pode selecionar Não ativado para desativar um cluster reconfigurado que não se aplica ao tipo de dispositivo.

Para saber mais, consulte Clusters no guia introdutório sobre Matter.

Atributos e comandos

Para configurar atributos e comandos, siga estas etapas:

Localize o cluster On/Off.
Na mesma linha, clique no ícone Configurar .

Aqui, você pode ativar ou desativar atributos, definir várias opções de atributo e pesquisar atributos por nome.

Clique em Comandos para configurar ações para este cluster. Por exemplo, o cluster On/off de uma luz vai incluir 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 guia introdutório da Matter.

Gerar arquivos de origem do 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 genéricos do ZAP 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 os endpoints, você pode 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 o lighting-app.
Opcional. Abra os arquivos no ambiente de desenvolvimento integrado de sua preferência.

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 do ZAP

Os arquivos de origem comuns do ZAP, por exemplo, Attributes.h em zzz_generated/app-common/app-common/zap-generated/ids/, podem ser usados para receber e definir 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");
    }
}

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 atuais para criar novos exemplos exclusivos para seus tipos de dispositivo.
Crie arquivos .zap personalizados para seus projetos.

Personalizar

Os arquivos ZAP são gerados a partir de modelos ZAP. Quando você usa run_zaptool.sh para iniciar o ZAP, este 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 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 Matter, siga estas etapas ao trabalhar com o ZAP:

Crie modelos de ZAP.
Integre o ZAP ao seu SDK.

Recursos

Para mais recursos do ZAP, consulte o repositório do ZAP (zap) no GitHub.