Enelix-EMS/docs/module/Wassererwaermer/README.md

Verbraucher Warmwassererwaermer

Status: implementiert fuer IP-Symcon 8.0+ und den Enelix-2-Vertrag 3.0.

Das Modul bindet einen elektrischen Warmwasserspeicher mit einer oder mehreren exklusiven Leistungsstufen an den Enelix-Manager an. Der Manager kann nur eine der aktuell angebotenen Leistungen vorgeben. Lokale Schutz- und Komfortregeln fuer Mindesttemperatur, Maximaltemperatur, Zeitplan und Legionellenfunktion haben Vorrang vor einer Manager-Vorgabe.

Das Modul ist eine gezielte Adaption des Enelix-1-Moduls Boiler_x_Stufig. Zyklische Altlogik und alte Kommunikationsvariablen wurden nicht uebernommen. Die Regelung arbeitet ereignisbasiert und verwendet ausschliesslich den Enelix-2-Nachrichtenvertrag.

Technisches Merkmal	Wert
Modulname	VerbraucherWarmwassererwaermer
Alias	Wassererwärmer
Modul-ID	{B7C54AF4-AD7D-4FE4-B75D-203693906251}
Modultyp	Geraeteinstanz (3)
Funktionspraefix	ENELIX
Enelix-Vertrag	3.0

Funktionsumfang

• beliebig viele, eindeutig konfigurierte Leistungsstufen inklusive 0 W,
• exklusive Break-before-make-Schaltung der Stufenkontakte,
• lokale Mindest- und Maximaltemperatur mit Hysterese,
• optionale PT1-Glaettung des Temperaturmesswerts,
• thermische Vorhersage fuer taegliche Solltemperatur-Zeitpunkte,
• zweistufige Legionellenfunktion mit Fruehest- und Spaetestintervall,
• berechnete Istleistung, aktive Stufe und bezogene Energie,
• ereignisbasierte Regelung mit einstellbarer Lastwechselsperre,
• Kommunikation mit manuell oder automatisch zugeordneten Enelix-Managern,
• optionale Diagnosevariablen und Debug-Logging.

Voraussetzungen

• IP-Symcon ab Version 8.0,
• installierte Bibliothek Enelix-EMS vom Branch develop,
• eine Integer- oder Floatvariable als Temperaturfuehler,
• mindestens eine positive Leistungsstufe,
• je Leistungsstufe eine eigene Booleanvariable mit funktionsfaehiger Aktion,
• ein Enelix-Manager, dem die Verbraucherinstanz aktiv zugeordnet wird.

Die Schaltkontakte duerfen nicht mehrfach verwendet werden. Der Anlagenaufbau muss sicherstellen, dass die konfigurierten Leistungsstufen elektrisch zulaessig sind. Die Software ersetzt keine hardwareseitigen Verriegelungen, Temperaturbegrenzer oder Schutzorgane.

Regelungsablauf

Eine Neuberechnung wird insbesondere ausgeloest durch:

• einen neuen oder aktualisierten Temperaturmesswert,
• das Ein- oder Ausschalten von Aktiv,
• eine neue Manager-Vorgabe,
• eine Aenderung der bedienbaren Temperatursollwerte,
• das Ende der Lastwechselsperre,
• das Uebernehmen einer neuen Instanzkonfiguration,
• eine periodische Vollmeldung an den Manager.

Meldeintervall ist kein Regelintervall. Es stellt die regelmaessige vollstaendige Rueckmeldung sicher. Die Lastwechselsperre verwendet einen einmaligen Timer und loest nach ihrem Ablauf genau eine Neuberechnung aus.

Die Zielentscheidung folgt dieser Prioritaet:

