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

# Verbraucher 1-Stufig

> Status: implementiert fuer IP-Symcon 8 und den Enelix-2-Vertrag `4.0`.

Das Modul schaltet einen elektrischen Ein-/Aus-Verbraucher. Im frei
schaltbaren Zustand meldet es bei PV `[0, Nennleistung]` und bei Peak `[0]`.
Ist die Tagesmindestlaufzeit faellig, wird bei PV die Nennleistung erzwungen.
Bei Peak ist konfigurierbar, ob `[0, Nennleistung]` angeboten oder die
Nennleistung ohne Sperrmoeglichkeit erzwungen wird. Waerend einer
Mindest-Ein- oder Mindest-Aus-Zeit sowie bei einer ausstehenden Rueckmeldung
wird unabhaengig von der Betriebsart nur der aktuelle bestaetigte
Leistungswert angeboten.

## 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 der zustandsabhaengigen Mindestzeit,
- das Ablaufen einer Manager-Vorgabe,
- den naechsten relevanten Zeitpunkt der Tageslaufzeitplanung.

Es gibt keinen Regelzyklus, kein `Interval`, keinen `IdleCounterMax` und
keinen allgemeinen `Umschaltabstand`. `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 neun
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 physisch eingeschaltet. |
| `Mindestlaufzeit` | Integer | `0` | Geforderte Laufzeit pro lokalem Kalendertag in Sekunden, maximal 86400. |
| `PeakSperreBeiMindestlaufzeitAnbieten` | Boolean | `true` | Bietet bei faelliger Tagesmindestlaufzeit im Peakbetrieb zusaetzlich `0` als Sperre an. Bei `false` wird die Nennleistung lokal erzwungen. |
| `Mindesteinschaltdauer` | Integer | `5` | Mindestzeit in Sekunden, die ein bestaetigter Ein-Zustand gehalten wird. |
| `Mindestausschaltdauer` | Integer | `5` | Mindestzeit in Sekunden, die ein bestaetigter Aus-Zustand gehalten wird. |
| `DiagnosevariablenAnzeigen` | Boolean | `false` | Legt gemeinsame und modulspezifische Diagnosevariablen an. |

Beide Mindestzeiten duerfen `0` sein. Die lokale Aktion `Aktiv=false`
bleibt der einzige bewusste Override und schaltet sicher aus, auch wenn die
Mindesteinschaltdauer noch laeuft.

`EinstellungenInVisu` ist Teil der gemeinsamen Verbraucherbasis. Das Modul
besitzt derzeit keine zusaetzlichen bedienbaren Einstellvariablen und wertet
diese Property deshalb nicht weiter aus.

## Variablen

Immer sichtbar:

| Ident | Typ / Zugriff | Beschreibung |
| --- | --- | --- |
| `Aktiv` | Boolean / bedienbar | Lokale EMS-Freigabe; Startwert `false`. |
| `Schaltzustand` | Boolean / Anzeige | Bestaetigter oder aus dem Aktor berechneter Zustand. |
| `Tageslaufzeit` | Integer / Anzeige | Bestaetigte Laufzeit des lokalen Kalendertags in Sekunden. |

Mit `DiagnosevariablenAnzeigen` werden zusaetzlich angelegt:

- `Istleistung`
- `Leistungsquelle`
- `Sollleistung`
- `SollwertGueltig`
- `Verfuegbar`
- `AenderungMoeglich`
- `Stoerung`
- `Stoertext`
- `Rueckmeldefehler`
- `SchaltbefehlAusstehend`
- `RestMindestzeit`

Die Regellogik arbeitet mit persistenten Attributen und ist nicht von der
Sichtbarkeit der Diagnosevariablen abhaengig.

## Mindest-Ein- und Mindest-Aus-Zeit

Nach einer bestaetigten Einschaltung wird fuer
`Mindesteinschaltdauer` Sekunden kein regulaeres Ausschalten angeboten. Nach
einer bestaetigten Ausschaltung blockiert `Mindestausschaltdauer` ein
regulaeres Einschalten.

Waerend einer Mindestzeit gilt:

- `AenderungMoeglich=false`,
- `Schaltbereit=false`,
- `RestMindestzeit_s` enthaelt die verbleibenden Sekunden,
- `Leistungswerte_W` enthaelt nur die bestaetigte Istleistung.

Ein einmaliger Timer loest am Ende der Mindestzeit genau eine Neuberechnung
aus. Der fruehere allgemeine `Umschaltabstand` ist vollstaendig entfallen.

## Rueckmeldung und Schaltbereitschaft

Ohne separate Rueckmeldung wird der logische Zustand der Aktorvariable als
sofortige Schaltbestaetigung verwendet.

Mit `RueckmeldungVariableID` ist ausschliesslich deren Booleanwert fuer
`Schaltzustand`, `Istleistung_W`, Tageslaufzeit und den Beginn der
Mindestzeit massgeblich. Nach einem Aktorbefehl und vor der passenden
Rueckmeldung meldet das Modul:

- die bisherige bestaetigte Istleistung,
- `SchaltbefehlAusstehend=true`,
- `Schaltbereit=false`,
- `AenderungMoeglich=false`,
- nur den bisherigen Leistungswert in `Leistungswerte_W`.

Sobald die Rueckmeldung den Zielzustand bestaetigt, beginnt die passende
Mindest-Ein- oder Mindest-Aus-Zeit. Es gibt bewusst keinen zusaetzlichen
zyklischen Rueckmelde-Timeout. Bleibt die Rueckmeldung aus, bleibt der
Schaltbefehl sichtbar ausstehend.

Weichen Aktor- und Rueckmeldezustand ohne ausstehenden Schaltbefehl voneinander
ab, wird `Rueckmeldefehler=true`, `Verfuegbar=false` und eine Stoerung
gemeldet.

## Tagesmindestlaufzeit

Die Tageslaufzeit wird mit der in IP-Symcon eingestellten lokalen Zeitzone
gefuehrt. Sommer- und Winterzeit sowie der Wechsel um Mitternacht werden
beruecksichtigt. Nur der bestaetigte Ein-Zustand zaehlt.

Ist die konfigurierte Tagesmindestlaufzeit noch nicht erreicht, wird der
Verbraucher zum spaetestmoeglichen Zeitpunkt angefordert, an dem die
Restlaufzeit bis Mitternacht noch erfuellt werden kann. Im PV-Betrieb wird die
Nennleistung dann lokal erzwungen. Im Peakbetrieb meldet das Modul bei
aktivierter Property `PeakSperreBeiMindestlaufzeitAnbieten` wie Enelix 1
`[0, Nennleistung]`, sodass der Manager zwischen Sperren und Nachholen der
Laufzeit waehlen kann. Ist die Property deaktiviert, wird auch im Peakbetrieb
nur die Nennleistung angeboten und lokal erzwungen. Eine noch aktive
Mindestausschaltdauer hat Vorrang; eine unmoegliche Restlaufzeit kann nicht
rueckwirkend nachgeholt werden.

## Managerkommunikation

Das Modul implementiert
`VerbraucherSchnittstelle::ManagerdatenEmpfangen()` und verwendet
ausschliesslich Vertrag `4.0`. Der Verbraucher besitzt keine
Manager-ID-Property. Er akzeptiert nur Manager, in deren manueller oder
automatischer Verbraucherzuordnung seine Instanz aktiv eingetragen ist.

Neben den gemeinsamen Vertragsfeldern werden diese Zustaende gemeldet:

- `Schaltzustand`
- `SchaltbefehlAusstehend`
- `Schaltbereit`
- `RestMindestzeit_s`
- `Tageslaufzeit_s`
- `Rueckmeldefehler`

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 und bei Bedarf `SchaltkontaktInvertiert` aktivieren.
5. Optional eine separate Boolean-Rueckmeldung auswaehlen. Dort muss
   `true` dem physisch eingeschalteten Verbraucher entsprechen.
6. Tagesmindestlaufzeit, Mindest-Einschaltdauer und Mindest-Ausschaltdauer
   passend zum angeschlossenen Geraet festlegen.
7. Die 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.
- Eine Ein-Vorgabe setzt zuerst den Aktor; mit separater Rueckmeldung bleibt
  `SchaltbefehlAusstehend=true`, bis diese einschaltet.
- Die Mindesteinschaltdauer beginnt erst mit der Ein-Rueckmeldung.
- Vor Ablauf der Mindesteinschaltdauer wird kein Ausschalten angeboten.
- Nach bestaetigter Ausschaltung beginnt die Mindestausschaltdauer.
- Vor Ablauf der Mindestausschaltdauer wird kein Einschalten angeboten.
- `RestMindestzeit_s` erreicht 0 und `Schaltbereit` wird danach true.
- `Tageslaufzeit` steigt nur bei bestaetigtem Ein-Zustand.
- Ein unerwarteter Unterschied zwischen Aktor und Rueckmeldung erzeugt eine
  Stoerung.
- Nach einem Neustart wird keine alte Manager-Vorgabe ungeprueft fortgesetzt.

## Tests

Nur dieses Modul:

```bash
composer check:verbraucher-einstufig
```

Gesamtes Repository inklusive dieser Modulsuite:

```bash
composer check
```

Die separate Suite und ihre Struktur sind unter
[`tests/VerbraucherEinStufig`](../../../tests/VerbraucherEinStufig/README.md)
dokumentiert.

## Migration

Die Zuordnung der Enelix-1- und bisherigen Enelix-2-Zeitwerte steht in
[`docs/migration/Verbraucher-1-Stufig.md`](../../migration/Verbraucher-1-Stufig.md).