> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# Climate Platform

> API reference for implementing climate entities in Home Assistant

The climate platform allows integrations to control HVAC (heating, ventilation, air conditioning) devices. Climate entities can control temperature, humidity, fan mode, and more.

## Base Class

All climate entities inherit from `ClimateEntity`, which is defined in `homeassistant.components.climate`.

```python theme={null}
from homeassistant.components.climate import ClimateEntity

class MyClimate(ClimateEntity):
    """Representation of a climate device."""
```

## HVAC Modes

Climate entities operate in different HVAC modes:

```python theme={null}
from homeassistant.components.climate import HVACMode

class MyClimate(ClimateEntity):
    """A climate device."""

    _attr_hvac_modes = [HVACMode.OFF, HVACMode.HEAT, HVACMode.COOL, HVACMode.AUTO]
```

Available HVAC modes:

* `OFF` - HVAC is off
* `HEAT` - Heating mode
* `COOL` - Cooling mode
* `HEAT_COOL` - Heat/cool to a temperature range
* `AUTO` - Automatic mode
* `DRY` - Dry/dehumidify mode
* `FAN_ONLY` - Fan only mode

## Required Properties

### hvac\_mode

The current HVAC mode.

```python theme={null}
@cached_property
def hvac_mode(self) -> HVACMode | None:
    """Return hvac operation ie. heat, cool mode."""
    return self._attr_hvac_mode
```

### hvac\_modes

List of available HVAC modes.

```python theme={null}
@cached_property
def hvac_modes(self) -> list[HVACMode]:
    """Return the list of available hvac operation modes."""
    return self._attr_hvac_modes
```

### temperature\_unit

The unit of temperature (Celsius or Fahrenheit).

```python theme={null}
@cached_property
def temperature_unit(self) -> str:
    """Return the unit of measurement used by the platform."""
    return self._attr_temperature_unit
```

## Required Methods

### set\_hvac\_mode

Set the HVAC mode.

```python theme={null}
async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
    """Set new target hvac mode."""
    await self._device.set_mode(hvac_mode)
    self._attr_hvac_mode = hvac_mode
    self.async_write_ha_state()
```

### set\_temperature

Set target temperature (and optionally HVAC mode).

```python theme={null}
async def async_set_temperature(self, **kwargs: Any) -> None:
    """Set new target temperature."""
    if (temperature := kwargs.get(ATTR_TEMPERATURE)) is not None:
        await self._device.set_temperature(temperature)
        self._attr_target_temperature = temperature
    
    if (hvac_mode := kwargs.get(ATTR_HVAC_MODE)) is not None:
        await self.async_set_hvac_mode(hvac_mode)
    
    self.async_write_ha_state()
```

## Optional Properties

### current\_temperature

The current temperature reading.

```python theme={null}
@cached_property
def current_temperature(self) -> float | None:
    """Return the current temperature."""
    return self._attr_current_temperature
```

### target\_temperature

The target temperature. Required if `ClimateEntityFeature.TARGET_TEMPERATURE` is set.

```python theme={null}
@cached_property
def target_temperature(self) -> float | None:
    """Return the temperature we try to reach."""
    return self._attr_target_temperature
```

### target\_temperature\_high / target\_temperature\_low

Temperature range for heat/cool mode. Required if `ClimateEntityFeature.TARGET_TEMPERATURE_RANGE` is set.

```python theme={null}
@cached_property
def target_temperature_high(self) -> float | None:
    """Return the highbound target temperature we try to reach."""
    return self._attr_target_temperature_high

@cached_property
def target_temperature_low(self) -> float | None:
    """Return the lowbound target temperature we try to reach."""
    return self._attr_target_temperature_low
```

### current\_humidity

The current humidity reading.

```python theme={null}
@cached_property
def current_humidity(self) -> float | None:
    """Return the current humidity."""
    return self._attr_current_humidity
```

### target\_humidity

The target humidity. Required if `ClimateEntityFeature.TARGET_HUMIDITY` is set.

```python theme={null}
@cached_property
def target_humidity(self) -> float | None:
    """Return the humidity we try to reach."""
    return self._attr_target_humidity
```

### hvac\_action

The current action (what the device is actually doing).

