Enelix-EMS/docs/module/Manager/README.md

Manager

Status: Implementiert. Führt Hauptmanager und Peakshaving zusammen.

Der Manager liest die Netzleistung, verwaltet ausschliesslich die ausgewählten Verbraucher und verteilt Leistung im PV- oder Peak-Betrieb. Die Prioritäten kommen aus den Verbrauchermeldungen.

Variablen

Ohne angelegte Diagnosevariablen existieren nur Aktiv, Betriebsart und Netzleistung.

Ident	Typ / Zugriff	Beschreibung
Aktiv	Boolean / bedienbar	Regelung ein/aus; Start false.
Betriebsart	String / Anzeige	Inaktiv, PV oder Peak.
Netzleistung	Float / Anzeige	Aktuelle Netzleistung in W; positiv Bezug, negativ Einspeisung.
NetzleistungGueltig	Boolean / Logging	Messquelle vorhanden und aktuell.
WirksameLastspitzengrenze	Float / Logging	Aktuelle feste oder monatliche Bezugsgrenze in W.
WirksameEinspeisegrenze	Float / Logging	Anlagenweite Einspeisegrenze in W.
Abregelbedarf	Float / Logging	Aktuell erforderliche PV-Leistungsreduktion in W.
Wechselrichterstatus	String/JSON / Logging	Verteilte Grenzen und Zustand der PV-Regelung.
Verteilbudget	Float / Logging	Aktuell verfügbares Budget in W.
VerbraucherAnzahl	Integer / Logging	Anzahl zugeordneter Verbraucher.
VerbraucherVerfuegbar	Integer / Logging	Anzahl aktuell verfügbarer Verbraucher.
Verbraucherstatus	String/JSON / Logging	Letzte vollständige Meldungen.
Prognosestatus	String / Logging	NichtVerwendet, Verbunden oder Fehler.
SDLStatus	String / Logging	Status des SDL/VGT-Anschlusses.
Lizenzstatus	String / Logging	Status der Lizenzprüfung.
Stoerueberwachungsstatus	String / Logging	Status der externen Störüberwachung.
Sammelstoerung	Boolean / Logging	Eigene und weitergeleitete Störungen.
Stoertext	String / Logging	Lesbare Sammelmeldung.

Properties

