Skip to main content

Climate entity

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.

NameTypeDefaultDescription
current_humidityfloat | NoneNoneThe current humidity.
current_temperaturefloat | NoneNoneThe current temperature.
fan_modestr | NoneRequired by SUPPORT_FAN_MODEThe current fan mode.
fan_modeslist[str] | NoneRequired by SUPPORT_FAN_MODEThe list of available fan modes.
hvac_actionHVACAction | NoneNoneThe current HVAC action (heating, cooling)
hvac_modeHVACMode | NoneRequiredThe current operation (e.g. heat, cool, idle). Used to determine state.
hvac_modeslist[HVACMode]RequiredList of available operation modes. See below.
max_humidityfloatDEFAULT_MAX_HUMIDITY (value == 99)The maximum humidity.
max_tempfloatDEFAULT_MAX_TEMP (value == 35 °C)The maximum temperature in temperature_unit.
min_humidityfloatDEFAULT_MIN_HUMIDITY (value == 30)The minimum humidity.
min_tempfloatDEFAULT_MIN_TEMP (value == 7 °C)The minimum temperature in temperature_unit.
precisionfloatAccording to temperature_unitThe precision of the temperature in the system. Defaults to tenths for TEMP_CELSIUS, whole number otherwise.
preset_modestr | NoneRequired by SUPPORT_PRESET_MODEThe current active preset.
preset_modeslist[str] | NoneRequired by SUPPORT_PRESET_MODEThe available presets.
swing_modestr | NoneRequired by SUPPORT_SWING_MODEThe swing setting.
swing_modeslist[str] | NoneRequired by SUPPORT_SWING_MODEReturns the list of available swing modes.
target_humidityfloat | NoneNoneThe target humidity the device is trying to reach.
target_temperaturefloat | NoneNoneThe temperature currently set to be reached.
target_temperature_highfloat | NoneRequired by TARGET_TEMPERATURE_RANGEThe upper bound target temperature
target_temperature_lowfloat | NoneRequired by TARGET_TEMPERATURE_RANGEThe lower bound target temperature
target_temperature_stepfloat | NoneNoneThe supported step size a target temperature can be increased or decreased
temperature_unitstrRequiredThe 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.

NameDescription
HVACMode.OFFThe device is turned off.
HVACMode.HEATThe device is set to heat to a target temperature.
HVACMode.COOLThe device is set to cool to a target temperature.
HVACMode.HEAT_COOLThe device is set to heat/cool to a target temperature range.
HVACMode.AUTOThe device is set to a schedule, learned behavior, AI.
HVACMode.DRYThe device is set to dry/humidity mode.
HVACMode.FAN_ONLYThe 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.

NameDescription
HVACAction.OFFDevice is turned off.
HVACAction.PREHEATINGDevice is preheating.
HVACAction.HEATINGDevice is heating.
HVACAction.COOLINGDevice is cooling.
HVACAction.DRYINGDevice is drying.
HVACAction.FANDevice has fan on.
HVACAction.IDLEDevice is idle.
HVACAction.DEFROSTINGDevice 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.

NameDescription
NONENo preset is active
ECODevice is running an energy-saving mode
AWAYDevice is in away mode
BOOSTDevice turn all valve full up
COMFORTDevice is in comfort mode
HOMEDevice is in home mode
SLEEPDevice is prepared for sleep
ACTIVITYDevice 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.

NameDescription
SWING_OFFThe fan is not swinging.
SWING_ONThe fan is swinging.
SWING_VERTICALThe fan is swinging vertical.
SWING_HORIZONTALThe fan is swinging horizontal.
SWING_BOTHThe 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.

ValueDescription
TARGET_TEMPERATUREThe device supports a target temperature.
TARGET_TEMPERATURE_RANGEThe device supports a ranged target temperature. Used for HVAC modes heat_cool and auto
TARGET_HUMIDITYThe device supports a target humidity.
FAN_MODEThe device supports fan modes.
PRESET_MODEThe device supports presets.
SWING_MODEThe device supports swing modes.
TURN_ONThe device supports turn on.
TURN_OFFThe 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."""