Plataforma avançada de ZCL (ZAP)

A ZCL Advanced Platform (ZAP) é um mecanismo de modelo do node.js baseado em clusters do 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 GUI.
• Crie modelos que geram automaticamente definições de modelo de dados, callbacks e outros códigos-fonte do Matter.
• Crie e use arquivos ZAP pré-configurados para incluir nos SDKs.

Instalar

1. Acesse a página de versões do ZAP.

2. Procure a versão marcada como "Latest" (a maioria será marcada como "pré-lançamento").

3. Nessa versão, no cabeçalho Assets, selecione o pacote designado para seu sistema operacional e faça o download dele.

4. Em uma máquina que executa o Debian ou o 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. 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. Esse é um bom exemplo para explorar várias configurações de cluster.

Executar

1. Escolha um arquivo ZAP de um dos exemplos de Matter.
2. No diretório raiz do repositório do 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 settings Configurações, é possível configurar a interface do usuário do ZAP, incluindo a escolha do tema claro ou escuro e a ativação ou desativação das ferramentas para desenvolvedores.

Ao clicar em tune 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 extension Extensões para adicionar clusters ou comandos ZCL personalizados ao Configurador de Clusters Zigbee.

Usar

Endpoints

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

O endpoint 0 inclui clusters gerais que são relevantes para todo o nó, por exemplo, clusters de rede, comissionamento, descritor, credenciais operacionais e OTA.

Nas próximas etapas, você vai analisar e configurar o Endpoint - 1 Matter Luz com intensidade regulável do exemplo lighting-app.

1. No repositório Matter connectedhomeip, execute o ZAP.

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

2. Clique em Endpoint - 1 e em edit EDITAR.

3. 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 manual do Matter.

Clusters

Os clusters, atributos e opções de relatório predefinidos são ativados no 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 do search 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 tipo de dispositivo.

Para saber mais, consulte Clusters no manual do Matter.

Atributos e comandos

Para configurar atributos e comandos, siga estas etapas:

1. Localize o cluster On/Off.

2. Na mesma linha, clique no ícone Configurar settings.

   

Nessa seção, é possível ativar ou desativar atributos, definir várias opções de atributos e pesquisar atributos search por nome.

Clique em Comandos para configurar ações para esse cluster. Por exemplo, o cluster On/off de uma luz inclui os comandos On, Off e Toggle. Alguns clusters, como o Temperature Measurement, podem não ter comandos associados.

Para saber mais, consulte Atributos e comandos no manual do Matter.

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 que os endpoints estiverem configurados, você poderá gerar arquivos de origem para integrar ao seu projeto.

1. Clique em video_settings Gerar.
2. 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.
3. Opcional. Abra os arquivos no seu ambiente de desenvolvimento integrado preferido.

A ZAP gera definições, funções e outros códigos-fonte personalizados para o tipo de dispositivo e a configuração da 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 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:

namespace DeviceTemperatureConfiguration {
  namespace Attributes {

  namespace CurrentTemperature {
    static constexpr AttributeId Id = 0x00000000;
    } // namespace CurrentTemperature

  ...

  } // namespace Attributes
} // namespace DeviceTemperatureConfiguration

#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 dispositivo.
• 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 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.