Neues Ladestationsmodul mit ocpp Modul erstellt.

2026-05-10 10:56:34 +02:00
parent 51b27d568a
commit bba6494c59
27 changed files with 3290 additions and 0 deletions
@@ -0,0 +1,262 @@
+# OCPP-Ladestationsmodul fuer Symcon
+
+Stand: 2026-05-10
+
+Diese Dokumentation fasst die lokalen Anhaenge zum neuen Symcon-Ladestationsmodul zusammen und beschreibt die Zielarchitektur fuer `Ladestation_OCPP` und `OCPP_Server`.
+
+## Zielbild
+
+Das neue Ladestationsmodul wird konsequent OCPP-orientiert aufgebaut. Es soll die fachliche Wirkung von `Ladestation_v2` erreichen, aber die alte interne Struktur nicht kopieren.
+
+Verbindliche Grundsaetze:
+
+- Kommunikation zur Ladestation erfolgt OCPP-only.
+- OCPP 1.6 wird fuer Phase 1 unterstuetzt.
+- OCPP 2.0.1 wird strukturell vorbereitet.
+- OCPP 2.1 und bidirektionales Laden werden als spaetere Erweiterung vorbereitet.
+- Hersteller-Sonderfunktionen laufen nur ueber OCPP `DataTransfer`.
+- Keine Hersteller-HTTP-APIs, keine Hersteller-Cloud-APIs, keine OAuth-/Cloud-Token im Ladestationsmodul.
+- Der bestehende EMS-Vertrag zum `Manager` bleibt stabil.
+
+## Modulaufteilung
+
+`Ladestation_OCPP` ist die fachliche Ladepunkt-/Connector-Instanz. Sie bildet Status, Messwerte, Managementmodi, Diagnose und EMS-Schnittstelle ab.
+
+`OCPP_Server` ist ein separates Transport-Scaffold. Es bereitet WebHook/WebSocket, Routing und Frame-Puffer vor. Die Trennung ist wichtig, weil mehrere Ladepunkte an einem Transport haengen koennen.
+
+## EMS-Vertrag
+
+`Ladestation_OCPP` ist ein Verbraucher des bestehenden Energiemanagers. Die folgenden Idents sind Pflicht und duerfen nicht umbenannt werden:
+
+| Ident | Typ | Bedeutung |
+| --- | --- | --- |
+| `Sperre_Prio` | Integer | Prioritaet fuer Peak-Shaving |
+| `PV_Prio` | Integer | Prioritaet fuer Solarladen |
+| `Idle` | Boolean | Modul ist bereit fuer neue Leistungszuteilung |
+| `Aktuelle_Leistung` | Float | aktuell wirksame Leistung in W |
+| `Bezogene_Energie` | Float | Importenergie fuer Fairness/Bilanz |
+| `PowerSteps` | String | JSON-Array erlaubter Leistungsstufen in W |
+| `Power` | Float | vom Manager gesetzter Sollwert |
+| `Is_Peak_Shaving` | Boolean | aktueller Manager-Modus |
+| `Leistung_Delta` | Float | Soll/Ist-Abweichung in W |
+| `IdleCounter` | Integer | Zaehler fuer Regelruhe |
+
+Pflicht-Actions:
+
+- `GetCurrentData(bool Peak)`
+- `SetAktuelle_Leistung(power)`
+- `Do_UserCalc()`
+
+Positive Werte bedeuten Laden/Verbrauch, `0` bedeutet aus/neutral. Negative Werte sind fuer spaeteres bidirektionales Laden reserviert und in Phase 1 nicht aktiv.
+
+## Phase 1 Umfang
+
+Phase 1 ist ein produktionsnaher Scaffold, aber noch kein fertig abgenommener OCPP-CSMS.
+
+Sichtbar und vorbereitet:
+
+- OCPP 1.6 Grundgeruest.
+- OCPP 2.0.1/2.1 Adapterklassen als Struktur.
+- Manager-Anbindung mit `PowerSteps`.
+- Managementmodi: Nie laden, Immer laden, Konstanter Strom, Nur Solar.
+- Status-, Messwert- und Diagnosevariablen.
+- Messwertnormalisierung fuer Import/Export, Strom, Spannung, Leistung, SoC, Temperatur.
+- Transaktionsspeicher als Symcon-Attribut.
+- Fail-Safe Defaults.
+- ChargingProfile-Erzeugung als OCPP-kompatibles Datenmodell.
+
+Noch nicht produktiv fertig:
+
+- echte dauerhafte WebSocket-CSMS-Verbindung mit realer Station.
+- vollstaendige OCPP-1.6/2.0.1 State Machine.
+- automatische 1p/3p-Umschaltung mit Hardwarefreigabe.
+- bidirektionales Laden.
+- Tarifoptimierung.
+
+## OCPP-Kommunikation
+
+OCPP-Nachrichten werden intern in `OCPPMessage` normalisiert:
+
+```text
+version
+direction
+action
+uniqueId
+payload
+timestamp
+chargePointId
+```
+
+Eingehend vorbereitet:
+
+- `BootNotification`
+- `Heartbeat`
+- `StatusNotification`
+- `Authorize`
+- `StartTransaction`
+- `StopTransaction`
+- `TransactionEvent`
+- `MeterValues`
+- `DataTransfer`
+
+Ausgehend vorbereitet:
+
+- `SetChargingProfile`
+- `ClearChargingProfile`
+- `Reset`
+
+## Transport-Spike
+
+OCPP erwartet, dass die Ladestation eine WebSocket-Verbindung zum CSMS aufbaut. Symcon muss hier die CSMS-Rolle uebernehmen.
+
+Relevante Symcon-Optionen:
+
+- WebSocket Client: offizieller Symcon I/O fuer ausgehende WebSocket-Verbindungen.
+- WebHook Control: unterstuetzt WebSockets und kann Daten an Skripte oder PHP-Module weiterleiten.
+- `ProcessHookData()`: PHP-Modul-Einstieg fuer registrierte WebHooks.
+
+Bewertung fuer Phase 1:
+
+- `OCPP_Server` kapselt diese Frage, damit `Ladestation_OCPP` fachlich stabil bleibt.
+- Der produktive Rueckkanal und Dauerbetrieb muessen mit Simulator oder OCPP-1.6-Referenzstation getestet werden.
+- Ohne bestaetigten Transport wird kein externer Middleware-Dienst als Standard eingebaut.
+
+Quellen:
+
+- https://www.symcon.de/de/service/dokumentation/modulreferenz/io/websocketclient/
+- https://www.symcon.de/de/service/dokumentation/modulreferenz/webhook-control/
+- https://www.symcon.de/de/service/dokumentation/entwicklerbereich/sdk-tools/sdk-php/module/processhookdata/
+
+## Variablenkatalog
+
+Bedienung:
+
+- `Ladebereit`
+- `Managementmodus`
+- `Mindestladestrom`
+- `Konstantstrom`
+- `Max_Current_abs`
+- `SafeCurrent`
+- `SafeOff`
+- `AutomatischePhasenumschaltung`
+- `ManuelleSperre`
+- `VNB_Mode`
+- `VNB_Limit_A`
+- `VNB_Limit_W`
+
+Status:
+
+- `OCPP_Online`
+- `OCPP_Version`
+- `ChargePointId`
+- `EVSEId`
+- `ConnectorId`
+- `ConnectorStatus`
+- `ChargingState`
+- `TransactionId`
+- `Car_detected`
+- `Car_is_full`
+- `Fahrzeugstatus`
+- `Is_1_ph`
+- `NumberPhases`
+- `PhaseToUse`
+- `AktuellerEffektivSollwert`
+- `AktiveFreigabequelle`
+- `AktiverSperrgrund`
+- `AktiverReduktionsgrund`
+- `LetzterFreigabewechsel`
+- `LetztesIdToken`
+
+Messwerte:
+
+- `Ladeleistung_Effektiv`
+- `Entladeleistung_Effektiv`
+- `Strom_L1`, `Strom_L2`, `Strom_L3`
+- `Spannung_L1`, `Spannung_L2`, `Spannung_L3`
+- `Leistung_L1`, `Leistung_L2`, `Leistung_L3`
+- `Bezogene_Energie`
+- `Abgegebene_Energie`
+- `SoC`
+- `Temperatur`
+- `MesswertQualitaet`
+- `LetzterMeterValueZeitpunkt`
+
+Diagnose:
+
+- `Kommunikationsstatus`
+- `LetzteMeldung`
+- `LetzteMeldungZeit`
+- `Fehlerklasse`
+- `AktuelleStoerung`
+- `WarnungAktiv`
+- `FehlerAktiv`
+- `StoerungAktiv`
+- `LetzterOCPPFehlercode`
+- `LetztesChargingProfileAccepted`
+- `LetzterCommandTimestamp`
+- `LetzterCommandStatus`
+- `SollIstAbweichung`
+
+## Messwertnormalisierung
+
+OCPP-Messwerte werden auf interne Symcon-Kernwerte abgebildet:
+
+| OCPP-Measurand | Symcon-Wert |
+| --- | --- |
+| `Power.Active.Import` | `Ladeleistung_Effektiv` |
+| `Power.Active.Export` | `Entladeleistung_Effektiv` |
+| `Energy.Active.Import.Register` | `Bezogene_Energie` |
+| `Energy.Active.Export.Register` | `Abgegebene_Energie` |
+| `Current.Import` mit Phase | `Strom_L1/L2/L3` |
+| `Voltage` mit Phase | `Spannung_L1/L2/L3` |
+| `Power.Active.Import` mit Phase | `Leistung_L1/L2/L3` |
+| `SoC` | `SoC` |
+| `Temperature` | `Temperatur` |
+
+Import und Export werden niemals saldiert. Fehlende Messwerte gelten als unbekannt, nicht als `0`.
+
+## Phasenlogik
+
+Standard-AC-Laden wird nicht als asymmetrische Einzelphasenregelung umgesetzt.
+
+Regeln:
+
+- Dreiphasiges Laden nutzt einen gemeinsamen Stromwert pro aktiver Phase.
+- Einphasiges Laden wird mit `numberPhases = 1` abgebildet.
+- `phaseToUse` wird nur verwendet, wenn Station und OCPP-Version es nachweislich unterstuetzen.
+- Automatische Phasenumschaltung ist standardmaessig aus.
+- Umschaltung unter Last ist nicht erlaubt, wenn die Station keine sichere Umschaltung garantiert.
+
+## Fail-Safe
+
+Defaultwerte:
+
+- `MinCurrent`: 6 A
+- `SafeCurrent`: 6 A
+- `SafeOff`: 0 A
+- `EMSWatchdogSeconds`: 120 s
+- `OCPPHeartbeatTimeoutSeconds`: mindestens 90 s
+- `CommandAckTimeoutSeconds`: 30 s
+
+Bei EMS-Ausfall oder OCPP-Ausfall setzt das Modul Warnungen und blockiert keine Sicherheitsgrenzen. Kritische Stoerungen fuehren zu sicherer Reduktion bis 0 A.
+
+## Test- und Abnahmekriterien
+
+Vor produktiver Nutzung sind mindestens diese Tests noetig:
+
+- Modulinstallation in IP-Symcon.
+- Manager erkennt `Ladestation_OCPP` als Verbraucher.
+- `PowerSteps` reagieren auf Managementmodus, Ladefreigabe, Fahrzeugstatus und Peak.
+- OCPP-1.6-Simulator sendet `BootNotification`, `Heartbeat`, `StatusNotification`, `MeterValues`.
+- `SetChargingProfile` wird korrekt als OCPP-Frame erzeugt.
+- EMS-Watchdog und OCPP-Watchdog setzen klare Warnungen.
+- Kein Hersteller-HTTP oder Cloud-Token wird verwendet.
+
+## Meilensteine
+
+1. M1: Scaffold, EMS-Vertrag, OCPP 1.6-Grundstruktur, Transport-Spike.
+2. M2: Phasenmessung, Worst-Phase-Logik, Gruppenlimit.
+3. M3: OCPP 2.0.1 Device Model, `TransactionEvent`, `numberPhases`, `phaseToUse`.
+4. M4: OCPP 2.1 und bidirektionales Laden.
+5. M5: Robustheit, Watchdogs, Wiederanlauf, Testfaelle.
+6. M6: Monitoring, Betrieb, Admin-Doku.