Esta página foi traduzida pela API Cloud Translation.

Plataforma avançada de ZCL (ZAP)

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 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 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 por nome, por exemplo, 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 o lighting-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:

Crie modelos ZAP.
Integre o ZAP ao seu SDK.

Recursos

Para conferir outros recursos do ZAP, consulte o repositório ZAP (zap) (link em inglês) no GitHub.