Enhance Heating & Cooling Degree Days integration with weather entity support

- Added support for weather entities to enable forecast-based degree days estimates.
- Introduced new sensors for estimated HDD/CDD for today and tomorrow.
- Implemented automatic migration of existing entities to a new unique_id format to prevent conflicts.
- Updated configuration flow to validate weather entities and handle reconfiguration.
- Improved error handling and logging for weather entity issues.
- Added translations and documentation updates for new features.

Author: alepee

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Weather entity support for forecast-based degree days estimates
+- New sensors: HDD/CDD Estimated Today (combines actual + forecast data)
+- New sensors: HDD/CDD Estimated Tomorrow (forecast-based)
+- Reconfiguration flow to update integration settings
+- Repairs platform to handle weather entity regression (no longer supports hourly forecasts)
+- Automatic refresh of forecast sensors when weather entity updates
+
+### Changed
+- Unique IDs now include entry_id to prevent conflicts with multiple instances
+- Forecast sensors values are rounded to 1 decimal place
+- Automatic migration of existing entities to new unique_id format (preserves history)
+
+### Fixed
+- Fixed duplicate unique_id errors when multiple integration instances are configured
+
 ## [1.0.2] - 2025-11-05
 
 ### Added

custom_components/heating_cooling_degree_days/__init__.py

@@ -4,7 +4,8 @@
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import Platform
-from homeassistant.core import HomeAssistant
+from homeassistant.core import HomeAssistant, callback
+from homeassistant.helpers.event import async_track_state_change
 
 from .const import (
     CONF_BASE_TEMPERATURE,
@@ -13,12 +14,14 @@
     CONF_INCLUDE_WEEKLY,
     CONF_TEMPERATURE_SENSOR,
     CONF_TEMPERATURE_UNIT,
+    CONF_WEATHER_ENTITY,
     DEFAULT_INCLUDE_COOLING,
     DEFAULT_INCLUDE_MONTHLY,
     DEFAULT_INCLUDE_WEEKLY,
     DOMAIN,
 )
 from .coordinator import HDDDataUpdateCoordinator
+from .migrations import async_migrate_entity_unique_ids
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -71,6 +74,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
             include_cooling=include_cooling,
             include_weekly=include_weekly,
             include_monthly=include_monthly,
+            weather_entity=entry.data.get(CONF_WEATHER_ENTITY),
         )
 
         # Load stored data before first refresh
@@ -84,6 +88,32 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         hass.data.setdefault(DOMAIN, {})
         hass.data[DOMAIN][entry.entry_id] = coordinator
 
+        # Migrate old entities with old unique_id format to new format
+        # This must be done BEFORE setting up platforms to avoid conflicts
+        await async_migrate_entity_unique_ids(hass, entry)
+
+        # Set up listener for weather entity changes if configured
+        weather_entity = entry.data.get(CONF_WEATHER_ENTITY)
+        if weather_entity:
+
+            @callback
+            def async_weather_state_changed(entity_id, old_state, new_state):
+                """Handle weather entity state changes."""
+                if new_state is None:
+                    return
+                # Trigger coordinator refresh when weather forecast updates
+                _LOGGER.debug(
+                    "Weather entity %s state changed, triggering coordinator refresh",
+                    entity_id,
+                )
+                hass.async_create_task(coordinator.async_request_refresh())
+
+            # Listen for changes to the weather entity
+            async_track_state_change(hass, weather_entity, async_weather_state_changed)
+            _LOGGER.debug(
+                "Registered state change listener for weather entity %s", weather_entity
+            )
+
         # Set up all the platforms
         _LOGGER.debug("Setting up platforms: %s", PLATFORMS)
         await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)

custom_components/heating_cooling_degree_days/calculations.py

@@ -1,11 +1,12 @@
 """Heating and Cooling Degree Days calculation functions."""
 
-from datetime import datetime
+from datetime import datetime, timedelta
 import logging
 
 from homeassistant.components.recorder import get_instance
 from homeassistant.components.recorder.history import get_significant_states
 from homeassistant.core import HomeAssistant