1. Bei deaktivierter Instanz oder ungueltiger Temperatur ist der Verbraucher nicht verfuegbar und wird ausgeschaltet. Eine ungueltige Konfiguration wird bereits beim Uebernehmen mit Status 202 abgewiesen.
2. Unterschreitet die Temperatur die wirksame Mindesttemperatur oder reicht die verbleibende Zeit bis zum naechsten Zeitplanziel rechnerisch nicht aus, wird die hoechste Leistungsstufe lokal erzwungen.
3. Ab der wirksamen Maximaltemperatur wird ausgeschaltet.
4. Im Bereich unmittelbar unter der Maximaltemperatur wird eine bereits aktive Stufe bis zum Erreichen der Abschaltgrenze gehalten.
5. In allen anderen Zustaenden darf der Manager zwischen 0 W und allen konfigurierten Leistungsstufen waehlen.

Lokale Zwangsvorgaben werden mit AenderungMoeglich=false und einem entsprechend eingeschraenkten Leistungswerte_W gemeldet.

Konfiguration

Das Modul besitzt 19 Properties: sechs gemeinsame Verbraucher-Properties und 13 modulspezifische Properties.

Manager und Zeitverhalten

Ident	Typ	Standard	Beschreibung
PrioritaetPV	Integer	0	Prioritaet im PV-Betrieb; kleinere Werte werden zuerst beruecksichtigt.
PrioritaetPeak	Integer	0	Prioritaet im Peak-Betrieb; kleinere Werte werden zuerst beruecksichtigt.
Meldeintervall	Integer	10	Abstand der vollstaendigen Verbraucherrueckmeldungen in Sekunden.
VorgabeTimeout	Integer	120	Zeit in Sekunden, nach der eine nicht erneuerte Manager-Vorgabe ungueltig wird.
LastwechselSperrzeit	Integer	5	Mindestzeit zwischen zwei Lastwechseln in Sekunden.

Speichereinstellungen

Ident	Typ	Standard	Beschreibung
LeistungsStufen	JSON-Liste	[]	Positive Leistung, Stufennummer und Boolean-Schaltkontakt jeder Stufe.
Boilerfuehler_PT1	Integer	0	Objekt-ID der Integer- oder Floatvariable fuer die Speichertemperatur.
LegionellenfunktionAktiv	Boolean	true	Aktiviert die periodische Anhebung auf Legionellentemperatur.
LegionellenMinimalintervallTage	Integer	4	Fruehestens: Legionellentemperatur wird zur Maximaltemperatur.
LegionellenMaximalintervallTage	Integer	7	Spaetestens: Legionellentemperatur wird zur Mindesttemperatur.

Jeder Eintrag in LeistungsStufen besteht aus:

Feld	Anforderung
Stufe	Positive Ganzzahl.
Leistung	Eindeutige positive Ganzzahl in Watt.
Schaltkontakt_Stufe	Eindeutige Objekt-ID einer Booleanvariable.

Die Eintraege werden intern nach Leistung sortiert. 0 W wird automatisch als Aus-Zustand in das Leistungsangebot aufgenommen und darf nicht als eigene Stufe konfiguriert werden.

Erweiterte Speichereinstellungen

Ident	Typ	Standard	Beschreibung
Boilervolumen	Integer	300	Speichervolumen in Litern fuer die thermische Zeitplanprognose.
Hysterese	Float	5.0	Temperaturhysterese in Kelvin.
Zeitplan	JSON-Liste	[]	Taegliche Zielwerte mit Uhrzeit im Format HH:MM und Solltemperatur.

Der jeweils naechste Zeitplaneintrag wird fuer heute oder den folgenden Tag ermittelt. Reicht die verbleibende Zeit bei maximaler elektrischer Leistung rechnerisch nicht mehr aus, wird sofort die hoechste Stufe angefordert. Die Berechnung verwendet Wasser mit 4186 J/(kg K) und beruecksichtigt keine Speicher- oder Leitungsverluste. Fuer Datum und Uhrzeit gilt die in IP-Symcon eingestellte lokale Zeitzone.

Erweiterte sonstige Einstellungen

