feat(zigbee): Add option to set initial (default) value (#12147)

* feat(zigbee): Add option to set initial (default) value

* feat(zigbee): Update temp examples

* ci(pre-commit): Apply automatic fixes

---------

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Co-authored-by: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com>

Author: 3 people

docs/en/zigbee/ep_carbon_dioxide_sensor.rst

@@ -54,6 +54,21 @@ Sets the minimum and maximum measurement values.
 
 This function will return ``true`` if successful, ``false`` otherwise.
 
+setDefaultValue
+^^^^^^^^^^^^^^^
+
+Sets the default (initial) value for the carbon dioxide sensor in ppm. This value will be used as the initial measured value when the device is in factory reset mode and before the sensor provides actual readings.
+
+.. code-block:: arduino
+
+    bool setDefaultValue(float defaultValue);
+
+* ``defaultValue`` - Default CO2 concentration value in ppm
+
+**Important:** Must be called before adding the EP to Zigbee class. Only effective when the device is in factory reset mode (before commissioning/joining a network).
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
 setTolerance
 ^^^^^^^^^^^^
 

docs/en/zigbee/ep_flow_sensor.rst

@@ -70,6 +70,21 @@ Sets the minimum and maximum measurement values.
 
 This function will return ``true`` if successful, ``false`` otherwise.
 
+setDefaultValue
+^^^^^^^^^^^^^^^
+
+Sets the default (initial) value for the flow sensor in 0.1 m³/h. This value will be used as the initial measured value when the device is in factory reset mode and before the sensor provides actual readings.
+
+.. code-block:: arduino
+
+    bool setDefaultValue(float defaultValue);
+
+* ``defaultValue`` - Default flow rate value in 0.1 m³/h
+
+**Important:** Must be called before adding the EP to Zigbee class. Only effective when the device is in factory reset mode (before commissioning/joining a network).
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
 setTolerance
 ^^^^^^^^^^^^
 

docs/en/zigbee/ep_illuminance_sensor.rst

@@ -60,6 +60,21 @@ Sets the minimum and maximum measurement values.
 
 This function will return ``true`` if successful, ``false`` otherwise.
 
+setDefaultValue
+^^^^^^^^^^^^^^^
+
+Sets the default (initial) value for the illuminance sensor. This value will be used as the initial measured value when the device is in factory reset mode and before the sensor provides actual readings.
+
+.. code-block:: arduino
+
+    bool setDefaultValue(uint16_t defaultValue);
+
+* ``defaultValue`` - Default illuminance value in lux
+
+**Important:** Must be called before adding the EP to Zigbee class. Only effective when the device is in factory reset mode (before commissioning/joining a network).
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
 setTolerance
 ^^^^^^^^^^^^
 

docs/en/zigbee/ep_pm25_sensor.rst

@@ -60,6 +60,21 @@ Sets the minimum and maximum measurement values.
 
 This function will return ``true`` if successful, ``false`` otherwise.
 
+setDefaultValue
+^^^^^^^^^^^^^^^
+
+Sets the default (initial) value for the PM2.5 sensor in 0.1 μg/m³. This value will be used as the initial measured value when the device is in factory reset mode and before the sensor provides actual readings.
+
+.. code-block:: arduino
+
+    bool setDefaultValue(float defaultValue);
+
+* ``defaultValue`` - Default PM2.5 concentration value in 0.1 μg/m³
+
+**Important:** Must be called before adding the EP to Zigbee class. Only effective when the device is in factory reset mode (before commissioning/joining a network).
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
 setTolerance
 ^^^^^^^^^^^^
 

docs/en/zigbee/ep_pressure_sensor.rst

@@ -60,6 +60,21 @@ Sets the minimum and maximum measurement values.
 
 This function will return ``true`` if successful, ``false`` otherwise.
 
+setDefaultValue
+^^^^^^^^^^^^^^^
+
+Sets the default (initial) value for the pressure sensor in 1 hPa. This value will be used as the initial measured value when the device is in factory reset mode and before the sensor provides actual readings.
+
+.. code-block:: arduino
+
+    bool setDefaultValue(int16_t defaultValue);
+
+* ``defaultValue`` - Default pressure value in hPa
+
+**Important:** Must be called before adding the EP to Zigbee class. Only effective when the device is in factory reset mode (before commissioning/joining a network).
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
 setTolerance
 ^^^^^^^^^^^^
 

docs/en/zigbee/ep_temperature_sensor.rst

@@ -60,6 +60,21 @@ Sets the minimum and maximum temperature values for the sensor.
 
 This function will return ``true`` if successful, ``false`` otherwise.
 
+setDefaultValue
+^^^^^^^^^^^^^^^
+
+Sets the default (initial) value for the temperature sensor in 0.01°C resolution. This value will be used as the initial measured value when the device is in factory reset mode and before the sensor provides actual readings.
+
+.. code-block:: arduino
+
+    bool setDefaultValue(float defaultValue);
+
+* ``defaultValue`` - Default temperature value in degrees Celsius
+
+**Important:** Must be called before adding the EP to Zigbee class. Only effective when the device is in factory reset mode (before commissioning/joining a network).
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
 setTolerance
 ^^^^^^^^^^^^
 

docs/en/zigbee/ep_wind_speed_sensor.rst

@@ -70,6 +70,21 @@ Sets the minimum and maximum measurement values.
 
 This function will return ``true`` if successful, ``false`` otherwise.
 
+setDefaultValue
+^^^^^^^^^^^^^^^
+
+Sets the default (initial) value for the wind speed sensor in 0.01 m/s. This value will be used as the initial measured value when the device is in factory reset mode and before the sensor provides actual readings.
+
+.. code-block:: arduino
+
+    bool setDefaultValue(float defaultValue);
+
+* ``defaultValue`` - Default wind speed value in 0.01 m/s
+
+**Important:** Must be called before adding the EP to Zigbee class. Only effective when the device is in factory reset mode (before commissioning/joining a network).
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
 setTolerance
 ^^^^^^^^^^^^
 

libraries/Zigbee/examples/Zigbee_Temp_Hum_Sensor_Sleepy/Zigbee_Temp_Hum_Sensor_Sleepy.ino

@@ -135,15 +135,18 @@ void setup() {
   // Set minimum and maximum temperature measurement value (10-50°C is default range for chip temperature measurement)
   zbTempSensor.setMinMaxValue(10, 50);
 
+  // Set default (initial) value for the temperature sensor to 10.0°C to match the minimum temperature measurement value (default value is 0.0°C)
+  zbTempSensor.setDefaultValue(10.0);
+
   // Set tolerance for temperature measurement in °C (lowest possible value is 0.01°C)
   zbTempSensor.setTolerance(1);
 
   // Set power source to battery, battery percentage and battery voltage (now 100% and 3.5V for demonstration)
   // The value can be also updated by calling zbTempSensor.setBatteryPercentage(percentage) or zbTempSensor.setBatteryVoltage(voltage) anytime after Zigbee.begin()
   zbTempSensor.setPowerSource(ZB_POWER_SOURCE_BATTERY, 100, 35);
 
-  // Add humidity cluster to the temperature sensor device with min, max and tolerance values
-  zbTempSensor.addHumiditySensor(0, 100, 1);
+  // Add humidity cluster to the temperature sensor device with min, max, tolerance and default values
+  zbTempSensor.addHumiditySensor(0, 100, 1, 0.0);
 
   // Set callback for default response to handle status of reported data, there are 2 options.
 

libraries/Zigbee/examples/Zigbee_Temperature_Sensor/Zigbee_Temperature_Sensor.ino

@@ -68,6 +68,9 @@ void setup() {
   // Set minimum and maximum temperature measurement value (10-50°C is default range for chip temperature measurement)
   zbTempSensor.setMinMaxValue(10, 50);
 
+  // Optional: Set default (initial) value for the temperature sensor to 10.0°C to match the minimum temperature measurement value
+  zbTempSensor.setDefaultValue(10.0);
+
   // Optional: Set tolerance for temperature measurement in °C (lowest possible value is 0.01°C)
   zbTempSensor.setTolerance(1);
 

libraries/Zigbee/src/ep/ZigbeeCarbonDioxideSensor.cpp

@@ -38,6 +38,19 @@ ZigbeeCarbonDioxideSensor::ZigbeeCarbonDioxideSensor(uint8_t endpoint) : ZigbeeE
   _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};
 }
 
+bool ZigbeeCarbonDioxideSensor::setDefaultValue(float defaultValue) {
+  float zb_default_value = defaultValue / 1000000.0f;
+  esp_zb_attribute_list_t *carbon_dioxide_measure_cluster =
+    esp_zb_cluster_list_get_cluster(_cluster_list, ESP_ZB_ZCL_CLUSTER_ID_CARBON_DIOXIDE_MEASUREMENT, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE);
+  esp_err_t ret =
+    esp_zb_cluster_update_attr(carbon_dioxide_measure_cluster, ESP_ZB_ZCL_ATTR_CARBON_DIOXIDE_MEASUREMENT_MEASURED_VALUE_ID, (void *)&zb_default_value);
+  if (ret != ESP_OK) {
+    log_e("Failed to set default value: 0x%x: %s", ret, esp_err_to_name(ret));
+    return false;
+  }
+  return true;
+}
+
 bool ZigbeeCarbonDioxideSensor::setMinMaxValue(float min, float max) {
   float zb_min = min / 1000000.0f;
   float zb_max = max / 1000000.0f;