Skip to main content

Light Entity

A light entity controls the brightness, hue and saturation color value, white value, color temperature and effects of a light source. Derive platform entities from homeassistant.components.light.LightEntity.

Properties

NameTypeDefaultDescription
brightnessint | NoneNoneThe brightness of this light between 1..255
color_modeColorMode | NoneNoneThe color mode of the light. The returned color mode must be present in the supported_color_modes property unless the light is rendering an effect.
color_temp_kelvinint | NoneNoneThe CT color value in K. This property will be copied to the light's state attribute when the light's color mode is set to ColorMode.COLOR_TEMP and ignored otherwise.
effectstr | NoneNoneThe current effect. Should be EFFECT_OFF if the light supports effects and no effect is currently rendered.
effect_listlist[str] | NoneNoneThe list of supported effects.
hs_colortuple[float, float] | NoneNoneThe hue and saturation color value (float, float). This property will be copied to the light's state attribute when the light's color mode is set to ColorMode.HS and ignored otherwise.
is_onbool | NoneNoneIf the light entity is on or not.
max_color_temp_kelvinint | NoneNoneThe coldest color_temp_kelvin that this light supports.
min_color_temp_kelvinint | NoneNoneThe warmest color_temp_kelvin that this light supports.
rgb_colortuple[int, int, int] | NoneNoneThe rgb color value (int, int, int). This property will be copied to the light's state attribute when the light's color mode is set to ColorMode.RGB and ignored otherwise.
rgbw_colortuple[int, int, int, int] | NoneNoneThe rgbw color value (int, int, int, int). This property will be copied to the light's state attribute when the light's color mode is set to ColorMode.RGBW and ignored otherwise.
rgbww_colortuple[int, int, int, int, int] | NoneNoneThe rgbww color value (int, int, int, int, int). This property will be copied to the light's state attribute when the light's color mode is set to ColorMode.RGBWW and ignored otherwise.
supported_color_modesset[ColorMode] | NoneNoneFlag supported color modes.
xy_colortuple[float, float] | NoneNoneThe xy color value (float, float). This property will be copied to the light's state attribute when the light's color mode is set to ColorMode.XY and ignored otherwise.

Color Modes

New integrations must implement both color_mode and supported_color_modes. If an integration is upgraded to support color mode, both color_mode and supported_color_modes should be implemented.

Supported color modes are defined by using values in the ColorMode enum.

If a light does not implement the supported_color_modes, the LightEntity will attempt deduce it based on deprecated flags in the supported_features property:

  • Start with an empty set
  • If SUPPORT_COLOR_TEMP is set, add ColorMode.COLOR_TEMP
  • If SUPPORT_COLOR is set, add ColorMode.HS
  • If SUPPORT_WHITE_VALUE is set, add ColorMode.RGBW
  • If SUPPORT_BRIGHTNESS is set and no color modes have yet been added, add ColorMode.BRIGHTNESS
  • If no color modes have yet been added, add ColorMode.ONOFF

If a light does not implement the color_mode, the LightEntity will attempt to deduce it based on which of the properties are set and which are None:

  • If supported_color_modes includes ColorMode.RGBW and white_value and hs_color are both not None: ColorMode.RGBW
  • Else if supported_color_modes includes ColorMode.HS and hs_color is not None: ColorMode.HS
  • Else if supported_color_modes includes ColorMode.COLOR_TEMP and color_temp is not None: ColorMode.COLOR_TEMP
  • Else if supported_color_modes includes ColorMode.BRIGHTNESS and brightness is not None: ColorMode.BRIGHTNESS
  • Else if supported_color_modes includes ColorMode.ONOFF: ColorMode.ONOFF
  • Else: ColorMode.UNKNOWN
ValueDescription
ColorMode.UNKNOWNThe light's color mode is not known.
ColorMode.ONOFFThe light can be turned on or off. This mode must be the only supported mode if supported by the light.
ColorMode.BRIGHTNESSThe light can be dimmed. This mode must be the only supported mode if supported by the light.
ColorMode.COLOR_TEMPThe light can be dimmed and its color temperature is present in the state.
ColorMode.HSThe light can be dimmed and its color can be adjusted. The light's brightness can be set using the brightness parameter and read through the brightness property. The light's color can be set using the hs_color parameter and read through the hs_color property. hs_color is an (h, s) tuple (no brightness).
ColorMode.RGBThe light can be dimmed and its color can be adjusted. The light's brightness can be set using the brightness parameter and read through the brightness property. The light's color can be set using the rgb_color parameter and read through the rgb_color property. rgb_color is an (r, g, b) tuple (not normalized for brightness).
ColorMode.RGBWThe light can be dimmed and its color can be adjusted. The light's brightness can be set using the brightness parameter and read through the brightness property. The light's color can be set using the rgbw_color parameter and read through the rgbw_color property. rgbw_color is an (r, g, b, w) tuple (not normalized for brightness).
ColorMode.RGBWWThe light can be dimmed and its color can be adjusted. The light's brightness can be set using the brightness parameter and read through the brightness property. The light's color can be set using the rgbww_color parameter and read through the rgbww_color property. rgbww_color is an (r, g, b, cw, ww) tuple (not normalized for brightness).
ColorMode.WHITEThe light can be dimmed and its color can be adjusted. In addition, the light can be set to white mode. The light's brightness can be set using the brightness parameter and read through the brightness property. The light can be set to white mode by using the white parameter with the desired brightness as value. Note that there's no white property. If both brighthness and white are present in a service call, the white parameter will be updated with the value of brightness. If this mode is supported, the light must also support at least one of ColorMode.HS, ColorMode.RGB, ColorMode.RGBW, ColorMode.RGBWW or ColorMode.XY and must not support ColorMode.COLOR_TEMP.
ColorMode.XYThe light can be dimmed and its color can be adjusted. The light's brightness can be set using the brightness parameter and read through the brightness property. The light's color can be set using the xy_color parameter and read through the xy_color property. xy_color is an (x, y) tuple.

