二十 Home Assistant 实体-灯

灯光实体

灯光实体用于控制光源的亮度、色调、饱和度、白色值、色温及效果等。从 homeassistant.components.light.LightEntity 派生平台实体。

属性

名称	类型	默认值	描述
brightness	整数或 None	None	灯光亮度，取值范围在1到255之间。
color_mode	ColorMode 或 None	None	灯光颜色模式。除非灯光正在呈现效果，否则返回的颜色模式必须在 supported_color_modes 属性中存在。
color_temp_kelvin	整数或 None	None	以开尔文（K）为单位的色温颜色值。当灯光颜色模式设置为 ColorMode.COLOR_TEMP 时，此属性将复制到灯光的状态属性中，否则将被忽略。
effect	字符串或 None	None	当前效果。如果灯光支持效果且当前未呈现效果，则应为 EFFECT_OFF。
effect_list	字符串列表或 None	None	支持的效果列表。
hs_color	包含两个浮点数的元组或 None	None	色调和饱和度颜色值（浮点数，浮点数）。当灯光颜色模式设置为 ColorMode.HS 时，此属性将复制到灯光的状态属性中，否则将被忽略。
is_on	布尔值或 None	None	灯光实体是否打开。
max_color_temp_kelvin	整数或 None	None	此灯光支持的最冷色温（开尔文）。
min_color_temp_kelvin	整数或 None	None	此灯光支持的最暖色温（开尔文）。
rgb_color	包含三个整数的元组或 None	None	RGB颜色值（整数，整数，整数）。当灯光颜色模式设置为 ColorMode.RGB 时，此属性将复制到灯光的状态属性中，否则将被忽略。
rgbw_color	包含四个整数的元组或 None	None	RGBW颜色值（整数，整数，整数，整数）。当灯光颜色模式设置为 ColorMode.RGBW 时，此属性将复制到灯光的状态属性中，否则将被忽略。
rgbww_color	包含五个整数的元组或 None	None	RGBWW颜色值（整数，整数，整数，整数，整数）。当灯光颜色模式设置为 ColorMode.RGBWW 时，此属性将复制到灯光的状态属性中，否则将被忽略。
supported_color_modes	ColorMode 集合或 None	None	标志支持的颜色模式。
xy_color	包含两个浮点数的元组或 None	None	xy颜色值（浮点数，浮点数）。当灯光颜色模式设置为 ColorMode.XY 时，此属性将复制到灯光的状态属性中，否则将被忽略。

颜色模式

新集成必须实现 color_mode 和 supported_color_modes。如果一个集成升级以支持颜色模式，也应同时实现这两个属性。

支持的颜色模式通过使用 ColorMode 枚举中的值来定义。

如果灯光未实现 supported_color_modes，LightEntity 将尝试根据 supported_features 属性中的已弃用标志来推断它：

1. 从一个空集开始。
2. 如果设置了 SUPPORT_COLOR_TEMP，添加 ColorMode.COLOR_TEMP。
3. 如果设置了 SUPPORT_COLOR，添加 ColorMode.HS。
4. 如果设置了 SUPPORT_WHITE_VALUE，添加 ColorMode.RGBW。
5. 如果设置了 SUPPORT_BRIGHTNESS 且尚未添加任何颜色模式，添加 ColorMode.BRIGHTNESS。
6. 如果尚未添加任何颜色模式，添加 ColorMode.ONOFF。

如果灯光未实现 color_mode，LightEntity 将尝试根据设置了哪些属性以及哪些属性为 None 来推断它：

1. 如果 supported_color_modes 包括 ColorMode.RGBW 且 white_value 和 hs_color 都不为 None：ColorMode.RGBW。
2. 否则，如果 supported_color_modes 包括 ColorMode.HS 且 hs_color 不为 None：ColorMode.HS。
3. 否则，如果 supported_color_modes 包括 ColorMode.COLOR_TEMP 且 color_temp 不为 None：ColorMode.COLOR_TEMP。
4. 否则，如果 supported_color_modes 包括 ColorMode.BRIGHTNESS 且 brightness 不为 None：ColorMode.BRIGHTNESS。
5. 否则，如果 supported_color_modes 包括 ColorMode.ONOFF：ColorMode.ONOFF。
6. 否则：ColorMode.UNKNOWN。

值	描述
ColorMode.UNKNOWN	灯光颜色模式未知。
ColorMode.ONOFF	灯光可以打开或关闭。如果灯光支持此模式，此模式必须是唯一支持的模式。
ColorMode.BRIGHTNESS	灯光可以调光。如果灯光支持此模式，此模式必须是唯一支持的模式。
ColorMode.COLOR_TEMP	灯光可以调光且其色温在状态中存在。
ColorMode.HS	灯光可以调光且其颜色可以调整。灯光亮度可以使用 brightness 参数设置并通过 brightness 属性读取。灯光颜色可以使用 hs_color 参数设置并通过 hs_color 属性读取。hs_color 是一个（色调，饱和度）元组（不含亮度）。
ColorMode.RGB	灯光可以调光且其颜色可以调整。灯光亮度可以使用 brightness 参数设置并通过 brightness 属性读取。灯光颜色可以使用 rgb_color 参数设置并通过 rgb_color 属性读取。rgb_color 是一个（红，绿，蓝）元组（未针对亮度进行归一化）。
ColorMode.RGBW	灯光可以调光且其颜色可以调整。灯光亮度可以使用 brightness 参数设置并通过 brightness 属性读取。灯光颜色可以使用 rgbw_color 参数设置并通过 rgbw_color 属性读取。rgbw_color 是一个（红，绿，蓝，白）元组（未针对亮度进行归一化）。
ColorMode.RGBWW	灯光可以调光且其颜色可以调整。灯光亮度可以使用 brightness 参数设置并通过 brightness 属性读取。灯光颜色可以使用 rgbww_color 参数设置并通过 rgbww_color 属性读取。rgbww_color 是一个（红，绿，蓝，冷白，暖白）元组（未针对亮度进行归一化）。
ColorMode.WHITE	灯光可以调光且其颜色可以调整。此外，灯光可以设置为白色模式。灯光亮度可以使用 brightness 参数设置并通过 brightness 属性读取。可以使用 white 参数并将所需亮度作为值将灯光设置为白色模式。请注意，没有 white 属性。如果在服务调用中同时存在 brightness 和 white，white 参数将使用 brightness 的值进行更新。如果支持此模式，灯光还必须至少支持 ColorMode.HS、ColorMode.RGB、ColorMode.RGBW、ColorMode.RGBWW 或 ColorMode.XY 中的一种。
ColorMode.XY	灯光可以调光且其颜色可以调整。灯光亮度可以使用 brightness 参数设置并通过 brightness 属性读取。灯光颜色可以使用 xy_color 参数设置并通过 xy_color 属性读取。xy_color 是一个（x，y）元组。