```python theme={null}
@cached_property
def hvac_action(self) -> HVACAction | None:
    """Return the current running hvac operation if supported."""
    return self._attr_hvac_action
```

Available HVAC actions:

* `OFF` - Device is off
* `HEATING` - Device is heating
* `COOLING` - Device is cooling
* `DRYING` - Device is drying
* `IDLE` - Device is idle (on but not actively heating/cooling)
* `FAN` - Device fan is running

### fan\_mode / fan\_modes

Fan mode control. Requires `ClimateEntityFeature.FAN_MODE`.

```python theme={null}
@cached_property
def fan_mode(self) -> str | None:
    """Return the fan setting."""
    return self._attr_fan_mode

@cached_property
def fan_modes(self) -> list[str] | None:
    """Return the list of available fan modes."""
    return self._attr_fan_modes
```

Common fan modes: `auto`, `low`, `medium`, `high`, `on`, `off`

### preset\_mode / preset\_modes

Preset mode control. Requires `ClimateEntityFeature.PRESET_MODE`.

```python theme={null}
@cached_property
def preset_mode(self) -> str | None:
    """Return the current preset mode."""
    return self._attr_preset_mode

@cached_property
def preset_modes(self) -> list[str] | None:
    """Return a list of available preset modes."""
    return self._attr_preset_modes
```

Common preset modes: `none`, `eco`, `away`, `boost`, `comfort`, `home`, `sleep`, `activity`

### swing\_mode / swing\_modes

Swing mode control. Requires `ClimateEntityFeature.SWING_MODE`.

```python theme={null}
@cached_property
def swing_mode(self) -> str | None:
    """Return the swing setting."""
    return self._attr_swing_mode

@cached_property
def swing_modes(self) -> list[str] | None:
    """Return the list of available swing modes."""
    return self._attr_swing_modes
```

Common swing modes: `off`, `on`, `vertical`, `horizontal`, `both`

### min\_temp / max\_temp

Temperature range limits.

```python theme={null}
@cached_property
def min_temp(self) -> float:
    """Return the minimum temperature."""
    return self._attr_min_temp

@cached_property
def max_temp(self) -> float:
    """Return the maximum temperature."""
    return self._attr_max_temp
```

### min\_humidity / max\_humidity

Humidity range limits.

```python theme={null}
@cached_property
def min_humidity(self) -> float:
    """Return the minimum humidity."""
    return self._attr_min_humidity

@cached_property
def max_humidity(self) -> float:
    """Return the maximum humidity."""
    return self._attr_max_humidity
```

### supported\_features

Flags indicating which features are supported.

```python theme={null}
@cached_property
def supported_features(self) -> ClimateEntityFeature:
    """Return the list of supported features."""
    return self._attr_supported_features
```

Available features:

* `TARGET_TEMPERATURE` - Can set target temperature
* `TARGET_TEMPERATURE_RANGE` - Can set temperature range (high/low)
* `TARGET_HUMIDITY` - Can set target humidity
* `FAN_MODE` - Supports fan mode control
* `PRESET_MODE` - Supports preset modes
* `SWING_MODE` - Supports swing mode
* `SWING_HORIZONTAL_MODE` - Supports horizontal swing
* `TURN_ON` - Can be turned on
* `TURN_OFF` - Can be turned off

## Example Implementation

```python theme={null}
from homeassistant.components.climate import (
    ClimateEntity,
    ClimateEntityFeature,
    HVACMode,
)
from homeassistant.const import ATTR_TEMPERATURE, UnitOfTemperature

class SimpleThermostat(ClimateEntity):
    """A simple thermostat."""

    _attr_temperature_unit = UnitOfTemperature.CELSIUS
    _attr_hvac_modes = [HVACMode.OFF, HVACMode.HEAT, HVACMode.COOL, HVACMode.AUTO]
    _attr_supported_features = ClimateEntityFeature.TARGET_TEMPERATURE
    _attr_min_temp = 7
    _attr_max_temp = 35

    def __init__(self, name: str, device_id: str) -> None:
        """Initialize the climate device."""
        self._attr_name = name
        self._attr_unique_id = f"{device_id}_climate"
        self._attr_hvac_mode = HVACMode.OFF
        self._attr_current_temperature = None
        self._attr_target_temperature = 20

    async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
        """Set new target hvac mode."""
        await self._device.set_mode(hvac_mode)
        self._attr_hvac_mode = hvac_mode
        self.async_write_ha_state()

    async def async_set_temperature(self, **kwargs: Any) -> None:
        """Set new target temperature."""
        if (temperature := kwargs.get(ATTR_TEMPERATURE)) is not None:
            await self._device.set_temperature(temperature)
            self._attr_target_temperature = temperature
            self.async_write_ha_state()

    async def async_update(self) -> None:
        """Fetch new state data."""
        self._attr_current_temperature = await self._device.get_temperature()
```

