ESPHome implement light color modes (#53854)

homeassistant/components/esphome/light.py

@@ -1,35 +1,45 @@
 """Support for ESPHome lights."""
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
-from aioesphomeapi import LightInfo, LightState
+from aioesphomeapi import APIVersion, LightColorMode, LightInfo, LightState
 
 from homeassistant.components.light import (
     ATTR_BRIGHTNESS,
     ATTR_COLOR_TEMP,
     ATTR_EFFECT,
     ATTR_FLASH,
-    ATTR_HS_COLOR,
+    ATTR_RGB_COLOR,
+    ATTR_RGBW_COLOR,
+    ATTR_RGBWW_COLOR,
     ATTR_TRANSITION,
-    ATTR_WHITE_VALUE,
+    ATTR_WHITE,
+    COLOR_MODE_BRIGHTNESS,
+    COLOR_MODE_COLOR_TEMP,
+    COLOR_MODE_ONOFF,
+    COLOR_MODE_RGB,
+    COLOR_MODE_RGBW,
+    COLOR_MODE_RGBWW,
+    COLOR_MODE_UNKNOWN,
+    COLOR_MODE_WHITE,
     FLASH_LONG,
     FLASH_SHORT,
-    SUPPORT_BRIGHTNESS,
-    SUPPORT_COLOR,
-    SUPPORT_COLOR_TEMP,
     SUPPORT_EFFECT,
     SUPPORT_FLASH,
     SUPPORT_TRANSITION,
-    SUPPORT_WHITE_VALUE,
     LightEntity,
 )
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
-import homeassistant.util.color as color_util
 
-from . import EsphomeEntity, esphome_state_property, platform_async_setup_entry
+from . import (
+    EsphomeEntity,
+    EsphomeEnumMapper,
+    esphome_state_property,
+    platform_async_setup_entry,
+)
 
 FLASH_LENGTHS = {FLASH_SHORT: 2, FLASH_LONG: 10}
 
@@ -49,6 +59,22 @@ async def async_setup_entry(
     )
 
 
+_COLOR_MODES: EsphomeEnumMapper[LightColorMode, str] = EsphomeEnumMapper(
+    {
+        LightColorMode.UNKNOWN: COLOR_MODE_UNKNOWN,
+        LightColorMode.ON_OFF: COLOR_MODE_ONOFF,
+        LightColorMode.BRIGHTNESS: COLOR_MODE_BRIGHTNESS,
+        LightColorMode.WHITE: COLOR_MODE_WHITE,
+        LightColorMode.COLOR_TEMPERATURE: COLOR_MODE_COLOR_TEMP,
+        LightColorMode.COLD_WARM_WHITE: COLOR_MODE_COLOR_TEMP,
+        LightColorMode.RGB: COLOR_MODE_RGB,
+        LightColorMode.RGB_WHITE: COLOR_MODE_RGBW,
+        LightColorMode.RGB_COLOR_TEMPERATURE: COLOR_MODE_RGBWW,
+        LightColorMode.RGB_COLD_WARM_WHITE: COLOR_MODE_RGBWW,
+    }
+)
+
+
 # https://github.com/PyCQA/pylint/issues/3150 for all @esphome_state_property
 # pylint: disable=invalid-overridden-method
 
@@ -56,6 +82,11 @@ async def async_setup_entry(
 class EsphomeLight(EsphomeEntity[LightInfo, LightState], LightEntity):
     """A light implementation for ESPHome."""
 
+    @property
+    def _supports_color_mode(self) -> bool:
+        """Return whether the client supports the new color mode system natively."""
+        return self._api_version >= APIVersion(1, 6)
+
     @esphome_state_property
     def is_on(self) -> bool | None:  # type: ignore[override]
         """Return true if the light is on."""
@@ -64,22 +95,80 @@ class EsphomeLight(EsphomeEntity[LightInfo, LightState], LightEntity):
     async def async_turn_on(self, **kwargs: Any) -> None:
         """Turn the entity on."""
         data: dict[str, Any] = {"key": self._static_info.key, "state": True}
-        if ATTR_HS_COLOR in kwargs:
+        # rgb/brightness input is in range 0-255, but esphome uses 0-1
-            hue, sat = kwargs[ATTR_HS_COLOR]
+
-            red, green, blue = color_util.color_hsv_to_RGB(hue, sat, 100)
+        if (brightness_ha := kwargs.get(ATTR_BRIGHTNESS)) is not None:
-            data["rgb"] = (red / 255, green / 255, blue / 255)
+            data["brightness"] = brightness_ha / 255
-        if ATTR_FLASH in kwargs:
+
-            data["flash_length"] = FLASH_LENGTHS[kwargs[ATTR_FLASH]]
+        if (rgb_ha := kwargs.get(ATTR_RGB_COLOR)) is not None:
-        if ATTR_TRANSITION in kwargs:
+            rgb = tuple(x / 255 for x in rgb_ha)
-            data["transition_length"] = kwargs[ATTR_TRANSITION]
+            color_bri = max(rgb)
-        if ATTR_BRIGHTNESS in kwargs:
+            # normalize rgb
-            data["brightness"] = kwargs[ATTR_BRIGHTNESS] / 255
+            data["rgb"] = tuple(x / (color_bri or 1) for x in rgb)
-        if ATTR_COLOR_TEMP in kwargs:
+            if self._supports_color_mode:
-            data["color_temperature"] = kwargs[ATTR_COLOR_TEMP]
+                data["color_brightness"] = color_bri
-        if ATTR_EFFECT in kwargs:
+                data["color_mode"] = LightColorMode.RGB
-            data["effect"] = kwargs[ATTR_EFFECT]
+
-        if ATTR_WHITE_VALUE in kwargs:
+        if (rgbw_ha := kwargs.get(ATTR_RGBW_COLOR)) is not None:
-            data["white"] = kwargs[ATTR_WHITE_VALUE] / 255
+            # pylint: disable=invalid-name
+            *rgb, w = tuple(x / 255 for x in rgbw_ha)  # type: ignore[assignment]
+            color_bri = max(rgb)
+            # normalize rgb
+            data["rgb"] = tuple(x / (color_bri or 1) for x in rgb)
+            data["white"] = w
+            if self._supports_color_mode:
+                data["color_brightness"] = color_bri
+                data["color_mode"] = LightColorMode.RGB_WHITE
+
+        if (rgbww_ha := kwargs.get(ATTR_RGBWW_COLOR)) is not None:
+            # pylint: disable=invalid-name
+            *rgb, cw, ww = tuple(x / 255 for x in rgbww_ha)  # type: ignore[assignment]
+            color_bri = max(rgb)
+            # normalize rgb
+            data["rgb"] = tuple(x / (color_bri or 1) for x in rgb)
+            modes = self._native_supported_color_modes
+            if (
+                self._supports_color_mode
+                and LightColorMode.RGB_COLD_WARM_WHITE in modes
+            ):
+                data["cold_white"] = cw
+                data["warm_white"] = ww
+                target_mode = LightColorMode.RGB_COLD_WARM_WHITE
+            else:
+                # need to convert cw+ww part to white+color_temp
+                white = data["white"] = max(cw, ww)
+                if white != 0:
+                    min_ct = self.min_mireds
+                    max_ct = self.max_mireds
+                    ct_ratio = ww / (cw + ww)
+                    data["color_temperature"] = min_ct + ct_ratio * (max_ct - min_ct)
+                target_mode = LightColorMode.RGB_COLOR_TEMPERATURE
+
+            if self._supports_color_mode:
+                data["color_brightness"] = color_bri
+                data["color_mode"] = target_mode
+
+        if (flash := kwargs.get(ATTR_FLASH)) is not None:
+            data["flash_length"] = FLASH_LENGTHS[flash]
+
+        if (transition := kwargs.get(ATTR_TRANSITION)) is not None:
+            data["transition_length"] = transition
+
+        if (color_temp := kwargs.get(ATTR_COLOR_TEMP)) is not None:
+            data["color_temperature"] = color_temp
+            if self._supports_color_mode:
+                data["color_mode"] = LightColorMode.COLOR_TEMPERATURE
+
+        if (effect := kwargs.get(ATTR_EFFECT)) is not None:
+            data["effect"] = effect
+
+        if (white_ha := kwargs.get(ATTR_WHITE)) is not None:
+            # ESPHome multiplies brightness and white together for final brightness
+            # HA only sends `white` in turn_on, and reads total brightness through brightness property
+            data["brightness"] = white_ha / 255
+            data["white"] = 1.0
+            data["color_mode"] = LightColorMode.WHITE
+
         await self._client.light_command(**data)
 
     async def async_turn_off(self, **kwargs: Any) -> None:
@@ -97,10 +186,65 @@ class EsphomeLight(EsphomeEntity[LightInfo, LightState], LightEntity):
         return round(self._state.brightness * 255)
 
     @esphome_state_property
-    def hs_color(self) -> tuple[float, float] | None:
+    def color_mode(self) -> str | None:
-        """Return the hue and saturation color value [float, float]."""
+        """Return the color mode of the light."""
-        return color_util.color_RGB_to_hs(
+        if not self._supports_color_mode:
-            self._state.red * 255, self._state.green * 255, self._state.blue * 255
+            supported = self.supported_color_modes
+            if not supported:
+                return None
+            return next(iter(supported))
+
+        return _COLOR_MODES.from_esphome(self._state.color_mode)
+
+    @esphome_state_property
+    def rgb_color(self) -> tuple[int, int, int] | None:
+        """Return the rgb color value [int, int, int]."""
+        if not self._supports_color_mode:
+            return (
+                round(self._state.red * 255),
+                round(self._state.green * 255),
+                round(self._state.blue * 255),
+            )
+
+        return (
+            round(self._state.red * self._state.color_brightness * 255),
+            round(self._state.green * self._state.color_brightness * 255),
+            round(self._state.blue * self._state.color_brightness * 255),
+        )
+
+    @esphome_state_property
+    def rgbw_color(self) -> tuple[int, int, int, int] | None:
+        """Return the rgbw color value [int, int, int, int]."""
+        white = round(self._state.white * 255)
+        rgb = cast("tuple[int, int, int]", self.rgb_color)
+        return (*rgb, white)
+
+    @esphome_state_property
+    def rgbww_color(self) -> tuple[int, int, int, int, int] | None:
+        """Return the rgbww color value [int, int, int, int, int]."""
+        rgb = cast("tuple[int, int, int]", self.rgb_color)
+        if (
+            not self._supports_color_mode
+            or self._state.color_mode != LightColorMode.RGB_COLD_WARM_WHITE
+        ):
+            # Try to reverse white + color temp to cwww
+            min_ct = self._static_info.min_mireds
+            max_ct = self._static_info.max_mireds
+            color_temp = self._state.color_temperature
+            white = self._state.white
+
+            ww_frac = (color_temp - min_ct) / (max_ct - min_ct)
+            cw_frac = 1 - ww_frac
+
+            return (
+                *rgb,
+                round(white * cw_frac / max(cw_frac, ww_frac) * 255),
+                round(white * ww_frac / max(cw_frac, ww_frac) * 255),
+            )
+        return (
+            *rgb,
+            round(self._state.cold_white * 255),
+            round(self._state.warm_white * 255),
         )
 
     @esphome_state_property
@@ -108,33 +252,33 @@ class EsphomeLight(EsphomeEntity[LightInfo, LightState], LightEntity):
         """Return the CT color value in mireds."""
         return self._state.color_temperature
 
-    @esphome_state_property
-    def white_value(self) -> int | None:
-        """Return the white value of this light between 0..255."""
-        return round(self._state.white * 255)
-
     @esphome_state_property
     def effect(self) -> str | None:
         """Return the current effect."""
         return self._state.effect
 
+    @property
+    def _native_supported_color_modes(self) -> list[LightColorMode]:
+        return self._static_info.supported_color_modes_compat(self._api_version)
+
     @property
     def supported_features(self) -> int:
         """Flag supported features."""
         flags = SUPPORT_FLASH
-        if self._static_info.supports_brightness:
+
-            flags |= SUPPORT_BRIGHTNESS
+        # All color modes except UNKNOWN,ON_OFF support transition
+        modes = self._native_supported_color_modes
+        if any(m not in (LightColorMode.UNKNOWN, LightColorMode.ON_OFF) for m in modes):
             flags |= SUPPORT_TRANSITION
-        if self._static_info.supports_rgb:
-            flags |= SUPPORT_COLOR
-        if self._static_info.supports_white_value:
-            flags |= SUPPORT_WHITE_VALUE
-        if self._static_info.supports_color_temperature:
-            flags |= SUPPORT_COLOR_TEMP
         if self._static_info.effects:
             flags |= SUPPORT_EFFECT
         return flags
 
+    @property
+    def supported_color_modes(self) -> set[str] | None:
+        """Flag supported color modes."""
+        return set(map(_COLOR_MODES.from_esphome, self._native_supported_color_modes))
+
     @property
     def effect_list(self) -> list[str]:
         """Return the list of supported effects."""

homeassistant/components/esphome/manifest.json

@@ -3,7 +3,7 @@
   "name": "ESPHome",
   "config_flow": true,
   "documentation": "https://www.home-assistant.io/integrations/esphome",
-  "requirements": ["aioesphomeapi==5.1.1"],
+  "requirements": ["aioesphomeapi==6.0.0"],
   "zeroconf": ["_esphomelib._tcp.local."],
   "codeowners": ["@OttoWinter", "@jesserockz"],
   "after_dependencies": ["zeroconf", "tag"],

requirements_all.txt

@@ -164,7 +164,7 @@ aioeafm==0.1.2
 aioemonitor==1.0.5
 
 # homeassistant.components.esphome
-aioesphomeapi==5.1.1
+aioesphomeapi==6.0.0
 
 # homeassistant.components.flo
 aioflo==0.4.1

requirements_test_all.txt

@@ -103,7 +103,7 @@ aioeafm==0.1.2
 aioemonitor==1.0.5
 
 # homeassistant.components.esphome
-aioesphomeapi==5.1.1
+aioesphomeapi==6.0.0
 
 # homeassistant.components.flo
 aioflo==0.4.1