Energieverbrauchssensoren - Technische Dokumentation¶

Diese Dokumentation beschreibt die technische Implementierung der Energieverbrauchssensoren (elektrisch und thermisch) in der Lambda Heat Pumps Integration.

Übersicht¶

Die Integration bietet zwei Arten von Energieverbrauchssensoren:

Elektrische Energieverbrauchssensoren: Messen den Stromverbrauch (kWh)
Thermische Energieverbrauchssensoren: Messen die Wärmeabgabe (kWh)

Beide Typen werden nach Betriebsart (heating, hot_water, cooling, defrost) und Zeitraum (total, daily, monthly, yearly, hourly bei Heizen) aufgeteilt.

Architektur¶

Komponenten¶

┌─────────────────────────────────────────────────────────────┐
│                    Coordinator                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  _track_hp_energy_consumption()                       │  │
│  │    ├─ _track_hp_energy_type_consumption(electrical) │  │
│  │    └─ _track_hp_energy_type_consumption(thermal)     │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  _increment_energy_consumption()                      │  │
│  │  _increment_thermal_energy_consumption()              │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    utils.py                                 │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  increment_energy_consumption_counter()               │  │
│  │    - sensor_type: "electrical" | "thermal"            │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    sensor.py                                 │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  LambdaEnergyConsumptionSensor                        │  │
│  │    - set_energy_value()                               │  │
│  │    - native_value (berechnet aus period)              │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Datenfluss¶

Quellsensoren liefern kumulative Werte. Pro HP werden sie aus der lambda_wp_config.yaml (Abschnitt energy_consumption_sensors) gelesen; nur wenn nicht konfiguriert, gelten die Lambda-Standard-Sensoren:
Elektrisch: sensor_entity_id aus Config oder Default compressor_power_consumption_accumulated (Modbus Register 1021)
Thermisch: thermal_sensor_entity_id aus Config (optional) oder Default compressor_thermal_energy_output_accumulated (Modbus Register 1022)
Coordinator berechnet Deltas:
Liest Quellsensor-Werte
Berechnet Delta zwischen Updates
Erkennt Betriebsmodus-Wechsel (Flankenerkennung)
Utils aktualisieren Sensoren:
increment_energy_consumption_counter() aktualisiert alle Perioden
Unterstützt sowohl elektrische als auch thermische Sensoren
Entities speichern Werte:
LambdaEnergyConsumptionSensor speichert Total-Wert in _energy_value
Berechnet daily/monthly/yearly aus Total-Wert: native_value = _energy_value - _yesterday_value (bzw. previous_monthly/yearly)
Persistierung: Gespeichert wird der State (= Anzeige-Wert). Bei Daily/Monthly/Yearly muss beim Restore der kumulative Total aus diesem Wert rekonstruiert oder aus dem Attribut energy_value gelesen werden (siehe Abschnitt „Negative Daily/Monthly/Yearly-Werte“).

Einheitliches Delta-Verfahren: Elektrische und thermische Sensoren nutzen dasselbe Berechnungsmodell (Delta zum Vortag bzw. Vormonat/Vorjahr): Daily = Total - Yesterday, Monthly = Total - Previous Monthly, Yearly = Total - Previous Yearly. Dieselbe Logik in LambdaEnergyConsumptionSensor und increment_energy_consumption_counter gilt für beide.

Implementierung¶

1. Sensor-Erstellung¶

Sensoren werden in sensor.py erstellt:

# Elektrische Sensoren
for hp_idx in range(1, num_hps + 1):
    for mode in ENERGY_CONSUMPTION_MODES:
        for period in ENERGY_CONSUMPTION_PERIODS:
            sensor_id = f"{mode}_energy_{period}"
            sensor = LambdaEnergyConsumptionSensor(...)

# Thermische Sensoren
for hp_idx in range(1, num_hps + 1):
    for mode in ENERGY_CONSUMPTION_MODES:
        for period in ENERGY_CONSUMPTION_PERIODS:
            sensor_id = f"{mode}_thermal_energy_{period}"
            if sensor_template.get("data_type") == "thermal_calculated":
                sensor = LambdaEnergyConsumptionSensor(...)

2. Sensor-Templates¶

Templates sind in const.py definiert:

