ZCL 高级平台 (ZAP)

ZCL 高级平台 (ZAP) 是一个基于 Matter 集群的 node.js 模板引擎。

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

  • 通过 GUI 界面配置 Matter 端点、集群、特性和其他设备功能。
  • 创建可自动生成数据模型定义、回调和其他 Matter 源代码的模板。
  • 创建并使用预配置的 ZAP 文件，以将其纳入到您的 SDK 中。
ZAP 工具

安装

  1. 转到 ZAP 版本页面。

  2. 查找标记为“最新”的版本（大多数版本会带有“预发布”标记）。

  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 结尾。例如，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

设置

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

点击 选项后，您可以选择商品制造商、默认响应政策，并启用或停用命令发现功能。

ZAP 全局选项

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

使用

端点

lighting-app.zap 文件预先配置了 Matter 根节点 (Endpoint - 0) 和 Matter 调光灯 (Endpoint - 1)。

Endpoint - 0 包括与整个节点相关的常规集群，例如网络、调试、描述符、操作凭据和 OTA 集群。

ZAP 端点 0

在后续步骤中，您将查看并配置示例 lighting-app 中的 Endpoint - 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 Primer 中的设备和端点。

集群

默认情况下，端点 - 1 中会启用预定义的集群、属性和报告选项。

如需仅显示已启用的集群，请点击端点 - 1，然后从显示菜单中选择已启用的集群。您还可以按名称搜索 集群，例如 on。

已启用 ZAP 的集群

如需将任何集群启用为客户端、服务器或客户端和服务器，请使用启用下拉菜单。您还可以选择未启用以停用不适用于您的设备类型的预配置集群。

ZAP 停用集群

如需了解详情，请参阅 Matter Primer 中的集群。

属性和命令

如需配置属性和命令，请完成以下步骤：

  1. 找到 On/Off 集群。

  2. 在同一行，点击“配置”图标 。

    ZAP 配置

您可以在此处启用或停用属性，设置各种属性选项，以及按名称的 Search attribute 。

ZAP 属性

点击命令以配置此集群的操作。例如，灯的开启/关闭集群将包含开启、关闭和切换命令。某些集群（如 Temperature Measurement 集群）可能没有任何关联的命令。

ZAP 命令

如需了解详情，请参阅 Matter Primer 中的属性和命令。

生成 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>

配置 Endpoints 后，您可以生成源文件以集成到项目中。

  1. 点击 Generate。
  2. 选择一个文件夹以保存 ZAP 输出。例如，导航到 lighting-app 的 connectedhomeip/zzz_generated/lighting-app/zap-generated。
  3. 可选。在您的首选 IDE 中打开相关文件。

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 源文件（例如 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)。