Easee-Gateway und Ladestationsmodul implementieren

docs/module/Easee-Gateway/README.md

@@ -1,35 +1,77 @@
 # Easee Gateway
 
-> Status: Diskussionsentwurf. Kommunikationsmodul, kein Verbraucher und keine
-> Verwendung der Verbraucherbasis.
+> Status: implementiert fuer IP-Symcon 8 und die Easee Cloud API.
 
-Das bestehende Gateway wird übernommen. Anzeigen werden deutsch; technische
-Alt-Idents bleiben zur Kompatibilität erhalten. Eine passende vorhandene
-Verbindung soll bei der Instanziierung wiederverwendet werden.
+Das Modul stellt pro Easee-Nutzerkonto genau eine gemeinsame Verbindung bereit.
+Benutzername, Passwort, Access Token und Refresh Token verbleiben im Gateway.
+Mehrere Instanzen von **Ladestation Gateway** koennen denselben Elternknoten
+verwenden.
 
-## Variablen
+## Funktionsumfang
 
-| Technischer Ident / Anzeige | Typ / Zugriff | Beschreibung |
-| --- | --- | --- |
-| `Connected` / Verbunden | Boolean / Anzeige | SignalR-Verbindungsstatus. |
-| `SubscriptionCount` / Angemeldete Ladestationen | Integer / Anzeige | Anzahl registrierter Geräte. |
-| `LastError` / Letzter Fehler | String / Anzeige | Diagnose ohne Zugangsdaten. |
+- Anmeldung mit Easee-Benutzerkonto und automatische Token-Erneuerung,
+- gemeinsame Ereignisverbindung zu `streams.easee.com`,
+- Abonnement mehrerer Ladestationen mit aktuellem Zustand,
+- Verteilung der Easee-Observations an die passenden Kindinstanzen,
+- Stromvorgabe ueber `set_dynamic_charger_current`,
+- Wiederverbindung und erneute Anmeldung aller Stationen nach Unterbrechungen,
+- TLS-Zertifikatspruefung standardmaessig aktiv.
 
 ## Properties
 
-| Technischer Ident / Anzeige | Typ | Standard / Beschreibung |
+| Ident | Typ | Standard | Beschreibung |
+| --- | --- | --- | --- |
+| `Active` | Boolean | `true` | Aktiviert Anmeldung und Ereignisverbindung. |
+| `Username` | String | leer | E-Mail-Adresse oder Telefonnummer des Easee-Kontos. |
+| `Password` | Passwort | leer | Passwort, nur im Gateway gespeichert. |
+| `VerifyCertificate` | Boolean | `true` | Prueft TLS-Zertifikate fuer REST und WebSocket. |
+
+Die interne Property `Testmodus` ist nicht im Formular sichtbar und wird nur
+vom automatisierten IP-Symcon-Test verwendet.
+
+## Variablen
+
+| Ident | Typ | Beschreibung |
 | --- | --- | --- |
-| `Active` / Aktiv | Boolean | `true`; Verbindungsbetrieb, keine Ladefreigabe. |
-| `Username` / Benutzername | String | leer; Easee-Konto. |
-| `Password` / Passwort | String | leer; vertraulich. |
-| `VerifyCertificate` / Zertifikat prüfen | Boolean | `true`; TLS-Prüfung. |
+| `Connected` | Boolean | Ereignisverbindung ist betriebsbereit. |
+| `SubscriptionCount` | Integer | Anzahl angemeldeter Seriennummern. |
+| `LastError` | String | Letzter Fehler ohne Zugangsdaten oder Tokens. |
 
-## Verhalten
+## API und Ereignisse
 
-Nach einer Wiederverbindung werden Gerätezustände erst nach neuer gültiger
-Rückmeldung verwendet. Das Gateway sendet keine EMS-Verbrauchermeldung.
+Der Gateway-Transport ist in
+[Easee-Gateway-Schnittstelle](../../Schnittstelle-Easee-Gateway.md)
+vollstaendig beschrieben. Fuer Fahrzeug- und Phasenstatus werden insbesondere
+Observation `109` und `110` verteilt. Nach jeder Wiederverbindung wird der
+Cache verworfen und durch `SubscribeWithCurrentState` neu aufgebaut.
 
