二十 Home Assistant 实体-灯

最新推荐文章于 2025-04-25 22:35:23 发布

道古云飞

最新推荐文章于 2025-04-25 22:35:23 发布

阅读量994

点赞数 22

分类专栏： Home Assistant 集成文章标签：服务器 linux python 智能家居

本文链接：https://blog.youkuaiyun.com/tre4321/article/details/144378781

版权

Home Assistant 集成专栏收录该内容

27 篇文章

订阅专栏

灯光实体

灯光实体用于控制光源的亮度、色调、饱和度、白色值、色温及效果等。从 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 属性中的已弃用标志来推断它：

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

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

如果 supported_color_modes 包括 ColorMode.RGBW 且 white_value 和 hs_color 都不为 None：ColorMode.RGBW。
否则，如果 supported_color_modes 包括 ColorMode.HS 且 hs_color 不为 None：ColorMode.HS。
否则，如果 supported_color_modes 包括 ColorMode.COLOR_TEMP 且 color_temp 不为 None：ColorMode.COLOR_TEMP。
否则，如果 supported_color_modes 包括 ColorMode.BRIGHTNESS 且 brightness 不为 None：ColorMode.BRIGHTNESS。
否则，如果 supported_color_modes 包括 ColorMode.ONOFF：ColorMode.ONOFF。
否则：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系统良好集成，满足用户对灯光控制多样化的需求。