+from homeassistant.util import dt as dt_util
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -304,3 +305,242 @@ async def async_calculate_cdd(
 
     _LOGGER.debug("CDD calculation result: %.2f degree-days", result)
     return result
+
+
+def calculate_hdd_from_forecast(
+    forecast_data: list[dict], base_temp: float, start_time: datetime, end_time: datetime
+) -> float:
+    """Calculate HDD from weather forecast data.
+
+    Uses forecast entries that fall within the specified time range.
+    For each forecast entry, estimates HDD based on temperature and templow.
+
+    Args:
+        forecast_data: List of forecast dictionaries with 'datetime', 'temperature', 'templow'
+        base_temp: Base temperature for HDD calculation
+        start_time: Start of the period to calculate
+        end_time: End of the period to calculate
+
+    Returns:
+        float: Calculated HDD value rounded to 1 decimal place
+    """
+    if not forecast_data:
+        _LOGGER.debug("No forecast data provided for HDD calculation")
+        return 0
+
+    total_hdd = 0
+    used_forecasts = 0
+
+    for forecast in forecast_data:
+        # Get forecast datetime - handle both 'datetime' and 'dt' keys
+        forecast_dt = forecast.get("datetime") or forecast.get("dt")
+        if not forecast_dt:
+            continue
+
+        # Convert to datetime if it's a string
+        if isinstance(forecast_dt, str):
+            try:
+                forecast_dt = dt_util.parse_datetime(forecast_dt)
+            except (ValueError, TypeError):
+                _LOGGER.warning("Could not parse forecast datetime: %s", forecast_dt)
+                continue
+
+        # Skip if forecast is outside the time range
+        if forecast_dt < start_time or forecast_dt >= end_time:
+            continue
+
+        # Get temperature - for hourly forecasts, use temperature directly
+        # For daily forecasts, use templow and temperature average
+        temp = forecast.get("temperature")
+        templow = forecast.get("templow")
+
+        if temp is None:
+            continue
+
+        # For hourly forecasts, use temperature directly
+        # For daily forecasts (with templow), use average
+        if templow is not None:
+            avg_temp = (templow + temp) / 2
+        else:
+            avg_temp = temp
+
+        # Calculate HDD for this forecast period
+        # Assume each forecast represents approximately 1 hour
+        # (this is a simplification - actual duration may vary)
+        duration_days = 1.0 / 24.0  # 1 hour in days
+
+        # Calculate deficit from base temperature
+        deficit = max(0, base_temp - avg_temp)
+        forecast_hdd = deficit * duration_days
+
+        total_hdd += forecast_hdd
+        used_forecasts += 1
+
+    _LOGGER.debug(
+        "Calculated HDD from %d forecast entries: %.1f degree-days",
+        used_forecasts,
+        total_hdd,
+    )
+
+    return round(total_hdd, 1)
+
+
+def calculate_cdd_from_forecast(
+    forecast_data: list[dict], base_temp: float, start_time: datetime, end_time: datetime
+) -> float:
+    """Calculate CDD from weather forecast data.
+
+    Uses forecast entries that fall within the specified time range.
+    For each forecast entry, estimates CDD based on temperature and templow.
+
+    Args:
+        forecast_data: List of forecast dictionaries with 'datetime', 'temperature', 'templow'
+        base_temp: Base temperature for CDD calculation
+        start_time: Start of the period to calculate
+        end_time: End of the period to calculate
+
+    Returns:
+        float: Calculated CDD value rounded to 1 decimal place
+    """
+    if not forecast_data:
+        _LOGGER.debug("No forecast data provided for CDD calculation")
+        return 0
+
+    total_cdd = 0
+    used_forecasts = 0
+
+    for forecast in forecast_data:
+        # Get forecast datetime - handle both 'datetime' and 'dt' keys
+        forecast_dt = forecast.get("datetime") or forecast.get("dt")
+        if not forecast_dt:
+            continue
+
+        # Convert to datetime if it's a string
+        if isinstance(forecast_dt, str):
+            try:
+                forecast_dt = dt_util.parse_datetime(forecast_dt)
+            except (ValueError, TypeError):
+                _LOGGER.warning("Could not parse forecast datetime: %s", forecast_dt)
+                continue
+
+        # Skip if forecast is outside the time range
+        if forecast_dt < start_time or forecast_dt >= end_time:
+            continue
+
+        # Get temperature - for hourly forecasts, use temperature directly
+        # For daily forecasts, use templow and temperature average
+        temp = forecast.get("temperature")
+        templow = forecast.get("templow")
+
+        if temp is None:
+            continue
+
+        # For hourly forecasts, use temperature directly
+        # For daily forecasts (with templow), use average
+        if templow is not None:
+            avg_temp = (templow + temp) / 2
+        else:
+            avg_temp = temp
+
+        # Calculate CDD for this forecast period
+        # Assume each forecast represents approximately 1 hour
+        duration_days = 1.0 / 24.0  # 1 hour in days
+
+        # Calculate excess above base temperature
+        excess = max(0, avg_temp - base_temp)
+        forecast_cdd = excess * duration_days
+
+        total_cdd += forecast_cdd
+        used_forecasts += 1
+
+    _LOGGER.debug(
+        "Calculated CDD from %d forecast entries: %.1f degree-days",
+        used_forecasts,
+        total_cdd,
+    )
+
+    return round(total_cdd, 1)
+
+
+def combine_actual_and_forecast_hdd(
+    actual_readings: list[tuple[datetime, float]],
+    forecast_data: list[dict],
+    base_temp: float,
+    actual_end_time: datetime,
+    forecast_end_time: datetime,
+) -> float:
+    """Combine actual temperature readings with forecast data for HDD calculation.
+
+    Calculates HDD from actual readings up to actual_end_time, then adds
+    estimated HDD from forecast data for the remaining period.
+
+    Args:
+        actual_readings: List of (timestamp, temperature) tuples from actual sensor
+        forecast_data: List of forecast dictionaries
+        base_temp: Base temperature for HDD calculation
+        actual_end_time: End time for actual readings (start of forecast period)
+        forecast_end_time: End time for forecast period
+
+    Returns:
+        float: Combined HDD value rounded to 1 decimal place
+    """
+    # Calculate HDD from actual readings
+    actual_hdd = calculate_hdd_from_readings(actual_readings, base_temp)
+
+    # Calculate HDD from forecast for remaining period
+    forecast_hdd = calculate_hdd_from_forecast(
+        forecast_data, base_temp, actual_end_time, forecast_end_time
+    )
+
+    total_hdd = actual_hdd + forecast_hdd
+
+    _LOGGER.debug(
+        "Combined HDD: %.1f (actual) + %.1f (forecast) = %.1f",
+        actual_hdd,
+        forecast_hdd,
+        total_hdd,
+    )
+
+    return round(total_hdd, 1)
+
+
+def combine_actual_and_forecast_cdd(
+    actual_readings: list[tuple[datetime, float]],
+    forecast_data: list[dict],
+    base_temp: float,
+    actual_end_time: datetime,
+    forecast_end_time: datetime,
+) -> float:
+    """Combine actual temperature readings with forecast data for CDD calculation.
+
+    Calculates CDD from actual readings up to actual_end_time, then adds
+    estimated CDD from forecast data for the remaining period.
+
+    Args:
+        actual_readings: List of (timestamp, temperature) tuples from actual sensor
+        forecast_data: List of forecast dictionaries
+        base_temp: Base temperature for CDD calculation
+        actual_end_time: End time for actual readings (start of forecast period)
+        forecast_end_time: End time for forecast period
+
+    Returns:
+        float: Combined CDD value rounded to 1 decimal place
+    """
+    # Calculate CDD from actual readings
+    actual_cdd = calculate_cdd_from_readings(actual_readings, base_temp)
+
+    # Calculate CDD from forecast for remaining period
+    forecast_cdd = calculate_cdd_from_forecast(
+        forecast_data, base_temp, actual_end_time, forecast_end_time
+    )
+
+    total_cdd = actual_cdd + forecast_cdd
+
+    _LOGGER.debug(
+        "Combined CDD: %.1f (actual) + %.1f (forecast) = %.1f",
+        actual_cdd,
+        forecast_cdd,
+        total_cdd,
+    )
+
+    return round(total_cdd, 1)