Arduino ESP32 Zigbee 库开发指南：从网络角色到端点编程的完整实战

Arduino ESP32 Zigbee 库开发指南从网络角色到端点编程的完整实战【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32导读本文基于 arduino-esp32 仓库中的 Zigbee 库docs/en/zigbee/zigbee.rst系统讲解如何使用 Arduino 风格接口创建 Zigbee 3.0 兼容设备。你将掌握 Zigbee 网络的三种设备角色协调器/路由器/终端设备、ZigbeeCore单例核心类的全部网络管理 API、ZigbeeEP端点基类的设备信息/绑定/电源/时间/OTA 能力并了解从扫描入网到故障排查的完整实战路径。文中所有 API 说明均以仓库实际源码为准可直接对照 libraries/Zigbee/src/ZigbeeCore.h 与 libraries/Zigbee/src/ZigbeeEP.h 深入验证。Zigbee 库概览构建 Zigbee 3.0 设备的 Arduino 接口该 Zigbee 库为创建 Zigbee 3.0 兼容设备提供完整支持覆盖以下能力支持不同的 Zigbee 角色Coordinator 协调器、Router 路由器、End Device 终端设备网络管理扫描、入网、commissioning 配网面向多种设备类别的多端点Endpoint支持OTAOver-The-Air空中固件升级面向电池供电设备的电源管理时间同步高级绑定Binding与组Group管理从实现层面看该库构建于 ESP-ZIGBEE-SDK 之上提供高层的 Arduino 风格接口。在仓库中库的完整实现位于 libraries/Zigbee/src共 30 个具体端点类并有 30 个可运行的示例工程位于 libraries/Zigbee/examples。所有源码均受CONFIG_ZB_ENABLED宏保护参见 ZigbeeCore.h即只有选择了正确的 Zigbee 模式配置才会编译 Zigbee 相关代码。Zigbee 网络拓扑与设备角色Zigbee 是典型的树状网状Tree/Mesh网络文档给出了如下拓扑示意┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Coordinator │◄─────►│ Router │◄─────►│ Router │ │ (Gateway) │ │ (Repeater) │ │ (Thermostat) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ End Device │ │ │ │ (Sensor) │ │ │ └─────────────────┘ │ │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ End Device │ │ End Device │ │ (Sensor) │ │ (Sensor) │ └─────────────────┘ └─────────────────┘设备角色定义角色职责典型设备Coordinator协调器创建并管理网络存储网络信息是网络的“网关”网关、主控设备Router路由器扩展网络覆盖范围、转发消息通常市电供电灯、开关End Device终端设备可长时间休眠的电池供电设备各类传感器三种角色在源码中对应枚举zigbee_role_tZigbeeCore.htypedef enum { ZIGBEE_COORDINATOR 0, ZIGBEE_ROUTER 1, ZIGBEE_END_DEVICE 2 } zigbee_role_t;角色相关的默认网络配置在 ZigbeeCore.h 中三种角色各有对应的默认配置宏可作为理解底层行为的关键依据ZIGBEE_DEFAULT_ED_CONFIG()终端设备默认ed_timeout为ESP_ZB_ED_AGING_TIMEOUT_64MIN64 分钟老化超时keep_alive为 3000 ms支持休眠ZIGBEE_DEFAULT_ROUTER_CONFIG()/ZIGBEE_DEFAULT_COORDINATOR_CONFIG()二者默认max_children 10即协调器和路由器最多可接入 10 个子设备。Zigbee 库的三层结构文档明确指出库被拆分为三个主要组件ZigbeeCore管理 Zigbee 网络的主类负责网络启停、角色配置、端点管理、网络发现、OTA 更新与电源管理ZigbeeEP所有 Zigbee 端点的基类提供所有端点类型共用的功能具体端点类Specific endpoint classes位于 libraries/Zigbee/src/ep继承ZigbeeEP为灯、开关、传感器等各设备类型提供专属功能。ZigbeeCore网络操作的总入口ZigbeeCore类是所有 Zigbee 操作的唯一入口以**单例singleton**方式实现——全局仅有一个实例直接以Zigbee访问无需手动创建对象。这一设计在 ZigbeeCore.h 中有明确体现#if !defined(NO_GLOBAL_INSTANCES) !defined(NO_GLOBAL_ZIGBEE) extern ZigbeeCore Zigbee; #endifZigbeeCore 管理的核心事务包括网络操作启动、停止和管理 Zigbee 网络设备角色管理配置设备为 Coordinator、Router 或 End Device端点管理添加和管理多个设备端点网络发现扫描并加入现有网络OTA 更新管理空中固件升级电源管理为电池供电设备配置休眠模式ZigbeeEP所有端点的公共基类ZigbeeEP为所有端点提供以下公共能力详见 zigbee_ep.rst 与 ZigbeeEP.h设备信息Device Information配置制造商和型号信息帮助网络识别设备绑定管理Binding Management端点间建立直接通信链路无需手动寻址即可自动发送命令电源管理Power Management上报电源类型与电池状态帮助网络优化通信模式时间同步Time Synchronization与网络时间同步支持基于时间的操作与调度OTA 支持接收空中固件升级以增加新功能或修复缺陷设备发现Device Discovery读取网络中其他设备的制造商与型号信息。具体端点类覆盖主流智能家居设备类型库提供了覆盖灯、开关、传感器等类别的端点类全部继承自ZigbeeEP与文档ep_*系列页面一一对应。从源码目录 libraries/Zigbee/src/ep 可以确认的端点类包括照明类ZigbeeLight开/关灯、ZigbeeDimmableLight可调光灯、ZigbeeColorDimmableLight彩色可调光灯开关类ZigbeeSwitch、ZigbeeColorDimmerSwitch、ZigbeeContactSwitch、ZigbeeDoorWindowHandle传感器类ZigbeeTempSensor、ZigbeeOccupancySensor、ZigbeeIlluminanceSensor、ZigbeePM25Sensor、ZigbeeCarbonDioxideSensor、ZigbeePressureSensor、ZigbeeFlowSensor、ZigbeeWindSpeedSensor、ZigbeeVibrationSensor执行器类ZigbeeFanControl、ZigbeeThermostat、ZigbeeWindowCovering、ZigbeePowerOutlet计量与网关类ZigbeeElectricalMeasurement、ZigbeeGateway、ZigbeeRangeExtender、ZigbeeAnalog、ZigbeeBinary、ZigbeeMultistate每个端点类提供该设备类型专属的 cluster簇与功能例如ZigbeeLight提供开/关/获取状态能力ZigbeeThermostat提供温度控制能力。同时libraries/Zigbee/examples 下提供了与这些端点类一一对应的 30 个示例工程如Zigbee_On_Off_Light、Zigbee_Temp_Hum_Sensor_Sleepy、Zigbee_Scan_Networks、Zigbee_OTA_Client可直接在 Arduino IDE 中打开编译。ZigbeeCore 核心 API 详解以下 API 完整继承自 zigbee_core.rst并在源码中均可找到对应实现ZigbeeCore.h、ZigbeeCore.cpp。网络初始化begin / start / stopbegin()初始化 Zigbee 协议栈并启动网络有两种重载形式bool begin(zigbee_role_t role ZIGBEE_END_DEVICE, bool erase_nvs false); bool begin(esp_zb_cfg_t *role_cfg, bool erase_nvs false);role设备角色默认ZIGBEE_END_DEVICErole_cfg自定义角色配置结构体用于覆盖默认网络参数erase_nvs是否擦除 NVS 存储默认false。函数初始化成功返回true否则返回false。从 ZigbeeCore.cpp 的源码实现可以看到begin(role)内部根据角色选择ZIGBEE_DEFAULT_COORDINATOR_CONFIG()、ZIGBEE_DEFAULT_ROUTER_CONFIG()或ZIGBEE_DEFAULT_ED_CONFIG()默认配置后调用底层zigbeeInit()并以ZB_BEGIN_TIMEOUT_DEFAULT30000 ms即 30 秒见 ZigbeeCore.h为超时等待协议栈启动信号若超时失败终端设备和路由器非协调器会调用resetNVRAMChannelMask()重置 NVRAM 中的信道掩码以便重新加入。重要角色与 Arduino IDE 配置的对应关系根据文档提示不同角色必须在 Arduino IDE 中设置对应的Zigbee mode与Partition Scheme分区方案ZIGBEE_COORDINATOR 与 ZIGBEE_ROUTERZigbee mode 选Zigbee ZCZR (coordinator/router)Partition scheme 选Zigbee ZCZR xMB with spiffsx为所选 Flash 大小的 MB 数ZIGBEE_END_DEVICEZigbee mode 选Zigbee ED (end device)Partition scheme 选Zigbee xMB with spiffsx为所选 Flash 大小的 MB 数这一要求在示例工程中也有硬性校验。例如 Zigbee_On_Off_Light.ino#ifndef ZIGBEE_MODE_ED #error Zigbee end device mode is not selected in Tools-Zigbee mode #endif若未在 Tools 菜单中选择正确的 Zigbee 模式编译会直接报错。start()在stop()停止协议栈后重新启动void start();stop()停止 Zigbee 协议栈典型用途是省电或需要将射频让给其他任务使用void stop();网络状态查询started / connected / getRolebool started(); // 协议栈是否已启动返回 true 表示运行中 bool connected(); // 设备是否已连入 Zigbee 网络 zigbee_role_t getRole(); // 返回当前角色ZIGBEE_COORDINATOR / ZIGBEE_ROUTER / ZIGBEE_END_DEVICE在示例中connected()常被用于等待入网完成如 Zigbee_On_Off_Light.inowhile (!Zigbee.connected()) { Serial.print(.); delay(100); }端点管理addEndpointbool addEndpoint(ZigbeeEP *ep);ep要添加的端点对象指针添加成功返回true。从源码 ZigbeeCore.cpp 看addEndpoint会将端点对象登记到ep_objects列表并把端点的 cluster 列表与配置注册到底层esp_zb_ep_list对于 Home Gateway 设备ESP_ZB_HA_HOME_GATEWAY_DEVICE_ID使用专用的esp_zb_ep_list_add_gateway_ep()其余使用esp_zb_ep_list_add_ep()。若端点配置或 cluster 列表未初始化会返回false并打印错误日志。示例中的典型用法是先Zigbee.addEndpoint(zbLight)注册所有端点再调用Zigbee.begin()启动。网络配置信道掩码与扫描时长void setPrimaryChannelMask(uint32_t mask); // 默认扫描全部信道 11-26掩码 0x07FFF800 void setScanDuration(uint8_t duration); // 扫描时长 1-41 最快、4 最慢 uint8_t getScanDuration(); // 返回当前扫描时长1-4在 ZigbeeCore.cpp 的构造函数中_primary_channel_mask初始化为ESP_ZB_TRANSCEIVER_ALL_CHANNELS_MASK_scan_duration默认为 3。扫描时长会通过esp_zb_bdb_set_scan_duration()应用到协议栈ZigbeeCore.cpp。电源管理Rx On When Idle 与超时void setRxOnWhenIdle(bool rx_on_when_idle); // true 保持接收器开启false 允许休眠 bool getRxOnWhenIdle(); // 返回当前接收器空闲设置 void setTimeout(uint32_t timeout); // 网络操作超时毫秒默认 30000 mssetRxOnWhenIdle(false)是休眠型电池设备的关键配置。在 ZigbeeCore.cpp 的esp_zb_task中可以看到当角色为终端设备且配置了电池供电时会调用底层zb_set_ed_node_descriptor(0, Zigbee.getRxOnWhenIdle(), 1)工作区使休眠设备在网络上被正确识别为电池供电类型。网络发现扫描、结果与清理void scanNetworks(uint32_t channel_mask ESP_ZB_TRANSCEIVER_ALL_CHANNELS_MASK, uint8_t scan_duration 5); int16_t scanComplete(); zigbee_scan_result_t *getScanResult(); void scanDelete();scanComplete()的返回值语义ZigbeeCore.h 注释-2扫描失败或未启动-1扫描进行中0未发现任何网络0发现的网络数量getScanResult()返回指向扫描结果的指针无结果时返回NULL结果类型为zigbee_scan_result_t即底层esp_zb_network_descriptor_tZigbeeCore.h。scanDelete()用于从内存中释放扫描结果。仓库提供了完整示例 Zigbee_Scan_Networks 演示这一流程。协调器专属网络管理以下 API 仅对协调器角色有意义void setRebootOpenNetwork(uint8_t time); // 重启后保持网络开放入网 time 秒 void openNetwork(uint8_t time); // 开放网络允许设备加入持续 time 秒 void closeNetwork(); // 关闭网络禁止新设备加入这是协调器“配对模式”的开关设备要入网协调器必须先处于开放入网状态这正对应后文故障排查中“确保协调器处于配对模式”的建议。射频与主机配置void setRadioConfig(esp_zb_radio_config_t config); esp_zb_radio_config_t getRadioConfig(); void setHostConfig(esp_zb_host_config_t config); esp_zb_host_config_t getHostConfig();构造函数中默认radio_mode ZB_RADIO_MODE_NATIVE使用原生 15.4 射频与host_connection_mode ZB_HOST_CONNECTION_MODE_NONE禁用主机连接ZigbeeCore.cpp。对于需要外部射频如 UART RCP的场景ZigbeeCore.h 还提供了ZIGBEE_DEFAULT_UART_RCP_RADIO_CONFIG()默认配置宏UART1、460800 波特率、8N1。调试与工具函数void setDebugMode(bool debug); // true 开启调试输出 bool getDebugMode(); void factoryReset(bool restart true); // 恢复出厂设置restarttrue 表示重置后重启 void onGlobalDefaultResponse(void (*callback)(zb_cmd_type_t resp_to_cmd, esp_zb_zcl_status_t status, uint8_t endpoint, uint16_t cluster)); static const char *formatIEEEAddress(const esp_zb_ieee_addr_t addr); // 格式化 IEEE 长地址如 AA:BB:CC:DD:EE:FF:00:11 static const char *formatShortAddress(uint16_t addr); // 格式化短地址如 0x1234formatIEEEAddress与formatShortAddress的实现位于 ZigbeeCore.h前者按%02X:%02X:...格式输出 8 字节 IEEE 地址后者按0x%04X输出 16 位短地址适合在调试日志中打印设备地址。onGlobalDefaultResponse注册的全局回调会在所有端点收到 default response默认响应时被调用。ZigbeeEP 端点基类 API 详解以下 API 完整继承自 zigbee_ep.rst实现在 ZigbeeEP.h 与 ZigbeeEP.cpp 中。设备信息配置bool setManufacturerAndModel(const char *name, const char *model);name制造商名称最长 32 字符model型号标识最长 32 字符。源码中ZB_MAX_NAME_LENGTH 32ZigbeeEP.h限定了名称长度。此外还有版本相关 API二者必须在Zigbee.begin()之前调用void setVersion(uint8_t version); // 应用版本 0-255写入 Basic cluster 的 Application Version 属性 void setHardwareVersion(uint8_t version); // 硬件版本 0-255写入 Basic cluster 的 Hardware Version 属性 uint8_t getEndpoint(); // 返回端点号1-254端点号范围 1-254 与 Zigbee 协议规范的端点取值范围一致。示例中的用法是zbLight.setManufacturerAndModel(Espressif, ZBLightBulb);绑定管理Binding绑定允许端点与其他设备建立直接通信链路实现无需手动寻址的自动命令传输。bool bound(); // 端点是否已有绑定设备 std::listzb_device_params_t * getBoundDevices(); // 获取绑定设备列表 void printBoundDevices(); // 打印绑定设备信息到 Serial void printBoundDevices(Print print); // 打印到自定义 Print 对象 void allowMultipleBinding(bool bind); // true 允许一绑多false 仅单绑定 void setManualBinding(bool bind); // true 手动绑定false 自动绑定默认 void clearBoundDevices(); // 清除该端点全部绑定 bool epAllowMultipleBinding(); // 查询是否允许多绑定 bool epUseManualBinding(); // 查询是否处于手动绑定模式文档特别说明setManualBinding(true)适用于 ZHA 或 Z2MZigbee2MQTT等需要手动绑定的场景。绑定设备参数结构体zb_device_params_t定义于 ZigbeeEP.h包含ieee_addrIEEE 地址、endpoint端点号与short_addr短地址三个字段。电源管理bool setPowerSource(zb_power_source_t power_source, uint8_t percentage 0xff, uint8_t voltage 0xff); bool setBatteryPercentage(uint8_t percentage); // 电池百分比 0-100 bool setBatteryVoltage(uint8_t voltage); // 电池电压单位 100 mV例如 35 表示 3.5 V bool reportBatteryPercentage(); // 向网络上报电池百分比电源类型枚举定义于 ZigbeeEP.htypedef enum { ZB_POWER_SOURCE_UNKNOWN 0x00, ZB_POWER_SOURCE_MAINS 0x01, // 市电供电 ZB_POWER_SOURCE_BATTERY 0x03, // 电池供电 } zb_power_source_t;源码注释特别指出电池电压battery voltage不是可上报reportable属性因此库只提供reportBatteryPercentage()用于周期性上报电量。休眠传感器示例 Zigbee_Temp_Hum_Sensor_Sleepy 演示了完整的电池设备配置流程。时间同步bool addTimeCluster(tm time {}, int32_t gmt_offset 0); // 添加时间簇gmt_offset 单位为秒 bool setTime(tm time); // 设置当前时间 bool setTimezone(int32_t gmt_offset); // 设置时区偏移秒 struct tm getTime(uint8_t endpoint 1, int32_t short_addr 0x0000, esp_zb_ieee_addr_t ieee_addr {}); int32_t getTimezone(uint8_t endpoint 1, int32_t short_addr 0x0000, esp_zb_ieee_addr_t ieee_addr {});addTimeCluster有两种语义要作为服务器簇拥有时间和 GMT 偏移供网络其他设备读取则在time结构体中填入当前时间并传入gmt_offset要作为客户端簇从网络获取时间则保持默认参数。getTime()/getTimezone()默认从协调器短地址0x0000、端点 1读取时间属于阻塞式调用。OTA 升级支持bool addOTAClient( uint32_t file_version, uint32_t downloaded_file_ver, uint16_t hw_version, uint16_t manufacturer 0x1001, uint16_t image_type 0x1011, uint8_t max_data_size 223 ); void requestOTAUpdate();file_version当前固件版本downloaded_file_ver已下载文件版本hw_version硬件版本manufacturer制造商代码默认0x1001image_type镜像类型代码默认0x1011max_data_sizeOTA 传输最大数据块大小默认与推荐值均为 223。从 ZigbeeEP.h 可以看到两个重要的时间常量ZB_CMD_TIMEOUT10000 ms 命令超时与OTA_UPGRADE_QUERY_INTERVAL1 小时即1 * 60分钟。requestOTAUpdate()的触发策略是首次请求在 1 分钟内发出之后每小时自动请求一次ZigbeeEP.h 注释。完整示例参见 Zigbee_OTA_Client。设备发现char *readManufacturer(uint8_t endpoint, uint16_t short_addr, esp_zb_ieee_addr_t ieee_addr); char *readModel(uint8_t endpoint, uint16_t short_addr, esp_zb_ieee_addr_t ieee_addr);两个 API 分别从目标设备读取制造商名称与型号标识返回字符串指针读取失败返回NULL。参数为目标设备的端点号、短地址与 IEEE 地址。事件回调void onIdentify(void (*callback)(uint16_t)); // 识别事件回调参数为识别时长秒 void onDefaultResponse(void (*callback)(zb_cmd_type_t resp_to_cmd, esp_zb_zcl_status_t status)); void onOTAStateChange(void (*callback)(bool state)); // OTA 状态变更回调onDefaultResponse回调仅在该端点收到默认响应时触发与 ZigbeeCore 的全局onGlobalDefaultResponse所有端点生效互补。此外基类还暴露了一系列可覆写的虚函数如zbAttributeSet、zbIdentify、zbOTAState等见 ZigbeeEP.h具体端点类通过这些覆写实现各自的业务逻辑。快速上手一个 Zigbee 灯的完整示例以 Zigbee_On_Off_Light 为例展示端到端编程流程#include Arduino.h #ifndef ZIGBEE_MODE_ED #error Zigbee end device mode is not selected in Tools-Zigbee mode #endif #include Zigbee.h #define ZIGBEE_LIGHT_ENDPOINT 10 uint8_t led RGB_BUILTIN; uint8_t button BOOT_PIN; ZigbeeLight zbLight ZigbeeLight(ZIGBEE_LIGHT_ENDPOINT); void setup() { Serial.begin(115200); pinMode(led, OUTPUT); digitalWrite(led, LOW); pinMode(button, INPUT_PULLUP); // 设置制造商与型号 zbLight.setManufacturerAndModel(Espressif, ZBLightBulb); // 注册灯状态变更回调 zbLight.onLightChange(setLED); // 将端点注册到 ZigbeeCore Zigbee.addEndpoint(zbLight); // 启动 Zigbee默认作为终端设备 if (!Zigbee.begin()) { Serial.println(Zigbee failed to start!); ESP.restart(); } // 等待入网 while (!Zigbee.connected()) { Serial.print(.); delay(100); } Serial.println(); }这个示例完整展示了固定开发范式创建端点对象 → 配置设备信息与回调 →Zigbee.addEndpoint()注册 →Zigbee.begin()启动 → 轮询Zigbee.connected()等待入网。其loop()中还有一个值得借鉴的细节长按 BOOT 按键超过 3 秒即触发Zigbee.factoryReset()恢复出厂设置这是设备配网失败后的常用自救手段。常见问题排查与故障处理设备无法入网Device wont join network确保协调器处于配对模式调用Zigbee.openNetwork(time)开放网络检查设备是否配置了正确的角色ZIGBEE_END_DEVICE需要对应Zigbee ED模式验证信道掩码包含协调器所在信道默认掩码0x07FFF800覆盖 11-26 全部信道OTA 更新失败确保 OTA 服务器配置正确制造商代码、镜像类型需与服务器端匹配检查设备是否有足够的内存空间完成更新验证网络连接是否稳定电池设备不工作确保电源来源配置正确setPowerSource(ZB_POWER_SOURCE_BATTERY, ...)检查休眠/唤醒时序设置setRxOnWhenIdle(false)与ed_timeout老化参数验证父设备路由器/协调器始终处于供电状态——休眠终端设备的入网与数据转发都依赖父设备在网绑定问题Binding issues检查两个设备是否都支持所需的 cluster簇验证两个设备都已启用绑定默认自动绑定ZHA/Z2M 场景需setManualBinding(true)确保设备处于同一 Zigbee 网络网络连通性问题检查设备是否在有效通信范围内验证路由器配置是否正确市电供电设备应尽量使用 Router 角色以扩展网络排查其他 2.4 GHz 设备的干扰Wi-Fi、蓝牙等共用频段恢复出厂设置如果连接网络持续出现问题可以恢复出厂设置擦除全部网络设置使设备像全新设备一样重新配网Zigbee.factoryReset(true); // true 重置后重启结合 ZigbeeCore.cpp 的实现与示例factoryReset()会清空 NVS 中保存的网络凭据信道、网络密钥、短地址等之后设备需重新执行扫描、入网流程。开启调试模式为获得更详细的网络操作信息可在启动 Zigbee 之前开启调试模式Zigbee.setDebugMode(true); // 使用带 debug 后缀的 Zigbee 模式启动 Zigbee.begin();文档建议同时选择带有debug后缀的 Zigbee mode如Zigbee ED (end device) debug以获得更完整的协议栈日志输出便于定位入网、绑定等环节的问题。总结arduino-esp32 的 Zigbee 库通过ZigbeeCore单例网络管理、ZigbeeEP基类公共端点能力与 30 个具体端点类设备专属 cluster三层结构把 ESP-ZIGBEE-SDK 的复杂度封装为简洁的 Arduino 接口。开发者只需遵循“创建端点 → 注册到 Zigbee → begin 启动 → 等待 connected”的标准流程即可快速实现 Zigbee 3.0 协调器、路由器、终端设备并在此基础上接入绑定、OTA、时间同步、低功耗休眠等进阶能力。深入阅读 libraries/Zigbee/examples 下的示例工程与 libraries/Zigbee/src 的源码实现可以进一步掌握每个端点类的专属行为与底层 SDK 调用细节。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考