ENERGY_CONSUMPTION_SENSOR_TEMPLATES = {
    # Elektrische Sensoren
    "heating_energy_total": {
        "name": "Heating Energy Total",
        "unit": "kWh",
        "data_type": "energy_calculated",
        "state_class": "total_increasing",
        "device_class": "energy",
        "operating_state": "heating",
        "period": "total",
    },
    # Thermische Sensoren
    "heating_thermal_energy_total": {
        "name": "Heating Thermal Energy Total",
        "unit": "kWh",
        "data_type": "thermal_calculated",
        "state_class": "total_increasing",
        "device_class": "energy",
        "operating_state": "heating",
        "period": "total",
    },
    # ...
}

3. Coordinator-Tracking¶

Der Coordinator trackt beide Energiearten parallel:

async def _track_hp_energy_consumption(self, hp_idx, current_state, data):
    # Elektrische Energie
    await self._track_hp_energy_type_consumption(
        hp_idx, current_state, data,
        sensor_type="electrical",
        default_sensor_id_template="sensor.{name_prefix}_hp{hp_idx}_compressor_power_consumption_accumulated",
        increment_fn=self._increment_energy_consumption
    )

    # Thermische Energie
    await self._track_hp_energy_type_consumption(
        hp_idx, current_state, data,
        sensor_type="thermal",
        default_sensor_id_template="sensor.{name_prefix}_hp{hp_idx}_compressor_thermal_energy_output_accumulated",
        increment_fn=self._increment_thermal_energy_consumption
    )

4. Delta-Berechnung¶

Die generische Tracking-Funktion:

async def _track_hp_energy_type_consumption(
    self, hp_idx, current_state, data, sensor_type, 
    default_sensor_id_template, unit_check_fn, convert_to_kwh_fn,
    last_reading_dict, first_value_seen_dict, increment_fn
):
    # 1. Lese Quellsensor
    current_energy_state = self.hass.states.get(sensor_entity_id)
    current_energy = float(current_energy_state.state)

    # 2. Konvertiere zu kWh
    current_energy_kwh = convert_to_kwh_fn(current_energy, unit)

    # 3. Berechne Delta
    last_energy = last_reading_dict.get(f"hp{hp_idx}", None)
    energy_delta = calculate_energy_delta(current_energy_kwh, last_energy, max_delta=100.0)

    # 4. Bestimme Betriebsmodus
    mode = mode_mapping[current_state]  # heating, hot_water, cooling, defrost

    # 5. Aktualisiere Sensoren bei Moduswechsel oder kontinuierlich
    if current_state != last_state or (mode == "stby" or energy_delta > 0):
        await increment_fn(hp_idx, mode, energy_delta)

5. Sensor-Update¶

Die Update-Funktion aktualisiert alle Perioden:

async def increment_energy_consumption_counter(
    hass, mode, hp_index, energy_delta, name_prefix,
    use_legacy_modbus_names=True, energy_offsets=None,
    sensor_type="electrical"  # oder "thermal"
):
    for period in ["total", "daily", "monthly", "yearly", "2h", "4h"]:
        # Bestimme sensor_id basierend auf sensor_type
        if sensor_type == "thermal":
            sensor_id = f"{mode}_thermal_energy_{period}"
        else:
            sensor_id = f"{mode}_energy_{period}"

        # Finde Entity
        energy_entity = find_energy_entity(hass, entity_id)

        # Berechne neuen Wert
        current_value = float(state_obj.state)
        new_value = current_value + energy_delta

        # Wende Offset an (nur für total)
        if period == "total" and energy_offsets:
            new_value += offset

        # Aktualisiere Entity
        energy_entity.set_energy_value(new_value)

6. Entity-Implementierung¶

Die LambdaEnergyConsumptionSensor Klasse:

class LambdaEnergyConsumptionSensor(RestoreEntity, SensorEntity):
    def __init__(self, hass, entry, sensor_id, name, entity_id, 
                 unique_id, unit, state_class, device_class, 
                 device_type, hp_index, mode, period):
        self._energy_value = 0.0  # Total-Wert
        self._period = period
        # ...

    @property
    def native_value(self):
        """Berechnet Wert basierend auf period."""
        if self._period == "total":
            return self._energy_value
        elif self._period == "daily":
            return self._energy_value - self._yesterday_value
        elif self._period == "monthly":
            return self._energy_value - self._previous_monthly_value
        # ...

    def set_energy_value(self, value):
        """Wird von increment_energy_consumption_counter aufgerufen."""
        self._energy_value = value
        self.async_write_ha_state()

Quellsensoren¶

