Add support for underheat and saturation detection in heating control

Author: Alexwijn

custom_components/sat/const.py

@@ -16,6 +16,12 @@
 DEADBAND = 0.1
 BOILER_DEADBAND = 2
 HEATER_STARTUP_TIMEFRAME = 180
+DHW_OVERSHOOT_GUARD_SECONDS = 300.0
+
+OVERSHOOT_SUSTAIN_SECONDS = 60.0
+UNDERHEAT_SUSTAIN_SECONDS = 180.0
+SATURATION_SUSTAIN_SECONDS = 300.0
+
 PWM_ENABLE_MARGIN_CELSIUS = 0.5
 PWM_DISABLE_MARGIN_CELSIUS = 1.5
 PWM_ENABLE_LOW_MODULATION_PERCENT = 10

custom_components/sat/coordinator/__init__.py

@@ -2,7 +2,6 @@
 
 import logging
 from abc import abstractmethod
-from datetime import datetime
 from typing import Optional, Any
 
 from homeassistant.const import STATE_UNAVAILABLE, STATE_UNKNOWN

custom_components/sat/cycles/const.py

@@ -9,7 +9,6 @@
 # Flow vs. setpoint classification margins
 OVERSHOOT_MARGIN_CELSIUS: float = 3.0
 UNDERSHOOT_MARGIN_CELSIUS: float = -3.0
-OVERSHOOT_SUSTAIN_SECONDS: float = 60.0
 
 # Timeouts
 LAST_CYCLE_MAX_AGE_SECONDS: float = 6 * 3600

custom_components/sat/cycles/tracker.py

@@ -7,10 +7,10 @@
 from homeassistant.core import HomeAssistant
 
 from .classifier import CycleClassifier
-from .const import IN_BAND_MARGIN_CELSIUS, OVERSHOOT_MARGIN_CELSIUS, OVERSHOOT_SUSTAIN_SECONDS
+from .const import IN_BAND_MARGIN_CELSIUS, OVERSHOOT_MARGIN_CELSIUS
 from .history import CycleHistory
 from .types import Cycle, CycleMetrics, CycleShapeMetrics
-from ..const import EVENT_SAT_CYCLE_ENDED, EVENT_SAT_CYCLE_STARTED
+from ..const import EVENT_SAT_CYCLE_ENDED, EVENT_SAT_CYCLE_STARTED, OVERSHOOT_SUSTAIN_SECONDS
 from ..helpers import min_max, percentile_interpolated
 from ..types import CycleControlMode, CycleKind, Percentiles
 

custom_components/sat/device/__init__.py

@@ -32,6 +32,8 @@ def __init__(self) -> None:
         self._last_flame_on_at: Optional[float] = None
         self._last_flame_off_at: Optional[float] = None
         self._last_flame_off_was_overshoot: bool = False
+        self._last_hot_water_on_at: Optional[float] = None
+        self._last_hot_water_off_at: Optional[float] = None
 
         self._modulation_tracker = ModulationReliabilityTracker()
 
@@ -59,13 +61,44 @@ def modulation_reliable(self) -> Optional[bool]:
         return self._modulation_tracker.reliable
 
     @property
-    def flame_on_since(self) -> Optional[int]:
+    def status_snapshot(self) -> Optional[DeviceStatusSnapshot]:
+        """Expose the latest status snapshot context used by status evaluation."""
+        if (state := self._current_state) is None:
+            return None
+
+        return DeviceStatusSnapshot(
+            state=state,
+            last_cycle=self._last_cycle,
+            last_update_at=self._last_update_at,
+
+            last_flame_on_at=self._last_flame_on_at,
+            last_flame_off_at=self._last_flame_off_at,
+            last_flame_off_was_overshoot=self._last_flame_off_was_overshoot,
+
+            last_hot_water_on_at=self.hot_water_on_since,
+            last_hot_water_off_at=self.hot_water_off_since,
+
+            previous_state=self._previous_state,
+            previous_update_at=self._previous_update_at,
+            modulation_direction=self._determine_modulation_direction(),
+        )
+
+    @property
+    def flame_on_since(self) -> Optional[float]:
         return self._last_flame_on_at
 
     @property
-    def flame_off_since(self) -> Optional[int]:
+    def flame_off_since(self) -> Optional[float]:
         return self._last_flame_off_at
 
