diff --git a/homeassistant/components/generic_thermostat/__init__.py b/homeassistant/components/generic_thermostat/__init__.py index 6927b9fe26e5b..991bc0d29035b 100644 --- a/homeassistant/components/generic_thermostat/__init__.py +++ b/homeassistant/components/generic_thermostat/__init__.py @@ -12,7 +12,7 @@ async_remove_helper_config_entry_from_source_device, ) -from .const import CONF_HEATER, CONF_SENSOR, PLATFORMS +from .const import CONF_DUR_COOLDOWN, CONF_HEATER, CONF_MIN_DUR, CONF_SENSOR, PLATFORMS _LOGGER = logging.getLogger(__name__) @@ -91,8 +91,13 @@ async def async_migrate_entry(hass: HomeAssistant, config_entry: ConfigEntry) -> helper_config_entry_id=config_entry.entry_id, source_device_id=source_device_id, ) + if config_entry.minor_version < 3: + # Set `cycle_cooldown` to `min_cycle_duration` to mimic the old behavior + if CONF_MIN_DUR in options: + options[CONF_DUR_COOLDOWN] = options[CONF_MIN_DUR] + hass.config_entries.async_update_entry( - config_entry, options=options, minor_version=2 + config_entry, options=options, minor_version=3 ) _LOGGER.debug( diff --git a/homeassistant/components/generic_thermostat/climate.py b/homeassistant/components/generic_thermostat/climate.py index 26a368bcd6693..10b24ec17cab4 100644 --- a/homeassistant/components/generic_thermostat/climate.py +++ b/homeassistant/components/generic_thermostat/climate.py @@ -5,6 +5,7 @@ import asyncio from collections.abc import Mapping from datetime import datetime, timedelta +from functools import partial import logging import math from typing import Any @@ -38,7 +39,9 @@ UnitOfTemperature, ) from homeassistant.core import ( + CALLBACK_TYPE, DOMAIN as HOMEASSISTANT_DOMAIN, + Context, CoreState, Event, EventStateChangedData, @@ -46,27 +49,30 @@ State, callback, ) -from homeassistant.exceptions import ConditionError -from homeassistant.helpers import condition, config_validation as cv +from homeassistant.helpers import config_validation as cv from homeassistant.helpers.device import async_entity_id_to_device from homeassistant.helpers.entity_platform import ( AddConfigEntryEntitiesCallback, AddEntitiesCallback, ) from homeassistant.helpers.event import ( + async_call_later, async_track_state_change_event, async_track_time_interval, ) from homeassistant.helpers.reload import async_setup_reload_service from homeassistant.helpers.restore_state import RestoreEntity from homeassistant.helpers.typing import ConfigType, DiscoveryInfoType, VolDictType +from homeassistant.util import dt as dt_util from .const import ( CONF_AC_MODE, CONF_COLD_TOLERANCE, + CONF_DUR_COOLDOWN, CONF_HEATER, CONF_HOT_TOLERANCE, CONF_KEEP_ALIVE, + CONF_MAX_DUR, CONF_MAX_TEMP, CONF_MIN_DUR, CONF_MIN_TEMP, @@ -98,6 +104,8 @@ vol.Optional(CONF_AC_MODE): cv.boolean, vol.Optional(CONF_MAX_TEMP): vol.Coerce(float), vol.Optional(CONF_MIN_DUR): cv.positive_time_period, + vol.Optional(CONF_MAX_DUR): cv.positive_time_period, + vol.Optional(CONF_DUR_COOLDOWN): cv.positive_time_period, vol.Optional(CONF_MIN_TEMP): vol.Coerce(float), vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string, vol.Optional(CONF_COLD_TOLERANCE, default=DEFAULT_TOLERANCE): vol.Coerce(float), @@ -167,6 +175,8 @@ async def _async_setup_config( target_temp: float | None = config.get(CONF_TARGET_TEMP) ac_mode: bool | None = config.get(CONF_AC_MODE) min_cycle_duration: timedelta | None = config.get(CONF_MIN_DUR) + max_cycle_duration: timedelta | None = config.get(CONF_MAX_DUR) + cycle_cooldown: timedelta | None = config.get(CONF_DUR_COOLDOWN) cold_tolerance: float = config[CONF_COLD_TOLERANCE] hot_tolerance: float = config[CONF_HOT_TOLERANCE] keep_alive: timedelta | None = config.get(CONF_KEEP_ALIVE) @@ -190,6 +200,8 @@ async def _async_setup_config( target_temp=target_temp, ac_mode=ac_mode, min_cycle_duration=min_cycle_duration, + max_cycle_duration=max_cycle_duration, + cycle_cooldown=cycle_cooldown, cold_tolerance=cold_tolerance, hot_tolerance=hot_tolerance, keep_alive=keep_alive, @@ -221,6 +233,8 @@ def __init__( target_temp: float | None, ac_mode: bool | None, min_cycle_duration: timedelta | None, + max_cycle_duration: timedelta | None, + cycle_cooldown: timedelta | None, cold_tolerance: float, hot_tolerance: float, keep_alive: timedelta | None, @@ -240,8 +254,16 @@ def __init__( heater_entity_id, ) self.ac_mode = ac_mode - self.min_cycle_duration = min_cycle_duration + self.min_cycle_duration = min_cycle_duration or timedelta() + self.max_cycle_duration = max_cycle_duration + self.cycle_cooldown = cycle_cooldown or timedelta() self._cold_tolerance = cold_tolerance + # Subtract the cooldown so it doesn't impact startup + self._last_toggled_time = dt_util.utcnow() - self.cycle_cooldown + self._cycle_callback: CALLBACK_TYPE | None = None + self._check_callback: CALLBACK_TYPE | None = None + # Context ID used to detect our own toggles + self._last_context_id: str | None = None self._hot_tolerance = hot_tolerance self._keep_alive = keep_alive self._hvac_mode = initial_hvac_mode @@ -289,6 +311,7 @@ async def async_added_to_hass(self) -> None: self.hass, [self.heater_entity_id], self._async_switch_changed ) ) + self.async_on_remove(self._cancel_timers) if self._keep_alive: self.async_on_remove( @@ -482,6 +505,18 @@ def _async_switch_changed(self, event: Event[EventStateChangedData]) -> None: self.hass.async_create_task( self._check_switch_initial_state(), eager_start=True ) + + # Update timestamp on toggle + self._last_toggled_time = new_state.last_changed + + # If the user toggles the switch, assume they want control and clear the timers. + # Note: If a manual interaction occurs within the 2s context window of a switch + # toggle initiated by us, we may not detect manual control. Users are advised to + # use the climate entity for reliable control, not the switch entity. + if new_state.context.id != self._last_context_id: + _LOGGER.debug("External switch change detected, clearing timers") + self._last_context_id = None + self._cancel_timers() self.async_write_ha_state() @callback @@ -517,57 +552,69 @@ async def _async_control_heating( if not self._active or self._hvac_mode == HVACMode.OFF: return - # If the `force` argument is True, we - # ignore `min_cycle_duration`. - # If the `time` argument is not none, we were invoked for - # keep-alive purposes, and `min_cycle_duration` is irrelevant. - if not force and time is None and self.min_cycle_duration: - if self._is_device_active: - current_state = STATE_ON - else: - current_state = HVACMode.OFF - try: - long_enough = condition.state( - self.hass, - self.heater_entity_id, - current_state, - self.min_cycle_duration, - ) - except ConditionError: - long_enough = False - - if not long_enough: - return + if force and time is not None and self.max_cycle_duration: + # We were invoked due to `max_cycle_duration`, so turn off + _LOGGER.debug( + "Turning off heater %s due to max cycle time of %s", + self.heater_entity_id, + self.max_cycle_duration, + ) + self._cancel_cycle_timer() + await self._async_heater_turn_off() + return assert self._cur_temp is not None and self._target_temp is not None - - min_temp = self._target_temp - self._cold_tolerance - max_temp = self._target_temp + self._hot_tolerance + too_cold = self._target_temp > self._cur_temp + self._cold_tolerance + too_hot = self._target_temp < self._cur_temp - self._hot_tolerance + now = dt_util.utcnow() if self._is_device_active: - if (self.ac_mode and self._cur_temp <= min_temp) or ( - not self.ac_mode and self._cur_temp >= max_temp - ): - _LOGGER.debug("Turning off heater %s", self.heater_entity_id) - await self._async_heater_turn_off() + if (self.ac_mode and too_cold) or (not self.ac_mode and too_hot): + # Make sure it's past the `min_cycle_duration` before turning off + if ( + self._last_toggled_time + self.min_cycle_duration <= now + or force + ): + _LOGGER.debug("Turning off heater %s", self.heater_entity_id) + await self._async_heater_turn_off() + elif self._check_callback is None: + _LOGGER.debug( + "Minimum cycle time not reached, check again at %s", + self._last_toggled_time + self.min_cycle_duration, + ) + self._check_callback = async_call_later( + self.hass, + now - self._last_toggled_time + self.min_cycle_duration, + self._async_timer_control_heating, + ) elif time is not None: - # The time argument is passed only in keep-alive case + # This is a keep-alive call, so ensure it's on _LOGGER.debug( - "Keep-alive - Turning on heater heater %s", + "Keep-alive - Turning on heater %s", self.heater_entity_id, ) + await self._async_heater_turn_on(keepalive=True) + elif (self.ac_mode and too_hot) or (not self.ac_mode and too_cold): + # Make sure it's past the `cycle_cooldown` before turning on + if self._last_toggled_time + self.cycle_cooldown <= now or force: + _LOGGER.debug("Turning on heater %s", self.heater_entity_id) await self._async_heater_turn_on() - elif (self.ac_mode and self._cur_temp > max_temp) or ( - not self.ac_mode and self._cur_temp < min_temp - ): - _LOGGER.debug("Turning on heater %s", self.heater_entity_id) - await self._async_heater_turn_on() + elif self._check_callback is None: + _LOGGER.debug( + "Cooldown time not reached, check again at %s", + self._last_toggled_time + self.cycle_cooldown, + ) + self._check_callback = async_call_later( + self.hass, + now - self._last_toggled_time + self.cycle_cooldown, + self._async_timer_control_heating, + ) elif time is not None: - # The time argument is passed only in keep-alive case + # This is a keep-alive call, so ensure it's off _LOGGER.debug( "Keep-alive - Turning off heater %s", self.heater_entity_id ) - await self._async_heater_turn_off() + await self._async_heater_turn_off(keepalive=True) @property def _is_device_active(self) -> bool | None: @@ -577,19 +624,48 @@ def _is_device_active(self) -> bool | None: return self.hass.states.is_state(self.heater_entity_id, STATE_ON) - async def _async_heater_turn_on(self) -> None: + async def _async_heater_turn_on(self, keepalive: bool = False) -> None: """Turn heater toggleable device on.""" data = {ATTR_ENTITY_ID: self.heater_entity_id} + # Create a new context for this service call so we can identify + # the resulting state change event as originating from us + new_context = Context(parent_id=self._context.id if self._context else None) + self.async_set_context(new_context) + self._last_context_id = new_context.id await self.hass.services.async_call( - HOMEASSISTANT_DOMAIN, SERVICE_TURN_ON, data, context=self._context + HOMEASSISTANT_DOMAIN, SERVICE_TURN_ON, data, context=new_context ) + if not keepalive: + # Update timestamp on turn on + self._last_toggled_time = dt_util.utcnow() + self._cancel_check_timer() + if self.max_cycle_duration: + _LOGGER.debug( + "Scheduling maximum run-time shut-off for %s", + self._last_toggled_time + self.max_cycle_duration, + ) + self._cancel_cycle_timer() + self._cycle_callback = async_call_later( + self.hass, + self.max_cycle_duration, + partial(self._async_control_heating, force=True), + ) - async def _async_heater_turn_off(self) -> None: + async def _async_heater_turn_off(self, keepalive: bool = False) -> None: """Turn heater toggleable device off.""" data = {ATTR_ENTITY_ID: self.heater_entity_id} + # Create a new context for this service call so we can identify + # the resulting state change event as originating from us + new_context = Context(parent_id=self._context.id if self._context else None) + self.async_set_context(new_context) + self._last_context_id = new_context.id await self.hass.services.async_call( - HOMEASSISTANT_DOMAIN, SERVICE_TURN_OFF, data, context=self._context + HOMEASSISTANT_DOMAIN, SERVICE_TURN_OFF, data, context=new_context ) + if not keepalive: + # Update timestamp on turn off + self._last_toggled_time = dt_util.utcnow() + self._cancel_timers() async def async_set_preset_mode(self, preset_mode: str) -> None: """Set new preset mode.""" @@ -613,3 +689,30 @@ async def async_set_preset_mode(self, preset_mode: str) -> None: await self._async_control_heating(force=True) self.async_write_ha_state() + + async def _async_timer_control_heating(self, _: datetime | None = None) -> None: + """Reset check timer and control heating.""" + self._check_callback = None + await self._async_control_heating() + + @callback + def _cancel_check_timer(self) -> None: + """Reset check timer.""" + if self._check_callback: + _LOGGER.debug("Cancelling scheduled state check") + self._check_callback() + self._check_callback = None + + @callback + def _cancel_cycle_timer(self) -> None: + """Reset cycle timer.""" + if self._cycle_callback: + _LOGGER.debug("Cancelling scheduled shut-off") + self._cycle_callback() + self._cycle_callback = None + + @callback + def _cancel_timers(self) -> None: + """Reset timers.""" + self._cancel_check_timer() + self._cancel_cycle_timer() diff --git a/homeassistant/components/generic_thermostat/config_flow.py b/homeassistant/components/generic_thermostat/config_flow.py index 88a09013d75d9..5dbccfabe8c81 100644 --- a/homeassistant/components/generic_thermostat/config_flow.py +++ b/homeassistant/components/generic_thermostat/config_flow.py @@ -3,6 +3,7 @@ from __future__ import annotations from collections.abc import Mapping +from datetime import timedelta from typing import Any, cast import voluptuous as vol @@ -12,16 +13,20 @@ from homeassistant.const import CONF_NAME, DEGREE from homeassistant.helpers import selector from homeassistant.helpers.schema_config_entry_flow import ( + SchemaCommonFlowHandler, SchemaConfigFlowHandler, + SchemaFlowError, SchemaFlowFormStep, ) from .const import ( CONF_AC_MODE, CONF_COLD_TOLERANCE, + CONF_DUR_COOLDOWN, CONF_HEATER, CONF_HOT_TOLERANCE, CONF_KEEP_ALIVE, + CONF_MAX_DUR, CONF_MAX_TEMP, CONF_MIN_DUR, CONF_MIN_TEMP, @@ -63,6 +68,12 @@ vol.Optional(CONF_KEEP_ALIVE): selector.DurationSelector( selector.DurationSelectorConfig(allow_negative=False) ), + vol.Optional(CONF_MAX_DUR): selector.DurationSelector( + selector.DurationSelectorConfig(allow_negative=False) + ), + vol.Optional(CONF_DUR_COOLDOWN): selector.DurationSelector( + selector.DurationSelectorConfig(allow_negative=False) + ), vol.Optional(CONF_MIN_TEMP): selector.NumberSelector( selector.NumberSelectorConfig( mode=selector.NumberSelectorMode.BOX, unit_of_measurement=DEGREE, step=0.1 @@ -90,13 +101,31 @@ } +async def _validate_config( + handler: SchemaCommonFlowHandler, user_input: dict[str, Any] +) -> dict[str, Any]: + """Validate config.""" + if all(x in user_input for x in (CONF_MIN_DUR, CONF_MAX_DUR)): + min_cycle = timedelta(**user_input[CONF_MIN_DUR]) + max_cycle = timedelta(**user_input[CONF_MAX_DUR]) + + if min_cycle >= max_cycle: + raise SchemaFlowError("min_max_runtime") + + return user_input + + CONFIG_FLOW = { "user": SchemaFlowFormStep(vol.Schema(CONFIG_SCHEMA), next_step="presets"), "presets": SchemaFlowFormStep(vol.Schema(PRESETS_SCHEMA)), } OPTIONS_FLOW = { - "init": SchemaFlowFormStep(vol.Schema(OPTIONS_SCHEMA), next_step="presets"), + "init": SchemaFlowFormStep( + vol.Schema(OPTIONS_SCHEMA), + validate_user_input=_validate_config, + next_step="presets", + ), "presets": SchemaFlowFormStep(vol.Schema(PRESETS_SCHEMA)), } @@ -104,7 +133,7 @@ class ConfigFlowHandler(SchemaConfigFlowHandler, domain=DOMAIN): """Handle a config or options flow.""" - MINOR_VERSION = 2 + MINOR_VERSION = 3 config_flow = CONFIG_FLOW options_flow = OPTIONS_FLOW diff --git a/homeassistant/components/generic_thermostat/const.py b/homeassistant/components/generic_thermostat/const.py index d4c25f698d229..902efc6c347c6 100644 --- a/homeassistant/components/generic_thermostat/const.py +++ b/homeassistant/components/generic_thermostat/const.py @@ -20,6 +20,8 @@ CONF_HOT_TOLERANCE = "hot_tolerance" CONF_MAX_TEMP = "max_temp" CONF_MIN_DUR = "min_cycle_duration" +CONF_MAX_DUR = "max_cycle_duration" +CONF_DUR_COOLDOWN = "cycle_cooldown" CONF_MIN_TEMP = "min_temp" CONF_PRESETS = { p: f"{p}_temp" diff --git a/homeassistant/components/generic_thermostat/strings.json b/homeassistant/components/generic_thermostat/strings.json index 5257be051a29b..d81889c83cd4c 100644 --- a/homeassistant/components/generic_thermostat/strings.json +++ b/homeassistant/components/generic_thermostat/strings.json @@ -16,11 +16,13 @@ "data": { "ac_mode": "Cooling mode", "cold_tolerance": "Cold tolerance", + "cycle_cooldown": "Cooldown period after running", "heater": "Actuator switch", "hot_tolerance": "Hot tolerance", "keep_alive": "Keep-alive interval", + "max_cycle_duration": "Maximum run time", "max_temp": "Maximum target temperature", - "min_cycle_duration": "Minimum cycle duration", + "min_cycle_duration": "Minimum run time", "min_temp": "Minimum target temperature", "name": "[%key:common::config_flow::data::name%]", "target_sensor": "Temperature sensor" @@ -28,10 +30,12 @@ "data_description": { "ac_mode": "Set the actuator specified to be treated as a cooling device instead of a heating device.", "cold_tolerance": "Minimum amount of difference between the temperature read by the temperature sensor the target temperature that must change prior to being switched on. For example, if the target temperature is 25 and the tolerance is 0.5 the heater will start when the sensor goes below 24.5.", + "cycle_cooldown": "After switching off, the minimum amount of time that must elapse before it can be switched back on.", "heater": "Switch entity used to cool or heat depending on A/C mode.", "hot_tolerance": "Minimum amount of difference between the temperature read by the temperature sensor the target temperature that must change prior to being switched off. For example, if the target temperature is 25 and the tolerance is 0.5 the heater will stop when the sensor equals or goes above 25.5.", - "keep_alive": "Trigger the heater periodically to keep devices from losing state. When set, min cycle duration is ignored.", - "min_cycle_duration": "Set a minimum amount of time that the switch specified must be in its current state prior to being switched either off or on.", + "keep_alive": "Trigger the heater periodically to keep devices from losing state.", + "max_cycle_duration": "Once switched on, the maximum amount of time that can elapse before it will be switched off.", + "min_cycle_duration": "Once switched on, the minimum amount of time that must elapse before it may be switched off.", "target_sensor": "Temperature sensor that reflects the current temperature." }, "description": "Create a climate entity that controls the temperature via a switch and sensor.", @@ -40,14 +44,19 @@ } }, "options": { + "error": { + "min_max_runtime": "Minimum run time must be less than the maximum run time." + }, "step": { "init": { "data": { "ac_mode": "[%key:component::generic_thermostat::config::step::user::data::ac_mode%]", "cold_tolerance": "[%key:component::generic_thermostat::config::step::user::data::cold_tolerance%]", + "cycle_cooldown": "[%key:component::generic_thermostat::config::step::user::data::cycle_cooldown%]", "heater": "[%key:component::generic_thermostat::config::step::user::data::heater%]", "hot_tolerance": "[%key:component::generic_thermostat::config::step::user::data::hot_tolerance%]", "keep_alive": "[%key:component::generic_thermostat::config::step::user::data::keep_alive%]", + "max_cycle_duration": "[%key:component::generic_thermostat::config::step::user::data::max_cycle_duration%]", "max_temp": "[%key:component::generic_thermostat::config::step::user::data::max_temp%]", "min_cycle_duration": "[%key:component::generic_thermostat::config::step::user::data::min_cycle_duration%]", "min_temp": "[%key:component::generic_thermostat::config::step::user::data::min_temp%]", @@ -56,9 +65,11 @@ "data_description": { "ac_mode": "[%key:component::generic_thermostat::config::step::user::data_description::ac_mode%]", "cold_tolerance": "[%key:component::generic_thermostat::config::step::user::data_description::cold_tolerance%]", + "cycle_cooldown": "[%key:component::generic_thermostat::config::step::user::data_description::cycle_cooldown%]", "heater": "[%key:component::generic_thermostat::config::step::user::data_description::heater%]", "hot_tolerance": "[%key:component::generic_thermostat::config::step::user::data_description::hot_tolerance%]", "keep_alive": "[%key:component::generic_thermostat::config::step::user::data_description::keep_alive%]", + "max_cycle_duration": "[%key:component::generic_thermostat::config::step::user::data_description::max_cycle_duration%]", "min_cycle_duration": "[%key:component::generic_thermostat::config::step::user::data_description::min_cycle_duration%]", "target_sensor": "[%key:component::generic_thermostat::config::step::user::data_description::target_sensor%]" } diff --git a/tests/components/generic_thermostat/test_climate.py b/tests/components/generic_thermostat/test_climate.py index d082308236a24..b7cb19233a141 100644 --- a/tests/components/generic_thermostat/test_climate.py +++ b/tests/components/generic_thermostat/test_climate.py @@ -4,6 +4,7 @@ from unittest.mock import patch from freezegun import freeze_time +from freezegun.api import FrozenDateTimeFactory import pytest import voluptuous as vol @@ -42,7 +43,11 @@ callback, ) from homeassistant.exceptions import ServiceValidationError -from homeassistant.helpers import device_registry as dr, entity_registry as er +from homeassistant.helpers import ( + device_registry as dr, + entity_platform, + entity_registry as er, +) from homeassistant.helpers.typing import StateType from homeassistant.setup import async_setup_component from homeassistant.util import dt as dt_util @@ -540,6 +545,40 @@ async def test_temp_change_heater_on_outside_tolerance(hass: HomeAssistant) -> N assert call.data["entity_id"] == ENT_SWITCH +async def test_external_toggle_resets_min_cycle( + hass: HomeAssistant, freezer: FrozenDateTimeFactory +) -> None: + """Test that an external toggle cancels the min_cycle scheduled check.""" + # Set up thermostat with min cycle duration and cooldown + await _setup_thermostat_with_min_cycle_duration(hass, False, HVACMode.HEAT) + + fake_changed = datetime.datetime.now(dt_util.UTC) + # Perform initial actions at the same frozen time so the cycle timer is recent + freezer.move_to(fake_changed) + # Start with switch on and record service call registrations + calls = _setup_switch(hass, True) + + # Cause condition to try to turn off (inside min cycle) + await common.async_set_temperature(hass, 25) + _setup_sensor(hass, 30) + await hass.async_block_till_done() + + # No service calls should have been made because we're within min_cycle + assert len(calls) == 0 + + # Simulate an external toggle shortly after (resets internals) + freezer.move_to(fake_changed + datetime.timedelta(minutes=1)) + hass.states.async_set(ENT_SWITCH, STATE_OFF) + await hass.async_block_till_done() + + # Advance past the original min_cycle; since callbacks were cancelled by + # the external toggle, no automatic turn_off should occur + async_fire_time_changed(hass, fake_changed + datetime.timedelta(minutes=11)) + await hass.async_block_till_done() + + assert len(calls) == 0 + + @pytest.mark.usefixtures("setup_comp_2") async def test_temp_change_heater_off_within_tolerance(hass: HomeAssistant) -> None: """Test if temperature change doesn't turn off within tolerance.""" @@ -795,6 +834,9 @@ async def _setup_thermostat_with_min_cycle_duration( "heater": ENT_SWITCH, "target_sensor": ENT_SENSOR, "ac_mode": ac_mode, + # cycle_cooldown ensures switch stays off for n minutes + "cycle_cooldown": datetime.timedelta(minutes=10), + # min_cycle_duration only ensures switch stays on for n minutes "min_cycle_duration": datetime.timedelta(minutes=10), "initial_hvac_mode": initial_hvac_mode, } @@ -950,6 +992,8 @@ async def setup_comp_7(hass: HomeAssistant) -> None: "target_sensor": ENT_SENSOR, "ac_mode": True, "min_cycle_duration": datetime.timedelta(minutes=15), + # cycle_cooldown ensures switch stays off for n minutes + "cycle_cooldown": datetime.timedelta(minutes=15), "keep_alive": datetime.timedelta(minutes=10), "initial_hvac_mode": HVACMode.COOL, } @@ -1024,6 +1068,8 @@ async def setup_comp_8(hass: HomeAssistant) -> None: "heater": ENT_SWITCH, "target_sensor": ENT_SENSOR, "min_cycle_duration": datetime.timedelta(minutes=15), + # cycle_cooldown ensures switch stays off for n minutes + "cycle_cooldown": datetime.timedelta(minutes=15), "keep_alive": datetime.timedelta(minutes=10), "initial_hvac_mode": HVACMode.HEAT, } @@ -1082,6 +1128,195 @@ async def test_temp_change_heater_trigger_off_long_enough_2( assert call.data["entity_id"] == ENT_SWITCH +async def test_max_cycle_duration_turns_off(hass: HomeAssistant) -> None: + """Test that max_cycle_duration forces the heater off after the duration.""" + hass.config.temperature_unit = UnitOfTemperature.CELSIUS + assert await async_setup_component( + hass, + CLIMATE_DOMAIN, + { + "climate": { + "platform": "generic_thermostat", + "name": "test", + "cold_tolerance": 0.3, + "hot_tolerance": 0.3, + "target_temp": 25, + "heater": ENT_SWITCH, + "target_sensor": ENT_SENSOR, + "min_cycle_duration": datetime.timedelta(minutes=0), + "max_cycle_duration": datetime.timedelta(minutes=10), + "initial_hvac_mode": HVACMode.HEAT, + } + }, + ) + await hass.async_block_till_done() + + calls = _setup_switch(hass, False) + # Ensure sensor indicates below target so heater will turn on + _setup_sensor(hass, 20) + await hass.async_block_till_done() + + # Heater should have been turned on + assert len(calls) == 1 + call = calls[0] + assert call.service == SERVICE_TURN_ON + + # Advance time to trigger max cycle shut-off + test_time = datetime.datetime.now(dt_util.UTC) + async_fire_time_changed(hass, test_time) + await hass.async_block_till_done() + async_fire_time_changed(hass, test_time + datetime.timedelta(minutes=10)) + await hass.async_block_till_done() + + # One additional turn_off call should have occurred + assert len(calls) == 2 + assert calls[1].service == SERVICE_TURN_OFF + + +async def test_external_toggle_resets_max_cycle( + hass: HomeAssistant, freezer: FrozenDateTimeFactory +) -> None: + """Test that an external toggle cancels the max_cycle scheduled check.""" + hass.config.temperature_unit = UnitOfTemperature.CELSIUS + assert await async_setup_component( + hass, + CLIMATE_DOMAIN, + { + "climate": { + "platform": "generic_thermostat", + "name": "test", + "cold_tolerance": 0.3, + "hot_tolerance": 0.3, + "target_temp": 25, + "heater": ENT_SWITCH, + "target_sensor": ENT_SENSOR, + "min_cycle_duration": datetime.timedelta(minutes=0), + "max_cycle_duration": datetime.timedelta(minutes=10), + "initial_hvac_mode": HVACMode.HEAT, + } + }, + ) + await hass.async_block_till_done() + + calls = _setup_switch(hass, False) + # Trigger heater to turn on + _setup_sensor(hass, 20) + await hass.async_block_till_done() + assert len(calls) == 1 + + # Simulate an external toggle event shortly after (resets internals) + test_time = datetime.datetime.now(dt_util.UTC) + async_fire_time_changed(hass, test_time) + freezer.move_to(test_time + datetime.timedelta(minutes=1)) + hass.states.async_set(ENT_SWITCH, STATE_ON) + await hass.async_block_till_done() + + # Advance past the original max duration; since callbacks were cancelled by + # the external toggle, no automatic turn_off should occur + async_fire_time_changed(hass, test_time + datetime.timedelta(minutes=11)) + await hass.async_block_till_done() + + # Only the original turn_on call should be present + assert len(calls) == 1 + + +async def test_default_cycle_cooldown_allows_immediate_restart( + hass: HomeAssistant, +) -> None: + """Test default `cycle_cooldown` allows immediate restart when omitted.""" + hass.config.temperature_unit = UnitOfTemperature.CELSIUS + # Do not provide `cycle_cooldown` here; default should be zero timedelta + assert await async_setup_component( + hass, + CLIMATE_DOMAIN, + { + "climate": { + "platform": "generic_thermostat", + "name": "test", + "cold_tolerance": 0.3, + "hot_tolerance": 0.3, + "target_temp": 25, + "heater": ENT_SWITCH, + "target_sensor": ENT_SENSOR, + "min_cycle_duration": datetime.timedelta(minutes=0), + "initial_hvac_mode": HVACMode.HEAT, + } + }, + ) + await hass.async_block_till_done() + + # Start with the switch ON so the thermostat can issue a turn_off + calls = _setup_switch(hass, True) + + # Trigger off + _setup_sensor(hass, 30) + await hass.async_block_till_done() + assert len(calls) == 1 + assert calls[0].service == SERVICE_TURN_OFF + + # Reflect the physical device change (services are not changing state in + # this test harness). Update the entity to OFF so the thermostat sees the + # device as inactive and can attempt to turn it on again. + hass.states.async_set(ENT_SWITCH, STATE_OFF) + await hass.async_block_till_done() + + # Immediately trigger on again; with default cooldown=0 this should be allowed + _setup_sensor(hass, 20) + await hass.async_block_till_done() + assert len(calls) == 2 + assert calls[1].service == SERVICE_TURN_ON + + +async def test_cycle_cooldown_schedules_restart_after_cooldown( + hass: HomeAssistant, freezer: FrozenDateTimeFactory +) -> None: + """Test that cooldown blocks restart and schedules a restart check.""" + hass.config.temperature_unit = UnitOfTemperature.CELSIUS + now = datetime.datetime.now(dt_util.UTC) + freezer.move_to(now) + + assert await async_setup_component( + hass, + CLIMATE_DOMAIN, + { + "climate": { + "platform": "generic_thermostat", + "name": "test", + "cold_tolerance": 0.3, + "hot_tolerance": 0.3, + "target_temp": 25, + "heater": ENT_SWITCH, + "target_sensor": ENT_SENSOR, + "min_cycle_duration": datetime.timedelta(minutes=0), + "cycle_cooldown": datetime.timedelta(minutes=15), + "initial_hvac_mode": HVACMode.HEAT, + } + }, + ) + await hass.async_block_till_done() + + # Force the thermostat into cooldown by faking a recent toggle time. + thermostats = hass.data[entity_platform.DATA_DOMAIN_PLATFORM_ENTITIES][ + (CLIMATE_DOMAIN, "generic_thermostat") + ] + thermostat = thermostats[ENTITY] + thermostat._last_toggled_time = now + + # Ensure turning on is blocked while in cooldown + calls = _setup_switch(hass, False) + _setup_sensor(hass, 20) + await hass.async_block_till_done() + assert len(calls) == 0 + + # Advance to end of cooldown and trigger the scheduled check + freezer.move_to(now + datetime.timedelta(minutes=15)) + async_fire_time_changed(hass, now + datetime.timedelta(minutes=15)) + await hass.async_block_till_done() + + assert len(calls) == 1 + assert calls[0].service == SERVICE_TURN_ON + + @pytest.fixture async def setup_comp_9(hass: HomeAssistant) -> None: """Initialize components.""" @@ -1098,6 +1333,8 @@ async def setup_comp_9(hass: HomeAssistant) -> None: "heater": ENT_SWITCH, "target_sensor": ENT_SENSOR, "min_cycle_duration": datetime.timedelta(minutes=15), + # cycle_cooldown ensures switch stays off for n minutes + "cycle_cooldown": datetime.timedelta(minutes=15), "keep_alive": datetime.timedelta(minutes=10), "precision": 0.1, } @@ -1155,12 +1392,12 @@ async def test_zero_tolerances(hass: HomeAssistant) -> None: await common.async_set_temperature(hass, 25) assert len(calls) == 0 - # if the switch is on, it should turn off + # if the switch is on, it should remain on calls = _setup_switch(hass, True) _setup_sensor(hass, 25) await hass.async_block_till_done() await common.async_set_temperature(hass, 25) - assert len(calls) == 1 + assert len(calls) == 0 async def test_custom_setup_params(hass: HomeAssistant) -> None: diff --git a/tests/components/generic_thermostat/test_config_flow.py b/tests/components/generic_thermostat/test_config_flow.py index 9fec488d449a1..8c842e6c35f40 100644 --- a/tests/components/generic_thermostat/test_config_flow.py +++ b/tests/components/generic_thermostat/test_config_flow.py @@ -2,16 +2,20 @@ from unittest.mock import patch +import pytest from syrupy.assertion import SnapshotAssertion from syrupy.filters import props from homeassistant.components.climate import PRESET_AWAY +from homeassistant.components.generic_thermostat.config_flow import _validate_config from homeassistant.components.generic_thermostat.const import ( CONF_AC_MODE, CONF_COLD_TOLERANCE, CONF_HEATER, CONF_HOT_TOLERANCE, CONF_KEEP_ALIVE, + CONF_MAX_DUR, + CONF_MIN_DUR, CONF_PRESETS, CONF_SENSOR, DOMAIN, @@ -26,6 +30,7 @@ UnitOfTemperature, ) from homeassistant.core import HomeAssistant +from homeassistant.helpers.schema_config_entry_flow import SchemaFlowError from tests.common import MockConfigEntry @@ -225,3 +230,39 @@ async def test_config_flow_with_keep_alive(hass: HomeAssistant) -> None: await hass.async_block_till_done() assert len(mock_setup_entry.mock_calls) == 1 + + +async def test_validate_config_min_max_duration() -> None: + """Test _validate_config with min and max cycle duration validation.""" + # Test valid case: min_dur < max_dur + user_input = { + CONF_MIN_DUR: {"seconds": 30}, + CONF_MAX_DUR: {"minutes": 1}, + } + result = await _validate_config(None, user_input) + assert result == user_input + + # Test invalid case: min_dur >= max_dur + user_input_invalid = { + CONF_MIN_DUR: {"minutes": 2}, + CONF_MAX_DUR: {"minutes": 1}, + } + with pytest.raises(SchemaFlowError) as exc_info: + await _validate_config(None, user_input_invalid) + assert str(exc_info.value) == "min_max_runtime" + + # Test equal durations (should fail) + user_input_equal = { + CONF_MIN_DUR: {"minutes": 1}, + CONF_MAX_DUR: {"minutes": 1}, + } + with pytest.raises(SchemaFlowError) as exc_info: + await _validate_config(None, user_input_equal) + assert str(exc_info.value) == "min_max_runtime" + + # Test without both durations (should pass) + user_input_partial = { + CONF_MIN_DUR: {"seconds": 30}, + } + result = await _validate_config(None, user_input_partial) + assert result == user_input_partial diff --git a/tests/components/generic_thermostat/test_init.py b/tests/components/generic_thermostat/test_init.py index 0d0c95b459db4..84e741d7df957 100644 --- a/tests/components/generic_thermostat/test_init.py +++ b/tests/components/generic_thermostat/test_init.py @@ -8,7 +8,11 @@ from homeassistant.components import generic_thermostat from homeassistant.components.generic_thermostat.config_flow import ConfigFlowHandler -from homeassistant.components.generic_thermostat.const import DOMAIN +from homeassistant.components.generic_thermostat.const import ( + CONF_DUR_COOLDOWN, + CONF_MIN_DUR, + DOMAIN, +) from homeassistant.config_entries import ConfigEntry, ConfigEntryState from homeassistant.core import Event, HomeAssistant, callback from homeassistant.helpers import device_registry as dr, entity_registry as er @@ -595,7 +599,7 @@ async def test_migration_1_1( assert generic_thermostat_entity_entry.device_id == switch_entity_entry.device_id assert generic_thermostat_config_entry.version == 1 - assert generic_thermostat_config_entry.minor_version == 2 + assert generic_thermostat_config_entry.minor_version == 3 async def test_migration_from_future_version( @@ -622,3 +626,36 @@ async def test_migration_from_future_version( await hass.async_block_till_done() assert config_entry.state is ConfigEntryState.MIGRATION_ERROR + + +async def test_migration_1_2(hass: HomeAssistant) -> None: + """Test migration from 1.2 to 1.3 copies CONF_MIN_DUR to CONF_DUR_COOLDOWN.""" + config_entry = MockConfigEntry( + data={}, + domain=DOMAIN, + options={ + "name": "My generic thermostat", + "heater": "switch.test", + "target_sensor": "sensor.test", + CONF_MIN_DUR: {"hours": 0, "minutes": 5, "seconds": 0}, + "ac_mode": False, + "cold_tolerance": 0.3, + "hot_tolerance": 0.3, + }, + title="My generic thermostat", + version=1, + minor_version=2, + ) + config_entry.add_to_hass(hass) + + # Run migration + result = await generic_thermostat.async_migrate_entry(hass, config_entry) + assert result is True + + # After migration, cooldown should be set to min_cycle_duration and minor version bumped + assert config_entry.options.get(CONF_DUR_COOLDOWN) == { + "hours": 0, + "minutes": 5, + "seconds": 0, + } + assert config_entry.minor_version == 3