Ident	Typ	Standard	Beschreibung
TemperaturMaxAlter	Integer	30	Maximal zulaessiges Alter des Temperaturmesswerts in Sekunden.
BoilertemperaturGlaetten	Boolean	false	Aktiviert die PT1-Glaettung.
ZeitKonstante	Integer	120	PT1-Zeitkonstante in Sekunden.
EinstellungenInVisu	Boolean	false	Zeigt Temperatursollwerte an und gibt ihre Bedienung frei.
DiagnosevariablenAnzeigen	Boolean	false	Legt die 14 Diagnosevariablen an.
LoggingEin	Boolean	false	Aktiviert laufende Debug-Ausgaben des Moduls.

Alle Zeitwerte und Intervalle muessen groesser als 0 sein. Die beiden Prioritaeten muessen mindestens 0 betragen. Das Legionellen-Minimalintervall darf nicht groesser als das Maximalintervall sein.

Temperaturverarbeitung

Der Rohwert des konfigurierten Fuehlers muss numerisch und juenger als TemperaturMaxAlter sein. Andernfalls werden TemperaturGueltig=false, Verfuegbar=false und eine Stoerung gemeldet; eine aktive Stufe wird ausgeschaltet.

Ohne Glaettung entspricht Boilertemperatur dem letzten gueltigen Rohwert. Mit aktivierter Glaettung verwendet das Modul ein PT1-Glied. Der erste Wert initialisiert den Filter; danach wird die tatsaechlich seit der letzten Temperaturberechnung vergangene Zeit verwendet.

Die Solltemperaturen werden bei der ersten Initialisierung auf folgende Werte gesetzt:

Variable	Initialwert
Mindesttemperatur	45.0 Grad C
Maximaltemperatur	60.0 Grad C
Legionellentemperatur	65.0 Grad C

Es gilt immer:

Mindesttemperatur < Maximaltemperatur <= Legionellentemperatur

Temperaturwerte muessen zwischen 0 und 100 Grad C liegen. Bedienaktionen sind nur erlaubt, wenn EinstellungenInVisu=true gesetzt ist.

Hysterese und lokales Nachladen

Sinkt die Temperatur unter die wirksame Mindesttemperatur, beginnt das lokale Nachladen mit der hoechsten Leistungsstufe. Es endet, sobald mindestens Mindesttemperatur + Hysterese erreicht ist. Oberhalb der wirksamen Maximaltemperatur wird ausgeschaltet.

Ist bereits eine Stufe aktiv und liegt die Temperatur bei mindestens Maximaltemperatur - Hysterese, wird diese Stufe bis zur Abschaltgrenze gehalten. Dadurch werden unnoetige Stufenwechsel kurz vor dem Ziel vermieden.

Legionellenfunktion

Die Legionellenfunktion arbeitet zweistufig:

1. Ab LegionellenMinimalintervallTage wird die Legionellentemperatur zur wirksamen Maximaltemperatur. Der Manager kann die Aufheizung innerhalb des verbleibenden Zeitfensters ermoeglichen.
2. Ab LegionellenMaximalintervallTage wird die Legionellentemperatur auch zur wirksamen Mindesttemperatur. Die hoechste Stufe wird dadurch lokal erzwungen, bis das Ziel erreicht ist.

Erreicht die gueltige Speichertemperatur die Legionellentemperatur, wird der Zeitpunkt als erfolgreicher Abschluss gespeichert und das Intervall beginnt neu. LegioCounter zeigt die Sekunden seit diesem Abschluss.

Legionellentemperatur wird nur als Symcon-Variable angelegt, wenn LegionellenfunktionAktiv=true ist. Beim Ausschalten der Funktion wird die Variable geloescht; der letzte Wert bleibt intern erhalten und steht bei einem spaeteren Wiedereinschalten wieder zur Verfuegung.

Lastwechselsperre und Schaltsicherheit