+    @property
+    def hot_water_on_since(self) -> Optional[float]:
+        return self._last_hot_water_on_at
+
+    @property
+    def hot_water_off_since(self) -> Optional[float]:
+        return self._last_hot_water_off_at
+
     async def async_added_to_hass(self, hass: HomeAssistant, device_id: str) -> None:
         """Restore device state from storage when the integration loads."""
         self._hass = hass
@@ -112,33 +145,19 @@ def update(self, state: DeviceState, last_cycle: Optional["Cycle"], timestamp: f
             self._last_flame_off_at = None
 
         self._record_flame_transitions(self._previous_state, state)
+        self._record_hot_water_transitions(self._previous_state, state)
 
         if self._modulation_tracker.update(state) and self._hass is not None:
             self._hass.create_task(self.async_save_data())
 
         self._current_status = self._determine_status()
 
     def _determine_status(self) -> BoilerStatus:
-        state = self._current_state
-        previous = self._previous_state
-
-        if state is None:
+        if (snapshot := self.status_snapshot) is None:
             # Should not happen in normal usage; treat as inactive.
             return BoilerStatus.OFF
 
-        return DeviceStatusEvaluator.evaluate(DeviceStatusSnapshot(
-            state=state,
-
-            last_cycle=self._last_cycle,
-            last_update_at=self._last_update_at,
-            last_flame_on_at=self._last_flame_on_at,
-            last_flame_off_at=self._last_flame_off_at,
-            last_flame_off_was_overshoot=self._last_flame_off_was_overshoot,
-
-            previous_state=previous,
-            previous_update_at=self._previous_update_at,
-            modulation_direction=self._determine_modulation_direction(),
-        ))
+        return DeviceStatusEvaluator.evaluate(snapshot)
 
     def _determine_modulation_direction(self) -> int:
         """Determine modulation direction."""
@@ -192,9 +211,25 @@ def _record_flame_transitions(self, previous: Optional[DeviceState], current: De
             self._last_flame_on_at = self._last_update_at
             self._last_flame_off_was_overshoot = False
 
+    def _record_hot_water_transitions(self, previous: Optional[DeviceState], current: DeviceState) -> None:
+        """Track domestic hot water ON/OFF timestamps."""
+        if previous is None:
+            if current.hot_water_active:
+                self._last_hot_water_on_at = self._last_update_at
+
+            return
+
+        if previous.hot_water_active and not current.hot_water_active:
+            # DHW ON -> OFF
+            self._last_hot_water_off_at = self._last_update_at
+
+        elif not previous.hot_water_active and current.hot_water_active:
+            # DHW OFF -> ON
+            self._last_hot_water_on_at = self._last_update_at
+
 
 __all__ = [
-    "DeviceTracker",
     "DeviceState",
+    "DeviceTracker",
     "DeviceCapabilities",
 ]

custom_components/sat/device/status.py

@@ -21,6 +21,8 @@ class DeviceStatusSnapshot:
     last_flame_on_at: Optional[float]
     last_flame_off_at: Optional[float]
     last_flame_off_was_overshoot: bool
+    last_hot_water_on_at: Optional[float]
+    last_hot_water_off_at: Optional[float]
 
     modulation_direction: int
     previous_update_at: Optional[float]

custom_components/sat/heating_control.py

@@ -12,15 +12,24 @@
 
 from .const import (
     COLD_SETPOINT,
+    DHW_OVERSHOOT_GUARD_SECONDS,
     MINIMUM_RELATIVE_MODULATION,
-    MINIMUM_SETPOINT, EVENT_SAT_CYCLE_ENDED,
+    MINIMUM_SETPOINT, EVENT_SAT_CYCLE_ENDED, UNDERHEAT_SUSTAIN_SECONDS, SATURATION_SUSTAIN_SECONDS, OVERSHOOT_SUSTAIN_SECONDS,
 )
 from .coordinator import SatDataUpdateCoordinator
 from .cycles import Cycle, CycleHistory, CycleStatistics, CycleTracker
-from .cycles.const import OVERSHOOT_MARGIN_CELSIUS, OVERSHOOT_SUSTAIN_SECONDS
+from .cycles.const import OVERSHOOT_MARGIN_CELSIUS, UNDERSHOOT_MARGIN_CELSIUS
 from .device import DeviceState, DeviceTracker
 from .entry_data import SatConfig
-from .helpers import event_timestamp, float_value, int_value, timestamp, clamp
+from .helpers import (
+    clamp,
+    event_timestamp,
+    float_value,
+    int_value,
+    is_within_elapsed_window,
+    sustained_runtime,
+    timestamp,
+)
 from .manufacturers.geminox import Geminox
 from .pwm import PWM, PWMState
 from .types import BoilerStatus, CycleControlMode, HeaterState, PWMStatus, RelativeModulationState
@@ -84,9 +93,12 @@ def __init__(self, hass: HomeAssistant, coordinator: SatDataUpdateCoordinator, c
         self._last_outside_temperature: Optional[float] = None
 
         self._flame_off_hold_setpoint: Optional[float] = None
-        self._sustained_overshoot_started_at: Optional[float] = None
         self._coordinator_listener_remove: Optional[Callable[[], None]] = None
 
+        self._sustained_overshoot_started_at: Optional[float] = None
+        self._sustained_underheat_started_at: Optional[float] = None
+        self._sustained_saturation_started_at: Optional[float] = None
+
     @property
     def device_status(self) -> BoilerStatus:
         """Report the current boiler status."""
@@ -172,8 +184,8 @@ def restore(self, old_state: State) -> None:
 
     def reset(self) -> None:
         """Reset heating control state on major changes."""
-        self._sustained_overshoot_started_at = None
         self._pwm.reset()
+        self._reset_pwm_disable_guards()
 
     async def update(self, demand: HeatingDemand) -> None:
         """Apply a new demand update and push commands to the coordinator."""
@@ -195,6 +207,11 @@ async def update(self, demand: HeatingDemand) -> None:
                 requested_setpoint=demand.requested_setpoint,
             )
 
+            self._maybe_disable_pwm_runtime(
+                demand=demand,
+                device_state=self._coordinator.state
+            )
+
             self._compute_relative_modulation_value()
 
             if self.control_mode == CycleControlMode.PWM:
@@ -204,8 +221,9 @@ async def update(self, demand: HeatingDemand) -> None:
                 self._compute_continuous_control_setpoint(demand.requested_setpoint)
         else:
             self._pwm.disable()
+            self._reset_pwm_disable_guards()
+
             self._control_setpoint = MINIMUM_SETPOINT
-            self._sustained_overshoot_started_at = None
             self._relative_modulation_value = self._config.pwm.maximum_relative_modulation
 
         await self._coordinator.async_set_control_setpoint(self._control_setpoint)
@@ -228,9 +246,9 @@ def _handle_coordinator_update(self, time: Optional[datetime] = None) -> None:
                 pwm=self._pwm.state,
                 device_state=self._coordinator.state,
                 control_setpoint=self._control_setpoint,
-                relative_modulation=self._relative_modulation_value,
                 requested_setpoint=self._last_requested_setpoint,
                 outside_temperature=self._last_outside_temperature,
+                relative_modulation=self._relative_modulation_value,
             )
         )
 
