feat(zigbee): Use contexpr, cb typedefs, cb simplification

Author: P-R-O-C-H-Y

docs/en/zigbee/ep_color_dimmable_light.rst

@@ -89,6 +89,19 @@ This function will return ``true`` if successful, ``false`` otherwise.
 Callback Functions
 ******************
 
+Callback Type Definitions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For better type safety and readability, typedefs are provided for all callback functions:
+
+.. code-block:: arduino
+
+    typedef void (*ZigbeeColorLightRgbCallback)(bool state, uint8_t red, uint8_t green, uint8_t blue, uint8_t level);
+    typedef void (*ZigbeeColorLightHsvCallback)(bool state, uint8_t hue, uint8_t saturation, uint8_t value);
+    typedef void (*ZigbeeColorLightTempCallback)(bool state, uint8_t level, uint16_t color_temperature);
+
+These typedefs can be used instead of raw function pointer syntax for better code clarity.
+
 onLightChange
 ^^^^^^^^^^^^^
 
@@ -102,6 +115,12 @@ Sets the legacy callback function for light state changes (RGB mode).
 
 * ``callback`` - Function pointer to the light change callback (state, red, green, blue, level)
 
+  * ``state`` - Light state (true = on, false = off)
+  * ``red`` - Red component (0-255)
+  * ``green`` - Green component (0-255)
+  * ``blue`` - Blue component (0-255)
+  * ``level`` - Brightness level (0-255)
+
 .. note::
    This method is deprecated. Please use ``onLightChangeRgb()`` for RGB/XY mode callbacks.
 
@@ -112,9 +131,17 @@ Sets the callback function for RGB/XY color mode changes.
 
 .. code-block:: arduino
 
+    void onLightChangeRgb(ZigbeeColorLightRgbCallback callback);
+    // or using raw function pointer syntax:
     void onLightChangeRgb(void (*callback)(bool, uint8_t, uint8_t, uint8_t, uint8_t));
 
 * ``callback`` - Function pointer to the RGB light change callback (state, red, green, blue, level)
+  
+  * ``state`` - Light state (true = on, false = off)
+  * ``red`` - Red component (0-255)
+  * ``green`` - Green component (0-255)
+  * ``blue`` - Blue component (0-255)
+  * ``level`` - Brightness level (0-255)
 
 onLightChangeHsv
 ^^^^^^^^^^^^^^^^
@@ -123,9 +150,16 @@ Sets the callback function for HSV (Hue/Saturation) color mode changes.
 
 .. code-block:: arduino
 
-    void onLightChangeHsv(void (*callback)(bool, uint8_t, uint8_t, uint8_t, uint8_t));
+    void onLightChangeHsv(ZigbeeColorLightHsvCallback callback);
+    // or using raw function pointer syntax:
+    void onLightChangeHsv(void (*callback)(bool, uint8_t, uint8_t, uint8_t));
 
-* ``callback`` - Function pointer to the HSV light change callback (state, hue, saturation, value, level)
+* ``callback`` - Function pointer to the HSV light change callback (state, hue, saturation, value)
+  
+  * ``state`` - Light state (true = on, false = off)
+  * ``hue`` - Hue component (0-254)
+  * ``saturation`` - Saturation component (0-254)
+  * ``value`` - Value/brightness component (0-255)
 
 onLightChangeTemp
 ^^^^^^^^^^^^^^^^^
@@ -134,9 +168,15 @@ Sets the callback function for color temperature mode changes.
 
 .. code-block:: arduino
 
+    void onLightChangeTemp(ZigbeeColorLightTempCallback callback);
+    // or using raw function pointer syntax:
     void onLightChangeTemp(void (*callback)(bool, uint8_t, uint16_t));
 
 * ``callback`` - Function pointer to the temperature light change callback (state, level, temperature_mireds)
+  
+  * ``state`` - Light state (true = on, false = off)
+  * ``level`` - Brightness level (0-255)
+  * ``temperature_mireds`` - Color temperature in mireds (inverse of Kelvin)
 
 Control Methods
 ***************

libraries/Zigbee/src/ep/ZigbeeColorDimmableLight.cpp

@@ -54,7 +54,6 @@ ZigbeeColorDimmableLight::ZigbeeColorDimmableLight(uint8_t endpoint) : ZigbeeEP(
   _color_capabilities = ZIGBEE_COLOR_CAPABILITY_X_Y; //default XY color supported only
 
   // Initialize callbacks to nullptr
-  _on_light_change = nullptr;
   _on_light_change_rgb = nullptr;
   _on_light_change_hsv = nullptr;
   _on_light_change_temp = nullptr;
@@ -245,24 +244,15 @@ void ZigbeeColorDimmableLight::zbAttributeSet(const esp_zb_zcl_set_attr_value_me
   }
 }
 
