ESP32 Arduino Zigbee 风速传感器端点开发指南ZigbeeWindSpeedSensor 类与 Wind Speed Measurement Cluster 全解析【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32本指南完整讲解 arduino-esp32 仓库中 Zigbee 库的ZigbeeWindSpeedSensor类它是符合 Zigbee Home AutomationHA标准的风速测量端点Endpoint用于气象站、风机监控、农业气象、海事与智能家居等场景。阅读完本文你将掌握该端点的全部 API 用法、底层 ZCL 属性编码规则、端点注册流程以及一套可直接运行的 End Device 示例和 HomeAssistant ZHA 集成方案。功能概述与典型应用ZigbeeWindSpeedSensor类继承自通用的 ZigbeeEP 基类为 Zigbee 网络提供风速传感器端点实现 Zigbee HA 标准中针对风速测量设备的规范。类声明位于 ZigbeeWindSpeedSensor.h实现位于 ZigbeeWindSpeedSensor.cpp。核心特性以 m/s 为单位的风速测量可配置的测量量程最小值/最大值容差Tolerance与上报Reporting配置自动上报能力与常见端点功能集成绑定、OTA 等由基类ZigbeeEP提供Zigbee HA 标准合规典型应用场景气象站风力涡轮机监测农业气象监测海事应用智能家居气象系统工业风况监测底层实现原理设备 ID 与集群构成从源码结构看风速传感器没有专属的 Zigbee HA 设备 ID构造函数中使用了通用传感器设备 IDZigbeeWindSpeedSensor::ZigbeeWindSpeedSensor(uint8_t endpoint) : ZigbeeEP(endpoint) { _device_id ESP_ZB_HA_SIMPLE_SENSOR_DEVICE_ID; zigbee_wind_speed_sensor_cfg_t windspeed_sensor_cfg ZIGBEE_DEFAULT_WIND_SPEED_SENSOR_CONFIG(); _cluster_list zigbee_wind_speed_sensor_clusters_create(windspeed_sensor_cfg); _ep_config {.endpoint _endpoint, .app_profile_id ESP_ZB_AF_HA_PROFILE_ID, .app_device_id ESP_ZB_HA_SIMPLE_SENSOR_DEVICE_ID, .app_device_version 0}; }端点创建时注册了三个 Server 角色集群见zigbee_wind_speed_sensor_clusters_createZigbeeWindSpeedSensor.cppBasic 集群基础信息zcl 版本、电源类型Identify 集群设备识别/定位Wind Speed Measurement 集群风速测量核心集群ZCL 集群 ID 为ESP_ZB_ZCL_CLUSTER_ID_WIND_SPEED_MEASUREMENT默认集群配置由宏ZIGBEE_DEFAULT_WIND_SPEED_SENSOR_CONFIG()定义ZigbeeWindSpeedSensor.h其中measured_value、min_measured_value、max_measured_value均使用 ESP Zigbee Stack 提供的默认值。关键0.01 m/s 定点编码。整个类内部所有浮点风速值在写入 ZCL 属性前都通过zb_windspeed_to_u16转为uint16_tstatic uint16_t zb_windspeed_to_u16(float windspeed) { return (uint16_t)(windspeed * 100); }也就是说传入的1.23m/s 会被编码为123存入 ZCL 属性。调用所有 API 时传入的值单位均为 m/s而底层属性单位是 0.01 m/s这一点在后面的 HomeAssistant 集成读数转换中同样重要。构造函数ZigbeeWindSpeedSensor(uint8_t endpoint);endpoint—— 端点号取值范围1–254。创建一个新的 Zigbee 风速传感器端点。创建后还需通过Zigbee.addEndpoint(sensor)注册到 Zigbee Core再调用Zigbee.begin()启动网络。API 方法详解以下方法均声明于 ZigbeeWindSpeedSensor.h实现细节可对照 ZigbeeWindSpeedSensor.cpp。setWindSpeed —— 设置测量值bool setWindSpeed(float value);value—— 风速值单位 m/s内部按 0.01 m/s 编码。更新 Wind Speed Measurement 集群的measured_value属性。实现中调用基类的setClusterAttribute(ESP_ZB_ZCL_CLUSTER_ID_WIND_SPEED_MEASUREMENT, ..., ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_MEASURED_VALUE_ID, zb_windspeed, false)。成功返回true失败返回false并打印log_e错误日志。该函数适合在测量任务中周期性调用。setMinMaxValue —— 设置测量量程bool setMinMaxValue(float min, float max);min—— 最小风速值单位 m/s0.01 m/s 编码max—— 最大风速值单位 m/s0.01 m/s 编码分别更新min_measured_value与max_measured_value两个属性ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_MIN/MAX_MEASURED_VALUE_ID。任何一步失败都会返回false。典型用法如示例中的setMinMaxValue(0, 50)表示量程 050 m/s。setDefaultValue —— 设置默认初始值bool setDefaultValue(float defaultValue);defaultValue—— 默认风速值单位 m/s0.01 m/s 编码。该值将作为设备处于出厂重置状态、传感器尚未给出真实读数时的初始测量值。实现直接更新measured_value属性bool ZigbeeWindSpeedSensor::setDefaultValue(float defaultValue) { uint16_t zb_default_value zb_windspeed_to_u16(defaultValue); ... esp_err_t ret esp_zb_cluster_update_attr(windspeed_measure_cluster, ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_MEASURED_VALUE_ID, (void *)zb_default_value); ... }重要必须在将端点添加到 Zigbee 类Zigbee.addEndpoint之前调用且仅在设备处于出厂重置模式即加入/配网之前时生效。setTolerance —— 设置测量容差bool setTolerance(float tolerance);tolerance—— 容差值单位 m/s0.01 m/s 编码最低可取 0.01 m/s。容差属性不包含在默认集群配置中因此实现中通过esp_zb_wind_speed_measurement_cluster_add_attr动态追加ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_TOLERANCE_ID属性ZigbeeWindSpeedSensor.cpp。容差用于定义设备测量精度范围也参与上报触发判断。setReporting —— 配置上报bool setReporting(uint16_t min_interval, uint16_t max_interval, float delta);min_interval—— 最小上报间隔单位秒max_interval—— 最大上报间隔单位秒delta—— 触发上报所需的最小变化量单位 m/s0.01 m/s 编码实现构造esp_zb_zcl_reporting_info_t上报配置结构方向为ESP_ZB_ZCL_CMD_DIRECTION_TO_SRV集群为 Wind Speed Measurement属性为measured_valuedelta.u16同样乘以 100 转换为 ZCL 编码最后调用基类setClusterReporting()注册上报ZigbeeWindSpeedSensor.cpp。必须在Zigbee.begin()之后调用示例代码注释中明确说明。上报触发规则官方示例注释min 1, max 0仅在风速变化量达到delta时上报min 0, max 10每 10 秒上报一次或风速变化量达到delta时上报min 0, max 10, delta 0无论风速是否变化每 10 秒上报一次。reportWindSpeed —— 手动上报bool reportWindSpeed();手动上报当前风速值。实现构造esp_zb_zcl_report_attr_cmd_t命令方向为ESP_ZB_ZCL_CMD_DIRECTION_TO_CLI通过基类reportClusterAttribute()发送 report attributes 命令ZigbeeWindSpeedSensor.cpp。可用于按钮触发、事件触发等场景例如示例中短按按键时调用。完整示例End Device 风速传感器仓库在 libraries/Zigbee/examples/Zigbee_Wind_Speed_Sensor/ 提供了完整可运行的示例Zigbee_Wind_Speed_Sensor.ino下面结合源码逐段说明。编译期检查与全局对象#include Arduino.h #ifndef ZIGBEE_MODE_ED #error Zigbee coordinator mode is not selected in Tools-Zigbee mode #endif #include Zigbee.h #define BUTTON_PIN 9 //Boot button for C6/H2 #define WIND_SPEED_SENSOR_ENDPOINT_NUMBER 10 ZigbeeWindSpeedSensor zbWindSpeedSensor ZigbeeWindSpeedSensor(WIND_SPEED_SENSOR_ENDPOINT_NUMBER);使用#ifndef ZIGBEE_MODE_ED做编译期检查提醒必须在Tools → Zigbee mode中选择EDEnd Device模式同时在Tools → Partition Scheme中选择正确的 Zigbee 分区方案。示例面向 ESP32-C6/H2 开发板Boot 按键接 GPIO 9端点号取 10。setup注册端点并启动 Zigbeevoid setup() { Serial.begin(115200); while (!Serial) { delay(10); } pinMode(BUTTON_PIN, INPUT); // 可选设置 Zigbee 设备名称与型号 zbWindSpeedSensor.setManufacturerAndModel(Espressif, ZigbeeWindSpeedSensor); // 设置风速测量量程单位 m/s zbWindSpeedSensor.setMinMaxValue(0, 50); // 设置测量容差单位 m/s最低 0.01 m/s zbWindSpeedSensor.setTolerance(1); // 将端点注册到 Zigbee Core Zigbee.addEndpoint(zbWindSpeedSensor); Serial.println(Starting Zigbee...); if (!Zigbee.begin()) { Serial.println(Zigbee failed to start!); Serial.println(Rebooting...); ESP.restart(); } else { Serial.println(Zigbee started successfully!); } Serial.println(Connecting to network); while (!Zigbee.connected()) { Serial.print(.); delay(100); } Serial.println(); // 启动风速读取任务 xTaskCreate(windspeed_sensor_value_update, wind_speed_sensor_update, 3072, NULL, 10, NULL); // 设置上报必须在 Zigbee.begin() 之后调用 zbWindSpeedSensor.setReporting(1, 0, 1); }要点setManufacturerAndModel由基类提供用于设置 Basic 集群的制造商与型号字符串。调用顺序setMinMaxValue/setTolerance等属性设置必须在addEndpoint之前完成setReporting必须在Zigbee.begin()之后调用。Zigbee.begin()失败会自动重启设备连接网络前通过Zigbee.connected()轮询等待。周期读取任务模拟风速数据static void windspeed_sensor_value_update(void *arg) { for (;;) { // 读取风速传感器值此处用内部温度传感器模拟 float windspeed temperatureRead(); log_v(Wind speed sensor value: %.2fm/s, windspeed); zbWindSpeedSensor.setWindSpeed(windspeed); delay(1000); } }示例用 ESP32 内部温度传感器读数模拟风速每秒调用一次setWindSpeed()更新端点属性。实际项目中应替换为真实风速计如风杯式或超声波风速仪的采样值。loop按键出厂重置与手动上报void loop() { if (digitalRead(BUTTON_PIN) LOW) { // 按键按下 delay(100); int startTime millis(); while (digitalRead(BUTTON_PIN) LOW) { delay(50); if ((millis() - startTime) 3000) { // 长按 3 秒恢复出厂设置并重启 Serial.println(Resetting Zigbee to factory and rebooting in 1s.); delay(1000); Zigbee.factoryReset(); } } zbWindSpeedSensor.reportWindSpeed(); // 短按手动上报当前风速 } delay(100); }长按 3 秒调用Zigbee.factoryReset()恢复出厂设置并重启用于设备重新配网短按调用reportWindSpeed()手动上报一次当前风速是reportWindSpeed方法的典型事件触发用法。HomeAssistant ZHA 集成仓库示例目录下的 README.md 给出了将 ESP32 风速传感器接入 HomeAssistant ZHA 的完整方案。由于 HomeAssistant ZHA 对 wind speed 集群cluster 1035原生支持有限官方推荐两条路线路线一通过 ZHA ToolkitHACS 插件读取属性在 HomeAssistant 中通过 HACS 安装 ZHA Toolkit - Service for advanced Zigbee Usage 并重启在 Configuration → Devices Services → Helpers 中新增一个 Number 辅助变量如wind_speed新建自动化触发器设为每 30 秒的 Time Pattern动作使用 ZHA Toolkit 的 Read Attribute示例 YAML 如下action: zha_toolkit.attr_read metadata: {} data: ieee: f0:f5:bd:ff:fe:0e:61:30 # 设备 IEEE 地址 endpoint: 10 # 风速设备端点号 cluster: 1035 # wind speed 集群 attribute: 0 # 读取 measured value 属性 state_id: input_number.wind_speed # 保存到辅助变量 state_value_template: value/100 # 将 u16 编码转换为浮点 m/s注意state_value_template: value/100因为设备侧按 0.01 m/s 定点编码读取到的原始 u16 值必须除以 100 才能还原为 m/s 浮点值这与前文zb_windspeed_to_u16的编码规则正好对应。之后wind_speed即成为 HomeAssistant 实体可用于仪表盘展示或其它自动化。路线二自定义 Quirk 设备处理器对进阶用户可编写自定义 quirk 直接支持 wind speed 集群获得更无缝的集成体验。该方案需要熟悉 Python 与 Zigbee 协议但能对设备行为提供更灵活的掌控。注意事项与最佳实践单位一致性所有 API 参数以 m/s 为单位底层属性为 0.01 m/s 定点 u16。设置与读取两端需保持同样的换算逻辑×100 / ÷100。调用时序setDefaultValue、setMinMaxValue、setTolerance等属性配置须在Zigbee.addEndpoint()之前setDefaultValue仅在出厂重置模式加入网络前生效setReporting必须在Zigbee.begin()之后调用。编译配置示例依赖ZIGBEE_MODE_ED宏必须在 Arduino IDE 的 Tools → Zigbee mode 选择 End DeviceED并选择配套的 Zigbee Partition Scheme。返回值为false的排查所有方法失败时都会通过log_e输出 ESP-IDF 错误码如esp_err_to_name、esp_zb_zcl_status_to_name结合串口日志可快速定位属性更新、集群注册或上报配置失败的原因。上报策略合理组合min_interval、max_interval与delta可平衡网络流量与数据实时性——需要即时感知风速突变时使用小的delta需要周期性数据时设置max_interval。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考