Note that in color modes ColorMode.RGB, ColorMode.RGBW and ColorMode.RGBWW there is brightness information both in the light's brightness property and in the color. As an example, if the light's brightness is 128 and the light's color is (192, 64, 32), the overall brightness of the light is: 128/255 * max(192, 64, 32)/255 = 38%.

If the light is in mode ColorMode.HS, ColorMode.RGB or ColorMode.XY, the light's state attribute will contain the light's color expressed in hs, rgb and xy color format. Note that when the light is in mode ColorMode.RGB, the hs and xy state attributes only hold the chromaticity of the rgb color as the hs and xy pairs do not hold brightness information.

If the light is in mode ColorMode.RGBW or ColorMode.RGBWW, the light's state attribute will contain the light's color expressed in hs, rgb and xy color format. The color conversion is an approximation done by adding the white channels to the color.

White color modes

There are two white color modes, ColorMode.COLOR_TEMP and ColorMode.WHITE. The difference between the two modes is that ColorMode.WHITE does not allow adjusting the color temperature whereas ColorMode.COLOR_TEMP does allow adjusting the color temperature.

A lamp with adjustable color temperature is typically implemented by at least two banks of LEDs, with different color temperature, typically one bank of warm-white LEDs and one bank of cold-white LEDs. A light with non-adjustable color temperature typically only has a single bank of white LEDs.

Color Mode when rendering effects

When rendering an effect, the color_mode should be set according to the adjustments supported by the effect. If the effect does not support any adjustments, the color_mode should be set to ColorMode.ONOFF. If the effect allows adjusting the brightness, the color_mode should be set to ColorMode.BRIGHTNESS.

When rendering an effect, it's allowed to set the color_mode to a more restrictive mode than the color modes indicated by the supported_color_mode property:

  • A light which supports colors is allowed to set color_mode to ColorMode.ONOFF or ColorMode.BRIGHTNESS when controlled by an effect
  • A light which supports brightness is allowed to set color_mode to ColorMode.ONOFF when controlled by an effect

Supported Features

Supported features are defined by using values in the LightEntityFeature enum and are combined using the bitwise or (|) operator.

ValueDescription
EFFECTControls the effect a light source shows
FLASHControls the duration of a flash a light source shows
TRANSITIONControls the duration of transitions between color and effects

Methods

Turn on Light Device

class MyLightEntity(LightEntity):
def turn_on(self, **kwargs):
"""Turn the device on."""

async def async_turn_on(self, **kwargs):
"""Turn device on."""

Note that there's no color_mode passed to the async_turn_on method, instead only a single color attribute is allowed. It is guaranteed that the integration will only receive a single color attribute in a turn_oncall, which is guaranteed to be supported by the light according to the light's supported_color_modes property. To ensure this, colors in the service call will be translated before the entity's async_turn_on method is called if the light doesn't support the corresponding color mode:

Color typeTranslation
color_tempWill be removed from the service call if not supported and translated to hs_color, rgb_color, rgbw_color, rgbww_color or xy_color if supported by the light.
hs_colorWill be removed from the service call if not supported and translated to rgb_color, rgbw_color, rgbww_color or xy_color if supported by the light.
rgb_colorWill be removed from the service call if not supported and translated to rgbw_color, rgbww_color, hs_color or xy_color if supported by the light.
rgbw_colorWill be removed from the service call if not supported.
rgbww_colorWill be removed from the service call if not supported.
xy_colorWill be removed from the service call if not supported and translated to hs_color, rgb_color, rgbw_color or rgbww_color if supported by the light.
Scaling brightness

Home Assistant includes a utility to scale brightness.

If the light supports brightness, sometimes the brightness value needs scaling:

from homeassistant.util.color import value_to_brightness

BRIGHTNESS_SCALE = (1, 1023)

...

@property
def brightness(self) -> Optional[int]:
"""Return the current brightness."""
return value_to_brightness(BRIGHTNESS_SCALE, self._device.brightness)

To scale the brightness to the device range:

from homeassistant.util.percentage import percentage_to_ranged_value
BRIGHTNESS_SCALE = (1, 1023)

...

class MyLightEntity(LightEntity):
async def async_turn_on(self, **kwargs) -> None:
"""Turn device on."""

...

value_in_range = math.ceil(percentage_to_ranged_value(BRIGHTNESS_SCALE, kwargs[ATTR_BRIGHTNESS]))

Turn Off Light Device

class MyLightEntity(LightEntity):
def turn_off(self, **kwargs):
"""Turn the device off."""

async def async_turn_off(self, **kwargs):
"""Turn device off."""