ZCL Advanced Platform (ZAP)

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

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

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

Установить

  1. Перейдите на страницу ZAP releases.

  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

Настроить

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

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

Просмотр глобальных настроек ZAP
Рисунок 2. Глобальные настройки ZAP

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

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

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

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

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

Просмотр конечной точки 0 ZAP
Рисунок 3. Конечная точка 0 в ZAP

На следующих шагах вы проверите и настроите конечную точку 1 Matter (светильник с регулируемой яркостью из примера lighting-app).

  1. Запустите ZAP из хранилища Matter connectedhomeip.

    scripts/tools/zap/run_zaptool.sh \
    examples/lighting-app/lighting-common/lighting-app.zap
  2. Нажмите Конечная точка – 1, а затем Изменить.

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

    ZAP: выбор устройства
    Рисунок 4. Выбор устройства в ZAP

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

Кластеры

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

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

Просмотр кластеров с включенным ZAP
Рисунок 5. Кластеры с включенной защитой от вредоносного ПО с нулевым временем задержки

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

Раскрывающееся меню ZAP Enable для отключения кластеров

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

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

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

  1. Найдите кластер On/Off.
  2. В той же строке нажмите на значок "Настроить" .

    ZAP Configure image view
    Рисунок 6. Настройка Zap

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

ZAP Attributes view image
Рисунок 7. Атрибуты ZAP

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

Просмотр конфигурации команд кластера ZAP

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

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

Примеры Matter используют исходный код, сгенерированный ZAP, который доступен в каталоге connectedhomeip/zzz_generated. Некоторые файлы относятся к определенным приложениям, а другие, общие, сгруппированы в папке 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, в IDE

Например, 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.