Verbraucher 1-Stufig eventbasiert implementieren

docs/adr/0002-verbraucher-einstufig-eventbasiert.md

@@ -0,0 +1,57 @@
+# ADR 0002: Verbraucher 1-Stufig arbeitet ereignisbasiert
+
+## Status
+
+Akzeptiert.
+
+## Kontext
+
+Das Enelix-1-Modul berechnete seinen Zustand in einem festen Intervall und
+bildete die Lastwechselsperre ueber `Interval`, `IdleCounterMax` und weitere
+zyklusabhaengige Zaehler ab. Dieses Verhalten passt nicht zur
+ereignisbasierten Enelix-2-Kommunikation und machte reale Zeitabstaende von
+mehreren Properties abhaengig.
+
+## Entscheidung
+
+Der neue `VerbraucherEinStufig` verwendet keine zyklische Regelberechnung.
+Schaltkontakt, Rueckmeldung, Manager-Vorgabe, Freigabe, Vorgabeablauf und
+Tagesplanung loesen die Regelung direkt aus.
+
+Als einziger modulspezifischer Wert fuer die Lastwechselbegrenzung wird
+`Umschaltabstand` in Sekunden registriert. Der Standardwert ist 5 Sekunden.
+Das Ende der Sperre wird durch einen einmaligen Timer ausgeloest.
+
+Das gemeinsame `Meldeintervall` bleibt erhalten, weil Vertrag `3.0`
+zusaetzlich zu Ereignismeldungen eine periodische Vollmeldung fordert. Dieser
+Timer ist kein Regelzyklus.
+
+Die Tagesmindestlaufzeit wird in realen Sekunden und lokaler Symcon-Zeitzone
+gezaehlt. Das Modul erzwingt den Betrieb erst zum spaetestmoeglichen Zeitpunkt,
+an dem die fehlende Laufzeit vor Mitternacht noch erreicht werden kann.
+
+## Alternativen
+
+- Ein fester Regelzyklus wurde verworfen, weil Reaktionszeit und Sperrzeit
+  wieder voneinander abhaengen wuerden.
+- Getrennte Ein- und Ausschaltzeiten wurden verworfen, weil sie fuer diese
+  Adaption nicht freigegeben sind.
+- Die feste Nachtphase aus Enelix 1 wurde verworfen, weil sie weder
+  konfigurierbar noch Teil der Enelix-2-Spezifikation ist.
+
+## Folgen
+
+- Lastwechsel reagieren ohne Polling auf relevante Ereignisse.
+- `Interval` und `IdleCounterMax` entfallen.
+- Der Manager sieht waehrend einer Sperre nur die aktuelle Leistung und
+  `AenderungMoeglich=false`.
+- Ein optionaler Rueckmeldekontakt muss innerhalb des Umschaltabstands folgen.
+- Tageslaufzeit und Mindestlaufzeit sind unabhaengig von einer Zyklusdauer.
+- Das Modul bleibt vollstaendig im Repository Enelix EMS; Enelix Utils erhaelt
+  keine geraetespezifische Logik.
+
+## Offene Punkte
+
+- Eine spaetere sperrbare Variante wird separat spezifiziert.
+- Unterschiedliche Ein- und Ausschaltabstaende benoetigen eine neue
+  Architekturentscheidung.

docs/migration/Verbraucher-1-Stufig.md