-## Offene Punkte
+## Fehlerbehandlung
 
-- Instanziierung und Wiederverwendung bestehender Verbindungen testen.
-- Aktuelle Easee-Endpunkte und Ereignisfelder vor Übernahme verifizieren.
+| Status | Bedeutung |
+| ---: | --- |
+| `102` | Verbindung aktiv. |
+| `104` | Gateway deaktiviert. |
+| `201` | Benutzername oder Passwort fehlt. |
+| `202` | Anmeldung oder Token-Erneuerung fehlgeschlagen. |
+| `203` | Ereignisverbindung fehlgeschlagen. |
+
+REST-Aufrufe verwenden 5 Sekunden Verbindungs- und 30 Sekunden
+Gesamt-Timeout. HTTP-401 fuehrt einmalig zu einer Token-Erneuerung und
+Wiederholung. Tokens werden nie als Variable oder Debugtext ausgegeben.
+
+## Inbetriebnahme
+
+1. Eine Instanz **Easee Gateway** erstellen.
+2. Benutzername und Passwort des Easee-Kontos eintragen.
+3. TLS-Pruefung aktiviert lassen.
+4. Speichern und Status `102` sowie `Connected=true` abwarten.
+5. Fuer jede Station eine Kindinstanz **Ladestation Gateway** anlegen.
+6. Bei mehreren Konten je Konto eine eigene Gateway-Instanz verwenden.
+
+## Tests
+
+`composer check` prueft Syntax und Unit-Tests. Der Funktionstest laeuft mit:
+
+```bash
+tests/Symcon/bin/run-symcon-tests.sh single EaseeGateway
+```

docs/module/Ladestation-Gateway/README.md

@@ -1,41 +1,112 @@
 # Ladestation Gateway
 
-> Status: Diskussionsentwurf. Eigenständiges Verbrauchermodul mit zugeordnetem
-> Easee Gateway; keine gemeinsame Ladestations-Basisklasse.
+> Status: implementiert fuer IP-Symcon 8 und den Enelix-2-Vertrag `4.0`.
 
-## Zusätzliche Variablen
+Das Modul bindet genau eine Easee-Ladestation als EMS-Verbraucher an. Es ist
+Kind eines **Easee Gateway** und besitzt keine Zugangsdaten.
 
