ZCL Advanced Platform (ZAP)

ZCL Advanced Platform (ZAP) – это механизм шаблонов node.js, основанный на кластерах Matter.

ZAP предоставляет следующие функции для приложений и SDK Matter:

  • Настраивайте конечные точки, кластеры, атрибуты и другие функции устройств Matter в графическом интерфейсе пользователя.
  • Создавайте шаблоны, которые автоматически генерируют определения моделей данных, обратные вызовы и другой исходный код Matter.
  • Создавайте и используйте предварительно настроенные ZAP-файлы, чтобы включать их в SDK.
ZAP Tool

Установить

  1. Перейдите на страницу ZAP releases (Выпуски ZAP).

  2. Найдите выпуск с тегом Latest (у большинства будет тег Pre-release).

  3. В разделе Assets (Объекты) выберите пакет для своей операционной системы и скачайте его.

  4. На компьютере с Debian или Ubuntu установите ZAP, выполнив следующую команду:

    sudo dpkg -i path/to/zap_installation_package

В Debian или Ubuntu Linux двоичный файл zap устанавливается в /usr/bin/. В других операционных системах двоичный файл может быть установлен в другом месте. В любом случае убедитесь, что путь к исполняемому файлу указан в переменной среды PATH.

ZAP-файлы

ZAP использует файлы шаблонов, которые называются ZAP-файлами. ZAP-файл – это JSON-файл, в котором определены конечные точки, команды, атрибуты и другие функции устройства. Названия ZAP-файлов заканчиваются на .zap. Пример: lighting-app.zap в connectedhomeip/examples/lighting-app/lighting-common.

Файл all-clusters-app.zap, который находится в connectedhomeip/examples/all-clusters-app/all-clusters-common, предварительно настроен с использованием распространенных кластеров Matter и трех конечных точек, включая тип устройства для ввода в эксплуатацию дополнительной сети Matter. Это хороший пример для изучения различных конфигураций кластера.

Выполнить

  1. Выберите ZAP-файл из одного из примеров Matter.
  2. В корневом каталоге репозитория Matter (connectedhomeip) запустите скрипт-оболочку run_zaptool.sh, указав путь к файлу .zap.

Пример:

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

Настроить

В разделе Settings (Настройки) можно настроить пользовательский интерфейс ZAP, в том числе выбрать светлую или тёмную тему, а также включить или отключить инструменты разработчика.

Нажав Options (Параметры), вы можете выбрать Product Manufacturer (Производитель продукта), Default Response Policy (Политика ответов по умолчанию), а также включить или отключить Command Discovery (Обнаружение команд).

Глобальные настройки ZAP

Нажмите Extensions (Расширения), чтобы добавить собственные кластеры или команды ZCL в Zigbee Clusters Configurator.

Использовать

Конечные точки

Файл lighting-app.zap предварительно настроен с корневым узлом Matter (Endpoint – 0) и регулируемым источником света Matter (Endpoint – 1).

Конечная точка 0 включает общие кластеры, относящиеся ко всему узлу, например кластеры Networking, Commissioning, Descriptor, Operational Credentials и OTA.

Конечная точка ZAP 0

На следующих шагах вы проверите и настроите Endpoint - 1 Matter Dimmable Light из примера lighting-app.

  1. Запустите ZAP из репозитория Matterconnectedhomeip.

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

  2. Нажмите Endpoint - 1 (Конечная точка – 1), а затем EDIT (Изменить).

  3. Примечание. Matter поддерживает различные типы устройств. В раскрывающемся списке Устройство начните вводить matter, чтобы изменить устройство, а затем нажмите Сохранить.

    ZAP: выбор устройства

Подробную информацию можно найти в разделе Устройства и конечные точки руководства по Matter.

Кластеры

В Endpoint – 1 по умолчанию включены стандартные кластеры, атрибуты и параметры отчетов.

Чтобы отобразить только включенные кластеры, нажмите Endpoint – 1 и выберите Включенные кластеры в меню Показать. Вы также можете искать кластеры по названию, например on.

Кластеры с включенным ZAP

Чтобы включить кластер в качестве клиента, сервера или клиента и сервера, используйте раскрывающийся список Включить. Вы также можете выбрать Не включено, чтобы отключить предварительно настроенный кластер, который не подходит для вашего типа устройства.

ZAP: отключить кластер

Подробнее о кластерах рассказывается в Matterруководстве по.

Атрибуты и команды

Чтобы настроить атрибуты и команды, выполните следующие действия:

  1. Найдите кластер On/Off.

  2. В той же строке нажмите на значок "Настроить" .

    Настройка ZAP

Здесь вы можете включить или отключить атрибуты, задать различные параметры атрибутов и выполнить поиск атрибутов по названию.

Атрибуты ZAP

Нажмите Команды, чтобы настроить действия для этого кластера. Например, кластер Вкл./Выкл. для светильника будет включать команды Вкл., Выкл. и Переключить. Некоторые кластеры, например Temperature Measurement, могут не иметь связанных команд.

Команды ZAP

Дополнительную информацию можно найти в разделе Атрибуты и команды руководства по Matter.

Создание исходных файлов ZAP

Примеры Matter используют исходный код, сгенерированный ZAP, который доступен в каталоге connectedhomeip/zzz_generated. Некоторые файлы относятся к определенным приложениям, а другие, общие файлы ZAP, сгруппированы в папке app-common.

#include <app-common/zap-generated/ids/Attributes.h>
#include <app-common/zap-generated/ids/Clusters.h>

После настройки конечных точек вы можете создать исходные файлы для интеграции в проект.

  1. Нажмите Сгенерировать.
  2. Выберите папку, в которой будут сохранены выходные данные ZAP. Например, перейдите в connectedhomeip/zzz_generated/lighting-app/zap-generated для lighting-app.
  3. Это необязательный параметр. Откройте файлы в своей интегрированной среде разработки.

ZAP генерирует определения, функции и другой исходный код, настроенный для вашего типа устройства и конфигурации ZAP.

Файлы, созданные ZAP

Например, callback-stub.cpp включает метод обратного вызова Cluster, который содержит только включенные вами кластеры:

void emberAfClusterInitCallback(EndpointId endpoint, ClusterId clusterId)
{
    switch (clusterId)
    {
     ...
     case ZCL_ON_OFF_CLUSTER_ID :
        emberAfOnOffClusterInitCallback(endpoint);
        break;
     ...
    }
}

Используйте исходные файлы ZAP

Для получения и настройки атрибутов типа устройства можно использовать общие исходные файлы ZAP, например Attributes.h в zzz_generated/app-common/app-common/zap-generated/ids/:

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");
    }
}

Разобравшись, как использовать ZAP-файлы в исходном коде Matter, вы можете интегрировать ZAP несколькими способами:

  • Используйте существующие файлы zzz_generated, чтобы создать новые примеры, уникальные для ваших типов устройств.
  • Создавайте собственные файлы .zap для своих проектов.

Настроить

ZAP-файлы создаются на основе шаблонов ZAP. Когда вы используете run_zaptool.sh для запуска ZAP, этот скрипт передает следующие шаблоны:

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 определяет название шаблона Matter и соответствующий выходной файл, используемый в примерах Matter.

{
    "path": "templates/app/callback-stub-src.zapt",
    "name": "ZCL callback-stub source",
    "output": "callback-stub.cpp"
}

Чтобы настроить решения Matter, вы можете выполнить следующие действия в ZAP:

Ресурсы

Дополнительные ресурсы по ZAP можно найти в хранилище ZAP (zap) на GitHub.