## Advanced Example with Multiple Features

```python theme={null}
class AdvancedClimate(ClimateEntity):
    """Climate device with humidity, fan, and preset control."""

    _attr_temperature_unit = UnitOfTemperature.CELSIUS
    _attr_hvac_modes = [HVACMode.OFF, HVACMode.HEAT, HVACMode.COOL, HVACMode.AUTO]
    _attr_fan_modes = ["auto", "low", "medium", "high"]
    _attr_preset_modes = ["none", "eco", "away", "boost"]
    _attr_supported_features = (
        ClimateEntityFeature.TARGET_TEMPERATURE
        | ClimateEntityFeature.TARGET_HUMIDITY
        | ClimateEntityFeature.FAN_MODE
        | ClimateEntityFeature.PRESET_MODE
    )

    def __init__(self) -> None:
        """Initialize the climate device."""
        self._attr_hvac_mode = HVACMode.OFF
        self._attr_current_temperature = 22
        self._attr_target_temperature = 22
        self._attr_current_humidity = 50
        self._attr_target_humidity = 50
        self._attr_fan_mode = "auto"
        self._attr_preset_mode = "none"

    async def async_set_temperature(self, **kwargs: Any) -> None:
        """Set new target temperature."""
        if (temp := kwargs.get(ATTR_TEMPERATURE)) is not None:
            self._attr_target_temperature = temp
        self.async_write_ha_state()

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

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

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

    async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
        """Set new hvac mode."""
        self._attr_hvac_mode = hvac_mode
        self.async_write_ha_state()
```

## Turn On/Off Support

Climate devices can implement turn on/off if they support it:

```python theme={null}
class ClimateWithPower(ClimateEntity):
    """Climate device with power control."""

    _attr_supported_features = (
        ClimateEntityFeature.TARGET_TEMPERATURE
        | ClimateEntityFeature.TURN_ON
        | ClimateEntityFeature.TURN_OFF
    )

    async def async_turn_on(self) -> None:
        """Turn the entity on."""
        await self._device.power_on()
        # Default implementation sets to first non-OFF mode
        await self.async_set_hvac_mode(HVACMode.AUTO)

    async def async_turn_off(self) -> None:
        """Turn the entity off."""
        await self.async_set_hvac_mode(HVACMode.OFF)
```

## Important Notes

* Climate entities must set `hvac_mode`, `hvac_modes`, and `temperature_unit`
* The `state` property is final and returns the current `hvac_mode` value
* Always declare `supported_features` to indicate which features your device supports
* Home Assistant handles temperature unit conversion automatically
* Service calls validate parameters against min/max values and available modes
* Use `async_write_ha_state()` after state changes to update Home Assistant

## Services

The climate platform automatically registers these services:

* `climate.set_hvac_mode` - Set HVAC mode
* `climate.set_temperature` - Set target temperature
* `climate.set_humidity` - Set target humidity (if supported)
* `climate.set_fan_mode` - Set fan mode (if supported)
* `climate.set_preset_mode` - Set preset mode (if supported)
* `climate.set_swing_mode` - Set swing mode (if supported)
* `climate.turn_on` - Turn on (if supported)
* `climate.turn_off` - Turn off (if supported)
* `climate.toggle` - Toggle on/off (if supported)

## See Also

* [Entity Documentation](/api/entity)
* [Climate Constants](https://github.com/home-assistant/core/blob/dev/homeassistant/components/climate/const.py)
* [Demo Climate Implementation](https://github.com/home-assistant/core/blob/dev/homeassistant/components/demo/climate.py)