Расширенная платформа ZCL (ZAP)

ZCL Advanced Platform (ZAP) — это шаблонизатор Node.js, основанный на Matter Clusters .

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

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

Установить

  1. Перейдите на страницу релизов ZAP .

  2. Ищите релизы с пометкой "Последние" (большинство будут помечены как "Предварительные релизы").

  3. В этом выпуске в разделе « Ресурсы » выберите пакет, предназначенный для вашей операционной системы, и загрузите его.

  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, включая выбор светлой или темной темы, а также включение или отключение инструментов разработчика.

Нажав кнопку «Параметры , вы можете выбрать производителя продукта , политику ответа по умолчанию , а также включить или отключить обнаружение команд.

ZAP Global Options

Нажмите Расширения », чтобы добавить пользовательские кластеры ZCL или команды в конфигуратор кластеров Zigbee.

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

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

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

Конечная точка - 0 включает общие кластеры, относящиеся ко всему узлу, например, кластеры сети, ввода в эксплуатацию, дескрипторов, учетных данных для работы и OTA-кластеров.

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

На следующих шагах вы проверите и настроите диммируемый светильник Endpoint - 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 Select Device

Для получения более подробной информации обратитесь к разделу «Устройства и конечные точки» в руководстве Matter Primer.

Кластеры

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

Чтобы отобразить только включенные кластеры, щелкните «Конечная точка - 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. Например, для lighting-app перейдите в папку connectedhomeip/zzz_generated/lighting-app/zap-generated .
  3. Необязательно . Откройте файлы в предпочитаемой вами IDE.

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

Файлы, сгенерированные ZAP

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

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/ .

Атрибуты.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-шаблонов . При запуске ZAP с помощью run_zaptool.sh этот скрипт передает следующие шаблоны:

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.