Ident	Typ	Standard / Beschreibung
Rolle	Auswahl	Alleine; alternativ Hauptmanager oder Untermanager.
NetzleistungVariableID	Integer	0*; gültige Messquelle vor Regelstart.
Netzleistungsfaktor	Float	1; auf W und die vereinbarte Vorzeichenrichtung normieren.
MesswertMaxAlter	Integer	60 s; auf echte Messaktualisierung bezogen.
VerbraucherZuordnung	String/JSON	[]; manuelle Auswahl aus Instanz-ID und Aktiv-Status.
AutomatischeVerbraucherZuordnung	String/JSON	[]; Auswahl aus automatisch gefundenen Verbrauchern.
AutomatischeSuche	Boolean	true; zeigt gefundene Verbraucher zur gezielten Auswahl.
SuchbereichID	Integer	0; optionaler Suchbereich für die automatische Suche.
KeepAlive	Integer	60 s; erneuert laufende Vorgaben zyklisch.
VerbraucherTimeout	Integer	60 s; erkennt ausgebliebene Verbrauchermeldungen.
Lastspitzenmodus	Auswahl	Aus; alternativ Konstant oder Monatlich.
Lastspitzengrenze	Float	Feste Grenze in W für Modus Konstant.
Monatsgrenzen	String/JSON	Editierbare Liste mit zwölf Monatswerten in W.
SollwertSolarladen	Float	0 W; gewünschte Netzleistung im Solarladebetrieb.
Umschaltdifferenz	Float	5 %; Mindestdifferenz der berechneten Sollleistungen vor Umschaltung.
EinspeisebegrenzungAktiv	Boolean	false; gemeinsame Exportgrenze am Netzanschlusspunkt aktivieren.
Einspeisegrenze	Float	Maximale Einspeisung der Gesamtanlage in W; 0 bedeutet Nulleinspeisung.
Einspeisetoleranz	Float	100 W; Totband gegen pendelnde Wechselrichtervorgaben.
NetzfahrplanAktiv	Boolean	false; lizenzierten, tarif- und prognosebasierten Netzzielwert verwenden.
AnlagenWechselrichter	String/JSON	[]; Wechselrichter mit Typ, AC-Grenzen sowie optionalen Istleistungs- und Begrenzungsregistern.
AnlagenPVFlaechen	String/JSON	[]; PV-Flaechen mit DC-Leistung, Ausrichtung und Wechselrichter-ID.
AnlagenBatterien	String/JSON	[]; Batteriespeicher mit Kapazitaeten, Leistungen, Kopplung und Wechselrichter-ID.
PrognosePVVariableID	Integer	0; PV-Leistung in W fuer die Prognosetelemetrie.
PrognoseHausverbrauchVariableID	Integer	0; Hausverbrauch in W fuer die Prognosetelemetrie.
PrognoseSOCVariableID	Integer	0; Batterie-Ladezustand in Prozent.
PrognoseSendeintervall	Integer	60 s; zulaessig sind 60 bis 3600 Sekunden.
PrognoseAnschluss	String/JSON	Verdeckte Altproperty fuer bestehende Konfigurationen.
SDLAnschluss	String/JSON	Optionaler SDL/VGT-Anschluss.
Lizenzcode	String	Im Enelix-Lizenzportal erworbener Aktivierungscode.
StoermeldeAnschluss	String/JSON	Optionaler Anschluss zur Störüberwachung.
DiagnosevariablenAnzeigen	Boolean	false; zusätzliche Diagnosevariablen anlegen oder entfernen.
LoggingEin	Boolean	false; laufende Meldungen im Debug-Fenster ausgeben.

Es gibt keine Sollwertquellenauswahl und keine zweite Prioritätseinstellung im Manager. Im Modus Aus bleibt Solarladen aktiv, nur die Peak-Begrenzung entfällt. Die Monatsgrenzen werden in den Grundeinstellungen über eine Schaltfläche ein- und ausgeblendet. Die automatische Verbrauchersuche kann dort erneut ausgeführt werden, ohne andere ungespeicherte Formulareingaben zu verlieren.

Anlagenweite Einspeisebegrenzung

Die Einspeisebegrenzung ist Bestandteil von Peak Shaving und arbeitet auf der Messung am Netzanschlusspunkt. Fuer jeden regelbaren PV- oder Hybridwechselrichter werden die Istleistungsvariable und eine bedienbare Begrenzungsvariable konfiguriert. Der Stellwert kann als Prozent der AC-Nennleistung oder als absolute Leistung in Watt ausgegeben werden.

Der Manager berechnet eine einzige Grenze fuer die Gesamtanlage. Beim Abregeln verteilt er sie nach der tatsaechlichen Erzeugung, beim Freigeben nach der AC-Nennleistung auf alle angebotenen Wechselrichter. Das Totband verhindert Pendeln am Grenzwert. Beim Abschalten des Managers oder der Funktion werden zuvor gesetzte Grenzen kontrolliert auf die jeweilige Nennleistung zurueckgesetzt. Wechselrichter ohne beide Register werden nicht geregelt; sobald eines der beiden Register gesetzt ist, muessen beide gueltig sein und das Begrenzungsregister eine IP-Symcon-Aktion besitzen.

Der intelligente Netzfahrplan verwendet die PV-, Verbrauchs- und Netzleistungsprognose sowie Tarife und Batteriespeicher. Liegt im Prognosezeitraum mehr PV-Ertrag als zulaessige Einspeisung vor, wird dieses Potenzial als flexibler Verbrauch beziehungsweise Speicherladung eingeplant. Damit werden Verbraucher in ertragreiche Zeitfenster verschoben, bevor der harte Anlagenregler die Wechselrichter reduziert. Ein fehlender oder abgelaufener Fahrplan fuehrt automatisch zum konfigurierten SollwertSolarladen zurueck; die harte Einspeisebegrenzung bleibt unabhaengig davon aktiv.

