Enelix-EMS/docs/module/Ladestation-Stand-Alone/README.md

Ladestation Stand-Alone

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

Das Modul bindet eine einzelne Ladestation direkt an Enelix EMS an. Es liest den Fahrzeug- und Ladezustand ueber die Geraete-API, ermittelt die Phasenzahl wie Enelix 1 und setzt den vom Manager gewaehlten Ladestrom. Es benoetigt keine Gateway-Instanz und hat keine technische Beziehung zum separaten Modul Ladestation Gateway.

Funktionsumfang

• direkte Statusabfrage und Steuerung der unterstuetzten Ladestationen,
• Fahrzeug-, Lade- und Phasenerkennung nach der Enelix-1-Logik,
• Leistungsangebote fuer PV- und Peakbetrieb,
• lokale Freigabe und Umschaltung zwischen Solar- und Normalbetrieb,
• Kommunikation mit dem Enelix Manager ueber den Nachrichtenvertrag 4.0,
• optional sichtbare Diagnosevariablen und schaltbares Debug-Logging,
• automatisierte Tests mit Fake-HTTP-Transport ohne reale Ladestation.

Unterstuetzte Geraete

Geraetetyp	Statusabfrage	Steuerung	Erforderliche Konfiguration
go-e Charger, alte API	GET /mqtt?payload=	alw und amp	IP-Adresse oder Hostname
go-e Charger Gemini / Gemini flex	GET /api/status	frc und amp	IP-Adresse oder Hostname
smart-me Pico	Pico-Charging-API	Load-Management-Current-API	Geraete-ID, Seriennummer, Benutzername und Passwort

Bei go-e wird die lokale HTTP-API verwendet. Die Geraeteadresse wird ohne http://, Pfad oder Parameter eingetragen. Die Pico-Anbindung verwendet HTTPS und HTTP Basic Auth gegen api.smart-me.com. Zugangsdaten werden weder als Variable noch im Debug-Protokoll oder im Diagnosefeld LetzterGeraetebefehl ausgegeben.

Fahrzeug- und Phasenerkennung

Die Auswertung folgt bewusst dem Verhalten der bisherigen Enelix-1-Ladestation:

1. Bei go-e gilt das Fahrzeug als verbunden, wenn car != 1 ist. Bei Pico wird entsprechend State != 1 ausgewertet.
2. Die gemessene Leistung wird bei der alten go-e-API mit Faktor 10, bei Gemini direkt in Watt und bei Pico von kW in Watt umgerechnet.
3. go-e meldet die drei Phasenstroeme einzeln. Sobald mindestens zwei Phasen Strom fuehren, wird dreiphasiges Laden direkt erkannt.
4. Sind beim Anstecken noch keine belastbaren Phasenwerte vorhanden, gibt das Modul zunaechst den konfigurierten Maximalstrom als Erkennungsstrom vor. Bis zur abgeschlossenen Erkennung bleibt Phasenzahl=0 und das EMS-Angebot [0].
5. Nach Phasenerkennungszeit gilt wie in Enelix 1: ueber 7500 W werden drei Phasen erkannt, andernfalls eine Phase. Die erkannte Phasenzahl bleibt bis zum Ausstecken erhalten und kippt waehrend einer Ladepause nicht zurueck.
6. Der Ladestrom wird aus der Leistung mit 230 W/A einphasig beziehungsweise 684 W/A dreiphasig berechnet.
7. Ein Ladeende wird nur nach zuvor tatsaechlich gemessener Ladeleistung erkannt. Eine vom EMS angeordnete Solarpause gilt deshalb nicht als FahrzeugGeladen.

Der normalisierte Fahrzeugstatus verwendet folgende Werte:

Wert	Bedeutung
0	unbekannt oder noch nicht ermittelt
1	kein Fahrzeug verbunden
2	Fahrzeug verbunden und bereit
3	Fahrzeug laedt
4	Fahrzeug geladen

Leistungsregelung

Ein Leistungsangebot groesser als 0 W wird nur erzeugt, wenn das Modul aktiviert, die Ladefreigabe gesetzt, ein Fahrzeug verbunden und das Fahrzeug noch nicht als geladen erkannt ist. Andernfalls meldet das Modul [0] und stoppt die Ladestation.

Betriebsart	Solarladen	Leistungsangebot
PV	ein	0 W und alle Ladestufen von 6 A bis zum konfigurierten Maximum
PV	aus	ausschliesslich die maximale Ladeleistung
Peak	ein	ausschliesslich [0]; die Ladestation wird gestoppt
Peak	aus	0 W und alle Ladestufen von 6 A bis zum konfigurierten Maximum