@@ -244,6 +262,10 @@ def _maybe_enable_pwm_on_sustained_overshoot(self, demand: HeatingDemand, device
             self._sustained_overshoot_started_at = None
             return
 
+        if is_within_elapsed_window(demand.timestamp, self._device_tracker.hot_water_off_since, DHW_OVERSHOOT_GUARD_SECONDS):
+            self._sustained_overshoot_started_at = None
+            return
+
         if demand.heater_state != HeaterState.ON:
             self._sustained_overshoot_started_at = None
             return
@@ -261,28 +283,88 @@ def _maybe_enable_pwm_on_sustained_overshoot(self, demand: HeatingDemand, device
             self._sustained_overshoot_started_at = None
             return
 
-        if self._sustained_overshoot_started_at is None:
-            self._sustained_overshoot_started_at = demand.timestamp
+        runtime = sustained_runtime(demand.timestamp, self._sustained_overshoot_started_at)
+        self._sustained_overshoot_started_at = runtime.started_at
+
+        if runtime.initialized or runtime.elapsed_seconds < OVERSHOOT_SUSTAIN_SECONDS:
             return
 
-        elapsed = demand.timestamp - self._sustained_overshoot_started_at
-        if elapsed < 0:
-            self._sustained_overshoot_started_at = demand.timestamp
+        _LOGGER.info(
+            "Sustained overshoot detected (flow=%.1f°C >= requested=%.1f°C + %.1f°C for %.0fs).",
+            device_state.flow_temperature, demand.requested_setpoint, OVERSHOOT_MARGIN_CELSIUS, runtime.elapsed_seconds
+        )
+
+        self._pwm.enable()
+        self._reset_pwm_disable_guards()
+
+    def _maybe_disable_pwm_runtime(self, demand: HeatingDemand, device_state: DeviceState) -> None:
+        if not self._pwm.enabled:
+            self._sustained_underheat_started_at = None
+            self._sustained_saturation_started_at = None
             return
 
-        if elapsed < OVERSHOOT_SUSTAIN_SECONDS:
+        if device_state.hot_water_active or is_within_elapsed_window(demand.timestamp, self._device_tracker.hot_water_off_since, DHW_OVERSHOOT_GUARD_SECONDS):
+            self._reset_pwm_disable_guards()
             return
 
+        if demand.heater_state != HeaterState.ON or demand.requested_setpoint <= COLD_SETPOINT:
+            self._reset_pwm_disable_guards()
+            return
+
+        if self._maybe_disable_pwm_on_sustained_underheat(demand=demand, device_state=device_state):
+            return
+
+        if self._maybe_disable_pwm_on_sustained_saturation(demand=demand):
+            return
+
+    def _maybe_disable_pwm_on_sustained_underheat(self, demand: HeatingDemand, device_state: DeviceState) -> bool:
+        flow_temperature = device_state.flow_temperature
+        if flow_temperature is None:
+            self._sustained_underheat_started_at = None
+            return False
+
+        underheat_threshold = demand.requested_setpoint + UNDERSHOOT_MARGIN_CELSIUS
+        if flow_temperature > underheat_threshold:
+            self._sustained_underheat_started_at = None
+            return False
+
+        runtime = sustained_runtime(demand.timestamp, self._sustained_underheat_started_at)
+        self._sustained_underheat_started_at = runtime.started_at
+
+        if runtime.initialized or runtime.elapsed_seconds < UNDERHEAT_SUSTAIN_SECONDS:
+            return False
+
         _LOGGER.info(
-            "Sustained overshoot detected (flow=%.1f°C >= requested=%.1f°C + %.1f°C for %.0fs).",
-            device_state.flow_temperature,
-            demand.requested_setpoint,
-            OVERSHOOT_MARGIN_CELSIUS,
-            elapsed,
+            "Disabling PWM due to sustained underheat (flow=%.1f°C <= requested=%.1f°C + %.1f°C for %.0fs).",
+            flow_temperature, demand.requested_setpoint, UNDERSHOOT_MARGIN_CELSIUS, runtime.elapsed_seconds,
         )
 
-        self._sustained_overshoot_started_at = None
-        self._pwm.enable()
+        self._pwm.disable()
+        self._reset_pwm_disable_guards()
+
+        return True
+
+    def _maybe_disable_pwm_on_sustained_saturation(self, demand: HeatingDemand) -> bool:
+        off_time_seconds = self._pwm.state.off_time_seconds
+        if off_time_seconds is None or off_time_seconds > 0:
+            self._sustained_saturation_started_at = None
+            return False
+
+        runtime = sustained_runtime(demand.timestamp, self._sustained_saturation_started_at)
+        self._sustained_saturation_started_at = runtime.started_at
+
+        if runtime.initialized or runtime.elapsed_seconds < SATURATION_SUSTAIN_SECONDS:
+            return False
+
+        _LOGGER.info(
+            "Disabling PWM due to sustained saturation (off_time=%ds for %.0fs).",
+            off_time_seconds, runtime.elapsed_seconds
+        )
+
+        self._pwm.disable()
+        self._reset_pwm_disable_guards()
+
+        return True
 
     def _compute_pwm_control_setpoint(self, requested_setpoint: float) -> None:
         """Apply the PWM setpoint override based on the current device state."""
@@ -428,3 +510,8 @@ def _compute_relative_modulation_value(self) -> None:
 
         if isinstance(self._coordinator.manufacturer, Geminox):
             self._relative_modulation_value = max(10, self._relative_modulation_value)
+
+    def _reset_pwm_disable_guards(self) -> None:
+        self._sustained_overshoot_started_at = None
+        self._sustained_underheat_started_at = None
+        self._sustained_saturation_started_at = None