Verbraucher 1-Stufig eventbasiert implementieren

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).