-void ZigbeeColorDimmableLight::lightChanged() {
-  if (_on_light_change) {
-    _on_light_change(_current_state, _current_color.r, _current_color.g, _current_color.b, _current_level);
-  }
-}
-
 void ZigbeeColorDimmableLight::lightChangedRgb() {
   if (_on_light_change_rgb) {
     _on_light_change_rgb(_current_state, _current_color.r, _current_color.g, _current_color.b, _current_level);
-  } else if (_on_light_change) { 
-    // Fallback to legacy callback (deprecated) to maintain backward compatibility.
-    _on_light_change(_current_state, _current_color.r, _current_color.g, _current_color.b, _current_level);
   }
 }
 
 void ZigbeeColorDimmableLight::lightChangedHsv() {
   if (_on_light_change_hsv) {
-    _on_light_change_hsv(_current_state, _current_hsv.h, _current_hsv.s, _current_hsv.v, _current_level);
+    _on_light_change_hsv(_current_state, _current_hsv.h, _current_hsv.s, _current_hsv.v);
   }
 }
 
@@ -309,8 +299,9 @@ bool ZigbeeColorDimmableLight::setLight(bool state, uint8_t level, uint8_t red,
 
   espXyColor_t xy_color = espRgbColorToXYColor(_current_color);
   espHsvColor_t hsv_color = espRgbColorToHsvColor(_current_color);
-  uint8_t hue = std::min((uint8_t)hsv_color.h, (uint8_t)254);         // Clamp to 0-254
-  uint8_t saturation = std::min((uint8_t)hsv_color.s, (uint8_t)254);  // Clamp to 0-254
+  // Clamp hue and saturation to valid Zigbee range (0-254, where 254 = 0xFE is max per ZCL spec)
+  uint8_t hue = std::min(std::max((uint8_t)hsv_color.h, (uint8_t)0), (uint8_t)254);
+  uint8_t saturation = std::min(std::max((uint8_t)hsv_color.s, (uint8_t)0), (uint8_t)254);
   // Update HSV state
   _current_hsv = hsv_color;
 
@@ -398,16 +389,26 @@ bool ZigbeeColorDimmableLight::setLightColor(espHsvColor_t hsv_color) {
     log_e("Failed to set light color mode: %d", ZIGBEE_COLOR_MODE_HUE_SATURATION);
     return false;
   }
-  // Update HSV state
+  // Update HSV state and level from value component
   _current_hsv = hsv_color;
+  _current_level = hsv_color.v;  // Use HSV value component to update brightness level
   lightChangedHsv();
 
-  uint8_t hue = std::min((uint8_t)hsv_color.h, (uint8_t)254);         // Clamp to 0-254
-  uint8_t saturation = std::min((uint8_t)hsv_color.s, (uint8_t)254);  // Clamp to 0-254
+  // Clamp hue and saturation to valid Zigbee range (0-254, where 254 = 0xFE is max per ZCL spec)
+  uint8_t hue = std::min(std::max((uint8_t)hsv_color.h, (uint8_t)0), (uint8_t)254);
+  uint8_t saturation = std::min(std::max((uint8_t)hsv_color.s, (uint8_t)0), (uint8_t)254);
 
-  log_v("Updating light HSV: H=%d, S=%d, V=%d", hue, saturation, hsv_color.v);
+  log_v("Updating light HSV: H=%d, S=%d, V=%d (level=%d)", hue, saturation, hsv_color.v, _current_level);
   /* Update light clusters */
   esp_zb_lock_acquire(portMAX_DELAY);
+  //set level (brightness from HSV value component)
+  ret = esp_zb_zcl_set_attribute_val(
+    _endpoint, ESP_ZB_ZCL_CLUSTER_ID_LEVEL_CONTROL, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_LEVEL_CONTROL_CURRENT_LEVEL_ID, &_current_level, false
+  );
+  if (ret != ESP_ZB_ZCL_STATUS_SUCCESS) {
+    log_e("Failed to set light level: 0x%x: %s", ret, esp_zb_zcl_status_to_name(ret));
+    goto unlock_and_return;
+  }
   //set hue
   ret = esp_zb_zcl_set_attribute_val(
     _endpoint, ESP_ZB_ZCL_CLUSTER_ID_COLOR_CONTROL, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE, ESP_ZB_ZCL_ATTR_COLOR_CONTROL_CURRENT_HUE_ID, &hue, false

libraries/Zigbee/src/ep/ZigbeeColorDimmableLight.h

@@ -65,11 +65,11 @@
   }
 
 // Color capabilities bit flags (matching ZCL spec) - can be combined with bitwise OR
-#define ZIGBEE_COLOR_CAPABILITY_HUE_SATURATION  (1 << 0)  // Bit 0: Hue/saturation supported
-#define ZIGBEE_COLOR_CAPABILITY_ENHANCED_HUE    (1 << 1)  // Bit 1: Enhanced hue supported
-#define ZIGBEE_COLOR_CAPABILITY_COLOR_LOOP      (1 << 2)  // Bit 2: Color loop supported
-#define ZIGBEE_COLOR_CAPABILITY_X_Y            (1 << 3)  // Bit 3: X/Y supported
-#define ZIGBEE_COLOR_CAPABILITY_COLOR_TEMP     (1 << 4)  // Bit 4: Color temperature supported
+static constexpr uint16_t ZIGBEE_COLOR_CAPABILITY_HUE_SATURATION = (1 << 0);  // Bit 0: Hue/saturation supported
+static constexpr uint16_t ZIGBEE_COLOR_CAPABILITY_ENHANCED_HUE = (1 << 1);   // Bit 1: Enhanced hue supported
+static constexpr uint16_t ZIGBEE_COLOR_CAPABILITY_COLOR_LOOP = (1 << 2);     // Bit 2: Color loop supported
+static constexpr uint16_t ZIGBEE_COLOR_CAPABILITY_X_Y = (1 << 3);            // Bit 3: X/Y supported
+static constexpr uint16_t ZIGBEE_COLOR_CAPABILITY_COLOR_TEMP = (1 << 4);     // Bit 4: Color temperature supported
 
 // Color mode enum values (matching ZCL spec)
 enum ZigbeeColorMode {
@@ -78,6 +78,14 @@ enum ZigbeeColorMode {
   ZIGBEE_COLOR_MODE_TEMPERATURE = 0x02,     // ColorTemperature
 };
 
+// Callback function type definitions for better readability and type safety
+// RGB callback: (state, red, green, blue, level)
+typedef void (*ZigbeeColorLightRgbCallback)(bool state, uint8_t red, uint8_t green, uint8_t blue, uint8_t level);
+// HSV callback: (state, hue, saturation, value) - value represents brightness (0-255)
+typedef void (*ZigbeeColorLightHsvCallback)(bool state, uint8_t hue, uint8_t saturation, uint8_t value);
+// Temperature callback: (state, level, color_temperature_in_mireds)
+typedef void (*ZigbeeColorLightTempCallback)(bool state, uint8_t level, uint16_t color_temperature);
+
 class ZigbeeColorDimmableLight : public ZigbeeEP {
 public:
   ZigbeeColorDimmableLight(uint8_t endpoint);
@@ -87,16 +95,16 @@ class ZigbeeColorDimmableLight : public ZigbeeEP {
   bool setLightColorCapabilities(uint16_t capabilities);
 
   [[deprecated("Use onLightChangeRgb() instead. This will be removed in a future major version.")]]
-  void onLightChange(void (*callback)(bool, uint8_t, uint8_t, uint8_t, uint8_t)) {
-    _on_light_change = callback;
+  void onLightChange(ZigbeeColorLightRgbCallback callback) {
+    _on_light_change_rgb = callback;
   }
-  void onLightChangeRgb(void (*callback)(bool, uint8_t, uint8_t, uint8_t, uint8_t)) {
+  void onLightChangeRgb(ZigbeeColorLightRgbCallback callback) {
     _on_light_change_rgb = callback;
   }
-  void onLightChangeHsv(void (*callback)(bool, uint8_t, uint8_t, uint8_t, uint8_t)) {
+  void onLightChangeHsv(ZigbeeColorLightHsvCallback callback) {
     _on_light_change_hsv = callback;
   }
-  void onLightChangeTemp(void (*callback)(bool, uint8_t, uint16_t)) {
+  void onLightChangeTemp(ZigbeeColorLightTempCallback callback) {
     _on_light_change_temp = callback;
   }
   void restoreLight() {
@@ -156,19 +164,17 @@ class ZigbeeColorDimmableLight : public ZigbeeEP {
   uint8_t getCurrentColorSaturation();
   uint16_t getCurrentColorTemperature();
 
-  void lightChanged();
   void lightChangedRgb();
   void lightChangedHsv();
   void lightChangedTemp();
   void lightChangedByMode();
-  //callback function to be called on light change (State, R, G, B, Level) - legacy
-  void (*_on_light_change)(bool, uint8_t, uint8_t, uint8_t, uint8_t);
+
   //callback function to be called on light change for RGB (State, R, G, B, Level)
-  void (*_on_light_change_rgb)(bool, uint8_t, uint8_t, uint8_t, uint8_t);
+  ZigbeeColorLightRgbCallback _on_light_change_rgb;
   //callback function to be called on light change for HSV (State, H, S, V, Level)
-  void (*_on_light_change_hsv)(bool, uint8_t, uint8_t, uint8_t, uint8_t);
+  ZigbeeColorLightHsvCallback _on_light_change_hsv;
   //callback function to be called on light change for TEMP (State, Level, Temperature)
-  void (*_on_light_change_temp)(bool, uint8_t, uint16_t);
+  ZigbeeColorLightTempCallback _on_light_change_temp;
 
   bool _current_state;
   uint8_t _current_level;