ZCL 高级平台 (ZAP)

ZCL Advanced Platform (ZAP) 是一个基于 Matter 集群的 Node.js 模板引擎。

ZAP 为 Matter 应用和 SDK 提供了以下功能：

  • 通过 GUI 界面配置 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 结尾。例如，connectedhomeip/examples/lighting-app/lighting-common 中的 lighting-app.zap。

位于 connectedhomeip/examples/all-clusters-app/all-clusters-common 中的 all-clusters-app.zap 文件已预配置常见的 Matter 集群和三个端点，包括一个 Matter 辅助网络配置设备类型。这是探索各种集群配置的好示例。

运行

  1. 从 Matter 示例中选择一个 ZAP 文件。
  2. 在 Matter 代码库的根目录 (connectedhomeip) 中，运行 run_zaptool.sh 封装容器脚本，并将 .zap 文件的路径传递给它。

例如：

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

设置

在 Settings 中，您可以配置 ZAP 界面，包括选择浅色或深色主题，以及启用或停用开发者工具。

点击 Options（选项）可选择产品制造商、默认响应政策，以及启用或停用命令发现。

ZAP 全局选项

点击 Extensions（扩展程序），将自定义 ZCL 集群或命令添加到 Zigbee 集群配置器。

使用

端点

lighting-app.zap 文件已预配置 Matter 根节点（端点 - 0）和 Matter 可调光灯（端点 - 1）。

端点 - 0 包含与整个节点相关的常规集群，例如网络、配置、描述符、操作凭据和 OTA 集群。

ZAP 端点 0

在后续步骤中，您将查看并配置示例 lighting-app 中的端点 - 1 Matter 可调光灯。

  1. 在 Matter 代码库 connectedhomeip 中，运行 ZAP。

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

  2. 依次点击端点 - 1 和 修改。

  3. 可选：Matter 支持各种设备类型。在设备下拉菜单中，开始输入 matter 以更改设备，然后点击保存。

    ZAP 选择设备

如需了解详情，请参阅 Matter 入门手册中的设备和端点。

集群

默认情况下，端点 - 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 包含一个 Cluster 回调方法，该方法仅包含您已启用的 Cluster：

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

使用 ZAP 源文件

常见的 ZAP 源文件（例如 zzz_generated/app-common/app-common/zap-generated/ids/ 中的 Attributes.h）可用于获取和设置设备类型属性：

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

了解如何在 Matter 源代码中使用 ZAP 文件后，您可以通过多种方式集成 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 资源，请参阅 GitHub 上的 ZAP 代码库 (zap)。