Esta página foi traduzida pela API Cloud Translation.

Plataforma avançada de ZCL (ZAP)

O ZCL Advanced Platform (ZAP) é um mecanismo de modelo node.js baseado em clusters Matter.

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

Configure Matter endpoints, clusters, atributos e outros recursos do dispositivo em uma interface GUI.
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 Versões do ZAP.
Procure a versão marcada como "Mais recente" (a maioria será marcada como "Pré-lançamento").
Nessa versão, na seção Recursos, selecione e faça o download do pacote designado para seu sistema operacional.
Em uma máquina que executa 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. Em qualquer caso, verifique se o local do executável está na 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 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, é pré-configurado com clusters Matter comuns e três endpoints, incluindo um tipo de dispositivo de comissionamento de rede secundária Matter. Este é 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 Matter (connectedhomeip), execute o script 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, é possível configurar a interface do usuário do ZAP, incluindo a escolha do tema claro ou escuro, e ativar ou desativar as ferramentas para desenvolvedores.

Ao clicar em Opções, você pode selecionar o Fabricante do produto, a Política de resposta padrão e ativar ou desativar a descoberta de comandos.

Clique em Extensões para adicionar clusters ou comandos ZCL personalizados ao Configurador de clusters Zigbee.

Usar

Endpoints

O arquivo lighting-app.zap já vem pré-configurado com um nó raiz Matter (Endpoint - 0) e uma luz dimerizável Matter (Endpoint - 1).

O Endpoint - 0 inclui clusters gerais relevantes para todo o nó, por exemplo, clusters de rede, provisionamento, descritor, credenciais operacionais e OTA.

Nas próximas etapas, você vai revisar e configurar o Endpoint - 1 Matter Dimmable Light do exemplo lighting-app.

No repositório connectedhomeip do Matter, 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 é compatível com 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 guia de conceitos básicos do Matter.

Clusters

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

Para mostrar apenas os 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 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 Configurar .

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

Clique em Comandos para configurar ações para este cluster. Por exemplo, o cluster Liga/desliga de uma luz inclui os comandos Ligar, Desligar e Alternar. Alguns clusters, como o Temperature Measurement, podem não ter comandos associados.

Para saber mais, consulte Atributos e comandos no guia de conceitos básicos do 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 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 que os endpoints estiverem configurados, você poderá 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

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 do Matter, há várias maneiras de integrar o ZAP:

Use os arquivos zzz_generated atuais para criar novos exemplos exclusivos para seus tipos de dispositivos.
Crie arquivos .zap personalizados para seus projetos.

Personalizar

Os arquivos ZAP são gerados com base em modelos ZAP. Quando você usa 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 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 do Matter, há várias próximas etapas que você pode seguir ao trabalhar com o ZAP:

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

Recursos

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