@@ -0,0 +1,60 @@
+# Migration von Verbraucher_1_Stufig
+
+Das Enelix-1-Modul wird nicht in-place aktualisiert. Das neue Modul verwendet
+eine neue Modul-ID, den Vertrag `3.0` und eine ereignisbasierte Regelung.
+
+## Eigenschaften
+
+| Enelix 1 | Enelix 2 | Migration |
+| --- | --- | --- |
+| `BoilerLeistung` | `Nennleistung` | Wert in ganzen Watt uebernehmen. |
+| `Schaltkontakt1` | `SchaltkontaktVariableID` | Boolean-Aktor uebernehmen und Aktion pruefen. |
+| nicht vorhanden | `SchaltkontaktInvertiert` | Nur bei umgekehrter Aktorlogik aktivieren. |
+| nicht vorhanden | `RueckmeldungVariableID` | Optional eine echte Boolean-Rueckmeldung zuordnen. |
+| `Mindesttlaufzeit` | `Mindestlaufzeit` | Alter Wert war in Minuten gedacht; fuer gleiches Verhalten mit 60 multiplizieren und als Sekunden eintragen. |
+| `Zeit_Zwischen_Zustandswechseln` | `Umschaltabstand` | Alte Minuten nicht uebernehmen. Neuen Sekundenwert bewusst festlegen; Standard ist 5 s. |
+| `Interval` | entfaellt | Keine zyklische Regelberechnung mehr. |
+| `IdleCounterMax` | entfaellt | Keine zyklusbasierte Idle-Erkennung mehr. |
+
+## Variablen und Verhalten
+
+| Enelix 1 | Enelix 2 |
+| --- | --- |
+| `DailyOnTime` | `Tageslaufzeit` in echten Sekunden |
+| `IstNacht` | entfaellt; Mindestlaufzeit wird am spaetestmoeglichen Start des lokalen Kalendertags erzwungen |
+| `IsTimerActive` | entfaellt; interne einmalige Timer |
+| `Aktuelle_Leistung` | gemeinsames `Istleistung` |
+| `Power` | gemeinsames `Sollleistung` |
+| `PowerSteps` | Vertragsfeld `Leistungswerte_W` |
+| `PV_Prio` | Property `PrioritaetPV` |
+| `Sperre_Prio` | Property `PrioritaetPeak` |
+| `Is_Peak_Shaving` | entfaellt; Betriebsart liegt im Manager |
+| `Leistung_Delta` | entfaellt; Leistungsverteilung liegt im Manager |
+| `Idle`, `IdleCounter` | entfallen |
+
+Die feste Enelix-1-Nachtzeit von 22:00 bis 07:00 wird nicht uebernommen.
+Enelix 2 plant nur den Zeitpunkt, ab dem die verbleibende Mindestlaufzeit vor
+dem lokalen Tagesende zwingend eingeschaltet werden muss.
+
+## Inbetriebnahme
+
+1. Bestehende Instanzkonfiguration und aktuelle Aktorlogik dokumentieren.
+2. Neue Instanz **Verbraucher 1-Stufig** anlegen.
+3. Leistung, Aktor, Invertierung und optional Rueckmeldung konfigurieren.
+4. Mindestlaufzeit von Minuten in Sekunden umrechnen.
+5. `Umschaltabstand` neu in Sekunden festlegen; nicht den alten Minutenwert
+   kopieren.
+6. Neue Instanz im Enelix-2-Manager aktiv zuordnen.
+7. Bei ausgeschalteter lokaler EMS-Freigabe Ein/Aus und Rueckmeldung
+   beaufsichtigt pruefen.
+8. Alte Instanz erst deaktivieren, danach `Aktiv` an der neuen Instanz
+   einschalten.
+9. Mindestens einen Timeout, einen verhinderten Lastwechsel und einen
+   Tageswechsel kontrollieren.
+
+## Rueckkehr
+
+Solange die alte Instanz nicht geloescht wurde, kann zurueckgekehrt werden,
+indem die neue Instanz im Manager deaktiviert und ausgeschaltet wird. Danach
+darf die alte Instanz wieder aktiviert werden. Beide Module duerfen nie
+gleichzeitig denselben Aktor steuern.

docs/module/README.md

@@ -1,7 +1,7 @@
 # EMS-Module und Modulentwürfe
 
-> Manager und Warmwassererwaermer sind als installierbare IP-Symcon-Module
-> umgesetzt. Die weiteren Ordner enthalten Besprechungsgrundlagen.
+> Manager, Warmwassererwaermer und Verbraucher 1-Stufig sind als installierbare
+> IP-Symcon-Module umgesetzt. Die weiteren Ordner enthalten Besprechungsgrundlagen.
 
 Alle steuerbaren Verbraucher verwenden die gemeinsamen Datenpunkte aus der
 [EMS-Schnittstelle](../Schnittstelle.md). In den Modul-READMEs stehen deshalb