Die Leistungsstufen entsprechen Enelix 1: 230 W pro Ampere einphasig und 684 W pro Ampere dreiphasig. Ohne gueltige Manager-Vorgabe faehrt das Modul bei aktivem Solarladen mit 0 A; bei ausgeschaltetem Solarladen verwendet es die maximale angebotene Leistung.

Nach einer Leistungsaenderung wird die aktuelle Stufe fuer ZeitZwischenZustandswechseln gehalten. Waehrend der Mindesteinschaltdauer bleiben positive Leistungsstufen regelbar, 0 W wird jedoch nicht angeboten. Nach dem Abschalten meldet das Modul waehrend der Mindestausschaltdauer ausschliesslich [0]. Sicherheitsabschaltungen durch Deaktivierung, fehlende Ladefreigabe, Ausstecken oder ein erkanntes Ladeende greifen sofort.

Bedienung

Ident	Wirkung
Aktiv	Gemeinsame lokale EMS-Freigabe. false setzt das Angebot auf [0] und stoppt die Ladestation.
Ladefreigabe	Lokale Freigabe fuer das Laden. Diese Variable ist nur mit EinstellungenInVisu=true sichtbar.
Solarladen	Schaltet das oben beschriebene PV-/Peak-Verhalten um. Diese Variable ist nur mit EinstellungenInVisu=true sichtbar.

Die Properties Ladefreigabe und Solarladen definieren die Startwerte. Eine Aenderung der jeweiligen Property wird beim Anwenden der Konfiguration in den lokalen Zustand uebernommen. Eine Bedienung der Variablen verwirft eine noch gueltige Manager-Vorgabe und berechnet das Leistungsangebot sofort neu.

Konfiguration

Gemeinsame EMS-Einstellungen

Property	Typ	Standard	Beschreibung
PrioritaetPV	Integer	0	Prioritaet des Verbrauchers im PV-Betrieb.
PrioritaetPeak	Integer	0	Prioritaet des Verbrauchers im Peakbetrieb.
Meldeintervall	Integer	10 s	Intervall fuer die periodische Vollmeldung an zugeordnete Manager.
VorgabeTimeout	Integer	120 s	Gueltigkeitsdauer einer Manager-Vorgabe ohne Erneuerung.
EinstellungenInVisu	Boolean	false	Blendet Ladefreigabe und Solarladen als bedienbare Variablen ein.
LoggingEin	Boolean	false	Aktiviert das laufende Debug-Protokoll des Moduls.

Ladestation und Diagnose

Property	Typ	Standard	Beschreibung
Geraetetyp	Integer	0	1 go-e alt, 2 go-e Gemini, 3 smart-me Pico; 0 ist nicht konfiguriert.
Geraeteadresse	String	leer	IP-Adresse oder Hostname fuer beide go-e-Varianten.
GeraeteID	String	leer	Geraete-ID fuer die Pico-Statusabfrage.
Seriennummer	String	leer	Seriennummer fuer die Pico-Stromvorgabe.
Benutzername	String	leer	Benutzername fuer die Pico-API.
Passwort	String	leer	Passwort fuer die Pico-API; im Formular als Passwortfeld dargestellt.
MaximalerLadestrom	Integer	16 A	Obergrenze der angebotenen Ladestufen; zulaessig sind 6 bis 32 A.
Phasenerkennungszeit	Integer	60 s	Dauer der Maximalstrom-Probe vor der leistungsbasierten Phasenerkennung.
FahrzeugstromErkennungszeit	Integer	90 s	Zeit, die eine stabile Stromunterschreitung anliegen muss, bevor die Fahrzeuggrenze mit 2,5 A Reserve uebernommen wird.
ZeitZwischenZustandswechseln	Integer	1 min	Mindestabstand zwischen zwei Leistungsaenderungen.
Mindesteinschaltdauer	Integer	0 min	Mindestdauer nach dem Einschalten, in der kein Abschalten auf 0 W angeboten wird.
Mindestausschaltdauer	Integer	0 min	Mindestpause nach dem Abschalten, in der nur 0 W angeboten werden.
Abfrageintervall	Integer	5 s	Intervall der Geraetestatusabfrage.
Ladefreigabe	Boolean	true	Startwert der lokalen Ladefreigabe.
Solarladen	Boolean	true	Startwert der lokalen Solarlogik.
DiagnosevariablenAnzeigen	Boolean	false	Blendet gemeinsame und ladestationsspezifische Diagnosevariablen ein.

Die internen Properties Testmodus und Testantwort gehoeren ausschliesslich zum automatisierten Symcon-Funktionstest und erscheinen nicht im Konfigurationsformular.

Variablen

Immer sichtbar:

Ident	Typ / Zugriff	Beschreibung
Aktiv	Boolean / bedienbar	Lokale EMS-Freigabe; der Initialwert ist false.
FahrzeugVerbunden	Boolean / Anzeige	Zeigt, ob die API ein verbundenes Fahrzeug meldet.
FahrzeugGeladen	Boolean / Anzeige	Ergebnis der kompatiblen Enelix-1-Voll-Erkennung.
Fahrzeugstatus	Integer / Anzeige	Normalisierter Status von 0 bis 4.
Ladestrom	Float / Anzeige	Aus der gemessenen Leistung ermittelter Ladestrom in A.
Phasenzahl	Integer / Anzeige	0 unbekannt, 1 einphasig oder 3 dreiphasig.

Nur mit EinstellungenInVisu=true sichtbar und bedienbar:

• Ladefreigabe
• Solarladen

Nur mit DiagnosevariablenAnzeigen=true sichtbar:

Ident	Beschreibung
Istleistung	Von der Ladestation gemessene Leistung in W.
Leistungsquelle	Immer 2 fuer eine gemessene Leistung.
Sollleistung	Letzte angenommene Manager-Vorgabe in W.
SollwertGueltig	Zeigt, ob die Vorgabe noch gueltig und im aktuellen Angebot enthalten ist.
Verfuegbar	Zeigt, ob die Ladestation grundsaetzlich Leistung aufnehmen kann.
AenderungMoeglich	Zeigt, ob das aktuelle Angebot mehr als eine Leistungsstufe enthaelt.
Stoerung	Sammelstatus fuer Konfigurations- und Kommunikationsfehler.
Stoertext	Letzte verstaendliche Fehlerbeschreibung.
LetzterGeraetebefehl	Letzte HTTP-Methode und URL ohne Zugangsdaten.
LeistungsangebotDiagnose	Aktuelles Leistungsangebot als JSON-Liste in W.

Die Regellogik speichert ihren Zustand unabhaengig von der Sichtbarkeit der Diagnosevariablen. Das Ein- oder Ausblenden veraendert daher nicht das Regelverhalten.

Managerkommunikation

Das Modul implementiert VerbraucherSchnittstelle::ManagerdatenEmpfangen() und verwendet ausschliesslich den Nachrichtenvertrag 4.0. Eine separate Manager-ID wird nicht konfiguriert. Das Modul akzeptiert Vorgaben nur von einem Manager, in dessen manueller oder automatischer Verbraucherzuordnung die Ladestation aktiv eingetragen ist.

An den Manager werden neben den gemeinsamen Feldern diese Zustaende gemeldet:

• Sollleistung_W
• FahrzeugVerbunden
• FahrzeugGeladen
• Fahrzeugstatus
• Phasenzahl
• Ladestrom_A
• Ladefreigabe
• Solarladen
• Ladefehler mit Stoertext

Eine Sollleistung wird nur angenommen, wenn sie im zuletzt berechneten Leistungsangebot enthalten ist. Nach VorgabeTimeout ohne Erneuerung wird sie ungueltig. Statusaenderungen werden kurz verzoegert und zusaetzlich alle Meldeintervall Sekunden an alle zugeordneten Manager gemeldet.

Instanzstatus und Fehlerbehandlung

Status	Bedeutung
102	Konfiguration und letzte Geraetekommunikation sind gueltig.
201	Konfiguration ungueltig, beispielsweise fehlende Adresse oder Pico-Zugangsdaten.
202	Geraetekommunikation oder Antwortauswertung fehlgeschlagen.

Bei einem Fehler meldet das Modul Verfuegbar=false, AenderungMoeglich=false und setzt Stoerung sowie Stoertext. HTTP-Anfragen verwenden 5 Sekunden Verbindungs- und 10 Sekunden Gesamt-Timeout. Antworten ab HTTP-Status 400 sowie unvollstaendige oder ungueltige JSON-Antworten gelten als Kommunikationsfehler.

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 Ladestation Stand-Alone suchen und eine Instanz anlegen.
3. Den Geraetetyp auswaehlen und die dazugehoerigen Verbindungsdaten eintragen: bei go-e nur IP-Adresse oder Hostname, bei Pico Geraete-ID, Seriennummer, Benutzername und Passwort.
4. Den maximal zulaessigen Ladestrom der Installation zwischen 6 und 32 A einstellen. Diese Grenze ersetzt keine elektrische Absicherung.
5. Abfrageintervall, Meldeintervall, VorgabeTimeout sowie die beiden Prioritaeten festlegen.
6. Die gewuenschten Startwerte fuer Ladefreigabe und Solarladen setzen.
7. Fuer die Erstinbetriebnahme EinstellungenInVisu, DiagnosevariablenAnzeigen und bei Bedarf LoggingEin aktivieren.
8. Die Instanz im Manager manuell aktiv zuordnen oder bei automatischer Suche in der gefundenen Liste aktivieren.
9. Zuerst ohne Fahrzeug kontrollieren, ob die Statusabfrage fehlerfrei ist. Danach unter Aufsicht ein Fahrzeug verbinden und Aktiv einschalten.