Nach jedem tatsaechlichen Lastwechsel wird fuer LastwechselSperrzeit Sekunden kein weiterer regulaerer Wechsel zugelassen. In dieser Zeit gilt:

• AenderungMoeglich=false,
• Leistungswerte_W enthaelt nur die aktuell gehaltene Leistung,
• eine abweichende Manager-Vorgabe wird abgewiesen,
• ein einmaliger Timer plant die Freigabe.

Ein sicherheitsbedingtes Ausschalten, beispielsweise bei ungueltiger Temperatur oder erreichter Maximaltemperatur, darf die Sperre uebergehen. Separate Variablen Idle oder IdleCounter existieren nicht.

Beim Schalten werden zuerst alle konfigurierten Kontakte ausgeschaltet und anschliessend hoechstens der Kontakt der Zielstufe eingeschaltet. Schlaegt ein Schaltvorgang fehl, versucht das Modul alle Kontakte auszuschalten, setzt die berechnete Istleistung auf 0 W und meldet einen Schaltfehler.

Variablen

Betriebs- und Einstellvariablen

Ident	Typ / Zugriff	Sichtbarkeit	Beschreibung
Aktiv	Boolean / bedienbar	immer	Lokale EMS-Freigabe; Startwert false.
Boilertemperatur	Float / Anzeige	immer	Letzter gueltiger, gegebenenfalls geglaetteter Temperaturwert.
Mindesttemperatur	Float / bedienbar	bei EinstellungenInVisu	Untere Grenze fuer lokales Nachladen.
Maximaltemperatur	Float / bedienbar	bei EinstellungenInVisu	Abschaltgrenze im Normalbetrieb.
Legionellentemperatur	Float / bedienbar	Funktion aktiv; Anzeige freigegeben	Ziel des Legionellenprogramms.

Diagnosevariablen

Mit DiagnosevariablenAnzeigen=true werden diese 14 Variablen angelegt. Beim Abschalten der Property werden sie wieder geloescht. Die Regellogik verwendet persistente interne Zustaende und funktioniert unabhaengig von diesen Anzeigevariablen.

Ident	Typ	Bedeutung
Istleistung	Float	Berechnete aktuelle Leistung in Watt.
Leistungsquelle	Integer	Immer 1 fuer berechnete Leistung.
Sollleistung	Integer	Aktuell angenommene oder lokal erzwungene Zielvorgabe in Watt.
SollwertGueltig	Boolean	Eine Manager-Vorgabe ist vorhanden und noch nicht abgelaufen.
Verfuegbar	Boolean	Das Modul kann grundsaetzlich durch das EMS gesteuert werden.
AenderungMoeglich	Boolean	Der Manager darf momentan eine neue Leistung vorgeben.
Stoerung	Boolean	Mindestens eine Stoerbedingung ist aktiv.
Stoertext	String	Zusammengefasste lesbare Stoerbeschreibung.
AktiveStufe	Integer	Stufennummer der berechneten aktuellen Leistung; 0 bedeutet aus.
BezogeneEnergie	Float	Aus Istleistung und verstrichener Zeit berechnete Energie in kWh.
TemperaturGueltig	Boolean	Temperaturfuehler vorhanden, numerisch und nicht veraltet.
NachladenAktiv	Boolean	Lokales Nachladen aufgrund der Mindesttemperatur ist aktiv.
LegionellenbetriebAktiv	Boolean	Das Fruehestintervall der Legionellenfunktion ist erreicht.
LegioCounter	Integer	Sekunden seit dem letzten erfolgreichen Legionellenabschluss.

Managerkommunikation

Das Modul implementiert VerbraucherSchnittstelle::ManagerdatenEmpfangen() und verwendet den Enelix-2-Vertrag 3.0. Es besitzt keine Manager-ID-Property. Zugelassen sind nur Manager, in deren manueller oder automatischer Verbraucherzuordnung die Instanz aktiv eingetragen ist.