@@ -13,7 +13,7 @@ nur zusätzliche Properties, Variablen, Zustände und offene Punkte.
 | [Batterie](Batterie/README.md) | Laden und Entladen eines Speichers |
 | [Wassererwärmer](Wassererwaermer/README.md) | Mehrstufige elektrische Erwärmung (implementiert) |
 | [Pufferspeicher](Pufferspeicher/README.md) | Heizstufen nach Heizkurve |
-| [Verbraucher 1-Stufig](Verbraucher-1-Stufig/README.md) | Ein-/Aus-Verbraucher |
+| [Verbraucher 1-Stufig](Verbraucher-1-Stufig/README.md) | Ein-/Aus-Verbraucher (implementiert) |
 | [Wärmepumpe](Waermepumpe/README.md) | Sperrkontakt oder SG Ready |
 | [Ladestation Stand-Alone](Ladestation-Stand-Alone/README.md) | Direkte Geräteanbindung |
 | [Ladestation Gateway](Ladestation-Gateway/README.md) | Ladestation am Easee Gateway |

docs/module/Verbraucher-1-Stufig/README.md

@@ -1,36 +1,156 @@
 # Verbraucher 1-Stufig
 
-> Status: Diskussionsentwurf.
+> Status: implementiert fuer IP-Symcon 8 und den Enelix-2-Vertrag `3.0`.
 
-Schaltet eine elektrische Last. Das Leistungsangebot ist üblicherweise
-`[0, Nennleistung]`.
+Das Modul schaltet einen elektrischen Ein-/Aus-Verbraucher. Im freien Zustand
+meldet es dem Manager das Leistungsangebot `[0, Nennleistung]`. Waerend der
+Umschaltsperre und bei lokal erzwungener Mindestlaufzeit wird nur der aktuell
+zulaessige Leistungswert angeboten.
 
-## Zusätzliche Variablen
+## Architekturentscheidung
+
+Die Regelung ist ereignisbasiert. Neuberechnungen werden ausgeloest durch:
+
+- eine neue Manager-Vorgabe,
+- eine Aenderung an Schaltkontakt oder optionaler Rueckmeldung,
+- das Ein- oder Ausschalten der lokalen EMS-Freigabe,
+- das Ende des Umschaltabstands,
+- das Ablaufen einer Manager-Vorgabe,
+- den naechsten relevanten Zeitpunkt der Tageslaufzeitplanung.
+
+Es gibt keinen Regelzyklus, kein `Interval` und keinen `IdleCounterMax`.
+`Meldeintervall` bleibt als vertraglich geforderte periodische Vollmeldung
+bestehen und steuert keine Regelberechnung.
+
+## Properties
+
+Zu den sechs gemeinsamen Verbraucher-Properties aus
+[`Schnittstelle.md`](../../Schnittstelle.md) kommen sieben
+Modul-Properties hinzu.
+
+| Ident | Typ | Standard | Beschreibung |
+| --- | --- | ---: | --- |
+| `Nennleistung` | Integer | `0` | Positive elektrische Leistung in W. |
+| `SchaltkontaktVariableID` | Integer | `0` | Boolean-Aktor mit Standard- oder benutzerdefinierter Aktion. |
+| `SchaltkontaktInvertiert` | Boolean | `false` | Kehrt die Ein-/Aus-Semantik des Aktors um. |
+| `RueckmeldungVariableID` | Integer | `0` | Optionale Boolean-Rueckmeldung; `true` bedeutet eingeschaltet. |
+| `Mindestlaufzeit` | Integer | `0` | Geforderte Laufzeit pro lokalem Kalendertag in Sekunden, maximal 86400. |
+| `Umschaltabstand` | Integer | `5` | Sekunden bis zum naechsten erlaubten Lastwechsel. |
+| `DiagnosevariablenAnzeigen` | Boolean | `false` | Legt gemeinsame Diagnosevariablen und `Rueckmeldefehler` an. |
+
+`EinstellungenInVisu` ist Teil der gemeinsamen Verbraucherbasis. Das Modul
+besitzt derzeit keine zusaetzlichen bedienbaren Einstellvariablen und wertet
+diese Property deshalb noch nicht weiter aus.
+
+## Variablen
+
+Immer sichtbar:
 
 | Ident | Typ / Zugriff | Beschreibung |
 | --- | --- | --- |
