Plataforma avançada de ZCL (ZAP)

A ZCL Advanced Platform (ZAP) é um mecanismo de modelo do Node.js baseado em Matter clusters.

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

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

Instalar

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

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

3. Nessa versão, em Recursos, selecione o pacote designado para seu sistema operacional e faça o download.

4. Em uma máquina que executa o Debian ou o Ubuntu, instale a 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

A 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 comuns do Matter e três endpoints, incluindo um tipo de dispositivo de comissionamento de rede secundária do Matter. Este é um bom exemplo para explorar várias configurações de cluster.

Corrida

1. Escolha um arquivo ZAP em um dos Matter exemplos.
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 da ZAP, incluindo a escolha do tema claro ou tema escuro, e ativar ou desativar as 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 Matter nó raiz (Endpoint - 0) e uma Matter luz regulável (Endpoint - 1).

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

Nas próximas etapas, você vai revisar e configurar Endpoint - 1 Matter Luz Regulável do exemplo lighting-app.

1. No Matter repo connectedhomeip, execute a ZAP.

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

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

3. Opcional: 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 são ativadas em Endpoint - 1 por padrão.

Para mostrar apenas os clusters ativados, clique em Endpoint - 1 e selecione Clusters ativados no menu Mostrar. Também é possível pesquisar search 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 tipo de dispositivo.

Para saber mais, consulte Clusters no Matter Primer.

Atributos e comandos

Para configurar atributos e comandos, siga estas etapas:

1. Localize o cluster On/Off.

2. Na mesma linha, clique no ícone de configuração settings.

   

Aqui, é 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 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 Matter usam o código-fonte gerado pela 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 forem configurados, você poderá gerar arquivos de origem para integrar ao projeto.

1. Clique em video_settings Gerar.
2. Selecione uma pasta para salvar a saída da 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 ativados:

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 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 Matter código-fonte, há várias maneiras de integrar a 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 a partir de modelos ZAP. Quando você usa run_zaptool.sh para iniciar a 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 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 a ZAP:

• Criar modelos ZAP.
• Integrar a ZAP ao seu SDK.

Recursos

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