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

# Verbraucher 1-Stufig

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

Das Modul schaltet einen elektrischen Ein-/Aus-Verbraucher. Im freien Zustand
meldet es dem Manager das Leistungsangebot `[0, Nennleistung]`. Waehrend der
Umschaltsperre und bei lokal erzwungener Mindestlaufzeit wird nur der aktuell
zulaessige 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 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 |
| --- | --- | --- |
| `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. |

Mit `DiagnosevariablenAnzeigen` werden diese Variablen zusaetzlich angelegt:

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

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

## Zeit- und Schaltverhalten

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.

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

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