二十七 Home Assistant 实体-气候(温度控制)

气候实体（Climate Entity）

气候实体用于控制温度、湿度或风扇，例如空调系统和加湿器等设备。需从 homeassistant.components.climate.ClimateEntity 派生一个平台实体。

属性

提示：属性应始终仅从内存返回信息，而不应进行 I/O 操作（如网络请求）。应实现 update() 或 async_update() 方法来获取数据。

名称	类型	默认值	描述
current_humidity	int 或 None	None	当前湿度。
current_temperature	float 或 None	None	当前温度。
fan_mode	str 或 None	由 SUPPORT_FAN_MODE 要求	当前风扇模式。
fan_modes	list[str] 或 None	由 SUPPORT_FAN_MODE 要求	可用风扇模式列表。
hvac_action	HVACAction 或 None	None	当前 HVAC 动作（制热、制冷等）
hvac_mode	HVACMode 或 None	必需	当前操作模式（例如制热、制冷、空闲）。用于确定设备状态。
hvac_modes	list[HVACMode]	必需	可用操作模式列表。见下文。
is_aux_heat	int 或 None	由 SUPPORT_AUX_HEAT 要求	辅助加热器开启时为 True。
max_humidity	int	DEFAULT_MAX_HUMIDITY（值为 99）	最大湿度。
max_temp	float	DEFAULT_MAX_TEMP（值为 35°C）	以 temperature_unit 为单位的最大温度。
min_humidity	int	DEFAULT_MIN_HUMIDITY（值为 30）	最小湿度。
min_temp	float	DEFAULT_MIN_TEMP（值为 7°C）	以 temperature_unit 为单位的最小温度。
precision	float	根据 temperature_unit 而定	系统中温度的精度。对于 TEMP_CELSIUS，默认为十分之一；否则为整数。
preset_mode	str 或 None	由 SUPPORT_PRESET_MODE 要求	当前激活的预设模式。
preset_modes	list[str] 或 None	由 SUPPORT_PRESET_MODE 要求	可用预设模式。
swing_mode	str 或 None	由 SUPPORT_SWING_MODE 要求	摆风设置。
swing_modes	list[str] 或 None	由 SUPPORT_SWING_MODE 要求	返回可用摆风模式列表。
target_humidity	int 或 None	None	设备试图达到的目标湿度。
target_temperature	float 或 None	None	当前设定要达到的温度。
target_temperature_high	float 或 None	由 TARGET_TEMPERATURE_RANGE 要求	目标温度上限。
target_temperature_low	float 或 None	由 TARGET_TEMPERATURE_RANGE 要求	目标温度下限。
target_temperature_step	float 或 None	None	目标温度可增减的支持步长。
temperature_unit	str	必需	系统的温度测量单位（TEMP_CELSIUS 或 TEMP_FAHRENHEIT）。

HVAC 模式

只能使用由 HVACMode 枚举提供的内置 HVAC 模式。如果需要其他模式，请改为添加预设。

名称	描述
HVACMode.OFF	设备关闭。
HVACMode.HEAT	设备设置为加热到目标温度。
HVACMode.COOL	设备设置为冷却到目标温度。
HVACMode.HEAT_COOL	设备设置为加热/冷却到目标温度范围。
HVACMode.AUTO	设备设置为按照时间表、学习行为或人工智能运行。
HVACMode.DRY	设备设置为干燥/湿度模式。
HVACMode.FAN_ONLY	设备仅开启风扇。不进行加热或冷却。

HVAC 动作

HVAC 动作描述当前设备的动作。这与模式不同，因为如果设备设置为加热且已达到目标温度，设备将不再主动加热。只能使用由 HVACAction 枚举提供的内置 HVAC 动作。

名称	描述
HVACAction.OFF	设备关闭。
HVACAction.PREHEATING	设备正在预热。
HVACAction.HEATING	设备正在加热。
HVACAction.COOLING	设备正在冷却。
HVACAction.DRYING	设备正在干燥。
HVACAction.FAN	设备风扇开启。
HVACAction.IDLE	设备空闲。

预设模式

设备可以有不同的预设模式展示给用户。常见的预设模式有 “Away”（外出）或 “Eco”（节能）。有一些内置预设模式提供翻译，但也允许添加自定义预设模式。

名称	描述
NONE	无预设模式激活。
ECO	设备处于节能模式。
AWAY	设备处于外出模式。
BOOST	设备将所有阀门开到最大。
COMFORT	设备处于舒适模式。
HOME	设备处于在家模式。
SLEEP	设备为睡眠做好准备。
ACTIVITY	设备对活动（例如移动传感器）做出反应。

风扇模式

设备的风扇可以有不同的状态。有一些内置风扇模式，但也允许使用自定义风扇模式。

