From d60130cc38ad5a3f1f85e4e25737131e0fa965c3 Mon Sep 17 00:00:00 2001 From: epenet <6771947+epenet@users.noreply.github.com> Date: Mon, 16 Dec 2024 19:06:08 +0100 Subject: [PATCH] Blog post about Kelvin as the preferred color temperature unit (#2495) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: AbĂ­lio Costa --- ...kelvin-preferred-color-temperature-unit.md | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 blog/2024-12-14-kelvin-preferred-color-temperature-unit.md diff --git a/blog/2024-12-14-kelvin-preferred-color-temperature-unit.md b/blog/2024-12-14-kelvin-preferred-color-temperature-unit.md new file mode 100644 index 00000000..98911360 --- /dev/null +++ b/blog/2024-12-14-kelvin-preferred-color-temperature-unit.md @@ -0,0 +1,105 @@ +--- +author: epenet +authorURL: https://github.com/epenet +title: "Use Kelvin as the preferred color temperature unit" +--- + +### Summary of changes + +In October 2022, Home Assistant migrated the preferred color temperature unit from mired to kelvin. + +It is now time to add deprecation warnings for the corresponding attributes, constants and properties: +* Deprecate state and capability attributes `ATTR_COLOR_TEMP`, `ATTR_MIN_MIREDS` and `ATTR_MAX_MIREDS` +* Deprecate constants `ATTR_KELVIN` and `ATTR_COLOR_TEMP` from the `light.turn_on` service call +* Deprecate properties `LightEntity.color_temp`, `LightEntity.min_mireds` and `LightEntity.max_mireds` +* Deprecate corresponding attributes `LightEntity._attr_color_temp`, `LightEntity._attr_min_mired` and `LightEntity._attr_max_mired` + +### Examples + +#### Custom minimum/maximum color temperature + +```python +class MyLight(LightEntity): + """Representation of a light.""" + + # Old + # _attr_min_mireds = 200 # 5000K + # _attr_max_mireds = 400 # 2500K + + # New + _attr_min_color_temp_kelvin = 2500 # 400 mireds + _attr_max_color_temp_kelvin = 5000 # 200 mireds +``` + +#### Default minimum/maximum color temperature + +```python +from homeassistant.components.light import DEFAULT_MAX_KELVIN, DEFAULT_MIN_KELVIN + +class MyLight(LightEntity): + """Representation of a light.""" + + # Old did not need to have _attr_min_mireds / _attr_max_mireds set + # New needs to set the default explicitly + _attr_min_color_temp_kelvin = DEFAULT_MIN_KELVIN + _attr_max_color_temp_kelvin = DEFAULT_MAX_KELVIN +``` + +#### Dynamic minimum/maximum color temperature + +```python +from homeassistant.util import color as color_util + +class MyLight(LightEntity): + """Representation of a light.""" + + # Old + # def min_mireds(self) -> int: + # """Return the coldest color_temp that this light supports.""" + # return device.coldest_temperature + # + # def max_mireds(self) -> int: + # """Return the warmest color_temp that this light supports.""" + # return device.warmest_temperature + + # New + def min_color_temp_kelvin(self) -> int: + """Return the warmest color_temp that this light supports.""" + return color_util.color_temperature_mired_to_kelvin(device.warmest_temperature) + + def max_color_temp_kelvin(self) -> int: + """Return the coldest color_temp that this light supports.""" + return color_util.color_temperature_mired_to_kelvin(device.coldest_temperature) +``` + +#### Service call + +```python +from homeassistant.components.light import ATTR_COLOR_TEMP_KELVIN +from homeassistant.util import color as color_util + +class MyLight(LightEntity): + """Representation of a light.""" + def turn_on(self, **kwargs: Any) -> None: + """Turn on the light.""" + # Old + # if ATTR_COLOR_TEMP in kwargs: + # color_temp_mired = kwargs[ATTR_COLOR_TEMP] + # color_temp_kelvin = color_util.color_temperature_mired_to_kelvin(color_temp_mired) + + # Old + # if ATTR_KELVIN in kwargs: + # color_temp_kelvin = kwargs[ATTR_KELVIN] + # color_temp_mired = color_util.color_temperature_kelvin_to_mired(color_temp_kelvin) + + # New + if ATTR_COLOR_TEMP_KELVIN in kwargs: + color_temp_kelvin = kwargs[ATTR_COLOR_TEMP_KELVIN] + color_temp_mired = color_util.color_temperature_kelvin_to_mired(color_temp_kelvin) +``` + +### Background information + +* [Community discussion about Kelvin temperature](https://community.home-assistant.io/t/wth-is-light-temperature-not-in-kelvin/467449/6) +* [Core PR #79591: Migration to Kelvin](https://github.com/home-assistant/core/pull/79591) +* [Architecture discussion #564](https://github.com/home-assistant/architecture/discussions/564)