feat(Zigbee): Adding Zigbee Wind speed sensor endpoint (#10455)

lboue · P-R-O-C-H-Y · pre-commit-ci-lite[bot] · web-flow · commit 07d6a5a0d2f7 · 2025-03-12T15:38:09.000+02:00
* Create ZigbeeWindSpeedSensor.h

* Create ZigbeeWindSpeedSensor.cpp

* Update ZigbeeWindSpeedSensor.cpp

* Update ZigbeeWindSpeedSensor.cpp

* Create ZigbeeWindSpeedSensor.ino

* Update ZigbeeWindSpeedSensor.ino

* Update ZigbeeWindSpeedSensor.ino

* Create ci.json

* Rename ZigbeeWindSpeedSensor.ino to Zigbee_Wind_Speed_Sensor.ino

* Rename ci.json to ci.json

* Update CMakeLists.txt

* Update Zigbee_Wind_Speed_Sensor.ino

* Update Zigbee_Wind_Speed_Sensor.ino

* Update Zigbee_Wind_Speed_Sensor.ino

* Update ZigbeeWindSpeedSensor.cpp

* Update ZigbeeWindSpeedSensor.cpp

Use ESP_ZB_HA_SIMPLE_SENSOR_DEVICE_ID device id

* feat(zigbee): Add windspeed sensor endpoint

* Update Zigbee.h

Add ZigbeeWindSpeedSensor.h

* update example

* add missing sdkconfig include

* add readme

* ci(pre-commit): Apply automatic fixes

* Update README.md

---------

Co-authored-by: Jan Procházka &lt;90197375+P-R-O-C-H-Y@users.noreply.github.com&gt;
Co-authored-by: pre-commit-ci-lite[bot] &lt;117423508+pre-commit-ci-lite[bot]@users.noreply.github.com&gt;
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -298,6 +298,7 @@ set(ARDUINO_LIBRARY_Zigbee_SRCS
   libraries/Zigbee/src/ep/ZigbeeAnalog.cpp
   libraries/Zigbee/src/ep/ZigbeeRangeExtender.cpp
   libraries/Zigbee/src/ep/ZigbeeGateway.cpp
+  libraries/Zigbee/src/ep/ZigbeeWindSpeedSensor.cpp
   )
 
 set(ARDUINO_LIBRARY_BLE_SRCS
diff --git a/libraries/Zigbee/examples/Zigbee_Wind_Speed_Sensor/README.md b/libraries/Zigbee/examples/Zigbee_Wind_Speed_Sensor/README.md
@@ -0,0 +1,60 @@
+# Zigbee Wind Speed Sensor Integration with HomeAssistant ZHA
+
+This guide provides a workaround for integrating a Zigbee Wind Speed Sensor with HomeAssistant using the ZHA integration. Since the wind speed cluster is not natively supported, we will use the ZHA Toolkit from HACS to read the wind speed attribute and store it in a helper variable.
+## Alternative Option: Creating a Custom Quirk
+
+For advanced users, a more robust solution is to create a custom quirk for your Zigbee Wind Speed Sensor. This approach involves writing a custom device handler that directly supports the wind speed cluster, providing a more seamless integration with HomeAssistant.
+
+Creating a custom quirk can be complex and requires familiarity with Python and the Zigbee protocol. However, it offers greater flexibility and control over your device's behavior.
+
+For more information and guidance on creating custom quirks, visit the [ZHA Device Handlers repository](https://github.com/zigpy/zha-device-handlers/).
+
+## Prerequisites
+
+- HomeAssistant installed and running
+- Zigbee Wind Speed Sensor paired with HomeAssistant ZHA
+- HACS (Home Assistant Community Store) installed. For more information, visit [HACS](https://hacs.xyz)
+
+## Steps
+
+### 1. Install ZHA Toolkit
+
+1. Open HomeAssistant.
+2. Navigate to HACS > Integrations.
+3. Search for "ZHA Toolkit - Service for advanced Zigbee Usage" and install it. For more information, visit the [ZHA Toolkit repository](https://github.com/mdeweerd/zha-toolkit).
+4. Restart HomeAssistant to apply changes.
+
+### 2. Create a Helper Variable
+
+1. Go to Configuration -> Devices & Services -> Helpers.
+2. Click on "Add Helper" and select "Number".
+3. Name the helper (e.g., `wind_speed`), set the minimum and maximum values, and save it.
+
+### 3. Create an Automation
+
+1. Go to Configuration > Automations & Scenes.
+2. Click on "Add Automation" and choose "Start with an empty automation".
+3. Set a name for the automation (e.g., `Read Wind Speed`).
+4. Add a trigger:
+    - Trigger Type: Time Pattern
+    - Every: 30 seconds
+5. Add an action (Then do):
+    - Action Type: ZHA Toolkit: Read Attribute
+    - Setup the action:
+      ```yaml
+        action: zha_toolkit.attr_read
+        metadata: {}
+        data:
+            ieee: f0:f5:bd:ff:fe:0e:61:30 #set device IEEE address
+            endpoint: 10 #set windspeed device endpoint
+            cluster: 1035 #use this windspeed cluster
+            attribute: 0 #read measurement value
+            state_id: input_number.wind_speed #save to created helper variable
+            state_value_template: value/100 #use correct value format (convert u16 to float)
+      ```
+6. Save the automation.
+
+## Conclusion
+
+By following these steps, you can successfully integrate your Zigbee Wind Speed Sensor with HomeAssistant using the ZHA integration and ZHA Toolkit. The wind speed readings will be updated every 30 seconds and stored in the helper variable for use in your HomeAssistant setup.
+The helper variable `wind_speed` is now an entity in HomeAssistant. You can use this entity to display the wind speed on your dashboard or in other automations.
diff --git a/libraries/Zigbee/examples/Zigbee_Wind_Speed_Sensor/Zigbee_Wind_Speed_Sensor.ino b/libraries/Zigbee/examples/Zigbee_Wind_Speed_Sensor/Zigbee_Wind_Speed_Sensor.ino
@@ -0,0 +1,119 @@
+// Copyright 2024 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @brief This example demonstrates Zigbee windspeed sensor.
+ *
+ * The example demonstrates how to use Zigbee library to create a end device wind speed sensor.
+ * The wind speed sensor is a Zigbee end device, which is controlled by a Zigbee coordinator.
+ *
+ * Proper Zigbee mode must be selected in Tools->Zigbee mode
+ * and also the correct partition scheme must be selected in Tools->Partition Scheme.
+ *
+ * Please check the README.md for instructions and more detailed description.
+ *
+ * Created by Jan Procházka (https://github.com/P-R-O-C-H-Y/)
+ */
+
+#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);
+
+/************************ WindSpeed sensor *****************************/
+static void windspeed_sensor_value_update(void *arg) {
+  for (;;) {
+    // Read wind speed sensor value (simulated now by temperature sensor)
+    float windspeed = temperatureRead();
+    log_v("Wind speed sensor value: %.2fm/s", windspeed);
+    // Update windspeed value in Windspeed sensor EP
+    zbWindSpeedSensor.setWindSpeed(windspeed);
+    delay(1000);
+  }
+}
+
+/********************* Arduino functions **************************/
+void setup() {
+  Serial.begin(115200);
+  while (!Serial) {
+    delay(10);
+  }
+
+  // Init button switch
+  pinMode(BUTTON_PIN, INPUT);
+
+  // Optional: set Zigbee device name and model
+  zbWindSpeedSensor.setManufacturerAndModel("Espressif", "ZigbeeWindSpeedSensor");
+
+  // Set minimum and maximum windspeed measurement value in m/s
+  zbWindSpeedSensor.setMinMaxValue(0, 50);
+
+  // Set tolerance for windspeed measurement in m/s (lowest possible value is 0.01 m/s)
+  zbWindSpeedSensor.setTolerance(1);
+
+  // Add endpoint to Zigbee Core
+  Zigbee.addEndpoint(&zbWindSpeedSensor);
+
+  Serial.println("Starting Zigbee...");
+  // When all EPs are registered, start Zigbee in End Device mode
+  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();
+
+  // Start Wind speed sensor reading task
+  xTaskCreate(windspeed_sensor_value_update, "wind_speed_sensor_update", 2048, NULL, 10, NULL);
+
+  // Set reporting interval for windspeed measurement in seconds, must be called after Zigbee.begin()
+  // min_interval and max_interval in seconds, delta (WindSpeed change in m/s)
+  // if min = 1 and max = 0, reporting is sent only when windspeed changes by delta
+  // if min = 0 and max = 10, reporting is sent every 10 seconds or windspeed changes by delta
+  // if min = 0, max = 10 and delta = 0, reporting is sent every 10 seconds regardless of windspeed change
+  zbWindSpeedSensor.setReporting(1, 0, 1);
+}
+
+void loop() {
+  // Checking button for factory reset
+  if (digitalRead(BUTTON_PIN) == LOW) {  // Push button pressed
+    // Key debounce handling
+    delay(100);
+    int startTime = millis();
+    while (digitalRead(BUTTON_PIN) == LOW) {
+      delay(50);
+      if ((millis() - startTime) > 3000) {
+        // If key pressed for more than 3secs, factory reset Zigbee and reboot
+        Serial.println("Resetting Zigbee to factory and rebooting in 1s.");
+        delay(1000);
+        Zigbee.factoryReset();
+      }
+    }
+    zbWindSpeedSensor.reportWindSpeed();
+  }
+  delay(100);
+}
diff --git a/libraries/Zigbee/examples/Zigbee_Wind_Speed_Sensor/ci.json b/libraries/Zigbee/examples/Zigbee_Wind_Speed_Sensor/ci.json
@@ -0,0 +1,7 @@
+{
+  "fqbn_append": "PartitionScheme=zigbee,ZigbeeMode=ed",
+  "requires": [
+    "CONFIG_SOC_IEEE802154_SUPPORTED=y",
+    "CONFIG_ZB_ENABLED=y"
+  ]
+}
diff --git a/libraries/Zigbee/src/Zigbee.h b/libraries/Zigbee/src/Zigbee.h
@@ -25,3 +25,4 @@
 #include "ep/ZigbeeVibrationSensor.h"
 #include "ep/ZigbeeRangeExtender.h"
 #include "ep/ZigbeeGateway.h"
+#include "ep/ZigbeeWindSpeedSensor.h"
diff --git a/libraries/Zigbee/src/ep/ZigbeeWindSpeedSensor.cpp b/libraries/Zigbee/src/ep/ZigbeeWindSpeedSensor.cpp
@@ -0,0 +1,98 @@
+#include "ZigbeeWindSpeedSensor.h"
+#if CONFIG_ZB_ENABLED
+
+esp_zb_cluster_list_t *zigbee_wind_speed_sensor_clusters_create(zigbee_wind_speed_sensor_cfg_t *wind_speed_sensor) {
+  esp_zb_basic_cluster_cfg_t *basic_cfg = wind_speed_sensor ? &(wind_speed_sensor->basic_cfg) : NULL;
+  esp_zb_identify_cluster_cfg_t *identify_cfg = wind_speed_sensor ? &(wind_speed_sensor->identify_cfg) : NULL;
+  esp_zb_wind_speed_measurement_cluster_cfg_t *wind_speed_cfg = wind_speed_sensor ? &(wind_speed_sensor->wind_speed_meas_cfg) : NULL;
+  esp_zb_cluster_list_t *cluster_list = esp_zb_zcl_cluster_list_create();
+  esp_zb_cluster_list_add_basic_cluster(cluster_list, esp_zb_basic_cluster_create(basic_cfg), ESP_ZB_ZCL_CLUSTER_SERVER_ROLE);
+  esp_zb_cluster_list_add_identify_cluster(cluster_list, esp_zb_identify_cluster_create(identify_cfg), ESP_ZB_ZCL_CLUSTER_SERVER_ROLE);
+  esp_zb_cluster_list_add_wind_speed_measurement_cluster(
+    cluster_list, esp_zb_wind_speed_measurement_cluster_create(wind_speed_cfg), ESP_ZB_ZCL_CLUSTER_SERVER_ROLE
+  );
+  return cluster_list;
+}
+
+// There is no device_id for wind speed sensor, we use a generic one
+ZigbeeWindSpeedSensor::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};
+}
+
+static uint16_t zb_windspeed_to_u16(float windspeed) {
+  return (uint16_t)(windspeed * 100);
+}
+
+void ZigbeeWindSpeedSensor::setMinMaxValue(float min, float max) {
+  uint16_t zb_min = zb_windspeed_to_u16(min);
+  uint16_t zb_max = zb_windspeed_to_u16(max);
+  esp_zb_attribute_list_t *windspeed_measure_cluster =
+    esp_zb_cluster_list_get_cluster(_cluster_list, ESP_ZB_ZCL_CLUSTER_ID_WIND_SPEED_MEASUREMENT, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE);
+  //
+  esp_zb_cluster_update_attr(windspeed_measure_cluster, ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_MIN_MEASURED_VALUE_ID, (void *)&zb_min);
+  esp_zb_cluster_update_attr(windspeed_measure_cluster, ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_MAX_MEASURED_VALUE_ID, (void *)&zb_max);
+}
+
+void ZigbeeWindSpeedSensor::setTolerance(float tolerance) {
+  // Convert tolerance to ZCL uint16_t
+  uint16_t zb_tolerance = zb_windspeed_to_u16(tolerance);
+  esp_zb_attribute_list_t *windspeed_measure_cluster =
+    esp_zb_cluster_list_get_cluster(_cluster_list, ESP_ZB_ZCL_CLUSTER_ID_WIND_SPEED_MEASUREMENT, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE);
+  esp_zb_wind_speed_measurement_cluster_add_attr(windspeed_measure_cluster, ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_TOLERANCE_ID, (void *)&zb_tolerance);
+}
+
+void ZigbeeWindSpeedSensor::setReporting(uint16_t min_interval, uint16_t max_interval, float delta) {
+  esp_zb_zcl_reporting_info_t reporting_info;
+  memset(&reporting_info, 0, sizeof(esp_zb_zcl_reporting_info_t));
+  reporting_info.direction = ESP_ZB_ZCL_CMD_DIRECTION_TO_SRV;
+  reporting_info.ep = _endpoint;
+  reporting_info.cluster_id = ESP_ZB_ZCL_CLUSTER_ID_WIND_SPEED_MEASUREMENT;
+  reporting_info.cluster_role = ESP_ZB_ZCL_CLUSTER_SERVER_ROLE;
+  reporting_info.attr_id = ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_MEASURED_VALUE_ID;
+  reporting_info.u.send_info.min_interval = min_interval;
+  reporting_info.u.send_info.max_interval = max_interval;
+  reporting_info.u.send_info.def_min_interval = min_interval;
+  reporting_info.u.send_info.def_max_interval = max_interval;
+  reporting_info.u.send_info.delta.u16 = (uint16_t)(delta * 100);  // Convert delta to ZCL uint16_t
+  reporting_info.dst.profile_id = ESP_ZB_AF_HA_PROFILE_ID;
+  reporting_info.manuf_code = ESP_ZB_ZCL_ATTR_NON_MANUFACTURER_SPECIFIC;
+  esp_zb_lock_acquire(portMAX_DELAY);
+  esp_zb_zcl_update_reporting_info(&reporting_info);
+  esp_zb_lock_release();
+}
+
+void ZigbeeWindSpeedSensor::setWindSpeed(float windspeed) {
+  uint16_t zb_windspeed = zb_windspeed_to_u16(windspeed);
+  log_v("Updating windspeed sensor value...");
+  /* Update windspeed sensor measured value */
+  log_d("Setting windspeed to %d", zb_windspeed);
+  esp_zb_lock_acquire(portMAX_DELAY);
+  esp_zb_zcl_set_attribute_val(
+    _endpoint, ESP_ZB_ZCL_CLUSTER_ID_WIND_SPEED_MEASUREMENT, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_MEASURED_VALUE_ID,
+    &zb_windspeed, false
+  );
+  esp_zb_lock_release();
+}
+
+void ZigbeeWindSpeedSensor::reportWindSpeed() {
+  /* Send report attributes command */
+  esp_zb_zcl_report_attr_cmd_t report_attr_cmd;
+  report_attr_cmd.address_mode = ESP_ZB_APS_ADDR_MODE_DST_ADDR_ENDP_NOT_PRESENT;
+  report_attr_cmd.attributeID = ESP_ZB_ZCL_ATTR_WIND_SPEED_MEASUREMENT_MEASURED_VALUE_ID;
+  report_attr_cmd.direction = ESP_ZB_ZCL_CMD_DIRECTION_TO_CLI;
+  report_attr_cmd.clusterID = ESP_ZB_ZCL_CLUSTER_ID_WIND_SPEED_MEASUREMENT;
+  report_attr_cmd.zcl_basic_cmd.src_endpoint = _endpoint;
+  report_attr_cmd.manuf_code = ESP_ZB_ZCL_ATTR_NON_MANUFACTURER_SPECIFIC;
+
+  esp_zb_lock_acquire(portMAX_DELAY);
+  esp_zb_zcl_report_attr_cmd_req(&report_attr_cmd);
+  esp_zb_lock_release();
+  log_v("Wind speed measurement report sent");
+}
+
+#endif  //CONFIG_ZB_ENABLED
diff --git a/libraries/Zigbee/src/ep/ZigbeeWindSpeedSensor.h b/libraries/Zigbee/src/ep/ZigbeeWindSpeedSensor.h
@@ -0,0 +1,56 @@
+/* Class of Zigbee WindSpeed sensor endpoint inherited from common EP class */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "sdkconfig.h"
+#if CONFIG_ZB_ENABLED
+
+#include "ZigbeeEP.h"
+#include "ha/esp_zigbee_ha_standard.h"
+
+#define ZIGBEE_DEFAULT_WIND_SPEED_SENSOR_CONFIG()                                         \
+  {                                                                                       \
+    .basic_cfg =                                                                          \
+      {                                                                                   \
+        .zcl_version = ESP_ZB_ZCL_BASIC_ZCL_VERSION_DEFAULT_VALUE,                        \
+        .power_source = ESP_ZB_ZCL_BASIC_POWER_SOURCE_DEFAULT_VALUE,                      \
+      },                                                                                  \
+    .identify_cfg =                                                                       \
+      {                                                                                   \
+        .identify_time = ESP_ZB_ZCL_IDENTIFY_IDENTIFY_TIME_DEFAULT_VALUE,                 \
+      },                                                                                  \
+    .wind_speed_meas_cfg = {                                                              \
+      .measured_value = ESP_ZB_ZCL_WIND_SPEED_MEASUREMENT_MEASURED_VALUE_DEFAULT,         \
+      .min_measured_value = ESP_ZB_ZCL_WIND_SPEED_MEASUREMENT_MIN_MEASURED_VALUE_DEFAULT, \
+      .max_measured_value = ESP_ZB_ZCL_WIND_SPEED_MEASUREMENT_MAX_MEASURED_VALUE_DEFAULT, \
+    },                                                                                    \
+  }
+
+typedef struct zigbee_wind_speed_sensor_cfg_s {
+  esp_zb_basic_cluster_cfg_t basic_cfg;       /*!<  Basic cluster configuration, @ref esp_zb_basic_cluster_cfg_s */
+  esp_zb_identify_cluster_cfg_t identify_cfg; /*!<  Identify cluster configuration, @ref esp_zb_identify_cluster_cfg_s */
+  esp_zb_wind_speed_measurement_cluster_cfg_t
+    wind_speed_meas_cfg; /*!<  Wind speed measurement cluster configuration, @ref esp_zb_wind_speed_measurement_cluster_cfg_s */
+} zigbee_wind_speed_sensor_cfg_t;
+
+class ZigbeeWindSpeedSensor : public ZigbeeEP {
+public:
+  ZigbeeWindSpeedSensor(uint8_t endpoint);
+  ~ZigbeeWindSpeedSensor() {}
+
+  // Set the WindSpeed value in 0,01 m/s
+  void setWindSpeed(float value);
+
+  // Set the min and max value for the WindSpeed sensor
+  void setMinMaxValue(float min, float max);
+
+  // Set the tolerance value for the WindSpeed sensor
+  void setTolerance(float tolerance);
+
+  // Set the reporting interval for WindSpeed measurement in seconds and delta
+  void setReporting(uint16_t min_interval, uint16_t max_interval, float delta);
+  void reportWindSpeed();
+};
+
+#endif  //CONFIG_ZB_ENABLED

Original file line number	Diff line number	Diff line change
`@@ -298,6 +298,7 @@ set(ARDUINO_LIBRARY_Zigbee_SRCS`
`298`	`298`	`libraries/Zigbee/src/ep/ZigbeeAnalog.cpp`
`299`	`299`	`libraries/Zigbee/src/ep/ZigbeeRangeExtender.cpp`
`300`	`300`	`libraries/Zigbee/src/ep/ZigbeeGateway.cpp`
	`301`	`+ libraries/Zigbee/src/ep/ZigbeeWindSpeedSensor.cpp`
`301`	`302`	`)`
`302`	`303`
`303`	`304`	`set(ARDUINO_LIBRARY_BLE_SRCS`