Anlagentopologie und Prognoseexport

Der Manager ist die fuehrende Quelle fuer die technischen Stammdaten. Die Konfiguration trennt Wechselrichter, PV-Flaechen und Batteriespeicher. AC-Leistung wird am Wechselrichter, DC-Leistung an der PV-Flaeche gepflegt. Modulanzahl und Modulleistung sind optional und muessen gemeinsam gesetzt werden.

PV-Flaechen und Batterien referenzieren ihren Wechselrichter ueber dessen stabile ID. Bei hybrid koennen beide denselben Wechselrichter verwenden. Der Export ENELIX_AnlagentopologieExportieren($InstanzID) weist dann eine gemeinsame AC-Grenze aus, damit PV und Batterie die Nennleistung nicht unabhaengig doppelt beanspruchen.

Der JSON-Export enthaelt die Vertragsversion 1.0, die Lizenz-Installations-ID, die drei Komponentenlisten, gemeinsame AC-Grenzen und aggregierte Summen fuer die schrittweise Prognoseanbindung. Tarif- und Variantenparameter bleiben im Prognoseportal. Eine nichtleere Topologie wird beim Speichern automatisch ueber einen separaten, widerrufbaren Installationszugang synchronisiert. Der Lizenzserver liefert diesen Zugang nur auf ausdrueckliche Geraeteanforderung; der Manager entfernt ihn vor dem Speichern aus der Lease und haelt ihn in einem internen Attribut. Der Lizenzcode wird nicht als API-Token verwendet. Ein Synchronisationsfehler erscheint im Prognosestatus, blockiert die lokale EMS-Regelung aber nicht.

Sind PV-Leistung, Hausverbrauch und Batterie-SOC gemeinsam konfiguriert, sendet der Manager diese Werte zusammen mit der faktorbereinigten Netzleistung und einem UTC-Zeitstempel im eingestellten Intervall. Das Minimum von 60 Sekunden passt zum Rate-Limit des Lizenzportals. Die Uebertragung nutzt denselben widerrufbaren Installationszugang wie die Topologie; Lizenzcode und Geraet Token werden weder als Telemetriefelder noch im Debug-Log ausgegeben. Bei HTTP 401 oder 403 verwirft der Manager den Geraetezugang und fordert ihn bei der naechsten Lizenzpruefung neu an.

Die Entscheidung und ihre Alternativen sind in ADR 0005 dokumentiert.

Lizenzierung

Der Manager arbeitet nur mit einer gueltigen Manager-Lizenz. Das Lizenzfeld steht zuoberst im Konfigurationsformular. Ohne Freigabe bleibt die Instanz mit Status 203 inaktiv und sendet keine Leistungsvorgaben.

Voraussetzungen

• Der Auftrag im Enelix-Lizenzportal ist bezahlt und enthaelt eine aktive Manager-Berechtigung.
• IP-Symcon erreicht https://license.enelix.ch ueber HTTPS (Port 443).
• Der Lizenzcode liegt im Format ENX-XXXX-XXXX-XXXX-XXXX vor.

Lizenz aktivieren

1. Manager-Konfiguration in IP-Symcon oeffnen.
2. Lizenzcode im Bereich Lizenzierung eintragen.
3. Lizenz pruefen und binden ausloesen.
4. Die erfolgreiche Freigabe am angezeigten Lizenzstatus kontrollieren.
5. Die Manager-Konfiguration mit Uebernehmen beziehungsweise OK speichern, damit der eingegebene Lizenzcode als Property erhalten bleibt.