Eine Manager-Vorgabe wird nur angenommen, wenn:

• Vertragsversion, Absender, Empfaenger und Datentypen gueltig sind,
• der Manager die Instanz aktiv zugeordnet hat,
• Sollleistung_W im zuletzt berechneten Leistungswerte_W enthalten ist.

Rueckmeldungen erfolgen bei relevanten Ereignissen, kurz verzoegert nach einer Manager-Vorgabe und zusaetzlich alle Meldeintervall Sekunden. Die kurze Verzoegerung verhindert eine synchrone Manager-Verbraucher-Endlosschleife.

Die Verbraucherrueckmeldung enthaelt insbesondere:

• Prioritaeten fuer PV- und Peak-Betrieb,
• Leistungswerte_W, AenderungMoeglich und Verfuegbar,
• Istleistung_W mit Leistungsquelle=1,
• Zustandseintraege fuer Sollleistung, Wassertemperatur, Maximaltemperatur, aktive Stufe, Nachladen, Legionellenbetrieb und Stoerungen.

Nach VorgabeTimeout Sekunden ohne Erneuerung wird eine Manager-Vorgabe bei der naechsten Neuberechnung, spaetestens bei der folgenden Vollmeldung, ungueltig. Beim Neustart wird keine alte Manager-Vorgabe ungeprueft wieder aufgenommen.

Abgrenzung des aktuellen Stands

• Istleistung, AktiveStufe und BezogeneEnergie sind berechnete Werte; das Modul besitzt keinen Anschluss fuer einen elektrischen Leistungsmesser.
• Die Stufenkontakte sind Aktoren, keine separate physische Rueckmeldung. Ihr Booleanzustand wird bei einer Regelberechnung auf Plausibilitaet geprueft.
• Externe Aenderungen an den Stufenkontakten loesen selbst keine Neuberechnung aus. Der Temperaturfuehler ist die abonnierte Messvariable.
• Der Zeitplan beschreibt taeglich wiederkehrende Zielzeitpunkte und keine einmaligen Kalendertermine.

Status- und Fehlerzustaende

Status	Bedeutung	Typische Ursache
102	Aktiv	Konfiguration und Temperaturmessung sind gueltig.
201	Temperaturmessung ungueltig	Fuehler fehlt, ist nicht numerisch oder zu alt.
202	Konfiguration ungueltig	Unzulaessige Intervalle, Temperaturen, Stufen, Kontakte oder Zeitplaneintraege.
203	Schaltfehler	Eine Aktion eines Stufenkontakts ist fehlgeschlagen.

Eine Uebertemperatur liegt vor, wenn Boilertemperatur die hoehere Grenze aus Maximal- und Legionellentemperatur um mehr als Hysterese ueberschreitet. Sie wird ueber Stoerung und Stoertext gemeldet; der Modulstatus bleibt ohne zusaetzlichen Schalt- oder Fuehlerfehler 102.

Installation und Inbetriebnahme

1. Im IP-Symcon Module Control den Branch develop der Bibliothek https://git.belevo.ch/ENELIX/Enelix-EMS.git installieren oder aktualisieren.
2. Unter Instanz hinzufuegen nach dem Alias Wassererwärmer oder dem Modulnamen VerbraucherWarmwassererwaermer suchen und eine Instanz anlegen.
3. Den Temperaturfuehler auswaehlen und TemperaturMaxAlter passend zum Aktualisierungsintervall des Fuehlers einstellen.
4. Alle Leistungsstufen mit positiver Leistung und jeweils eigenem Boolean-Schaltkontakt konfigurieren.
5. Normal-, Legionellen- und Zeitplanwerte pruefen. Danach die Konfiguration uebernehmen.
6. Die Instanz im Enelix-Manager manuell aktiv zuordnen oder bei automatischer Suche in der gefundenen Liste aktivieren.
7. Fuer die Erstpruefung DiagnosevariablenAnzeigen und bei Bedarf LoggingEin einschalten.
8. Unter Aufsicht Aktiv einschalten und jede Stufe einzeln pruefen. Dabei kontrollieren, dass nie zwei Stufenkontakte gleichzeitig aktiv sind.
9. Eine Manager-Vorgabe fuer 0 W und fuer jede konfigurierte Stufe pruefen.
10. Diagnosevariablen nach der Abnahme bei Bedarf wieder ausschalten.

