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
brightnessintNoneReturn the brightness of this light between 0..255
color_modestringNoneReturn the color mode of the light. The returned color mode must be present in the supported_color_modes property.
color_tempintNoneReturn the CT color value in mireds. 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.
effectStringNoneReturn the current effect.
effect_listlistNoneReturn the list of supported effects.
hs_colortupleNoneReturn the 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_onboolNoneReturns if the light entity is on or not.
max_miredsintintReturn the warmest color_temp that this light supports.
min_miredsintintReturn the coldest color_temp that this light supports.
rgb_colortupleNoneReturn the 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_colortupleNoneReturn the 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_colortupleNoneReturn the 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_modessetNoneFlag supported color modes.
supported_featuresintintFlag supported features.
white_valueintNoneReturn the white value of this light between 0..255. This is deprecated and will be removed in Home Assistant 2021.10.
xy_colortupleNoneReturn the 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_mode includes ColorMode.RGBW and white_value and hs_color are both not None: ColorMode.RGBW
  • Else if supported_color_mode includes ColorMode.HS and hs_color is not None: ColorMode.HS
  • Else if supported_color_mode includes ColorMode.COLOR_TEMP and color_temp is not None: ColorMode.COLOR_TEMP
  • Else if supported_color_mode includes ColorMode.BRIGHTNESS and brightness is not None: ColorMode.BRIGHTNESS
  • Else if supported_color_mode 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.
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.

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.

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."""