Enelix-EMS/docs/module/Verbraucher-1-Stufig

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 einer Mindest-Ein- oder Mindest-Aus-Zeit, waehrend einer ausstehenden Rueckmeldung und bei lokal erzwungener Tagesmindestlaufzeit wird 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 kommen acht 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.
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. Eine noch aktive Mindestausschaltdauer hat dabei Vorrang; eine unmoegliche Restlaufzeit kann nicht rueckwirkend nachgeholt werden.

Managerkommunikation

Das Modul implementiert VerbraucherSchnittstelle::ManagerdatenEmpfangen() und verwendet ausschliesslich 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.

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:

composer check:verbraucher-einstufig

Gesamtes Repository inklusive dieser Modulsuite:

composer check

Die separate Suite und ihre Struktur sind unter tests/VerbraucherEinStufig dokumentiert.

Migration

Die Zuordnung der Enelix-1- und bisherigen Enelix-2-Zeitwerte steht in docs/migration/Verbraucher-1-Stufig.md.