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]. Waerend 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 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.