Beim ersten Anlegen erzeugt die Manager-Instanz eine UUIDv4 als stabile Installations-ID. Die Aktivierung sendet ausschliesslich code und installationId per POST https://license.enelix.ch/api/v1/licenses/activate. Sie benoetigt weder Portal-Cookies noch einen CSRF-Token. Derselbe Code kann von derselben Installation erneut abgerufen werden; die Bindung an eine andere Installation wird vom Lizenzserver abgelehnt.

Berechtigungen

Berechtigung	Freigegebene Funktion
manager_standard	Manager-Grundregelung ohne Peak Shaving.
manager_peak	Bezugs- und Einspeisebegrenzung am Netzanschlusspunkt.
forecast_pv	PV-Ertragsprognose; interne Modellvarianten bleiben verborgen.
forecast_load	Verbrauchsprognose; interne Modellvarianten bleiben verborgen.
grid_schedule	Intelligenter Netzfahrplan inklusive PV- und Verbrauchsprognose sowie Vermeidung von Abregelung.

Wird mit manager_standard ein Lastspitzenmodus aktiviert, bleibt der Manager mit dem Hinweis Peak Shaving ist nicht lizenziert gesperrt. manager_peak gilt zugleich als Berechtigung fuer die Grundregelung.

Erneuerung und Offline-Betrieb

Die erfolgreiche Serverantwort wird als Lease in der Manager-Instanz gespeichert. Der Manager erneuert sie ab refreshAfter automatisch ueber denselben Aktivierungsendpunkt. Schlaegt eine Erneuerung fehl, wird fruehestens nach einer Stunde erneut angefragt. Eine bereits bestaetigte Entwicklungsfreigabe bleibt bis offlineUntil verwendbar. Der aktuelle Entwicklungsvertrag setzt diesen Zeitpunkt ungefaehr 14 Tage nach Ausstellung. Danach sperrt der Manager die Regelung, bis der Lizenzserver wieder eine gueltige Antwort liefert.

Die Installations-ID und die Lease liegen in internen Instanzattributen. Die ID wird erst nach dem Laden bestehender Attribute initialisiert und bleibt bei Modulupdates, Modul-Neuladen und einem normalen Neustart unveraendert. Bei einer Migration muss trotzdem die vollstaendige Manager-Instanz mitsamt ihren Attributen uebernommen werden. Eine neu erzeugte Instanz erhaelt eine andere Installations-ID und kann einen bereits gebundenen Code nicht selbststaendig uebertragen. Wurde die ID mit einer aelteren Manager-Version bereits ungewollt geaendert, muss im Lizenzportal einmalig ein Ersatzcode erzeugt und an die nun stabile ID gebunden werden.

Status und Fehlerbehebung

Anzeige / Serverstatus	Bedeutung und Massnahme
Lizenzcode fehlt.	Code eintragen, pruefen und die Konfiguration speichern.
Lizenzcode ist ungueltig.	Format und Zeichen des Codes kontrollieren.
HTTP 404	Code unbekannt oder zugehoeriger Auftrag noch nicht bezahlt.
HTTP 409	Code ist bereits an eine andere Installation gebunden.
HTTP 429	Zu viele Aktivierungsversuche; vor dem naechsten Versuch warten.
Lizenzserver nicht erreichbar	DNS, Internetzugang, HTTPS und Systemzeit des Symcon-Systems pruefen. Eine bestehende Lease gilt nur bis offlineUntil.
Offline-Freigabe ist abgelaufen.	Verbindung zum Lizenzserver wiederherstellen und Lizenz erneut pruefen.

Fuer eine genauere Diagnose koennen die Diagnosevariablen eingeblendet werden. Lizenzstatus zeigt dann den aktuellen Zustand. Mit aktiviertem Debug-Logging werden Fehlermeldungen der Lizenzpruefung ausgegeben, niemals jedoch der Lizenzcode selbst.

Datenschutz und Entwicklungsstand

