STM32WB 系列 Zigbee 群集模板使用完全指南（基于 AN5498）

在物联网智能家居、工业控制等场景中，Zigbee 技术以其低功耗、高可靠性成为短距离无线通信的核心选择。STM32WB 系列双核微控制器（Arm® Cortex-M4/Cortex-M0+）原生支持 Zigbee 协议，配合 Exegin ZCL（Zigbee Cluster Library）群集模板，可快速构建符合标准的 Zigbee 应用。本文基于意法半导体 AN5498 应用笔记，详解群集模板的核心概念、实操步骤、群集类型及调试要点，助力开发人员高效落地 Zigbee 产品。

资料获取：【应用笔记】AN5498_如何在STM32WB系列上使用Zigbee群集模板

1. 核心概述

1.1 群集模板的价值

Zigbee 群集是一组标准化的属性和命令集合，用于实现特定设备功能（如开关控制、温度测量）。Exegin 提供的群集模板已预置 Zigbee PRO 规范（[R1]）、ZCL 7 规范（[R2]）定义的强制性属性和命令，且部分已通过 Zigbee 联盟认证测试，开发者无需从零实现协议细节，仅需对接硬件接口或补充应用逻辑即可。

1.2 适用范围与核心依赖

• 硬件：STM32WB 系列微控制器（如 STM32WB55RG、STM32WB75VG）；
• 软件：ZSDK（Zigbee Software Development Kit）、Exegin ZCL 群集模板；
• 参考文档：需提前准备 Zigbee PRO 规范（[R1]）、ZCL 7 规范（[R2]）、ZSDK API 文档（[R3]）及智能能源标准（[R4]，如需）。

1.3 群集分类与架构

（1）群集三大类型

（2）客户端 - 服务器架构

Zigbee 群集的功能交互基于 “客户端 - 服务器” 模型：

• 服务器群集：运行在提供服务的设备上（如灯的 “开关服务器”），暴露属性和命令接口；
• 客户端群集：运行在控制设备上（如遥控器的 “开关客户端”），通过发送命令请求访问服务器功能；
• 端点关联：每个群集实例绑定到唯一端点（端点 ID 范围 1-239，0 及 240-255 为保留值），一个端点可包含多个群集（如 “开关 + 基本 + 报警群集”）。

2. 快速入门清单

开发前需完成以下准备，避免后续流程卡顿：

1. 确认应用所需的 ZCL 群集（如智能灯需 “OnOff 群集 + 颜色控制群集 + 基本群集”）；
2. 规划端点分配（多群集实例需对应多个端点）；
3. 准备参考文档（[R1]-[R4]）及 ZSDK 开发环境；
4. 明确群集角色（客户端 / 服务器）：如遥控器需实现 “OnOff 客户端”，灯需实现 “OnOff 服务器”。

3. 核心操作步骤（从端点到群集落地）

3.1 第一步：创建端点

端点是群集的载体，需先通过 ZSDK API 创建端点并配置 Profile ID（配置文件 ID）和 Device ID（设备 ID），示例代码如下：
#include "zcl.h"

ZbApsmeAddEndpointReqT add_ep_req;
ZbApsmeAddEndpointConfT add_ep_conf;

// 初始化请求结构体（必须归零，避免内存未初始化问题）
memset(&add_ep_req, 0, sizeof(add_ep_req));
memset(&add_ep_conf, 0, sizeof(add_ep_conf));

// 配置端点参数：端点ID=1，家居自动化Profile，开关设备
add_ep_req.endpoint = 1;
add_ep_req.profileId = ZCL_PROFILE_HOME_AUTOMATION;
add_ep_req.deviceId = ZCL_DEVICE_ONOFF_SWITCH;

// 调用API创建端点
ZbZclAddEndpoint(app->zb, &add_ep_req, &add_ep_conf);

• 关键说明：Profile ID 和 Device ID 在zcl.h中定义（如ZCL_PROFILE_HOME_AUTOMATION=0x0104），需根据设备类型选择。

3.2 第二步：实例化群集

端点创建后，通过群集专属的Alloc函数实例化客户端或服务器群集，示例如下：

（1）服务器群集实例化（如 “OnOff 服务器”）

#include "zcl.onoff.h"

// 定义命令回调结构体（仅实现需要的命令）
struct zcl_onoff_callbacks_t onoff_callbacks = {
    .on = app_onoff_on_handler,  // 处理“打开”命令
    .off = app_onoff_off_handler, // 处理“关闭”命令
    .toggle = NULL  // 不支持“切换”命令，返回默认响应
};

// 实例化OnOff服务器群集（绑定到端点1）
app->onoff_server = ZbZclOnOffServerAlloc(
    app->zb,          // ZSDK协议栈指针
    1,                // 端点ID
    &onoff_callbacks, // 命令回调
    app               // 自定义参数（回调中可获取）
);

// 检查实例化结果
if (app->onoff_server == NULL) {
    // 处理创建失败（如内存不足）
}

#include "zcl.onoff.h"

// 实例化OnOff客户端群集
app->onoff_client = ZbZclOnOffClientAlloc(
    app->zb,  // 协议栈指针
    1         // 端点ID
);

#include "zigbee.aps.h"

ZbApsmeBindReqT bind_req;
memset(&bind_req, 0, sizeof(bind_req));

// 配置绑定参数：源端点、源群集ID、目标地址（绑定表自动匹配）
bind_req.srcEndpoint = 1;
bind_req.clusterId = ZCL_CLUSTER_ONOFF;
bind_req.dstAddr.mode = ZB_APSDE_ADDRMODE_NOTPRESENT; // 使用绑定表

// 发起绑定请求
ZbApsmeBindReq(app->zb, &bind_req, NULL, app);

// 发送“打开”命令到绑定的服务器
ZbZclOnOffClientOnReq(
    app->onoff_client,
    &ZbApsAddrBinding,  // 绑定地址
    NULL,               // 命令参数（OnOff命令无额外参数）
    NULL,               // 响应回调（可选）
    app
);

enum ZclStatusCodeT app_onoff_on_handler(
    struct ZbZclClusterT *cluster,
    struct ZbZclAddrInfoT *src_info,
    void *arg
) {
    struct application *app = (struct application *)arg;
    // 控制硬件：打开LED（示例GPIO操作）
    HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET);
    // 更新本地属性状态
    ZbZclAttrIntegerWrite(cluster, ZCL_ONOFF_ATTR_ONOFF, 1);
    return ZCL_STATUS_SUCCESS;
}

// 定义可选属性列表
static const struct ZbZclAttrT onoff_optional_attrs[] = {
    {
        ZCL_ONOFF_ATTR_DELAY_OFF,  // 可选属性ID：关闭延迟
        ZCL_DATATYPE_UNSIGNED_16BIT, // 数据类型
        ZCL_ATTR_FLAG_NONE,        // 属性标志
        0, NULL, {0, 0}, {0, 0}
    }
};

// 向已实例化的服务器群集添加可选属性
if (ZbZclAttrAppendList(
    app->onoff_server,
    onoff_optional_attrs,
    ZCL_ATTR_LIST_LEN(onoff_optional_attrs)
) != ZCL_STATUS_SUCCESS) {
    // 处理添加失败
}