-| Ident | Typ / Zugriff | Beschreibung |
+## Varianten
+
+| Betriebsmodus | Verhalten |
+| --- | --- |
+| `Easee` | Solarladen kann als Startwert konfiguriert und lokal umgeschaltet werden. |
+| `Easee - Nur Solarladen` | Solarladen ist fest aktiv und kann nicht abgeschaltet werden. |
+
+Die alte eCarUp-Zusatzabhaengigkeit wird nicht uebernommen. Konto,
+Ladestatus und Steuerung laufen ausschliesslich ueber Easee.
+
+## Ereignisbasierter Status
+
+Das Modul pollt die Ladestation nicht. Es verarbeitet unmittelbar die vom
+Gateway gelieferten Easee-Observations:
+
+| Observation | Verwendung |
+| ---: | --- |
+| `47` | Maximalstrom der Ladestation. |
+| `104` | Kabelstromgrenze. |
+| `109` | Fahrzeugerkennung und Ladezustand. |
+| `110` | Aktive Ausgangsphase: Werte 10 bis 15 ergeben 1 Phase, Wert 30 ergibt 3 Phasen. |
+| `119` | Easee-Fehlercode. |
+| `120` | Gemessene Gesamtleistung in kW. |
+| `182..185` | Gemessene Leiterstroeme; der groesste Betrag ist der angezeigte Ladestrom. |
+
+Damit entfallen die alte 60-Sekunden-Erkennung, die 7500-W-Schwelle und die
+Voll-Erkennung aus einem unterschaetzten Strom. Fahrzeug, Ladeende und
+Phasenzahl stammen direkt aus der Easee API. Zweiphasige oder noch nicht
+zugewiesene Ausgangsphasen sowie unbekannte Betriebszustaende werden sicher
+als ungueltig behandelt und ergeben bis zur gueltigen 1-/3-Phasenmeldung nur
+`[0]`.
+
+## Properties
+
+| Ident | Typ | Standard | Beschreibung |
+| --- | --- | ---: | --- |
+| `Betriebsmodus` | Integer | `0` | `0` Easee, `1` Easee - Nur Solarladen. |
+| `Ladestationskennung` | String | leer | Easee-Seriennummer. |
+| `MaximalerLadestrom` | Integer | `16 A` | Lokale Obergrenze von 6 bis 32 A. API- und Kabelgrenze wirken zusaetzlich. |
+| `Ladefreigabe` | Boolean | `false` | Startwert der lokalen Ladefreigabe. |
+| `Solarladen` | Boolean | `true` | Startwert im normalen Easee-Modus. |
+| `PrioritaetPV` | Integer | `0` | Prioritaet im PV-Betrieb. |
+| `PrioritaetPeak` | Integer | `0` | Prioritaet im Peakbetrieb. |
+| `Meldeintervall` | Integer | `10 s` | Periodische Vollmeldung an den Manager. |
+| `VorgabeTimeout` | Integer | `120 s` | Ablauf einer nicht erneuerten Manager-Vorgabe. |
+| `EinstellungenInVisu` | Boolean | `false` | Zeigt Ladefreigabe und Solarladen. |
+| `DiagnosevariablenAnzeigen` | Boolean | `false` | Zeigt technische Diagnosewerte. |
+| `LoggingEin` | Boolean | `false` | Aktiviert Debugmeldungen ohne Geheimnisse. |
+
+## Variablen
+
+Immer sichtbar sind `Aktiv`, `FahrzeugVerbunden`, `FahrzeugGeladen`,
+`Fahrzeugstatus`, `Ladestrom` und `Phasenzahl`. Der normalisierte
+Fahrzeugstatus ist `0` unbekannt, `1` getrennt, `2` bereit, `3` laedt,
+`4` geladen oder `5` Fehler.
+
+Optional sichtbar sind die gemeinsamen EMS-Diagnosewerte sowie
+`GatewayVerbunden`, `ApiMaximalstrom`, `LetzterGeraetebefehl` und
+`LeistungsangebotDiagnose`.
+
+## Regelung
+
+Die Leistungsstufen und das PV-/Peak-Verhalten entsprechen der
+Ladestation Stand-Alone:
+
+| Betriebsart | Solarladen | Angebot |
 | --- | --- | --- |
-| `FahrzeugVerbunden` | Boolean / Anzeige | Nur bei gültigem Gatewaystatus aussagekräftig. |
-| `Fahrzeugstatus` | Integer / Anzeige | `0` unbekannt, `1` nicht verbunden, `2` bereit, `3` lädt, `4` voll, `5` Fehler. |
-| `Ladestrom` | Float / Anzeige | Aktueller Ladestrom in A. |
-| `Phasenzahl` | Integer / Anzeige | `0` unbekannt, `1` einphasig, `3` dreiphasig. |
-| `Ladefreigabe` | Boolean / lokal bedienbar | Lokale Ladeerlaubnis zusätzlich zu `Aktiv`. |
-| `Solarladen` | Boolean / lokal bedienbar | Überschussorientiertes Laden ein/aus. |
+| PV | ein | `[0, ...Ladestufen]` |
+| PV | aus | nur maximale Ladestufe |
+| Peak | ein | `[0]` |
+| Peak | aus | `[0, ...Ladestufen]` |
 
-## Zusätzliche Properties
+Die niedrigste Grenze aus Property, Observation `47` und Observation `104`
+bestimmt den angebotenen Maximalstrom. Eine neue Observation berechnet das
+Angebot sofort neu und meldet die Aenderung kurz gebuendelt an den Manager.
+Bei einer Gateway-Unterbrechung werden Fahrzeug- und Phasenstatus sofort
+verworfen; erst ein neuer aktueller Gateway-Zustand gibt die Regelung wieder
+frei. Die eigentliche Vorgabe wird als dynamischer Ladestrom mit `minutes=0`
+an Easee gesendet.
 
