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.

Name	Type	Default	Description
current_humidity	`float \| None`	`None`	The current humidity.
fan_mode	`str \| None`	Required by ClimateEntityFeature.FAN_MODE	The current fan mode.
fan_modes	`list[str] \| None`	Required by ClimateEntityFeature.FAN_MODE	The list of available fan modes.
hvac_action	`HVACAction \| None`	`None`	The action currently being performed. See below.
hvac_mode	`HVACMode \| None`	Required	The selected operation mode. See below. 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 `native_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 `native_temperature_unit`.
native_current_temperature	`float \| None`	`None`	The current temperature in `native_temperature_unit`.
native_target_temperature	`float \| None`	`None`	The temperature currently set to be reached, in `native_temperature_unit`.
native_target_temperature_high	`float \| None`	Required by TARGET_TEMPERATURE_RANGE	The upper bound target temperature, in `native_temperature_unit`.
native_target_temperature_low	`float \| None`	Required by TARGET_TEMPERATURE_RANGE	The lower bound target temperature, in `native_temperature_unit`.
native_temperature_unit	`str`	Required	The unit the entity reports temperatures in (`UnitOfTemperature.CELSIUS` or `UnitOfTemperature.FAHRENHEIT`). See Temperature units.
precision	`float`	According to the configured unit system	The precision of the temperature in the system. Defaults to tenths when the configured unit system uses `UnitOfTemperature.CELSIUS`, whole number otherwise.
preset_mode	`str \| None`	Required by ClimateEntityFeature.PRESET_MODE	The current active preset.
preset_modes	`list[str] \| None`	Required by ClimateEntityFeature.PRESET_MODE	The available presets.
swing_mode	`str \| None`	Required by ClimateEntityFeature.SWING_MODE	The swing setting.
swing_modes	`list[str] \| None`	Required by ClimateEntityFeature.SWING_MODE	Returns the list of available swing modes, only vertical modes in the case horizontal swing is implemented.
swing_horizontal_mode	`str \| None`	Required by ClimateEntityFeature.SWING_HORIZONTAL_MODE	The horizontal swing setting.
swing_horizontal_modes	`list[str] \| None`	Required by ClimateEntityFeature.SWING_HORIZONTAL_MODE	Returns the list of available horizontal swing modes.
target_humidity	`float \| None`	`None`	The target humidity the device is trying to reach.
target_humidity_step	`int \| None`	`None`	The supported step size a target humidity can be increased or decreased in an action call targeting the device.
target_temperature_step	`float \| None`	`None`	The supported step size a target temperature can be increased or decreased, in `native_temperature_unit`.

Temperature units

Integrations provide temperatures in the unit the device uses, and set native_temperature_unit to that unit. The climate entity converts the temperatures to the unit system configured by the user before writing them to the state machine, and adds a temperature_unit state attribute that holds the unit of the converted temperatures. The temperature_unit state attribute is set by the base class and can't be overridden by integrations.

Temperatures passed to set_temperature are converted to native_temperature_unit before the method is called.

HVAC modes

The HVAC mode is the behaviour that the device is requested to perform.

You are only allowed to use the built-in HVAC modes, provided by the HVACMode enum. For device options which modify how one or more of the modes behave, add a preset.

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 that the device is performing in order to fulfill the requested HVAC mode and preset, as determined by the device's own control algorithms.

You are only allowed to use the built-in HVAC actions provided by the HVACAction enum.

note

It might not be possible to accurately determine the correct HVAC action unless the device reports additional information. For example:

A thermostat with hysteresis has an ambiguous temperature range near the target temperature where it may be performing an action or may be idle.
A variable power device might continue to operate at a reduced power level after the target temperature is reached, rather than becoming idle.

For devices where the HVAC action cannot be accurately determined, do not implement hvac_action.

Name	Description
`HVACAction.OFF`	HVAC mode is `HVACMode.OFF`. The device will not perform any action unless the mode is changed.
`HVACAction.PREHEATING`	The device heat source is running, but is not at operating temperature yet.
`HVACAction.HEATING`	The device is adding heat to the space.
`HVACAction.COOLING`	The device is removing heat from the space.
`HVACAction.DRYING`	The device is removing moisture from the air in the space.
`HVACAction.FAN`	The device has fan on to circulate or ventilate air only.
`HVACAction.IDLE`	The device is not currently performing any action, but may start performing an action if conditions change.
`HVACAction.DEFROSTING`	The device is removing built up ice.

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 (for example, 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_TOP`
`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.

note

For integrations that don't have independent control of vertical and horizontal swing, all possible options should be listed in swing_modes, otherwise swing_modes provides vertical support and swing_horizontal_modes should provide horizontal support.

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.

Swing horizontal modes

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

note

This should only be implemented if the integration has independent control of vertical and horizontal swing. In such case the swing_modes property will provide vertical support and swing_horizontal_modes will provide horizontal support.

Name	Description
`SWING_OFF`	The fan is not swinging.
`SWING_ON`	The fan is swinging.

Restoring climate states

Climate entities which restore temperatures after restart or reload should not read them from the state attributes restored by RestoreEntity, because those are converted to the unit system configured by the user and rounded for display. Instead, those entities should extend RestoreClimate and call await self.async_get_last_climate_data() from async_added_to_hass to get access to the stored native_current_temperature, native_target_temperature, native_target_temperature_high and native_target_temperature_low, converted to the entity's current native_temperature_unit. Temperatures which are not valid numbers are returned as None.

Pass validate_range=True when the restored target temperatures are sent to the device, for example by an entity which can't read its state back from the device. Target temperatures outside min_temp and max_temp are then returned as None, and the entity should fall back to a default. Target temperatures at most half a degree outside the range, which can be caused by rounding, are clamped to the range instead.

class MyClimateEntity(RestoreClimate):
    async def async_added_to_hass(self) -> None:
        """Restore the target temperature."""
        await super().async_added_to_hass()
        if (
            climate_data := await self.async_get_last_climate_data(validate_range=True)
        ) is not None and (
            temperature := climate_data.native_target_temperature
        ) is not None:
            self._attr_native_target_temperature = temperature

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.
`SWING_HORIZONTAL_MODE`	The device supports horizontal 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: HVACMode) -> None:
        """Set new target hvac mode."""

    async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
        """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) -> None:
        """Turn the entity on."""

    async def async_turn_on(self) -> None:
        """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) -> None:
        """Turn the entity off."""

    async def async_turn_off(self) -> None:
        """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) -> None:
        """Toggle the entity."""

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

Set preset mode

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

    def set_preset_mode(self, preset_mode: str) -> None:
        """Set new target preset mode."""

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

Set fan mode

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

    def set_fan_mode(self, fan_mode: str) -> None:
        """Set new target fan mode."""

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

Set humidity

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

    def set_humidity(self, humidity: int) -> None:
        """Set new target humidity."""

    async def async_set_humidity(self, humidity: int) -> None:
        """Set new target humidity."""

Set swing mode

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

    def set_swing_mode(self, swing_mode: str) -> None:
        """Set new target swing operation."""

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

Set horizontal swing mode

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

    def set_swing_horizontal_mode(self, swing_horizontal_mode: str) -> None:
        """Set new target horizontal swing operation."""

    async def async_set_swing_horizontal_mode(self, swing_horizontal_mode: str) -> None:
        """Set new target horizontal 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: Any) -> None:
        """Set new target temperature."""

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

Properties​

Temperature units​

HVAC modes​

HVAC action​

Presets​

Fan modes​

Swing modes​

Swing horizontal modes​

Restoring climate states​

Supported features​

Methods​

Set HVAC mode​

Turn on​

Turn off​

Toggle​

Set preset mode​

Set fan mode​

Set humidity​

Set swing mode​

Set horizontal swing mode​

Set temperature​

Properties

Temperature units

HVAC modes

HVAC action

Presets

Fan modes

Swing modes

Swing horizontal modes

Restoring climate states

Supported features

Methods

Set HVAC mode

Turn on

Turn off

Toggle

Set preset mode

Set fan mode

Set humidity

Set swing mode

Set horizontal swing mode

Set temperature