STM32WB 系列 Zigbee 自定义 ZCL 集群开发全流程

在基于 STM32WB 系列芯片做 Zigbee 物联网开发时，官方 Exegin ZSDK 提供的标准 ZCL（Zigbee 集群库）模板虽能满足通用场景，但家电、工业传感等定制化设备往往需要创建专属的制造特定集群。ST 官方应用笔记 AN5491，就完整给出了 STM32WB 上自定义 ZCL 集群的开发逻辑、属性 / 指令交互流程，帮开发者快速落地符合 Zigbee 规范的定制化集群。

资料获取：【应用笔记】基于 STM32WB 系列创建制造特定集群

1. 开发前提：你需要先掌握这些基础

这份文档面向有 Zigbee 开发经验的工程师，上手自定义集群前，必须熟悉三类核心知识：

1. Zigbee PRO 网络基础通信规范
2. STM32WB 的 Exegin ZSDK 协议栈 API（AN5500）
3. ZSDK 官方集群模板的使用方法（AN5498）

简单说，ZCL 集群就是把同类设备功能打包成属性 + 指令的集合，比如开关集群包含 “开关状态” 属性、“开 / 关” 指令，自定义集群就是按产品需求，新建这套属性与指令体系。

2. ZCL 集群基础架构：客户端与服务器的分工

Zigbee 网络里的设备交互，都基于ZCL 客户端 + ZCL 服务器的模式：

• 客户端：发起操作（比如开关面板，发送开 / 关指令）
• 服务器：执行操作（比如智能灯，接收指令并响应）
• 集群模板：封装 ZCL 基础能力，开发者只需填充设备硬件交互逻辑
• ZSDK 协议栈：负责底层无线传输，支撑集群通信

以双节点网络为例，开关节点（客户端）的端点 1，可通过 Zigbee 网络，控制灯具节点（服务器）的端点 9，全程依靠 ZCL 集群完成指令与属性的传输。

3. 核心操作 1：ZCL 属性端到端交互流程

属性是集群的状态数据（如开关状态、亮度值、温度值），AN5491 详细拆解了属性读取 / 写入的完整链路：

3.1 客户端读取属性

客户端应用调用 ZSDK 基库函数ZbZclReadReq()，发送属性读取请求，绑定目标服务器节点后，等待服务器响应。

请求发出后，协议栈通过无线传输到服务器，服务器返回属性值，最终通过read_onoff_callback回调函数把结果传给应用层。

3.2 服务器配置属性

• 先用struct ZbZclAttrT定义属性列表（属性 ID、数据类型、标志位）
• 调用ZbZclAttrAppendList()把属性绑定到集群
• 两种属性管理方式：
  1. 无回调：协议栈自动管理属性值，应用直接读写
  2. 有回调：属性读写时触发自定义函数，对接硬件寄存器（如读取传感器真实数据）

3.3 交互关键规则

• 属性不存在时，服务器返回UNSUPPORTED_ATTRIBUTE状态
• 建议同时开启读 / 写回调，避免属性值不一致
• 回调处理完成后，必须返回ZCL_STATUS_SUCCESS标识执行成功

4. 核心操作 2：ZCL 指令端到端交互流程

指令是集群的动作命令（如查询日历、触发报警、开关灯），文档以日历集群 GetCalendar 指令为例，完整演示了指令交互逻辑：

4.1 客户端生成并发送指令

1. 填充指令参数（最早开始时间、日历类型、提供者 ID 等）
2. 调用集群模板专属函数ZbZclCalClientCommandGetCalReq()发送请求
3. 注册回调函数get_cal_cb，接收服务器响应

4.2 客户端处理三种响应结果

• 成功响应：服务器返回PublishCalendar数据，解析负载即可使用
• 默认响应：无自定义响应时，服务器返回状态码
• 传输失败：aps_status标识无 ACK、网络断开等错误，可触发重试 / 重入网

4.3 服务器接收与处理指令

1. 协议栈把消息传给 ZCL 集群基库
2. 集群模板解析指令，调用应用层注册的回调函数（如get_calendar）
3. 应用层处理业务逻辑，调用ZbZclCalServerSendPublishCalendar()返回响应
4. 按规范返回状态码：成功发响应用ZCL_STATUS_SUCCESS_NO_DEFAULT_RESPONSE，失败返回对应错误码

5. STM32WB 自定义制造集群开发核心逻辑

结合 AN5491 的指导，自定义 ZCL 集群的核心步骤可总结为 3 步：

1. 定义集群规范：按产品需求确定属性、指令、数据类型，对齐 Zigbee 标准
2. 实现集群模板：参考官方模板，编写客户端 / 服务器的指令处理、属性回调逻辑
3. 集成到应用：把自定义集群挂载到 STM32WB 的端点，对接硬件驱动，完成组网交互

整个开发过程完全复用 ZSDK 的基础能力，无需修改底层协议栈，大幅降低定制化开发难度。

6. 开发关键注意事项

1. 指令与属性必须严格遵循 Zigbee 集群库（ZCL）第 7 版规范
2. 回调函数要精简，避免阻塞 Zigbee 协议栈运行
3. 未定义的指令 / 属性，需返回标准错误码，保证网络兼容性
4. 自定义集群的客户端与服务器，要成对实现、参数对齐

AN5491 是 STM32WB 系列Zigbee 自定义 ZCL 制造集群的官方实操指南，清晰拆解了属性交互、指令通信的全流程，依托 Exegin ZSDK 协议栈与集群模板，开发者无需从零搭建 Zigbee 通信逻辑，只需聚焦产品功能定制，就能快速开发出符合 Zigbee 认证规范的专属集群，完美适配家电、工控、传感等定制化物联网设备的开发需求。