注意，在颜色模式 ColorMode.RGB、ColorMode.RGBW 和 ColorMode.RGBWW 中，灯光的亮度信息既存在于 brightness 属性中，也存在于颜色中。例如，如果灯光亮度为128，灯光颜色为（192，64，32），灯光的整体亮度为：128/255 * max(192, 64, 32)/255 = 38%。

如果灯光处于 ColorMode.HS、ColorMode.RGB 或 ColorMode.XY 模式，灯光的状态属性将包含以 hs、rgb 和 xy 颜色格式表示的灯光颜色。请注意，当灯光处于 ColorMode.RGB 模式时，hs 和 xy 状态属性仅保存 rgb 颜色的色度，因为 hs 和 xy 对不包含亮度信息。

如果灯光处于 ColorMode.RGBW 或 ColorMode.RGBWW 模式，灯光的状态属性将包含以 hs、rgb 和 xy 颜色格式表示的灯光颜色。颜色转换是通过将白色通道添加到颜色中来近似完成的。

呈现效果时的颜色模式

当呈现效果时，color_mode 应根据效果支持的调整来设置。如果效果不支持任何调整，color_mode 应设置为 ColorMode.ONOFF。如果效果允许调整亮度，color_mode 应设置为 ColorMode.BRIGHTNESS。

当呈现效果时，允许将 color_mode 设置为比 supported_color_mode 属性指示的颜色模式更受限的模式：

• 支持颜色的灯光在由效果控制时，允许将 color_mode 设置为 ColorMode.ONOFF 或 ColorMode.BRIGHTNESS。
• 支持亮度的灯光在由效果控制时，允许将 color_mode 设置为 ColorMode.ONOFF。

支持的功能

支持的功能通过使用 LightEntityFeature 枚举中的值来定义，并使用按位或（|）运算符组合。

值	描述
EFFECT	控制光源显示的效果。
FLASH	控制光源闪烁的持续时间。
TRANSITION	控制颜色和效果之间转换的持续时间。

方法

打开灯光设备

class MyLightEntity(LightEntity):
    def turn_on(self, **kwargs):
        """打开设备。"""
    async def async_turn_on(self, **kwargs):
        """打开设备。"""

注意，async_turn_on 方法没有传递 color_mode，而是只允许一个单一的颜色属性。可以保证集成在 turn_on 调用中只会收到一个单一的颜色属性，并且根据灯光的 supported_color_modes 属性，该颜色属性是灯光支持的。为确保这一点，如果灯光不支持相应的颜色模式，在调用实体的 async_turn_on 方法之前，服务调用中的颜色将被转换：

颜色类型	转换规则
color_temp	如果不支持，将从服务调用中删除；如果支持，将转换为 hs_color、rgb_color、rgbw_color、rgbww_color 或 xy_color。
hs_color	如果不支持，将从服务调用中删除；如果支持，将转换为 rgb_color、rgbw_color、rgbww_color 或 xy_color。
rgb_color	如果不支持，将从服务调用中删除；如果支持，将转换为 rgbw_color、rgbww_color、hs_color 或 xy_color。
rgbw_color	如果不支持，将从服务调用中删除。
rgbww_color	如果不支持，将从服务调用中删除。
xy_color	如果不支持，将从服务调用中删除；如果支持，将转换为 hs_color、rgb_color、rgbw_color 或 rgbww_color。

关闭灯光设备

class MyLightEntity(LightEntity):
    def turn_off(self, **kwargs):
        """关闭设备。"""
    async def async_turn_off(self, **kwargs):
        """关闭设备。"""

总结

文档主要介绍了Home Assistant中的灯光实体相关内容。包括灯光实体的功能（控制光源多方面属性）及派生方式，详细阐述了其众多属性（如亮度、颜色模式等各类属性的定义、默认值、作用及相互关系），深入解释了颜色模式（包括其实现要求、支持模式的定义与推断规则、不同模式下的特点及呈现效果时的模式设置），说明了支持的功能（通过特定枚举值及运算符定义），并提供了打开和关闭灯光设备的方法以及在方法调用中颜色属性转换的相关规则，为开发者在实现灯光控制相关功能时提供了全面、细致且系统的指导，有助于开发者准确地创建和操作灯光实体，使其能与Home Assistant系统良好集成，满足用户对灯光控制多样化的需求。