developers.home-assistant/docs/core/entity/climate.md

title	sidebar_label
Climate entity	Climate

A climate entity controls temperature, humidity, or fans, such as A/C systems and humidifiers. Derive a platform entity from homeassistant.components.climate.ClimateEntity

Properties

:::tip Properties should always only return information from memory and not do I/O (like network requests). Implement update() or async_update() to fetch data. :::

Name	Type	Default	Description
current_humidity	float | None	None	The current humidity.
current_temperature	float | None	None	The current temperature.
fan_mode	str | None	Required by SUPPORT_FAN_MODE	The current fan mode.
fan_modes	list[str] | None	Required by SUPPORT_FAN_MODE	The list of available fan modes.
hvac_action	HVACAction | None	None	The current HVAC action (heating, cooling)
hvac_mode	HVACMode | None	Required	The current operation (e.g. heat, cool, idle). Used to determine state.
hvac_modes	list[HVACMode]	Required	List of available operation modes. See below.
max_humidity	float	DEFAULT_MAX_HUMIDITY (value == 99)	The maximum humidity.
max_temp	float	DEFAULT_MAX_TEMP (value == 35 °C)	The maximum temperature in temperature_unit.
min_humidity	float	DEFAULT_MIN_HUMIDITY (value == 30)	The minimum humidity.
min_temp	float	DEFAULT_MIN_TEMP (value == 7 °C)	The minimum temperature in temperature_unit.
precision	float	According to temperature_unit	The precision of the temperature in the system. Defaults to tenths for TEMP_CELSIUS, whole number otherwise.
preset_mode	str | None	Required by SUPPORT_PRESET_MODE	The current active preset.
preset_modes	list[str] | None	Required by SUPPORT_PRESET_MODE	The available presets.
swing_mode	str | None	Required by SUPPORT_SWING_MODE	The swing setting.
swing_modes	list[str] | None	Required by SUPPORT_SWING_MODE	Returns the list of available swing modes.
target_humidity	float | None	None	The target humidity the device is trying to reach.
target_temperature	float | None	None	The temperature currently set to be reached.
target_temperature_high	float | None	Required by TARGET_TEMPERATURE_RANGE	The upper bound target temperature
target_temperature_low	float | None	Required by TARGET_TEMPERATURE_RANGE	The lower bound target temperature
target_temperature_step	float | None	None	The supported step size a target temperature can be increased or decreased
temperature_unit	str	Required	The unit of temperature measurement for the system (TEMP_CELSIUS or TEMP_FAHRENHEIT).

HVAC modes

You are only allowed to use the built-in HVAC modes, provided by the HVACMode enum. If you want another mode, add a preset instead.

Name	Description
HVACMode.OFF	The device is turned off.
HVACMode.HEAT	The device is set to heat to a target temperature.
HVACMode.COOL	The device is set to cool to a target temperature.
HVACMode.HEAT_COOL	The device is set to heat/cool to a target temperature range.
HVACMode.AUTO	The device is set to a schedule, learned behavior, AI.
HVACMode.DRY	The device is set to dry/humidity mode.
HVACMode.FAN_ONLY	The device only has the fan on. No heating or cooling taking place.

HVAC action

The HVAC action describes the current action. This is different from the mode, because if a device is set to heat, and the target temperature is already achieved, the device will not be actively heating anymore. It is only allowed to use the built-in HVAC actions, provided by the HVACAction enum.

Name	Description
HVACAction.OFF	Device is turned off.
HVACAction.PREHEATING	Device is preheating.
HVACAction.HEATING	Device is heating.
HVACAction.COOLING	Device is cooling.
HVACAction.DRYING	Device is drying.
HVACAction.FAN	Device has fan on.
HVACAction.IDLE	Device is idle.
HVACAction.DEFROSTING	Device is defrosting.

Presets

A device can have different presets that it might want to show to the user. Common presets are "Away" or "Eco". There are a couple of built-in presets that will offer translations, but you're also allowed to add custom presets.

Name	Description
NONE	No preset is active
ECO	Device is running an energy-saving mode
AWAY	Device is in away mode
BOOST	Device turn all valve full up
COMFORT	Device is in comfort mode
HOME	Device is in home mode
SLEEP	Device is prepared for sleep
ACTIVITY	Device is reacting to activity (e.g. movement sensors)