-| Ident | Typ | Standard / Beschreibung |
-| --- | --- | --- |
-| `Ladefreigabe` | Boolean | `false`. |
-| `Solarladen` | Boolean | `true`. |
-| `MaximalerLadestrom` | Float | `0*` A; Installations- und Gerätegrenze. |
-| `Ladestromschritt` | Float | `1` A; muss von Easee unterstützt sein. |
-| `MindestEinzeit` | Integer | `0` s. |
-| `MindestAuszeit` | Integer | `0` s. |
-| `GatewayID` | Integer | `0`; kompatibles Easee Gateway, erforderlich. |
-| `Ladestationskennung` | String | leer; eindeutige Station/Seriennummer im Gateway. |
+## Managerkommunikation
 
-Es gibt hier keine Zugangsdaten; sie liegen ausschliesslich im Easee Gateway.
-Ladefreigabe und Solarladen werden über `EinstellungenInVisu` eingeblendet.
+Das Modul implementiert den
+[EMS-Nachrichtenvertrag `4.0`](../../Schnittstelle.md). Es wird im Manager
+wie die Stand-Alone-Ladestation unter dem Lizenzkatalog `ev_charger`
+gefuehrt. Es gibt keine Manager-ID-Property; die Zuordnung erfolgt nur im
+Manager.
 
-## Zustand
+## Inbetriebnahme
 
-`Fahrzeugstatus`, `FahrzeugVerbunden`, `Ladefreigabe`, `Solarladen`,
-`Ladestrom_A`, `Ladefehler` und `Gatewayfehler`.
+1. Ein konfiguriertes Easee Gateway mit Status `102` bereitstellen.
+2. Darunter **Ladestation Gateway** erstellen.
+3. Variante, Seriennummer und elektrische Maximalgrenze konfigurieren.
+4. Ladefreigabe und Solarladen festlegen.
+5. Die Instanz im Enelix Manager aktiv zuordnen.
+6. Ohne Fahrzeug Status `1` und Angebot `[0]` pruefen.
+7. Fahrzeug verbinden und die API-Werte fuer Status und Phasenzahl kontrollieren.
+8. Erst danach `Aktiv` einschalten und eine kleine Vorgabe testen.
 
-## Offene Punkte
+## Tests
 
-- Reaktion aller zugeordneten Stationen bei Gatewayausfall im Praxistest festlegen.
-- Lokalen Mindestladebedarf bei deaktiviertem Solarladen genau festlegen.
+```bash
+composer check
+tests/Symcon/bin/run-symcon-tests.sh single LadestationGateway
+```

docs/module/README.md

@@ -1,8 +1,8 @@
 # EMS-Module und Modulentwürfe
 
-> Manager, Warmwassererwaermer, Verbraucher 1-Stufig und Ladestation
-> Stand-Alone sind als installierbare IP-Symcon-Module umgesetzt. Die weiteren
-> Ordner enthalten Besprechungsgrundlagen.
+> Manager, Warmwassererwaermer, Verbraucher 1-Stufig, Ladestation Stand-Alone,
+> Easee Gateway und Ladestation Gateway sind als installierbare IP-Symcon-Module
+> umgesetzt. Die weiteren Ordner enthalten Besprechungsgrundlagen.
 
 Alle steuerbaren Verbraucher verwenden die gemeinsamen Datenpunkte aus der
 [EMS-Schnittstelle](../Schnittstelle.md). In den Modul-READMEs stehen deshalb
@@ -17,8 +17,8 @@ nur zusätzliche Properties, Variablen, Zustände und offene Punkte.
 | [Verbraucher 1-Stufig](Verbraucher-1-Stufig/README.md) | Ein-/Aus-Verbraucher (implementiert) |
 | [Wärmepumpe](Waermepumpe/README.md) | Sperrkontakt oder SG Ready |
 | [Ladestation Stand-Alone](Ladestation-Stand-Alone/README.md) | Direkte Geräteanbindung (implementiert) |
-| [Ladestation Gateway](Ladestation-Gateway/README.md) | Ladestation am Easee Gateway |
-| [Easee Gateway](Easee-Gateway/README.md) | Gemeinsame Easee-Kommunikation |
+| [Ladestation Gateway](Ladestation-Gateway/README.md) | Eventbasierte Ladestation am Easee Gateway (implementiert) |
+| [Easee Gateway](Easee-Gateway/README.md) | Gemeinsame Easee-Kommunikation (implementiert) |
 
 ## Review-Regel