Esta página foi traduzida pela API Cloud Translation.

Plataforma avançada de ZCL (ZAP)

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

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

Configure endpoints, clusters, atributos e outros recursos do dispositivo Matter em uma interface de GUI.
Crie modelos que gerem 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 de lançamentos de ZAP.
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, confira se a localização 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 comissão de rede secundário Matter. Esse é um bom exemplo para analisar várias configurações de cluster.

Executar

Escolha um arquivo ZAP de um dos Matter exemplos.
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, é possível configurar a interface do usuário do ZAP, incluindo sua escolha de tema claro ou escuro e ativar ou desativar as ferramentas para desenvolvedores.

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

Clique em Extensões para adicionar clusters ou comandos ZCL personalizados ao Zigbee Clusters Configurator.

Use a

Endpoints

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

O Endpoint - 0 inclui clusters gerais 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 escurecida a partir do exemplo lighting-app.

No repositório Matter connectedhomeip, execute 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

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

Para exibir 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 um cluster como Cliente, Servidor ou Cliente e servidor, use a lista suspensa 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 você pode ativar ou desativar atributos, definir várias opções de atributos e Pesquisar atributos pelo nome.

Clique em Comandos para configurar ações para este cluster. Por exemplo, o cluster de ativação/desativação de uma luz incluirá os comandos Ativado, Desativado e Alternar. Alguns clusters, como o Temperature Measurement, podem não ter nenhum comando associado.

Para saber mais, consulte Atributos e comandos no Matter Primer.

Gerar arquivos de origem ZAP

Os exemplos de Matter usam código-fonte gerado por 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 os Endpoints, gere arquivos de origem para integrar ao seu projeto.

Clique em Gerar.
Selecione uma pasta para salvar a saída ZAP. Por exemplo, navegue até connectedhomeip/zzz_generated/lighting-app/zap-generated para 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 ZAP.

Por exemplo, callback-stub.cpp inclui um método de callback de cluster que inclui apenas o cluster 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 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 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, 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 Matter, há várias próximas etapas que você pode seguir ao trabalhar com ZAP:

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

Recursos

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