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
+```