diff --git a/README.de.md b/README.de.md index d00e10fe..36d73e5a 100644 --- a/README.de.md +++ b/README.de.md @@ -42,6 +42,7 @@ Diese Integration ist Open Source, weil ich daran glaube, der Community, die Hom ### Stromtarife & -netz - **Tarif-Integration** - Unterstützung für Tibber, Awattar, Nordpool, Octopus Energy und generische Preissensoren. +- **Externe Preisprognosen** - Ein optionaler [Prognosesensor](docs/price-forecast-input.de.md) übernimmt Vorhersagen eines eigenständigen Modells zur Diagnose. Veröffentlichte Tarifpreise bleiben die Grundlage der Steuerung. - **Einspeiselimit-Management** - Absorbieren potenziell abgeregelter Leistung möglich, z.B. wenn Einspeisebegrenzungen gelten. - **Netzsupplementierung** - Möglichkeit, eine bestimmte Menge an Netzstrom zu erlauben, um Geräte zusätzlich zu supplementieren. diff --git a/README.md b/README.md index b8bce928..a08f829d 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ The [0.4.0rc1 candidate notes](docs/release-candidate.md) explain migration and ### Tariffs & Grid - **Tariff Integration** - Support for Tibber, Awattar, Nordpool, Octopus Energy, and generic price sensors. +- **External Price Forecasts** - An optional [forecast sensor](docs/price-forecast-input.md) accepts predictions from a separate model for diagnostics. Published tariffs remain the basis for control. - **Export Limit Management** - Absorb would-be-curtailed power when feed-in caps apply. - **Grid Supplementation** - Allow a small amount of grid power to top up appliances. diff --git a/custom_components/pv_excess_control/config_flow.py b/custom_components/pv_excess_control/config_flow.py index b2da54aa..6b13ec7c 100644 --- a/custom_components/pv_excess_control/config_flow.py +++ b/custom_components/pv_excess_control/config_flow.py @@ -121,6 +121,7 @@ CONF_PLANNER_INTERVAL, CONF_PROTECT_FROM_PREEMPTION, CONF_PRICE_SENSOR, + CONF_PRICE_FORECAST_SENSOR, CONF_PV_POWER, CONF_HELPER_ONLY, CONF_REQUIRES_APPLIANCE, @@ -614,6 +615,11 @@ def _energy_schema( if tariff_provider != TariffProvider.NONE: schema_dict[vol.Required(CONF_PRICE_SENSOR, description={"suggested_value": d.get(CONF_PRICE_SENSOR)})] = SENSOR_ENTITY_SELECTOR + schema_dict[vol.Optional( + CONF_PRICE_FORECAST_SENSOR, + description={"suggested_value": d.get(CONF_PRICE_FORECAST_SENSOR)}, + )] = SENSOR_ENTITY_SELECTOR + schema_dict[vol.Optional( CONF_CHEAP_PRICE_THRESHOLD, description={"suggested_value": d.get(CONF_CHEAP_PRICE_THRESHOLD)}, @@ -1084,7 +1090,7 @@ async def async_step_energy( if not errors: self.data.update(user_input) # Clean optional energy keys not present in user_input - for key in [CONF_FEED_IN_TARIFF_SENSOR]: + for key in [CONF_FEED_IN_TARIFF_SENSOR, CONF_PRICE_FORECAST_SENSOR]: if key not in user_input: self.data.pop(key, None) return await self.async_step_forecast() @@ -1352,7 +1358,7 @@ async def async_step_energy( if not errors: self.data.update(user_input) # Clean optional energy keys not present in user_input - for key in [CONF_FEED_IN_TARIFF_SENSOR]: + for key in [CONF_FEED_IN_TARIFF_SENSOR, CONF_PRICE_FORECAST_SENSOR]: if key not in user_input: self.data.pop(key, None) return await self.async_step_forecast() diff --git a/custom_components/pv_excess_control/const.py b/custom_components/pv_excess_control/const.py index d9781f2e..c91b0732 100644 --- a/custom_components/pv_excess_control/const.py +++ b/custom_components/pv_excess_control/const.py @@ -124,6 +124,7 @@ class NotificationEvent(StrEnum): CONF_BATTERY_CAPACITY = "battery_capacity" CONF_TARIFF_PROVIDER = "tariff_provider" CONF_PRICE_SENSOR = "price_sensor" +CONF_PRICE_FORECAST_SENSOR = "price_forecast_sensor" CONF_CHEAP_PRICE_THRESHOLD = "cheap_price_threshold" CONF_BATTERY_CHARGE_PRICE_THRESHOLD = "battery_charge_price_threshold" CONF_FEED_IN_TARIFF = "feed_in_tariff" diff --git a/custom_components/pv_excess_control/coordinator.py b/custom_components/pv_excess_control/coordinator.py index 3e135647..dcc238d0 100644 --- a/custom_components/pv_excess_control/coordinator.py +++ b/custom_components/pv_excess_control/coordinator.py @@ -24,6 +24,7 @@ from homeassistant.util import dt as dt_util from .daily_state import nonnegative_number from .power_policy import battery_first_budget +from .price_forecast import PriceForecastError, parse_price_forecast from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed @@ -94,6 +95,7 @@ CONF_PLANNER_INTERVAL, CONF_PROTECT_FROM_PREEMPTION, CONF_PRICE_SENSOR, + CONF_PRICE_FORECAST_SENSOR, CONF_PV_POWER, CONF_REQUIRES_APPLIANCE, CONF_HELPER_ONLY, @@ -2409,6 +2411,32 @@ def _create_empty_plan(self) -> Plan: confidence=0.0, ) + def _read_price_forecast(self, *, now: datetime | None = None) -> dict[str, Any]: + """Read an optional forecast for diagnostics, outside tariff/control data.""" + entity_id = self.config_entry.data.get(CONF_PRICE_FORECAST_SENSOR) + result = { + "source_entity": entity_id or None, + "status": "not_configured", + "automation_eligible": False, + "snapshot": None, + } + if not entity_id: + return result + state = self.hass.states.get(entity_id) + if state is None: + result["status"] = "missing_sensor" + elif state.state in (STATE_UNKNOWN, STATE_UNAVAILABLE): + result["status"] = "unavailable" + else: + try: + snapshot = parse_price_forecast(state.attributes, now=now or dt_util.utcnow()) + except PriceForecastError as err: + result["status"] = str(err) + else: + result["status"] = "available" + result["snapshot"] = snapshot.as_dict() + return result + def _build_coordinator_data(self) -> dict[str, Any]: """Build a data dict that entity platforms can read.""" latest_power = self.power_history[-1] if self.power_history else None @@ -2427,6 +2455,7 @@ def _build_coordinator_data(self) -> dict[str, Any]: "battery_priority_status": getattr(self, "_battery_priority_status", "inactive"), "power_history": list(self.power_history), "current_plan": self.current_plan, + "price_forecast": self._read_price_forecast(), "forecast_status": getattr(self, "_forecast_status", "not_configured"), "forecast_remaining_today_kwh": getattr(getattr(self, "_forecast_data", None), "remaining_today_kwh", None), "forecast_tomorrow_total_kwh": getattr(getattr(self, "_forecast_data", None), "tomorrow_total_kwh", None), diff --git a/custom_components/pv_excess_control/price_forecast.py b/custom_components/pv_excess_control/price_forecast.py new file mode 100644 index 00000000..4b0b4f71 --- /dev/null +++ b/custom_components/pv_excess_control/price_forecast.py @@ -0,0 +1,148 @@ +"""Validate external electricity price forecasts without Home Assistant access. + +Version 1 is an observation contract. Its empirical bounds are not calibrated +probabilities and no accepted snapshot grants permission to control a device. +""" + +from __future__ import annotations + +from collections.abc import Mapping +from dataclasses import dataclass +from datetime import datetime, timedelta, timezone +import math +from typing import Any + + +class PriceForecastError(ValueError): + """A rejected snapshot, with a stable diagnostic reason.""" + + +@dataclass(frozen=True) +class PriceForecastInterval: + """One immutable interval with empirical price bounds in EUR/kWh.""" + + start: datetime + end: datetime + price: float + lower: float + upper: float + + def as_dict(self) -> dict[str, Any]: + """Return an independent JSON-compatible representation.""" + return { + "start": self.start.isoformat(), + "end": self.end.isoformat(), + "price": self.price, + "lower": self.lower, + "upper": self.upper, + } + + +@dataclass(frozen=True) +class PriceForecastSnapshot: + """An accepted forecast, deliberately distinct from a confirmed tariff.""" + + generated_at: datetime + expires_at: datetime + model: str + price_basis: str + intervals: tuple[PriceForecastInterval, ...] + + def as_dict(self) -> dict[str, Any]: + """Return only validated contract fields, without source-owned objects.""" + return { + "schema_version": 1, + "market": "DE-LU", + "unit": "EUR/kWh", + "price_basis": self.price_basis, + "generated_at": self.generated_at.isoformat(), + "expires_at": self.expires_at.isoformat(), + "model": self.model, + "quality": {"status": "experimental", "automation_eligible": False}, + "intervals": [row.as_dict() for row in self.intervals], + } + + +def _timestamp(value: Any) -> datetime: + if not isinstance(value, str): + raise PriceForecastError("invalid_timestamp") + try: + parsed = datetime.fromisoformat(value) + if parsed.tzinfo is None or parsed.utcoffset() is None: + raise ValueError("missing offset") + return parsed.astimezone(timezone.utc) + except (ValueError, OverflowError) as err: + raise PriceForecastError("invalid_timestamp") from err + + +def _number(value: Any) -> float: + if type(value) not in (int, float): + raise PriceForecastError("invalid_price") + try: + number = float(value) + except OverflowError as err: + raise PriceForecastError("invalid_price") from err + if not math.isfinite(number): + raise PriceForecastError("invalid_price") + return number + + +def parse_price_forecast(payload: Any, *, now: datetime) -> PriceForecastSnapshot: + """Validate version, meaning, freshness and interval coverage atomically. + + Missing, malformed or expired data raises ``PriceForecastError``. Zero and + negative prices are retained. Extra metadata is ignored rather than copied + into the accepted snapshot. All duration comparisons use UTC. + """ + if now.tzinfo is None or now.utcoffset() is None: + raise PriceForecastError("invalid_now") + now = now.astimezone(timezone.utc) + if not isinstance(payload, Mapping): + raise PriceForecastError("invalid_payload") + if type(payload.get("schema_version")) is not int or payload["schema_version"] != 1: + raise PriceForecastError("unsupported_schema") + if payload.get("market") != "DE-LU" or payload.get("unit") != "EUR/kWh": + raise PriceForecastError("unsupported_market_or_unit") + if payload.get("price_basis") not in ("wholesale", "retail"): + raise PriceForecastError("unsupported_price_basis") + quality = payload.get("quality") + if ( + not isinstance(quality, Mapping) + or quality.get("status") != "experimental" + or quality.get("automation_eligible") is not False + ): + raise PriceForecastError("unsupported_quality") + model = payload.get("model") + if not isinstance(model, str) or not model.strip() or len(model) > 128: + raise PriceForecastError("invalid_model") + generated = _timestamp(payload.get("generated_at")) + expires = _timestamp(payload.get("expires_at")) + if generated > now: + raise PriceForecastError("future_generation") + if not timedelta() < expires - generated <= timedelta(hours=6): + raise PriceForecastError("invalid_expiration") + if now >= expires: + raise PriceForecastError("expired") + rows = payload.get("intervals") + if not isinstance(rows, (list, tuple)) or not 1 <= len(rows) <= 672: + raise PriceForecastError("invalid_interval_count") + intervals = [] + previous_end = None + for row in rows: + if not isinstance(row, Mapping): + raise PriceForecastError("invalid_interval") + start, end = _timestamp(row.get("start")), _timestamp(row.get("end")) + if (end - start).total_seconds() not in (900, 1800, 3600): + raise PriceForecastError("invalid_interval_duration") + if previous_end is not None and start != previous_end: + raise PriceForecastError("noncontiguous_intervals") + if end - generated > timedelta(days=7): + raise PriceForecastError("horizon_too_long") + price, lower, upper = (_number(row.get(key)) for key in ("price", "lower", "upper")) + if not lower <= price <= upper: + raise PriceForecastError("invalid_bounds") + intervals.append(PriceForecastInterval(start, end, price, lower, upper)) + previous_end = end + if intervals[-1].end <= now: + raise PriceForecastError("no_future_intervals") + return PriceForecastSnapshot(generated, expires, model, payload["price_basis"], tuple(intervals)) diff --git a/custom_components/pv_excess_control/sensor.py b/custom_components/pv_excess_control/sensor.py index b775e333..d3b5aa8e 100644 --- a/custom_components/pv_excess_control/sensor.py +++ b/custom_components/pv_excess_control/sensor.py @@ -24,11 +24,11 @@ UnitOfTime, ) from homeassistant.core import HomeAssistant -from homeassistant.helpers.entity import DeviceInfo +from homeassistant.helpers.entity import DeviceInfo, EntityCategory from homeassistant.helpers.entity_platform import AddEntitiesCallback from homeassistant.helpers.update_coordinator import CoordinatorEntity -from .const import CONF_APPLIANCE_NAME, CONF_DYNAMIC_BATTERY_CHARGE_ENABLED, DOMAIN +from .const import CONF_APPLIANCE_NAME, CONF_DYNAMIC_BATTERY_CHARGE_ENABLED, CONF_PRICE_FORECAST_SENSOR, DOMAIN from .coordinator import PvExcessCoordinator from .entity_lifecycle import add_entities_by_subentry, device_info from .models import BatteryDischargeAction @@ -51,6 +51,10 @@ async def async_setup_entry( PvPlanConfidenceSensor(coordinator), ] + forecast_entity = getattr(config_entry, "data", {}).get(CONF_PRICE_FORECAST_SENSOR) + if isinstance(forecast_entity, str) and forecast_entity: + entities.append(PvPriceForecastSensor(coordinator)) + # Per-appliance sensors from subentries subentries = getattr(config_entry, "subentries", {}) for subentry_id, subentry in subentries.items(): @@ -107,6 +111,34 @@ def _data(self) -> dict[str, Any] | None: # --------------------------------------------------------------------------- +class PvPriceForecastSensor(PvExcessBaseSensor): + """Diagnostic status and validated external forecast, without control effects.""" + + _attr_icon = "mdi:chart-timeline-variant" + _attr_entity_category = EntityCategory.DIAGNOSTIC + _unrecorded_attributes = frozenset({"intervals"}) + + def __init__(self, coordinator: PvExcessCoordinator) -> None: + super().__init__(coordinator, "price_forecast", "Price Forecast") + + @property + def native_value(self) -> str: + """Report the input status, not a forecast price as a confirmed tariff.""" + return (self._data or {}).get("price_forecast", {}).get("status", "pending") + + @property + def extra_state_attributes(self) -> dict[str, Any]: + """Expose provenance and the current validated snapshot only.""" + data = (self._data or {}).get("price_forecast", {}) + attrs = {"source_entity": data.get("source_entity"), "automation_eligible": False} + if snapshot := data.get("snapshot"): + attrs.update(snapshot) + attrs["interval_count"] = len(snapshot["intervals"]) + attrs["forecast_start"] = snapshot["intervals"][0]["start"] + attrs["forecast_end"] = snapshot["intervals"][-1]["end"] + return attrs + + class PvExcessPowerSensor(PvExcessBaseSensor): """Sensor reporting current PV excess power in Watts.""" diff --git a/custom_components/pv_excess_control/strings.json b/custom_components/pv_excess_control/strings.json index 1b243cce..bb1dfea1 100644 --- a/custom_components/pv_excess_control/strings.json +++ b/custom_components/pv_excess_control/strings.json @@ -48,7 +48,8 @@ "cheap_price_threshold": "Cheap Price Threshold", "battery_charge_price_threshold": "Battery Charge Price Threshold", "feed_in_tariff": "Feed-in Tariff", - "feed_in_tariff_sensor": "Feed-in Tariff Sensor" + "feed_in_tariff_sensor": "Feed-in Tariff Sensor", + "price_forecast_sensor": "Electricity price forecast sensor (optional)" }, "data_description": { "tariff_provider": "Select your electricity price provider integration.", @@ -56,7 +57,8 @@ "cheap_price_threshold": "Price below which electricity is considered cheap.", "battery_charge_price_threshold": "Price below which battery charging from grid is allowed.", "feed_in_tariff": "Price received per kWh for energy exported to the grid.", - "feed_in_tariff_sensor": "Optional sensor for dynamic feed-in tariff (overrides static value)" + "feed_in_tariff_sensor": "Optional sensor for dynamic feed-in tariff (overrides static value)", + "price_forecast_sensor": "Optional external sensor with versioned price forecasts. Diagnostics only: forecasts do not replace published tariff prices or trigger charging." } }, "forecast": { @@ -467,7 +469,8 @@ "cheap_price_threshold": "Cheap Price Threshold", "battery_charge_price_threshold": "Battery Charge Price Threshold", "feed_in_tariff": "Feed-in Tariff", - "feed_in_tariff_sensor": "Feed-in Tariff Sensor" + "feed_in_tariff_sensor": "Feed-in Tariff Sensor", + "price_forecast_sensor": "Electricity price forecast sensor (optional)" }, "data_description": { "tariff_provider": "Select your electricity price provider integration.", @@ -475,7 +478,8 @@ "cheap_price_threshold": "Price below which electricity is considered cheap.", "battery_charge_price_threshold": "Price below which battery charging from grid is allowed.", "feed_in_tariff": "Price received per kWh for energy exported to the grid.", - "feed_in_tariff_sensor": "Optional sensor for dynamic feed-in tariff (overrides static value)" + "feed_in_tariff_sensor": "Optional sensor for dynamic feed-in tariff (overrides static value)", + "price_forecast_sensor": "Optional external sensor with versioned price forecasts. Diagnostics only: forecasts do not replace published tariff prices or trigger charging." } }, "forecast": { diff --git a/custom_components/pv_excess_control/translations/de.json b/custom_components/pv_excess_control/translations/de.json index 6f702c98..f159cbae 100644 --- a/custom_components/pv_excess_control/translations/de.json +++ b/custom_components/pv_excess_control/translations/de.json @@ -103,6 +103,15 @@ "additional_forecast_sensors": "Prognosen separater PV-Flächen. Doppelte Entity-IDs zählen nur einmal; keinen bereits enthaltenen Summensensor ergänzen.", "additional_forecast_tomorrow_sensors": "Diese Quellen und der einzelne Morgen-Sensor ersetzen gemeinsam den morgigen Anteil der primären Prognosen. Alle morgigen Flächen angeben." } + }, + "energy": { + "title": "Strompreise", + "data": { + "price_forecast_sensor": "Strompreis-Prognosesensor (optional)" + }, + "data_description": { + "price_forecast_sensor": "Optionaler externer Sensor mit versionierten Preisprognosen. Nur Diagnose: Prognosen ersetzen keine veröffentlichten Tarifpreise und lösen keine Ladung aus." + } } } }, @@ -127,6 +136,15 @@ "additional_forecast_sensors": "Prognosen separater PV-Flächen. Doppelte Entity-IDs zählen nur einmal; keinen bereits enthaltenen Summensensor ergänzen.", "additional_forecast_tomorrow_sensors": "Diese Quellen und der einzelne Morgen-Sensor ersetzen gemeinsam den morgigen Anteil der primären Prognosen. Alle morgigen Flächen angeben." } + }, + "energy": { + "title": "Strompreise", + "data": { + "price_forecast_sensor": "Strompreis-Prognosesensor (optional)" + }, + "data_description": { + "price_forecast_sensor": "Optionaler externer Sensor mit versionierten Preisprognosen. Nur Diagnose: Prognosen ersetzen keine veröffentlichten Tarifpreise und lösen keine Ladung aus." + } } } } diff --git a/custom_components/pv_excess_control/translations/en.json b/custom_components/pv_excess_control/translations/en.json index 1b243cce..bb1dfea1 100644 --- a/custom_components/pv_excess_control/translations/en.json +++ b/custom_components/pv_excess_control/translations/en.json @@ -48,7 +48,8 @@ "cheap_price_threshold": "Cheap Price Threshold", "battery_charge_price_threshold": "Battery Charge Price Threshold", "feed_in_tariff": "Feed-in Tariff", - "feed_in_tariff_sensor": "Feed-in Tariff Sensor" + "feed_in_tariff_sensor": "Feed-in Tariff Sensor", + "price_forecast_sensor": "Electricity price forecast sensor (optional)" }, "data_description": { "tariff_provider": "Select your electricity price provider integration.", @@ -56,7 +57,8 @@ "cheap_price_threshold": "Price below which electricity is considered cheap.", "battery_charge_price_threshold": "Price below which battery charging from grid is allowed.", "feed_in_tariff": "Price received per kWh for energy exported to the grid.", - "feed_in_tariff_sensor": "Optional sensor for dynamic feed-in tariff (overrides static value)" + "feed_in_tariff_sensor": "Optional sensor for dynamic feed-in tariff (overrides static value)", + "price_forecast_sensor": "Optional external sensor with versioned price forecasts. Diagnostics only: forecasts do not replace published tariff prices or trigger charging." } }, "forecast": { @@ -467,7 +469,8 @@ "cheap_price_threshold": "Cheap Price Threshold", "battery_charge_price_threshold": "Battery Charge Price Threshold", "feed_in_tariff": "Feed-in Tariff", - "feed_in_tariff_sensor": "Feed-in Tariff Sensor" + "feed_in_tariff_sensor": "Feed-in Tariff Sensor", + "price_forecast_sensor": "Electricity price forecast sensor (optional)" }, "data_description": { "tariff_provider": "Select your electricity price provider integration.", @@ -475,7 +478,8 @@ "cheap_price_threshold": "Price below which electricity is considered cheap.", "battery_charge_price_threshold": "Price below which battery charging from grid is allowed.", "feed_in_tariff": "Price received per kWh for energy exported to the grid.", - "feed_in_tariff_sensor": "Optional sensor for dynamic feed-in tariff (overrides static value)" + "feed_in_tariff_sensor": "Optional sensor for dynamic feed-in tariff (overrides static value)", + "price_forecast_sensor": "Optional external sensor with versioned price forecasts. Diagnostics only: forecasts do not replace published tariff prices or trigger charging." } }, "forecast": { diff --git a/docs/price-forecast-input.de.md b/docs/price-forecast-input.de.md new file mode 100644 index 00000000..89795d70 --- /dev/null +++ b/docs/price-forecast-input.de.md @@ -0,0 +1,86 @@ +# Eingang für externe Strompreisprognosen + +Das Vorhersagemodell läuft unabhängig von dieser Integration. Wähle seinen +Home-Assistant-Sensor unter **Konfigurieren → Strompreise → Strompreis-Prognosesensor**. +Die Angabe ist optional und unabhängig vom Tarifanbieter. Zum Entfernen die +Auswahl leeren. Nach Abschluss der Optionen wird der Eintrag neu geladen. + +Version 1 dient der Beobachtung und Auswertung. Sie erstellt einen Diagnosesensor +**Price Forecast** mit Quelle, Modell, Zeitstempeln und angenommenen Intervallen. +`available` bedeutet, dass Struktur und Datenfrische geprüft wurden; es bestätigt +keine Prognosegenauigkeit. Prognosen ersetzen keine bestätigten Tarifintervalle, +starten keine Ladung, ändern kein Batterieziel und geben keine Verbraucher frei. + +## Sensorformat + +Die Attribute des Quellsensors enthalten das unten gezeigte JSON-Objekt. Sein +Zustand kann `experimental` oder ein anderer verfügbarer Wert sein; `unknown` +und `unavailable` werden immer abgewiesen. Die Werte zeigen das Format und sind +keine aktuelle Prognose. + +```json +{ + "schema_version": 1, + "market": "DE-LU", + "unit": "EUR/kWh", + "price_basis": "wholesale", + "generated_at": "2026-11-01T12:00:00+00:00", + "expires_at": "2026-11-01T18:00:00+00:00", + "model": "calendar-v1", + "quality": {"status": "experimental", "automation_eligible": false}, + "intervals": [ + { + "start": "2026-11-01T13:00:00+00:00", + "end": "2026-11-01T14:00:00+00:00", + "price": 0.08, + "lower": 0.02, + "upper": 0.14 + } + ] +} +``` + +- `schema_version` ist die ganze Zahl `1`, der Markt `DE-LU`, die Einheit + `EUR/kWh`. +- `price_basis` ist `wholesale` oder `retail`. Großhandelspreise enthalten keine + Gebühren und Steuern des Haushaltstarifs; dieser Eingang rechnet sie nicht um. +- Jeder Zeitstempel enthält einen Zeitzonen-Offset; UTC wird empfohlen. Die + Erstellung darf nicht in der Zukunft liegen. Der Ablauf muss nach der + Erstellung und höchstens sechs Stunden später liegen. Ab diesem Zeitpunkt + wird der Datensatz abgewiesen. +- Zulässig sind 1–672 chronologische, lückenlos anschließende Intervalle mit + jeweils 15, 30 oder 60 Minuten Dauer. Jedes Ende liegt höchstens sieben + tatsächlich vergangene Tage nach der Erstellung. Mindestens ein Intervall + reicht noch in die Zukunft. UTC-Vergleiche erhalten Zeitumstellungen korrekt. +- Preise und Grenzen sind endliche JSON-Zahlen mit `lower <= price <= upper`. + Null und negative Preise sind gültig. Fehlende Zahlen, Wahrheitswerte, NaN und + Unendlich werden abgewiesen; fehlende Daten werden niemals zu null. +- `model` ist eine nichtleere Zeichenkette mit höchstens 128 Zeichen. Unterstützt + wird `experimental` mit dem booleschen Wert `automation_eligible: false`. + Grenzen beschreiben empirische Streuung und keine nachgewiesene + Wahrscheinlichkeitsabdeckung. +- Zusätzliche Metadaten sind erlaubt, werden aber nicht in den angenommenen + Datensatz übernommen. + +Ein unabhängiger Anbieter kann dieses JSON über einen Home-Assistant-REST- oder +MQTT-Sensor bereitstellen. Anbieter können dasselbe Format liefern, ohne +Modellabhängigkeiten in dieser Integration zu installieren. + +## Diagnose und Historie + +Der Diagnosesensor meldet `not_configured`, `missing_sensor`, `unavailable`, +`expired`, `no_future_intervals` oder einen Prüfgrund wie `unsupported_schema`, +`unsupported_market_or_unit`, `unsupported_quality`, `future_generation`, +`invalid_price`, `invalid_bounds` oder `noncontiguous_intervals`. Abgewiesene Daten +entfernen den angenommenen Datensatz bei der nächsten Koordinatoraktualisierung; +eine frühere erfolgreiche Prognose wird nicht als aktuell weitergeführt. + +Die angenommenen Attribute enthalten `forecast_start`, `forecast_end`, +`interval_count`, Erstellungs- und Ablaufzeit sowie die Intervalle. Das große +Attribut `intervals` dieses Diagnosesensors wird nicht im Recorder gespeichert. +Den rohen Quellsensor bei großen Kurven gegebenenfalls ebenfalls vom Recorder +ausschließen. + +Die Zuverlässigkeitsbewertung und eine spätere Verwendung für Batterieentscheidungen +sind eine getrennte Entwicklungsstufe. Dieser Eingang verlängert nicht den +Horizont des aktiven Planers. diff --git a/docs/price-forecast-input.md b/docs/price-forecast-input.md new file mode 100644 index 00000000..3a58c449 --- /dev/null +++ b/docs/price-forecast-input.md @@ -0,0 +1,80 @@ +# External electricity price forecast input + +The forecasting model runs independently of this integration. Select its Home +Assistant sensor in **Configure → Energy Pricing → Electricity price forecast +sensor**. This setting is optional and independent of the tariff provider. Clear +the selector to remove the input. Completing the options flow reloads the entry. + +Version 1 is for observation and evaluation. It creates a **Price Forecast** +diagnostic sensor with source, model, timestamps and accepted intervals. A status +of `available` means that the input passed structural and freshness validation; +it does not certify prediction accuracy. Forecasts never replace confirmed tariff +windows, start charging, change a battery target or authorize appliance control. + +## Sensor contract + +The source sensor's attributes must contain this JSON object. Its state can be +`experimental` or another available value; `unknown` and `unavailable` are always +rejected. Values below illustrate the format, not a current forecast. + +```json +{ + "schema_version": 1, + "market": "DE-LU", + "unit": "EUR/kWh", + "price_basis": "wholesale", + "generated_at": "2026-11-01T12:00:00+00:00", + "expires_at": "2026-11-01T18:00:00+00:00", + "model": "calendar-v1", + "quality": {"status": "experimental", "automation_eligible": false}, + "intervals": [ + { + "start": "2026-11-01T13:00:00+00:00", + "end": "2026-11-01T14:00:00+00:00", + "price": 0.08, + "lower": 0.02, + "upper": 0.14 + } + ] +} +``` + +- `schema_version` is the integer `1`, market `DE-LU`, unit `EUR/kWh`. +- `price_basis` is `wholesale` or `retail`. Wholesale prices exclude the household + tariff's fees and taxes; the input does not perform that conversion. +- Every timestamp includes a timezone offset. UTC is recommended. Generation + cannot be in the future, and expiration must be after generation and no more + than six hours later. At expiration the snapshot is rejected. +- There are 1–672 chronological, contiguous intervals lasting 15, 30 or 60 + minutes. Each end is at most seven elapsed days after generation. At least one + interval must still extend into the future. UTC comparisons preserve daylight + saving transitions. +- Prices and bounds are finite JSON numbers with `lower <= price <= upper`. + Zero and negative prices are valid. Missing numbers, booleans, NaN and infinity + are rejected; missing data never becomes zero. +- `model` is a nonempty string of at most 128 characters. The supported quality + is `experimental` with boolean `automation_eligible: false`. Bounds describe + empirical spread, not demonstrated probability coverage. +- Additional metadata is allowed but is not copied into the accepted snapshot. + +An independent producer can expose this JSON through a Home Assistant REST or +MQTT sensor. Producers can implement the same contract without adding forecasting +dependencies to this integration. + +## Diagnostics and history + +The diagnostic sensor reports `not_configured`, `missing_sensor`, `unavailable`, +`expired`, `no_future_intervals` or a validation reason such as +`unsupported_schema`, `unsupported_market_or_unit`, `unsupported_quality`, +`future_generation`, `invalid_price`, `invalid_bounds`, or +`noncontiguous_intervals`. Rejected input clears the accepted snapshot on the next +coordinator update; an old successful forecast is not retained as current. + +Accepted attributes include `forecast_start`, `forecast_end`, `interval_count`, +the model's generation/expiration times and its intervals. The large `intervals` +attribute is excluded from Recorder for this diagnostic entity. Exclude the raw +source sensor from Recorder separately if it also carries a large curve. + +Reliability evaluation and any future use of forecasts for battery decisions +belong to a separate development stage. This input does not extend the active +planner's horizon. diff --git a/scripts/public-docs.txt b/scripts/public-docs.txt index 08e33384..6d61dfd3 100644 --- a/scripts/public-docs.txt +++ b/scripts/public-docs.txt @@ -32,6 +32,8 @@ docs/generic-controls.md docs/installation.md docs/inverter-grid-charge-setup.md docs/migration.md +docs/price-forecast-input.de.md +docs/price-forecast-input.md docs/release-candidate.de.md docs/release-candidate.md docs/stabilization.md diff --git a/tests/test_price_forecast.py b/tests/test_price_forecast.py new file mode 100644 index 00000000..b572bd4a --- /dev/null +++ b/tests/test_price_forecast.py @@ -0,0 +1,237 @@ +"""External price forecasts must remain explicit, bounded and observation-only.""" + +from copy import deepcopy +from datetime import datetime, timedelta, timezone +from importlib import import_module +from pathlib import Path +from types import SimpleNamespace +from unittest.mock import MagicMock + +import pytest + + +NOW = datetime(2026, 11, 1, 12, tzinfo=timezone.utc) + + +def payload(): + return { + "schema_version": 1, + "market": "DE-LU", + "unit": "EUR/kWh", + "price_basis": "wholesale", + "generated_at": NOW.isoformat(), + "expires_at": (NOW + timedelta(hours=6)).isoformat(), + "model": "calendar-v1", + "quality": {"status": "experimental", "automation_eligible": False}, + "intervals": [{ + "start": NOW.isoformat(), + "end": (NOW + timedelta(minutes=15)).isoformat(), + "price": 0.0, + "lower": -0.03, + "upper": 0.04, + }], + } + + +def parser(): + # Attribute assertion makes the first red run report the missing feature. + package = import_module("custom_components.pv_excess_control") + assert (module_path := Path(package.__file__).parent / "price_forecast.py").exists(), str(module_path) + return import_module("custom_components.pv_excess_control.price_forecast") + + +def test_zero_and_negative_prices_are_preserved_and_input_is_not_mutated(): + source = payload() + expected = deepcopy(source) + snapshot = parser().parse_price_forecast(source, now=NOW) + assert snapshot.as_dict() == expected + assert source == expected + source["intervals"][0]["price"] = 100 + assert snapshot.as_dict()["intervals"][0]["price"] == 0 + expected["intervals"][0]["price"] = -0.01 + assert parser().parse_price_forecast(expected, now=NOW).intervals[0].price == -0.01 + + +@pytest.mark.parametrize("field,value", [ + ("schema_version", True), ("schema_version", 1.0), ("schema_version", 2), + ("unit", "ct/kWh"), ("market", "FR"), ("price_basis", "unknown"), + ("model", ""), ("generated_at", "2026-11-01T12:00:00"), + ("generated_at", (NOW + timedelta(seconds=1)).isoformat()), + ("expires_at", NOW.isoformat()), + ("expires_at", (NOW + timedelta(hours=7)).isoformat()), + ("quality", {"status": "validated", "automation_eligible": True}), + ("quality", {"status": "experimental", "automation_eligible": 0}), + ("intervals", []), +]) +def test_invalid_envelope_rejected(field, value): + source = payload() + source[field] = value + with pytest.raises(ValueError): + parser().parse_price_forecast(source, now=NOW) + + +@pytest.mark.parametrize("field,value", [ + ("price", None), ("price", True), ("price", "0.01"), ("price", float("nan")), + ("lower", float("-inf")), ("upper", float("inf")), + ("lower", 0.01), ("upper", -0.01), + ("end", (NOW + timedelta(minutes=5)).isoformat()), + ("start", "2026-11-01T12:00:00"), +]) +def test_invalid_interval_rejected(field, value): + source = payload() + source["intervals"][0][field] = value + with pytest.raises(ValueError): + parser().parse_price_forecast(source, now=NOW) + + +@pytest.mark.parametrize("offset", [0, 10, 30]) +def test_duplicate_overlap_and_gap_rejected(offset): + source = payload() + second = dict(source["intervals"][0]) + second["start"] = (NOW + timedelta(minutes=offset)).isoformat() + second["end"] = (NOW + timedelta(minutes=offset + 15)).isoformat() + source["intervals"].append(second) + with pytest.raises(ValueError): + parser().parse_price_forecast(source, now=NOW) + + +def test_horizon_and_interval_count_are_bounded(): + source = payload() + source["intervals"][0]["start"] = (NOW + timedelta(days=7)).isoformat() + source["intervals"][0]["end"] = (NOW + timedelta(days=7, minutes=15)).isoformat() + with pytest.raises(ValueError): + parser().parse_price_forecast(source, now=NOW) + source = payload() + source["intervals"] *= 673 + with pytest.raises(ValueError): + parser().parse_price_forecast(source, now=NOW) + + +def test_expired_data_and_exhausted_horizon_are_distinct(): + module = parser() + with pytest.raises(module.PriceForecastError, match="expired"): + module.parse_price_forecast(payload(), now=NOW + timedelta(hours=6)) + with pytest.raises(module.PriceForecastError, match="no_future_intervals"): + module.parse_price_forecast(payload(), now=NOW + timedelta(minutes=15)) + + +def test_dst_offsets_are_compared_as_elapsed_time(): + source = payload() + source["generated_at"] = "2026-10-25T00:00:00+00:00" + source["expires_at"] = "2026-10-25T06:00:00+00:00" + source["intervals"] = [ + {"start": "2026-10-25T02:00:00+02:00", "end": "2026-10-25T02:00:00+01:00", "price": 0, "lower": -0.1, "upper": 0.1}, + {"start": "2026-10-25T02:00:00+01:00", "end": "2026-10-25T03:00:00+01:00", "price": 0.2, "lower": 0.1, "upper": 0.3}, + ] + snapshot = parser().parse_price_forecast(source, now=datetime(2026, 10, 25, tzinfo=timezone.utc)) + assert snapshot.intervals[-1].end - snapshot.intervals[0].start == timedelta(hours=2) + + +def test_diagnostics_do_not_change_confirmed_tariffs_or_control(coordinator_factory, mock_tariff_at): + coordinator = coordinator_factory(config_data={"price_forecast_sensor": "sensor.forecast"}) + source = payload() + state = SimpleNamespace(state="experimental", attributes=source) + coordinator.hass.states.get.return_value = state + tariff = mock_tariff_at(0.5) + coordinator._last_tariff_info = tariff + original_data = dict(coordinator.config_entry.data) + assert hasattr(coordinator, "_read_price_forecast") + result = coordinator._read_price_forecast(now=NOW) + assert result["status"] == "available" + assert result["snapshot"]["intervals"][0]["price"] == 0 + assert result["automation_eligible"] is False + assert coordinator._last_tariff_info is tariff + assert tariff.current_price == 0.5 + assert coordinator._grid_charge_engaged is False + assert coordinator.config_entry.data == original_data + coordinator.hass.services.async_call.assert_not_called() + + +@pytest.mark.parametrize("state,expected", [(None, "missing_sensor"), ("unavailable", "unavailable"), ("unknown", "unavailable")]) +def test_unavailable_state_does_not_expose_old_predictions(coordinator_factory, state, expected): + coordinator = coordinator_factory(config_data={"price_forecast_sensor": "sensor.forecast"}) + coordinator.hass.states.get.return_value = None if state is None else SimpleNamespace(state=state, attributes=payload()) + assert hasattr(coordinator, "_read_price_forecast") + result = coordinator._read_price_forecast(now=NOW) + assert result["status"] == expected + assert result["snapshot"] is None + + +def test_absent_configuration_does_not_read_sensor(coordinator_factory): + coordinator = coordinator_factory() + assert hasattr(coordinator, "_read_price_forecast") + assert coordinator._read_price_forecast(now=NOW)["status"] == "not_configured" + coordinator.hass.states.get.assert_not_called() + + +@pytest.mark.parametrize("options", [False, True]) +async def test_energy_flow_accepts_and_clears_optional_input(options): + if options: + from tests.test_options_flow import _make_options_flow + flow = _make_options_flow() + else: + from tests.test_config_flow import _make_flow + flow = _make_flow() + from custom_components.pv_excess_control.config_flow import _energy_schema + schema = _energy_schema("none") + assert "price_forecast_sensor" in {str(key.schema) for key in schema.schema} + await flow.async_step_energy({"tariff_provider": "none", "price_forecast_sensor": "sensor.forecast"}) + assert flow.data["price_forecast_sensor"] == "sensor.forecast" + await flow.async_step_energy({"tariff_provider": "none"}) + assert "price_forecast_sensor" not in flow.data + + +def test_diagnostic_sensor_excludes_large_curve_from_recorder(): + sensors = import_module("custom_components.pv_excess_control.sensor") + assert hasattr(sensors, "PvPriceForecastSensor") + coordinator = MagicMock() + coordinator.data = {"price_forecast": {"status": "available", "source_entity": "sensor.forecast", "automation_eligible": False, "snapshot": payload()}} + sensor = sensors.PvPriceForecastSensor(coordinator) + assert sensor.native_value == "available" + assert sensor.extra_state_attributes["intervals"] == payload()["intervals"] + assert "intervals" in sensor._unrecorded_attributes + coordinator.data["price_forecast"] = {"status": "expired", "source_entity": "sensor.forecast", "automation_eligible": False, "snapshot": None} + assert sensor.native_value == "expired" + assert "intervals" not in sensor.extra_state_attributes + + +def test_updated_source_and_expiry_are_reflected_without_cached_snapshot(coordinator_factory, monkeypatch): + coordinator = coordinator_factory(config_data={"price_forecast_sensor": "sensor.first"}) + coordinator.hass.states.get.return_value = SimpleNamespace(state="experimental", attributes=payload()) + monkeypatch.setattr("custom_components.pv_excess_control.coordinator.dt_util.utcnow", lambda: NOW) + data = coordinator._build_coordinator_data() + assert data["price_forecast"]["status"] == "available" + coordinator.config_entry.data["price_forecast_sensor"] = "sensor.second" + monkeypatch.setattr("custom_components.pv_excess_control.coordinator.dt_util.utcnow", lambda: NOW + timedelta(hours=6)) + data = coordinator._build_coordinator_data() + assert data["price_forecast"]["source_entity"] == "sensor.second" + assert data["price_forecast"]["status"] == "expired" + assert data["price_forecast"]["snapshot"] is None + coordinator.config_entry.data.pop("price_forecast_sensor") + assert coordinator._build_coordinator_data()["price_forecast"]["status"] == "not_configured" + + +@pytest.mark.parametrize("attributes", [None, [], {}, {"schema_version": 1}]) +def test_malformed_input_is_contained_in_diagnostics(coordinator_factory, attributes): + coordinator = coordinator_factory(config_data={"price_forecast_sensor": "sensor.forecast"}) + coordinator.hass.states.get.return_value = SimpleNamespace(state="experimental", attributes=attributes) + data = coordinator._build_coordinator_data()["price_forecast"] + assert data["status"] != "available" + assert data["snapshot"] is None + coordinator.hass.services.async_call.assert_not_called() + + +async def test_sensor_registered_only_for_configured_input(): + from custom_components.pv_excess_control.const import DOMAIN + from custom_components.pv_excess_control.sensor import PvPriceForecastSensor, async_setup_entry + entry = SimpleNamespace(entry_id="entry", data={"price_forecast_sensor": "sensor.forecast"}, subentries={}) + coordinator = MagicMock(config_entry=entry) + hass = SimpleNamespace(data={DOMAIN: {entry.entry_id: coordinator}}) + entities = [] + await async_setup_entry(hass, entry, lambda added, **kwargs: entities.extend(added)) + assert len([entity for entity in entities if isinstance(entity, PvPriceForecastSensor)]) == 1 + assert entities[-1].unique_id == "entry_price_forecast" + entry.data.clear() + entities.clear() + await async_setup_entry(hass, entry, lambda added, **kwargs: entities.extend(added)) + assert not any(isinstance(entity, PvPriceForecastSensor) for entity in entities)