Fuer go-e muss IP-Symcon das Geraet im lokalen Netz per HTTP erreichen koennen. Fuer Pico ist ausgehender HTTPS-Zugriff auf api.smart-me.com erforderlich. Passwoerter gehoeren ausschliesslich in das dafuer vorgesehene Passwortfeld und niemals in Repository-Dateien, Skripte oder Screenshots.

Abnahmecheckliste

• Die Instanz erreicht Status 102, und Stoerung bleibt false.
• Ohne Fahrzeug sind FahrzeugVerbunden=false, Phasenzahl=0 und das Leistungsangebot [0].
• Nach dem Anstecken wird das Fahrzeug erkannt und bei unbekannten Phasen zunaechst der konfigurierte Maximalstrom zur Erkennung angefordert.
• Nach der Erkennungszeit werden bis 7500 W eine Phase, darueber drei Phasen gespeichert. Bei go-e koennen die einzelnen Phasenstroeme die Erkennung bereits vorher abschliessen.
• Die erkannte Phasenzahl bleibt bei einer anschliessenden Ladepause stabil.
• Die gemessene Leistung wird plausibel in Istleistung und Ladestrom abgebildet.
• Aktiv=false oder Ladefreigabe=false stoppt die Ladestation.
• PV mit Solarladen=true bietet 0 W und die Ladestufen an.
• PV mit Solarladen=false bietet nur die maximale Leistung an.
• Peak mit Solarladen=true stoppt die Ladestation und bietet nur [0] an.
• Peak mit Solarladen=false bietet 0 W und die Ladestufen an.
• Eine Manager-Vorgabe ausserhalb des gemeldeten Angebots wird abgewiesen.
• Leistungswechsel-, Mindest-Ein- und Mindest-Aus-Zeiten werden im gemeldeten Angebot sichtbar und vom Manager eingehalten.
• Nach Ablauf des Vorgabe-Timeouts gilt wieder das lokale Ersatzverhalten.
• Im Debug-Protokoll und in LetzterGeraetebefehl erscheinen keine Zugangsdaten.

Fehlersuche

• Status 201: Geraetetyp und Pflichtfelder kontrollieren. Bei go-e darf die Adresse kein Protokoll, keinen Pfad und keine Parameter enthalten. Bei Pico muessen alle vier Zugangsfelder befuellt sein.
• Status 202: Erreichbarkeit, DNS, lokale Firewall und API-Antwort pruefen. Stoertext enthaelt den konkreten Kommunikations- oder JSON-Fehler.
• Fahrzeug wird nicht erkannt: Rohstatus der Geraete-API kontrollieren. Der Adapter erwartet bei go-e car und nrg[11], bei Pico State und ActiveChargingPower.
• Phasenzahl bleibt laenger auf 0: Waehrend der Erkennungsphase muessen Ladestation und Fahrzeug den angeforderten Maximalstrom tatsaechlich freigeben. Bei Pico muss fuer eine sichere Dreiphasenerkennung waehrend der Erkennung mehr als 7500 W anliegen; go-e kann zusaetzlich anhand der einzelnen Phasenstroeme erkennen.
• Manager-Vorgabe wird abgewiesen: aktive Zuordnung im Manager sowie LeistungsangebotDiagnose und die Betriebsart kontrollieren.

Tests

Die Unit- und Adaptertests verwenden einen injizierten Fake-HTTP-Transport. Damit werden fuer go-e alt, go-e Gemini und smart-me Pico Statusantworten, URL, HTTP-Methode, Authentisierung und Steueraufrufe ohne reale Hardware geprueft.

Der Symcon-Funktionstest verwendet den internen Testmodus mit simulierten API-Antworten. Er prueft alle drei Geraetevarianten, die Maximalstrom-Probe beim Anstecken, stabile Phasen waehrend einer Ladepause, die Schaltsperren, Fahrzeugstrom-Erkennung, die Leistungsangebote in PV und Peak sowie die Umschaltung ueber den Solarladen-Button.

PHP-Syntax, Struktur- und Unit-Tests des gesamten Repositorys:

composer check

Funktionstest nur fuer die Ladestation gegen IP-Symcon 8:

tests/Symcon/bin/run-symcon-tests.sh single LadestationStandAlone

Vollstaendiger Symcon-Modultestlauf:

tests/Symcon/bin/run-symcon-tests.sh all

Aufbau, Testvertrag und Ergebnisdateien sind unter docs/testing/README.md beschrieben.