Merge fix/dhw-scheduling-and-heating-rate-learning: DHW volatility fix, offset tracker, constants consolidation

Author: enoch85

.github/copilot-instructions.md

@@ -37,6 +37,12 @@ source .venv/bin/activate
 14. **Use Black formatting** - All Python code must be formatted with Black (line length 100)
 15. **No `Any` type imports** - Use specific types (dataclasses, TypedDict, Protocol, etc.)
 16. **All imports at file top** - Place all imports at the top of files to avoid circular imports
+17. **Fetch real prices for debugging** - When investigating price volatility or any price-related issue:
+    - First check which price region is configured (SE1-SE4, NO1-NO5, DK1-DK2, FI, etc.) from logs or config
+    - Fetch current prices from Nordpool API for that **same region**
+    - Use: `curl "https://www.nordpoolgroup.com/api/marketdata/page/10?currency=SEK&endDate=YYYY-MM-DD"` or fetch via `fetch_webpage` tool
+    - Alternative: `curl "https://dataportal-api.nordpoolgroup.com/api/DayAheadPrices?date=YYYY-MM-DD&market=DayAhead&deliveryArea=SE4&currency=SEK"`
+    - Compare actual API prices with values in debug logs to verify correct behavior
 
 ---
 

README.md

@@ -5,7 +5,7 @@
 <img src="icons/logo.png" alt="EffektGuard Logo" width="200"/>
 
 [![hacs_badge](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/integration)
-![Version](https://img.shields.io/badge/version-0.4.19-blue)
+![Version](https://img.shields.io/badge/version-0.4.20-beta.1-blue)
 ![HA](https://img.shields.io/badge/Home%20Assistant-2025.10%2B-blue)
 [![Sponsor on GitHub](https://img.shields.io/badge/sponsor-GitHub%20Sponsors-1f425f?logo=github&style=for-the-badge)](https://github.com/sponsors/enoch85)
 

custom_components/effektguard/const.py

@@ -627,9 +627,18 @@ class OptimizationModeConfig:
 # Based on typical NIBE F-series compressor behavior
 COMPRESSOR_RAMP_UP_MINUTES: Final = 30  # Minutes to reach full speed from idle
 COMPRESSOR_COOL_DOWN_MINUTES: Final = 15  # Minutes for thermal stabilization after reduction
-COMPRESSOR_MIN_CYCLE_MINUTES: Final = (
+
+# Minimum duration for volatility detection (Jan 4, 2026)
+# Used by both price volatility (short price runs) and offset volatility (rapid reversals)
+# Based on compressor dynamics: 30 min ramp-up + 15 min cool-down = 45 min
+# Single source of truth - use MINUTES for offset tracking, QUARTERS for price logic
+MINUTES_PER_QUARTER: Final = 15  # 15-minute price quarters
+VOLATILE_MIN_DURATION_MINUTES: Final = (
     COMPRESSOR_RAMP_UP_MINUTES + COMPRESSOR_COOL_DOWN_MINUTES
 )  # 45min total
+VOLATILE_MIN_DURATION_QUARTERS: Final = (
+    VOLATILE_MIN_DURATION_MINUTES // MINUTES_PER_QUARTER
+)  # 3 quarters (45min / 15min)
 
 # Price forecast lookahead (Nov 27, 2025)
 # Forward-looking price optimization: reduce heating when cheaper period coming soon
@@ -646,9 +655,6 @@ class OptimizationModeConfig:
 PRICE_FORECAST_EXPENSIVE_THRESHOLD: Final = (
     1.5  # Price ratio - upcoming > 150% of current = "much more expensive"
 )
-PRICE_FORECAST_MIN_DURATION: Final = (
-    COMPRESSOR_MIN_CYCLE_MINUTES // 15
-)  # quarters - derived from compressor dynamics (45min / 15min = 3)
 PRICE_FORECAST_REDUCTION_OFFSET: Final = (
     -1.5
 )  # °C - reduce heating when cheap period coming (Dec 5, 2025: strengthened from -1.0)
@@ -929,6 +935,13 @@ class OptimizationModeConfig:
 DHW_MIN_AMOUNT_MAX: Final = 30  # Config maximum: 30 minutes
 CONF_DHW_MIN_AMOUNT: Final = "dhw_min_amount"  # Config key for min hot water minutes
 
+# DHW temperature-based heating rate (measured from real F750 data 2025-12-22)
+# 19:00 → 20:00: 23.8°C → 37.8°C = 14°C in 60 min = 14°C/hour
+# Used as fallback when insufficient history for dynamic calculation
+# The dhw_optimizer uses calculate_heating_rate() for dynamic estimation from BT7 history
+DHW_DEFAULT_HEATING_RATE: Final = 14.0  # °C/hour (measured from debug log)
+DHW_AMOUNT_HEATING_BUFFER: Final = 0.5  # Hours buffer for scheduling (arrive early, not late)
+
 # DHW thermal debt fallback thresholds (used only if climate detector unavailable)
 # These are balanced fixed values for rare fallback scenarios
 DM_DHW_BLOCK_FALLBACK: Final = -340.0  # Fallback: Never start DHW below this DM

custom_components/effektguard/coordinator.py

@@ -35,6 +35,7 @@
     DHW_MIN_AMOUNT_DEFAULT,
     DHW_READY_THRESHOLD,
     DHW_SAFETY_MIN,
+    DHW_WEATHER_COOLDOWN_MINUTES,
     DM_THRESHOLD_START,
     DOMAIN,
     MIN_DHW_TARGET_TEMP,
@@ -62,6 +63,7 @@
 from .optimization.weather_learning import WeatherPatternLearner
 from .utils.compressor_monitor import CompressorHealthMonitor
 from .utils.time_utils import get_current_quarter
+from .utils.volatile_helpers import OffsetVolatilityTracker
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -267,18 +269,22 @@ def __init__(
             minutes=UPDATE_INTERVAL_MINUTES
         )  # Throttle to coordinator update interval
 
+        # Offset volatility tracking (prevents rapid back-and-forth offset changes)
+        # Uses same min duration as price volatility (45 min) for consistency
+        self._offset_volatility_tracker = OffsetVolatilityTracker()
+
         # Peak tracking metadata (for sensor attributes)
         self.peak_today_time: datetime | None = None  # When today's peak occurred
         self.peak_today_source: str = "unknown"  # external_meter, nibe_currents, estimate
         self.peak_today_quarter: int | None = None  # 15-min quarter (0-95) for effect tariff
         self.yesterday_peak: float = 0.0  # Yesterday's peak for comparison
 
-        # DHW tracking
+        # DHW tracking (unified: is_hot_water OR temp_lux active)
         self.last_dhw_heated = None  # Last time DHW was in heating mode
         self.last_dhw_temp = None  # Last BT7 temperature for trend analysis
         self.dhw_heating_start = None  # When current/last DHW cycle started
         self.dhw_heating_end = None  # When last DHW cycle ended
-        self.dhw_was_heating = False  # Track state changes
+        self.dhw_was_active = False  # Track DHW state (is_hot_water OR temp_lux)
 
         # Spot price savings tracking (per-cycle accumulation)
         self._daily_spot_savings: float = 0.0  # Accumulates during day, recorded at midnight
@@ -497,14 +503,8 @@ async def async_initialize_learning(self) -> None:
                 # Restore DHW optimizer state (critical for Legionella safety tracking)
                 if "dhw_state" in learned_data and self.dhw_optimizer:
                     dhw_state = learned_data["dhw_state"]
-                    if "last_legionella_boost" in dhw_state:
-                        self.dhw_optimizer.last_legionella_boost = datetime.fromisoformat(
-                            dhw_state["last_legionella_boost"]
-                        )
-                        _LOGGER.info(
-                            "Restored last Legionella boost: %s",
-                            self.dhw_optimizer.last_legionella_boost,
-                        )
+                    # Use the new restore method for all DHW state
+                    self.dhw_optimizer.restore_from_persistence(dhw_state)
 
                 # Initialize DHW history from Home Assistant recorder (resilience to restarts)
                 # This checks past 14 days of BT7 data to detect recent Legionella cycles
@@ -825,21 +825,45 @@ async def _async_update_data(self) -> dict[str, Any]:
                 else:
                     current_power_for_decision = self.peak_today
 
-                # Check if DHW temporary lux is active
+                # Check if DHW is active (EITHER is_hot_water sensor OR temp_lux switch)
                 # When NIBE heats DHW, flow temp reads charging temp (45-60°C), not space heating
+                is_hot_water = (
+                    nibe_data.is_hot_water if hasattr(nibe_data, "is_hot_water") else False
+                )
                 temp_lux_active = False
                 if self.temp_lux_entity:
                     lux_state = self.hass.states.get(self.temp_lux_entity)
                     temp_lux_active = lux_state is not None and lux_state.state == STATE_ON
 
+                # Unified DHW active state: either source means DHW is heating
+                dhw_is_active = is_hot_water or temp_lux_active
+
+                # Track DHW transition: active → inactive triggers weather layer cooldown
+                # When DHW stops, flow temp remains elevated - needs cooldown period
+                # Uses DHW_WEATHER_COOLDOWN_MINUTES (30 min) before weather comp re-enables
+                if self.dhw_was_active and not dhw_is_active:
+                    self.dhw_heating_end = dt_util.now()
+                    _LOGGER.info(
+                        "DHW heating stopped - triggering weather layer cooldown (%d min)",
+                        DHW_WEATHER_COOLDOWN_MINUTES,
+                    )
+                elif not self.dhw_was_active and dhw_is_active:
+                    self.dhw_heating_start = dt_util.now()
+                    _LOGGER.info(
+                        "DHW heating started (is_hot_water=%s, temp_lux=%s)",
+                        is_hot_water,
+                        temp_lux_active,
+                    )
+                self.dhw_was_active = dhw_is_active
+
                 decision = await self.hass.async_add_executor_job(
                     self.engine.calculate_decision,
                     nibe_data,
                     price_data,
                     weather_data,
                     self.peak_this_month,  # Monthly peak threshold to protect
                     current_power_for_decision,  # Current whole-house power consumption
-                    temp_lux_active,  # DHW heating active - skip weather comp
+                    dhw_is_active,  # DHW heating active - skip weather comp
                     self.dhw_heating_end,  # When DHW last stopped - for cooldown
                 )
 
@@ -884,6 +908,24 @@ async def _async_update_data(self) -> dict[str, Any]:
                 # Fall back to safe operation (no offset)
                 decision = get_safe_default_decision()
 
+        # Check for volatile offset reversal before applying
+        # Prevents rapid back-and-forth that the heat pump can't follow (same logic as price volatility)
+        if self._offset_volatility_tracker.is_reversal_volatile(decision.offset):
+            volatile_reason = self._offset_volatility_tracker.get_volatile_reason(decision.offset)
+            _LOGGER.info(
+                "Offset change blocked: %s (keeping %.1f°C)",
+                volatile_reason,
+                self._offset_volatility_tracker.last_offset,
+            )
+            # Keep the previous offset
+            decision = OptimizationDecision(
+                offset=self._offset_volatility_tracker.last_offset,
+                reasoning=f"[{volatile_reason}] {decision.reasoning}",
+            )
+        else:
+            # Record the new offset for volatility tracking
+            self._offset_volatility_tracker.record_change(decision.offset, decision.reasoning)
+
         # Update current state
         self.current_offset = decision.offset
         self.last_decision_time = dt_util.utcnow()
@@ -1052,29 +1094,9 @@ async def _async_update_data(self) -> dict[str, Any]:
         if nibe_data and hasattr(nibe_data, "dhw_top_temp") and nibe_data.dhw_top_temp is not None:
             current_dhw_temp = nibe_data.dhw_top_temp
 
-            # Check if DHW is actively heating (from NIBE MyUplink sensor)
-            # This is more accurate than temperature thresholds alone
-            is_actively_heating = (
-                nibe_data.is_hot_water if hasattr(nibe_data, "is_hot_water") else False
-            )
-
-            # Track DHW heating cycle transitions (start/stop)
-            if is_actively_heating and not self.dhw_was_heating:
-                # DHW heating just started
-                self.dhw_heating_start = now_time
-                _LOGGER.info("DHW heating started at %s", now_time.strftime("%H:%M:%S"))
-            elif not is_actively_heating and self.dhw_was_heating:
-                # DHW heating just stopped
-                self.dhw_heating_end = now_time
-                if self.dhw_heating_start:
-                    duration = (now_time - self.dhw_heating_start).total_seconds() / 60
-                    _LOGGER.info(
-                        "DHW heating stopped at %s (duration: %.1f minutes)",
-                        now_time.strftime("%H:%M:%S"),
-                        duration,
-                    )
-
-            self.dhw_was_heating = is_actively_heating
+            # Use unified DHW active state (tracked earlier in update cycle)
+            # dhw_was_active combines is_hot_water sensor + temp_lux switch
+            is_actively_heating = self.dhw_was_active
 
             # Determine status using actual heating status + temperature
             if is_actively_heating:
@@ -1941,6 +1963,7 @@ async def async_update_config(self, options: dict[str, Any]) -> None:
             "dhw_evening_hour",
             "dhw_evening_enabled",
             "dhw_target_temp",
+            CONF_DHW_MIN_AMOUNT,  # Include min_amount to trigger rebuild when changed
         }
 
         if any(key in options for key in dhw_keys):
@@ -1951,6 +1974,8 @@ async def async_update_config(self, options: dict[str, Any]) -> None:
             from .optimization.dhw_optimizer import DHWDemandPeriod
 
             dhw_target = float(options.get("dhw_target_temp", DEFAULT_DHW_TARGET_TEMP))
+            # Get user-configured minimum hot water amount (default 5 minutes)
+            dhw_min_amount = int(options.get(CONF_DHW_MIN_AMOUNT, DHW_MIN_AMOUNT_DEFAULT))
             demand_periods = []
 
             if options.get("dhw_morning_enabled", True):
@@ -1960,6 +1985,7 @@ async def async_update_config(self, options: dict[str, Any]) -> None:
                         availability_hour=morning_hour,
                         target_temp=dhw_target,
                         duration_hours=2,
+                        min_amount_minutes=dhw_min_amount,  # Apply user's configured min amount
                     )
                 )
 
@@ -1970,6 +1996,7 @@ async def async_update_config(self, options: dict[str, Any]) -> None:
                         availability_hour=evening_hour,
                         target_temp=dhw_target,
                         duration_hours=3,
+                        min_amount_minutes=dhw_min_amount,  # Apply user's configured min amount
                     )
                 )
 
@@ -2150,14 +2177,9 @@ async def _save_learned_data(
                 summary = weather_learner.get_pattern_database_summary()
                 learned_data["weather_summary"] = summary
 
-            # Save DHW optimizer state (critical for Legionella safety and max wait tracking)
+            # Save DHW optimizer state (critical for Legionella safety, heating rate learning)
             if self.dhw_optimizer:
-                dhw_state = {}
-                if self.dhw_optimizer.last_legionella_boost:
-                    dhw_state["last_legionella_boost"] = (
-                        self.dhw_optimizer.last_legionella_boost.isoformat()
-                    )
-                # Note: last_dhw_heating_time tracked by thermal debt tracker, not optimizer
+                dhw_state = self.dhw_optimizer.get_dhw_state_for_persistence()
                 if dhw_state:
                     learned_data["dhw_state"] = dhw_state
 

custom_components/effektguard/manifest.json

@@ -9,5 +9,5 @@
   "iot_class": "calculated",
   "issue_tracker": "https://github.com/enoch85/EffektGuard/issues",
   "requirements": ["numpy>=1.21.0"],
-  "version": "v0.4.19"
+  "version": "v0.4.20-beta.1"
 }