-| `Schaltzustand` | Boolean / Anzeige | Rückgemeldeter oder berechneter Kontaktzustand. |
-| `Tageslaufzeit` | Integer / Anzeige | Laufzeit seit lokalem Tagesbeginn in Sekunden; persistent mit Tageskennung. |
+| `Aktiv` | Boolean / bedienbar | Lokale EMS-Freigabe; Startwert `false`. |
+| `Schaltzustand` | Boolean / Anzeige | Rueckgemeldeter oder aus dem Aktor berechneter Zustand. |
+| `Tageslaufzeit` | Integer / Anzeige | Laufzeit des lokalen Kalendertags in Sekunden. |
 
-## Zusätzliche Properties
+Mit `DiagnosevariablenAnzeigen` werden diese Variablen zusaetzlich angelegt:
 
-| Ident | Typ | Standard / Beschreibung |
-| --- | --- | --- |
-| `Nennleistung` | Float | `0*` W; grösser 0. |
-| `SchaltkontaktVariableID` | Integer | `0`; erforderlicher Boolean-Aktor mit Action. |
-| `SchaltkontaktInvertiert` | Boolean | `false`; Ein-/Aus-Semantik des Aktors. |
-| `RueckmeldungVariableID` | Integer | `0`; optionale echte Rückmeldung. |
-| `Mindestlaufzeit` | Integer | `0` s. |
-| `Umschaltabstand` | Integer | `60` s; Mindestabstand zwischen Änderungen. |
+- `Istleistung`
+- `Leistungsquelle`
+- `Sollleistung`
+- `SollwertGueltig`
+- `Verfuegbar`
+- `AenderungMoeglich`
+- `Stoerung`
+- `Stoertext`
+- `Rueckmeldefehler`
 
-Der frühere Ident `BoilerLeistung` wird durch `Nennleistung` ersetzt.
+Die Regellogik arbeitet mit persistenten Attributen und ist nicht von der
+Sichtbarkeit der Diagnosevariablen abhaengig.
 
-## Zustand
+## Zeit- und Schaltverhalten
 
-`Schaltzustand` als Status, `Tageslaufzeit_s` als Istwert und
-`Rueckmeldefehler` als Störung.
+Nach jedem Lastwechsel wird `AenderungMoeglich=false` gemeldet und das
+Leistungsangebot auf den aktuellen Wert eingeschraenkt. Nach
+`Umschaltabstand` Sekunden gibt ein einmaliger Timer den naechsten
+Lastwechsel frei. Der Standardwert betraegt 5 Sekunden.
 
-## Offene Punkte
+Die Tageslaufzeit wird mit der in IP-Symcon eingestellten lokalen Zeitzone
+gefuehrt. Sommer- und Winterzeit sowie der Wechsel um Mitternacht werden
+beruecksichtigt. Ist die konfigurierte Mindestlaufzeit noch nicht erreicht,
+wird der Verbraucher erst zum spaetestmoeglichen Zeitpunkt lokal
+eingeschaltet, an dem die Restlaufzeit bis Mitternacht noch erfuellt werden
+kann. In dieser Phase meldet er `AenderungMoeglich=false`.
 
