Climate entity

A climate entity controls the climate of a space: a thermostat, an air conditioner, a heat pump, or a radiator valve with a target temperature. It can also control humidity and the fan of the unit. Inherit from ClimateEntity in homeassistant.components.climate.

If the device only dries or humidifies the air, use a humidifier. If it heats water, use a water heater. A standalone fan is a fan.

For how the frontend shows a climate entity, see the climate more-info view.

Climate entities have these properties on top of the generic entity properties. Every property can be set with its _attr_ attribute, like _attr_hvac_mode.

Report every temperature in the unit of the device, and set native_temperature_unit to match. The climate entity converts the temperatures to the unit system of the installation before it writes the state, and adds a temperature_unit state attribute with the unit of the converted values. You cannot override that attribute.

It works the other way too: temperatures passed to set_temperature are converted to native_temperature_unit and checked against min_temp and max_temp before your method is called.

The HVAC mode is what the device is asked to do. Only use the modes of the HVACMode enum. When a device has an option that changes how a mode behaves, make it a preset instead of a new mode.

The HVAC action is what the device is doing right now to reach its mode and preset, as decided by its own control logic. Only use the actions of the HVACAction enum.

Be honest with hvac_action. A thermostat with hysteresis, or a variable power device that keeps running at low power after it reached its target, does not always know whether it is heating or idle. If the device cannot tell you what it is doing, leave hvac_action out.

Presets, fan modes, and swing modes are lists of strings. Home Assistant has constants with built-in translations for common values, and you can add your own values. Give custom values a translation and an icon with the translation key of the entity, under state_attributes (see icons).

• Presets: PRESET_NONE, PRESET_ECO, PRESET_AWAY, PRESET_BOOST, PRESET_COMFORT, PRESET_HOME, PRESET_SLEEP, and PRESET_ACTIVITY.
• Fan modes: FAN_ON, FAN_OFF, FAN_AUTO, FAN_LOW, FAN_MEDIUM, FAN_HIGH, FAN_TOP, FAN_MIDDLE, FAN_FOCUS, and FAN_DIFFUSE.
• Swing modes: SWING_ON, SWING_OFF, SWING_BOTH, SWING_VERTICAL, and SWING_HORIZONTAL.
• Horizontal swing modes: SWING_HORIZONTAL_ON and SWING_HORIZONTAL_OFF.

Only implement horizontal swing when the device controls vertical and horizontal swing separately. Then swing_modes covers the vertical direction and swing_horizontal_modes the horizontal one. Otherwise, put every option in swing_modes.

Home Assistant checks the mode in an action against your list before it calls you, and raises a validation error when it is not in there.

Combine the ClimateEntityFeature flags with | and set them as supported_features. See supported features.

Actions for a feature you did not set are rejected before they reach your entity.

Implement the sync or the async variant of each method, not both.

set_temperature receives ATTR_TEMPERATURE for a single target, or ATTR_TARGET_TEMP_LOW and ATTR_TARGET_TEMP_HIGH for a range, all in native_temperature_unit. It can also receive ATTR_HVAC_MODE, when the action sets the mode at the same time.

You do not always have to implement turn_on and turn_off. Without them, turn_off sets HVACMode.OFF when the device supports it. turn_on picks the only other mode when the device has two modes and one is OFF, and otherwise the first of HEAT_COOL, HEAT, and COOL the device supports. If the device has its own on and off, implement them, and set hvac_mode to the mode it lands in. toggle calls turn_on or turn_off based on whether hvac_mode is OFF.

The state is the value of hvac_mode: off, heat, cool, heat_cool, auto, dry, or fan_only. When hvac_mode is None, the state is unknown.

If your entity restores its temperatures after a restart, don't read them from the attributes of the last state that RestoreEntity gives you. Those are converted to the unit system of the installation and rounded for display. Inherit from RestoreClimate instead, and call async_get_last_climate_data() in async_added_to_hass.

It returns the stored native_current_temperature, native_target_temperature, native_target_temperature_high, and native_target_temperature_low, converted to your current native_temperature_unit, or None when there is nothing to restore. A temperature that is not a valid number comes back as None.

Pass validate_range=True when you send the restored targets to the device, like when the device can't report its own state. A target outside min_temp and max_temp then comes back as None, and you fall back to a default. A target at most half a degree outside the range, which rounding can cause, is clamped to the range instead. That half degree is in the unit the temperature was stored in, so a value stored in °F gets about 0.28 °C of room on an entity that now uses °C.

from homeassistant.components.climate import RestoreClimate


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

from typing import Any

from homeassistant.components.climate import (
    ClimateEntity,
    ClimateEntityFeature,
    HVACMode,
)
from homeassistant.const import ATTR_TEMPERATURE, UnitOfTemperature


class MyThermostat(ClimateEntity):
    """A thermostat that heats, or is off."""

    _attr_has_entity_name = True
    _attr_name = None
    _attr_hvac_modes = [HVACMode.OFF, HVACMode.HEAT]
    _attr_native_temperature_unit = UnitOfTemperature.CELSIUS
    _attr_target_temperature_step = 0.5
    _attr_supported_features = (
        ClimateEntityFeature.TARGET_TEMPERATURE
        | ClimateEntityFeature.TURN_ON
        | ClimateEntityFeature.TURN_OFF
    )

    def __init__(self, device: MyDevice) -> None:
        """Set up the thermostat."""
        self._device = device
        self._attr_unique_id = device.serial

    @property
    def hvac_mode(self) -> HVACMode:
        """Return the current mode."""
        return HVACMode.HEAT if self._device.heating else HVACMode.OFF

    @property
    def native_current_temperature(self) -> float:
        """Return the measured temperature."""
        return self._device.temperature

    @property
    def native_target_temperature(self) -> float:
        """Return the target temperature."""
        return self._device.setpoint

    async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
        """Set the mode."""
        await self._device.set_heating(hvac_mode == HVACMode.HEAT)

    async def async_set_temperature(self, **kwargs: Any) -> None:
        """Set the target temperature."""
        await self._device.set_setpoint(kwargs[ATTR_TEMPERATURE])

With TURN_ON and TURN_OFF set and only OFF and HEAT as modes, the default turn_on and turn_off call async_set_hvac_mode for you.