Die tatsächlich verwendeten Quellsensoren werden aus der lambda_wp_config.yaml ermittelt (Abschnitt energy_consumption_sensors: pro Wärmepumpe sensor_entity_id (elektrisch) und optional thermal_sensor_entity_id (thermisch). Nur wenn dort nichts konfiguriert ist oder ein Sensor ungültig, werden die folgenden Standard-Quellsensoren (Lambda-Modbus) verwendet.

Elektrische Energie (Standard bei fehlender Konfiguration)¶

Sensor: compressor_power_consumption_accumulated
Register: 1021 (HP1), 2021 (HP2), etc.
Einheit: Wh (wird zu kWh konvertiert)
Typ: int32, total_increasing

Thermische Energie (Standard bei fehlender Konfiguration)¶

Sensor: compressor_thermal_energy_output_accumulated
Register: 1022 (HP1), 2022 (HP2), etc.
Einheit: Wh (wird zu kWh konvertiert)
Typ: int32, total_increasing

Die thermischen Energy-Sensoren kommen mit diesem Release hinzu; die elektrischen gab es bereits. Weil die Quellsensoren der COP-Sensoren damit zu unterschiedlichen Zeitpunkten in der Integration vorhanden sind, nutzen die COP-Sensoren eine Baseline (Stichtag), damit die COP nur aus Deltas ab „beide Quellen vorhanden“ berechnet wird. Das gilt für Total- und für alle zyklischen COP-Sensoren (täglich, monatlich, jährlich, stündlich). Siehe COP-Sensoren – Warum Baseline?.

Betriebsmodus-Mapping¶

mode_mapping = {
    0: "stby",      # Standby
    1: "heating",   # CH - Heizen
    2: "hot_water", # DHW - Warmwasser
    3: "cooling",   # CC - Kühlen
    4: "stby",      # Standby (alternativ)
    5: "defrost",   # DEFROST - Abtauen
}

Flankenerkennung¶

Die Integration nutzt Flankenerkennung, um Energie-Deltas exakt dem aktiven Betriebsmodus zuzuordnen:

Moduswechsel erkannt: Delta wird dem neuen Modus zugeordnet
Kontinuierlicher Betrieb: Delta wird dem aktuellen Modus zugeordnet
Standby: Delta wird auch Standby zugeordnet (falls vorhanden)

Einheitenkonvertierung¶

Unterstützte Einheiten werden automatisch zu kWh konvertiert:

def _convert_energy_to_kwh_cached(self, value, unit):
    if unit == "Wh":
        return value / 1000.0
    elif unit == "kWh":
        return value
    elif unit == "MWh":
        return value * 1000.0
    else:
        return value  # Fallback

Persistierung¶

Total-Werte: Werden in LambdaEnergyConsumptionSensor gespeichert (RestoreEntity)
Last Readings: Werden im Coordinator gespeichert (_last_energy_reading, _last_thermal_energy_reading)
JSON-Persistierung: Coordinator speichert Werte in cycle_energy_persist.json
Energy-Sensor-States: Zusätzlich zu HA-Restore werden die Energy-Sensor-States (Total, Daily, Monthly, Yearly für elektrisch und thermisch) in cycle_energy_persist.json unter dem Schlüssel energy_sensor_states gespeichert; beim Neustart hat diese Quelle Vorrang, damit Anzeigewerte nicht fallen (z. B. 0,44 → 0,4).

Neustart-Werterhalt¶

set_energy_value() verringert nie: Der gespeicherte Wert wird nicht verringert (vermeidet Überschreiben durch veraltete Coordinator-/Total-Werte nach Neustart).
Kein Fallback-async_set: Kann der Coordinator die Entity-Referenz nicht auflösen, wird kein async_set mit möglicherweise veraltetem State ausgeführt.
native_value auf 2 Dezimalstellen gerundet: Vermeidet Float-Artefakte im persistierten State (z. B. 0,39999… statt 0,44).
State aus cycle_energy_persist bevorzugt: Nach restore_state(last_state) wird, falls der Coordinator einen State aus cycle_energy_persist für diese Entity hat, dieser angewendet (_apply_persisted_energy_state).

Konfiguration¶

Externe Quellsensoren (lambda_wp_config.yaml)¶

Die tatsächlich verwendeten Quellsensoren werden hier definiert. Pro HP können elektrischer und thermischer Quellsensor getrennt konfiguriert werden:

energy_consumption_sensors:
  hp1:
    sensor_entity_id: "sensor.shelly_lambda_gesamt_leistung"   # elektrisch
    thermal_sensor_entity_id: "sensor.waermemesser_hp1"        # optional, thermisch

sensor_entity_id: Quellsensor für elektrische Energie. Fehlt er (oder ist ungültig), wird sensor.{name}_hp{n}_compressor_power_consumption_accumulated verwendet.
thermal_sensor_entity_id (optional): Quellsensor für thermische Energie. Fehlt er (oder ist ungültig), wird sensor.{name}_hp{n}_compressor_thermal_energy_output_accumulated verwendet.

Validierung in utils.validate_external_sensors: Beide Sensoren werden bei Angabe (State oder Entity Registry) geprüft. Ist nur der thermische ungültig, wird er verworfen und der thermische Default genutzt; der elektrische Eintrag bleibt erhalten.

Offsets¶

Offsets können für Total-Sensoren konfiguriert werden:

energy_consumption_offsets:
  hp1:
    heating_energy_total: 1000.0
    heating_thermal_energy_total: 5000.0
    # ...

Fehlerbehandlung¶

Sensor-Wechsel-Erkennung¶

Elektrisch: Automatische Erkennung von Sensorwechseln (sensor_ids, last_energy_readings), Nullwert-Schutz, Rückwärtssprung-Schutz; bei Wechsel _handle_sensor_change.
Thermisch: Gleiche Resilienz wie elektrisch: thermal_sensor_ids, last_thermal_energy_readings, _handle_thermal_sensor_change; Persistierung in cycle_energy_persist.json.

Zero-Value Protection¶

if current_energy_kwh == 0.0:
    first_value_seen_dict[f"hp{hp_idx}"] = False
    return  # Warte auf ersten gültigen Wert

Overflow Protection¶

if current_energy_kwh < last_energy:
    # Sensor wurde zurückgesetzt oder gewechselt
    first_value_seen_dict[f"hp{hp_idx}"] = False
    last_reading_dict[f"hp{hp_idx}"] = None
    return

Negative Daily/Monthly/Yearly-Werte (Restore-Bug)¶

Symptom: current_daily_value (bzw. monthly/yearly) wird nach Neustart negativ angezeigt (z. B. -1305.88 kWh).

Ursache: Beim Persistieren speichert Home Assistant den State der Entity. Bei Daily-Sensoren ist der State der Anzeige-Wert (native_value = _energy_value - _yesterday_value), nicht der kumulative Total _energy_value. Beim Restore wurde früher _energy_value = float(last_state.state) gesetzt – also der Tageswert statt des Totals. Zusammen mit dem korrekt aus Attributen wiederhergestellten _yesterday_value ergibt sich dann: current_daily_value = _energy_value - _yesterday_value = (kleiner Tageswert) - (großer Vortag) = negativ.

Lösung in der Implementierung:

Beim Restore von Daily/Monthly/Yearly-Sensoren wird _energy_value nicht mehr aus last_state.state übernommen, sondern rekonstruiert:
Daily: _energy_value = _yesterday_value + angezeigter State (bzw. aus Attribut energy_value, falls persistiert).
Monthly/Yearly: analog mit _previous_monthly_value / _previous_yearly_value.
Der kumulative Total wird in den Attributen als energy_value mitpersistiert; beim nächsten Restore wird er direkt aus diesem Attribut gelesen, falls vorhanden.

Die Anzeige bleibt durch native_value = max(0.0, _energy_value - _yesterday_value) nach unten auf 0 begrenzt; durch die korrigierte Restore-Logik stimmen die internen Werte wieder und negative Werte treten nicht mehr auf.

Konsistenz Daily/Monthly/Yearly (yesterday/previous_* ≤ energy_value)¶

Problem: Nach Neustart können persistierte Daten (Recorder oder cycle_energy_persist) inkonsistent sein: yesterday_value bzw. previous_monthly_value / previous_yearly_value sind größer als energy_value. Dann wäre der Periodenwert (daily = energy_value − yesterday_value usw.) negativ.

Lösung in der Implementierung:

Restore (restore_state): Nach dem Setzen von _energy_value und _yesterday_value (bzw. _previous_monthly_value / _previous_yearly_value) wird geprüft: Ist der Basis-Wert größer als _energy_value, wird er auf _energy_value gesetzt (Korrektur + Log-Warnung). Die Rekonstruktion „displayed = yesterday + displayed“ wird nur ausgeführt, wenn _yesterday_value <= _energy_value (konsistent), damit kein Überschreiben mit falschem Wert erfolgt.
Persist-Anwendung (_apply_persisted_energy_state): Nach dem Übernehmen der Werte aus cycle_energy_persist wird für Daily/Monthly/Yearly dieselbe Prüfung durchgeführt; bei Bedarf Korrektur und Warnung.
Persist-Schreiben (Coordinator _collect_energy_sensor_states): Beim Speichern in cycle_energy_persist wird nie ein Paar mit yesterday_value bzw. previous_monthly_value / previous_yearly_value größer als energy_value geschrieben; der Basis-Wert wird vor dem Schreiben auf energy_value begrenzt.
Daily-Init (_initialize_daily_yesterday_value): Erkennt die Integration weiterhin negativen Tageswert (z. B. weil Total-Sensor beim Start noch nicht verfügbar war), setzt sie yesterday_value = energy_value und markiert Persist als „dirty“, damit die Korrektur beim nächsten Zyklus mitgespeichert wird.

Damit können nach Neustart keine negativen Daily-/Monthly-/Yearly-Werte mehr aus inkonsistenten persistierten Daten entstehen; die Korrektur ist an Restore, Persist-Anwendung und Persist-Schreiben verankert.

Migration Electrical (erstes Release)¶

Beim ersten Start nach einem Update werden bestehende elektrische Daily-/Monthly-/Yearly-Sensoren beim Umstieg auf das Delta-Verfahren einmalig migriert: Fehlt in den persistierten Daten das Attribut energy_value, werden die Werte aus dem zugehörigen Total-Sensor abgeleitet (restore_state() nutzt last_state.state als Anzeigewert und setzt, falls der Total-Sensor verfügbar ist, _energy_value und _yesterday_value bzw. _previous_monthly_value / _previous_yearly_value entsprechend). Der angezeigte Tages-/Monats-/Jahreswert bleibt erhalten, keine negativen Werte. Danach greift die normale Restore-Logik (mit persistiertem energy_value). Thermische Sensoren benötigen diese Migration nicht (sie wurden mit dem Delta-Verfahren eingeführt).

Erweiterungen¶

Neue Betriebsmodi hinzufügen¶

Modus zu ENERGY_CONSUMPTION_MODES in const.py hinzufügen
Sensor-Templates in ENERGY_CONSUMPTION_SENSOR_TEMPLATES hinzufügen
Modus-Mapping in _track_hp_energy_type_consumption erweitern

Neue Zeiträume hinzufügen¶

Zeitraum zu ENERGY_CONSUMPTION_PERIODS in const.py hinzufügen
Sensor-Templates für alle Modi hinzufügen
Reset-Logik in LambdaEnergyConsumptionSensor erweitern

Debugging¶

Logging¶

Aktiviere Debug-Logging für detaillierte Informationen:

logger:
  default: info
  logs:
    custom_components.lambda_heat_pumps.coordinator: debug
    custom_components.lambda_heat_pumps.utils: debug

Wichtige Log-Meldungen¶

DEBUG-010: Tracking startet für HP
DEBUG-014: Energie-Offsets werden geladen
Energy counters updated: Sensoren wurden aktualisiert
INTERNAL-SENSOR: Interner Modbus-Sensor wird verwendet

Tests¶

Tests befinden sich in tests/test_energy_consumption_sensors.py:

Sensor-Erstellung
Delta-Berechnung
Period-Berechnung (daily, monthly, yearly)
Offset-Anwendung
Einheitenkonvertierung

Energieverbrauchssensoren - Technische Dokumentation¶

Übersicht¶

Architektur¶

Komponenten¶

Datenfluss¶

Implementierung¶

1. Sensor-Erstellung¶

2. Sensor-Templates¶

3. Coordinator-Tracking¶

4. Delta-Berechnung¶

5. Sensor-Update¶

6. Entity-Implementierung¶

Quellsensoren¶

Elektrische Energie (Standard bei fehlender Konfiguration)¶

Thermische Energie (Standard bei fehlender Konfiguration)¶

Betriebsmodus-Mapping¶

Flankenerkennung¶

Einheitenkonvertierung¶

Persistierung¶

Neustart-Werterhalt¶

Konfiguration¶

Externe Quellsensoren (lambda_wp_config.yaml)¶

Offsets¶

Fehlerbehandlung¶

Sensor-Wechsel-Erkennung¶

Zero-Value Protection¶

Overflow Protection¶

Negative Daily/Monthly/Yearly-Werte (Restore-Bug)¶

Konsistenz Daily/Monthly/Yearly (yesterday/previous_* ≤ energy_value)¶

Migration Electrical (erstes Release)¶

Erweiterungen¶

Neue Betriebsmodi hinzufügen¶

Neue Zeiträume hinzufügen¶

Debugging¶

Logging¶

Wichtige Log-Meldungen¶

Tests¶

Siehe auch¶