Der Lizenzcode wird als Manager-Property in der IP-Symcon-Konfiguration gespeichert. Fuer den internen Abgleich mit der Lease verwendet der Manager zusaetzlich nur einen SHA-256-Hash und schreibt den Code nicht ins Debug-Log. Die aktuelle Serverantwort ist ein Entwicklungsvertrag mit development: true und noch nicht kryptografisch signiert. Ein optionaler Geraete-Public-Key sowie Challenge-, Heartbeat- oder separate Entitlement-Endpunkte werden vom Manager derzeit bewusst nicht verwendet.

Verteilalgorithmus

Der Manager bildet das Verteilbudget aus der aktuellen Netzleistung, dem Ziel der aktiven Betriebsart und der aktuellen Leistung aller frisch gemeldeten Verbraucher. Eine gültige Istleistung wird bevorzugt; fehlt sie, bleibt der im Zustand bestätigte Sollwert konservativ reserviert.

Nicht verfügbare, nicht änderbare oder aktuell angebotlose Verbraucher behalten ihre Leistung und erhalten keine neue Vorgabe. Die übrigen Verbraucher werden nach der gemeldeten PV- beziehungsweise Peak-Priorität und danach stabil nach Instanz-ID sortiert. Von ihrem jeweils kleinsten erlaubten Leistungswert aus wird das Budget in dieser Reihenfolge aufgefüllt. Einzelwerte und ganzzahlige Bereiche werden direkt verarbeitet; Lücken werden nie durch unzulässige Werte geschlossen. Eine verbleibende Abweichung wird im Verbraucherstatus dokumentiert.

Die Betriebsart wechselt unterhalb des Solar-Sollwerts zu PV und oberhalb der wirksamen Lastspitzengrenze zu Peak. Zwischen den beiden Zielwerten bleibt sie erhalten. Umschaltdifferenz verhindert zusätzlich einen Wechsel, wenn sich die beiden berechneten Korrekturen nicht ausreichend unterscheiden.

Laufzeit und Fehlerverhalten

• Netzleistungsänderungen und Verbrauchermeldungen lösen die Berechnung aus.
• Identische Sollwerte werden nur beim Keep-alive erneut gesendet.
• Diagnosevariablen und laufendes Debug-Logging werden getrennt aktiviert.
• Verbraucherpakete werden zentral geprüft und nur von aktiv zugeordneten Absendern angenommen.
• Veraltete oder noch fehlende Verbrauchermeldungen werden nicht verteilt und als Sammelstörung ausgewiesen.
• Bei fehlender oder veralteter Netzleistung bleibt die Regelung Inaktiv und sendet keine neuen Vorgaben.
• Ohne gueltige Manager-Berechtigung bleibt der Manager mit Status 203 gesperrt.
• Die Serverantwort wird lokal gespeichert und ab refreshAfter erneuert. Bei einem Verbindungsfehler gilt eine zuvor bestaetigte Entwicklungsfreigabe bis offlineUntil; danach wird die Regelung wieder gesperrt.
• manager_standard erlaubt die Grundregelung. Ein aktiver Lastspitzenmodus benoetigt manager_peak.
• Der Lizenzcode wird nie geloggt. Lokal wird fuer den Lease-Abgleich nur sein SHA-256-Wert gespeichert.
• Die oberen Anschlüsse bleiben optional. Solange kein konkreter Adapter implementiert ist, meldet ein aktivierter Anschluss den Status Fehler, ohne die lokale EMS-Regelung zu blockieren.

Schnittstellen

• Empfängt genau VerbraucherdatenEmpfangen(array $daten).
• Sendet an jeden Verbraucher nur Kopf und Sollleistung_W.
• Obere Anschlüsse: siehe Obere Anschlüsse.

Offene Punkte

• Monatliche Batteriereserve aus dem alten Peakshaving-Modul übernehmen?
• Anbieterformate für Prognose und Störüberwachung festlegen.
• Produktive signierte Lizenz-Leases nach Abschluss des Entwicklungsvertrags integrieren.
• Verhalten und Messabgrenzung bei Untermanagern im Anlagentest bestätigen.