Fan modes

A device's fan can have different states. There are a couple of built-in fan modes, but you're also allowed to use custom fan modes.

Name
FAN_ON
FAN_OFF
FAN_AUTO
FAN_LOW
FAN_MEDIUM
FAN_HIGH
FAN_MIDDLE
FAN_FOCUS
FAN_DIFFUSE

Swing modes

The device fan can have different swing modes that it wants the user to know about/control.

Name	Description
SWING_OFF	The fan is not swinging.
SWING_ON	The fan is swinging.
SWING_VERTICAL	The fan is swinging vertical.
SWING_HORIZONTAL	The fan is swinging horizontal.
SWING_BOTH	The fan is swinging both horizontal and vertical.

Supported features

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

Value	Description
TARGET_TEMPERATURE	The device supports a target temperature.
TARGET_TEMPERATURE_RANGE	The device supports a ranged target temperature. Used for HVAC modes heat_cool and auto
TARGET_HUMIDITY	The device supports a target humidity.
FAN_MODE	The device supports fan modes.
PRESET_MODE	The device supports presets.
SWING_MODE	The device supports swing modes.
TURN_ON	The device supports turn on.
TURN_OFF	The device supports turn off.

Methods

Set HVAC mode

class MyClimateEntity(ClimateEntity):
    # Implement one of these methods.

    def set_hvac_mode(self, hvac_mode):
        """Set new target hvac mode."""

    async def async_set_hvac_mode(self, hvac_mode):
        """Set new target hvac mode."""

Turn on

class MyClimateEntity(ClimateEntity):
    # Implement one of these methods.
    # The `turn_on` method should set `hvac_mode` to any other than
    # `HVACMode.OFF` by optimistically setting it from the service action
    # handler or with the next state update

    def turn_on(self):
        """Turn the entity on."""

    async def async_turn_on(self):
        """Turn the entity on."""

Turn off

class MyClimateEntity(ClimateEntity):
    # Implement one of these methods.
    # The `turn_off` method should set `hvac_mode` to `HVACMode.OFF` by
    # optimistically setting it from the service action handler or with the
    # next state update

    def turn_off(self):
        """Turn the entity off."""

    async def async_turn_off(self):
        """Turn the entity off."""

Toggle

class MyClimateEntity(ClimateEntity):
    # It's not mandatory to implement the `toggle` method as the base implementation
    # will call `turn_on`/`turn_off` according to the current HVAC mode.

    # If implemented, the `toggle` method should set `hvac_mode` to the right `HVACMode` by
    # optimistically setting it from the service action handler
    # or with the next state update.

    def toggle(self):
        """Toggle the entity."""

    async def async_toggle(self):
        """Toggle the entity."""

Set preset mode

class MyClimateEntity(ClimateEntity):
    # Implement one of these methods.

    def set_preset_mode(self, preset_mode):
        """Set new target preset mode."""

    async def async_set_preset_mode(self, preset_mode):
        """Set new target preset mode."""

Set fan mode

class MyClimateEntity(ClimateEntity):
    # Implement one of these methods.

    def set_fan_mode(self, fan_mode):
        """Set new target fan mode."""

    async def async_set_fan_mode(self, fan_mode):
        """Set new target fan mode."""

Set humidity

class MyClimateEntity(ClimateEntity):
    # Implement one of these methods.

    def set_humidity(self, humidity):
        """Set new target humidity."""

    async def async_set_humidity(self, humidity):
        """Set new target humidity."""

Set swing mode

class MyClimateEntity(ClimateEntity):
    # Implement one of these methods.

    def set_swing_mode(self, swing_mode):
        """Set new target swing operation."""

    async def async_set_swing_mode(self, swing_mode):
        """Set new target swing operation."""

Set temperature

:::note ClimateEntity has built-in validation to ensure that the target_temperature_low argument is lower than or equal to the target_temperature_high argument. Therefore, integrations do not need to validate this in their own implementation. :::

class MyClimateEntity(ClimateEntity):
    # Implement one of these methods.

    def set_temperature(self, **kwargs):
        """Set new target temperature."""

    async def async_set_temperature(self, **kwargs):
        """Set new target temperature."""