-- Sperrbare Variante später integrieren und vollständig überarbeiten.
-- Unterschiedliche Ein- und Ausschaltzeiten erst nach Freigabe ergänzen.
+Bei Aktivierung sehr kurz vor Tagesende kann eine unmoeglich hohe Restlaufzeit
+naturgemaess nicht mehr vollstaendig nachgeholt werden. Der Verbraucher wird
+dann sofort eingeschaltet und die tatsaechliche Laufzeit erfasst.
+
+## Rueckmeldung und Fehler
+
+Ohne separate Rueckmeldung wird der Schaltzustand aus der Aktorvariable
+berechnet. Mit `RueckmeldungVariableID` wartet das Modul bis zum Ende des
+Umschaltabstands auf den angeforderten Zustand. Liegt er dann nicht an, werden
+`Rueckmeldefehler=true`, `Stoerung=true` und `Verfuegbar=false` gemeldet.
+
+Die Istleistung ist immer berechnet: `0` oder `Nennleistung`. Deshalb wird
+`Leistungsquelle=1` gemeldet, auch wenn der Boolean-Schaltzustand ueber eine
+physische Rueckmeldung erfasst wird.
+
+## Managerkommunikation
+
+Das Modul implementiert
+`VerbraucherSchnittstelle::ManagerdatenEmpfangen()` und verwendet
+ausschliesslich den Vertrag `3.0`. Der Verbraucher besitzt keine
+Manager-ID-Property. Er akzeptiert nur Manager, in deren manueller oder
+automatischer Verbraucherzuordnung seine Instanz aktiv eingetragen ist.
+
+Rueckmeldungen erfolgen bei relevanten Ereignissen, kurz verzoegert nach einer
+Manager-Vorgabe und zusaetzlich alle `Meldeintervall` Sekunden. Eine Vorgabe
+wird nach `VorgabeTimeout` Sekunden ohne Erneuerung ungueltig.
+
+## Installation und Inbetriebnahme
+
+1. Im IP-Symcon Module Control den Testing-Branch `develop` der Bibliothek
+   `https://git.belevo.ch/ENELIX/Enelix-EMS.git` installieren oder
+   aktualisieren.
+2. Unter **Instanz hinzufuegen** nach **Verbraucher 1-Stufig** suchen und eine
+   Instanz anlegen.
+3. `Nennleistung` in ganzen Watt eintragen.
+4. Als `Schaltkontakt` eine Booleanvariable mit funktionsfaehiger Aktion
+   auswaehlen. Bei umgekehrter Aktorlogik `SchaltkontaktInvertiert`
+   aktivieren.
+5. Optional eine separate Boolean-Rueckmeldung auswaehlen. Dort muss
+   `true` dem physisch eingeschalteten Verbraucher entsprechen.
+6. Prioritaeten, `Mindestlaufzeit`, `Umschaltabstand`,
+   `Meldeintervall` und `VorgabeTimeout` einstellen und die Konfiguration
+   uebernehmen.
+7. Die neue Instanz im Manager manuell aktiv zuordnen oder bei automatischer
+   Suche in der gefundenen Liste aktivieren.
+8. Fuer die Erstpruefung `DiagnosevariablenAnzeigen` und bei Bedarf
+   `LoggingEin` einschalten.
+9. Unter Aufsicht `Aktiv` einschalten und ueber den Manager je eine Ein- und
+   Aus-Vorgabe pruefen.
+
+## Abnahmecheckliste
+
+- `Aktiv=false` schaltet den Ausgang aus.
+- `Aktiv=true` und eine Manager-Vorgabe `Nennleistung` schalten den Ausgang
+  ein.
+- Direkt nach einem Wechsel ist `AenderungMoeglich=false`; nach 5 Sekunden
+  wird es mit Standardkonfiguration wieder `true`.
+- Eine Gegenanforderung waehrend der Sperre wird vom Leistungsangebot
+  ausgeschlossen.
+- Die optionale Rueckmeldung folgt dem Ausgang innerhalb des
+  Umschaltabstands; andernfalls erscheint eine Stoerung.
+- `Tageslaufzeit` steigt nur im eingeschalteten Zustand und beginnt am
+  lokalen Tageswechsel wieder bei 0.
+- Nach Ablauf von `VorgabeTimeout` wird ohne neue Manager-Vorgabe
+  ausgeschaltet, sobald der Umschaltabstand dies zulaesst.
+- Nach Neustart oder erneuter Konfiguration wird der reale Schaltzustand
+  eingelesen; alte Manager-Vorgaben werden nicht ungeprueft fortgesetzt.
+
+## Migration
+
+Die Zuordnung der Enelix-1-Felder, Einheiten und bewusst entfallenen
+Kommunikationsvariablen steht in
+[`docs/migration/Verbraucher-1-Stufig.md`](../../migration/Verbraucher-1-Stufig.md).