Abnahmecheckliste

• Die Instanz erreicht Status 102.
• Aktiv=false schaltet alle Stufenkontakte aus.
• Der Fuehlerwert erscheint unverfaelscht oder erwartungsgemaess geglaettet in Boilertemperatur.
• Unterhalb der Mindesttemperatur wird die hoechste Stufe lokal erzwungen.
• Oberhalb der Maximaltemperatur werden alle Stufen ausgeschaltet.
• Jede Manager-Vorgabe schaltet genau den zugeordneten Kontakt.
• Direkt nach einem Wechsel ist AenderungMoeglich=false; nach der konfigurierten Sperrzeit wird ein regulaerer Wechsel wieder freigegeben.
• Eine Gegenanforderung waehrend der Sperre liegt nicht im gemeldeten Leistungsangebot.
• Ein veralteter oder ungueltiger Fuehlerwert fuehrt zu Status 201, einer Stoerung und sicherem Ausschalten.
• Bei aktiver Legionellenfunktion wird Legionellentemperatur angelegt; nach dem Abschalten der Funktion wird die Variable geloescht.
• Mit ausgeschalteten Diagnosevariablen bleiben Regelung und Kommunikation funktionsfaehig.

Diagnosehinweise

• Status 202: zuerst Fuehler-ID, Leistungsstufen, eindeutige Kontakte, Temperaturreihenfolge, Intervalle und Zeitplanformat pruefen.
• Status 201: VariableUpdated, Datentyp des Fuehlers und TemperaturMaxAlter kontrollieren.
• Status 203: Aktionen der Boolean-Schaltkontakte einzeln in IP-Symcon testen; das Modul versucht bei einem Fehler alle Kontakte auszuschalten.
• Manager-Vorgabe wird abgewiesen: Zuordnung im Manager, AenderungMoeglich und das aktuelle Leistungswerte_W pruefen.
• Unerwartetes Nachladen: Mindesttemperatur, Hysterese, naechstes Zeitplanziel und Alter des letzten Legionellenabschlusses kontrollieren.

Tests

WarmwasserReglerTest.php prueft die reine Regellogik fuer Leistungsstufen, PT1, Lastwechselsperre, Energieberechnung, thermische Prognose, Zeitplan und Legionellengrenzen.

WarmwassererwaermerModulstrukturTest.php prueft Metadaten, Formular, alle 19 Properties, ereignisbasierte Lastwechselsperre, Vertrag 3.0, bedarfsgesteuerte Diagnosevariablen, Legionellentemperatur, Temperatursollwerte und Break-before-make-Schaltung.

Migration von Enelix 1

Die Zuordnung der uebernommenen, angepassten und entfallenen Felder des alten Moduls Boiler_x_Stufig ist in docs/migration/Boiler-x-Stufig.md dokumentiert.

Wesentliche Unterschiede:

• Interval entfaellt; die Regelung ist ereignisbasiert.
• IdleCounterMax wird durch LastwechselSperrzeit in Sekunden ersetzt.
• Idle und IdleCounter entfallen vollstaendig.
• PowerSteps wird durch das Vertragsfeld Leistungswerte_W ersetzt.
• Prioritaeten sind Properties; Betriebsart und Leistungsverteilung liegen im Manager.
• Die neue Modul-ID erfordert eine neue Instanz; eine automatische Umwandlung des Enelix-1-Objekts findet nicht statt.