名称
FAN_ON	风扇开启。
FAN_OFF	风扇关闭。
FAN_AUTO	风扇自动。
FAN_LOW	风扇低速。
FAN_MEDIUM	风扇中速。
FAN_HIGH	风扇高速。
FAN_MIDDLE	风扇中速（另一种表示）。
FAN_FOCUS	风扇聚焦。
FAN_DIFFUSE	风扇扩散。

摆风模式

设备风扇可以有不同的摆风模式供用户了解和控制。

名称	描述
SWING_OFF	风扇不摆风。
SWING_ON	风扇摆风。
SWING_VERTICAL	风扇垂直摆风。
SWING_HORIZONTAL	风扇水平摆风。
SWING_BOTH	风扇水平和垂直都摆风。

支持的功能

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

值	描述
TARGET_TEMPERATURE	设备支持目标温度。
TARGET_TEMPERATURE_RANGE	设备支持目标温度范围。用于 HVAC 模式 heat_cool 和 auto。
TARGET_HUMIDITY	设备支持目标湿度。
FAN_MODE	设备支持风扇模式。
PRESET_MODE	设备支持预设模式。
SWING_MODE	设备支持摆风模式。
AUX_HEAT	设备支持辅助加热器。
TURN_ON	设备支持开启。
TURN_OFF	设备支持关闭。

方法

设置 HVAC 模式

class MyClimateEntity(ClimateEntity):
    # 实现以下方法之一
    def set_hvac_mode(self, hvac_mode):
        """设置新的目标 HVAC 模式。"""

    async def async_set_hvac_mode(self, hvac_mode):
        """设置新的目标 HVAC 模式。"""

设置预设模式

class MyClimateEntity(ClimateEntity):
    # 实现以下方法之一
    def set_preset_mode(self, preset_mode):
        """设置新的目标预设模式。"""

    async def async_set_preset_mode(self, preset_mode):
        """设置新的目标预设模式。"""

设置风扇模式

class MyClimateEntity(ClimateEntity):
    # 实现以下方法之一
    def set_fan_mode(self, fan_mode):
        """设置新的目标风扇模式。"""

    async def async_set_fan_mode(self, fan_mode):
        """设置新的目标风扇模式。"""

设置湿度

class MyClimateEntity(ClimateEntity):
    # 实现以下方法之一
    def set_humidity(self, humidity):
        """设置新的目标湿度。"""

    async def async_set_humidity(self, humidity):
        """设置新的目标湿度。"""

设置摆风模式

class MyClimateEntity(ClimateEntity):
    # 实现以下方法之一
    def set_swing_mode(self, swing_mode):
        """设置新的目标摆风操作。"""

    async def async_set_swing_mode(self, swing_mode):
        """设置新的目标摆风操作。"""

设置温度

class MyClimateEntity(ClimateEntity):
    # 实现以下方法之一
    def set_temperature(self, **kwargs):
        """设置新的目标温度。"""

    async def async_set_temperature(self, **kwargs):
        """设置新的目标温度。"""

控制辅助加热器

class MyClimateEntity(ClimateEntity):
    # 实现以下方法之一
    def turn_aux_heat_on(self):
        """打开辅助加热器。"""

    async def async_turn_aux_heat_on(self):
        """打开辅助加热器。"""

    # 实现以下方法之一
    def turn_aux_heat_off(self):
        """关闭辅助加热器。"""

    async def async_turn_aux_heat_off(self):
        """关闭辅助加热器。"""

总结

本文档介绍了 Home Assistant 中的气候实体（Climate Entity）相关内容。气候实体用于控制如空调、加湿器等设备的温度、湿度和风扇等功能。它具有一系列属性，包括当前湿度、温度、风扇模式、HVAC 动作和模式、预设模式、摆风模式、目标湿度和温度等，这些属性都有其特定的数据类型和默认值或要求，且属性获取数据应通过特定的 update() 或 async_update() 方法，而不是直接进行 I/O 操作。

在模式方面，HVAC 模式有多种内置类型如关闭、制热、制冷等，且只能使用这些内置模式，如需其他功能可通过预设实现；HVAC 动作则描述了设备当前的实际运行动作，与模式有所区别。预设模式、风扇模式和摆风模式也都有各自的内置选项，同时允许自定义。

此外，通过 ClimateEntityFeature 枚举定义了设备支持的功能，如支持目标温度、温度范围、湿度、风扇模式等，并使用按位或运算符组合。最后还介绍了针对各种功能的设置方法，如设置 HVAC 模式、预设模式、风扇模式等，以及控制辅助加热器的开启和关闭方法，这些方法在自定义气候实体类时需要根据实际情况实现。