feat(utils): adapt virtual battery and VGT interface

docs/module/VGT-Schnittstelle/README.md

@@ -1,42 +1,103 @@
 # VGT-Schnittstelle
 
-> Status: Diskussionsentwurf. Führt `MQTTPVSDL` und die vorhandenen
-> Batterie-Felder aus `MQTTBatterySDL` zusammen.
+> Status: Implementiert fuer IP-Symcon 8.0. Fuehrt `MQTTPVSDL` und
+> `MQTTBatterySDL` zusammen.
 
-Die bestehende MQTT-Arbeitsweise und technische Alt-Idents bleiben erhalten.
-Die Geräteart PV oder Batterie steuert nur die sichtbaren Felder.
+Die bestehende MQTT-Schnittstelle wurde unveraendert uebernommen. Weder
+Topic-Namen noch Request- und Response-Felder wurden erweitert oder
+umbenannt. Die Geraeteart bestimmt nur Regelverhalten und sichtbare Messwerte.
 
-## Variablen
+## Feste MQTT-Schnittstelle
 
-| Technischer Ident | Typ / Zugriff | Beschreibung |
+| Richtung | Topic |
+| --- | --- |
+| Lesen | `feedback-request/{TopicSuffix}` |
+| Leseantwort | `feedback-response/{TopicSuffix}` |
+| Steuern | `remote-control-request/{TopicSuffix}` |
+| Steuerantwort | `remote-control-response/{TopicSuffix}` |
+
+Ein Steuerauftrag verwendet weiterhin:
+
+```json
+{
+  "power_setpoint": 3500,
+  "strategy": "activate"
+}
+```
+
+Die Steuerantwort enthaelt weiterhin ausschliesslich
+`power_setpoint` und `strategy`.
+
+Die Leseantwort enthaelt fuer PV:
+
+- `power_production`
+- `is_ready`
+- `is_running`
+
+Bei der Geraeteart Batterie kommen unveraendert hinzu:
+
+- `state_of_charge`
+- `min_soc`
+- `max_soc`
+
+MQTT wird weiterhin mit Pakettyp 3, QoS 0 und `Retain=false` ueber den
+IP-Symcon-MQTT-Parent verwendet.
+
+## Batterie und virtuelle Batterie
+
+Im Batteriemodus wird `ReqActionID` auf die Variable `SDLSollleistung`
+der virtuellen Batterie gelegt. `PowerProductionID` verweist auf
+`SDLIstleistung`, `SoCID` auf `SDLLadezustand`.
+
+Die VGT-Schnittstelle schreibt niemals physische Batterieregister. Die
+virtuelle Batterie priorisiert den SDL-Auftrag und verteilt den gemeinsamen
+Nettosollwert.
+
+Die Vorzeichenumkehr von Enelix 1 bleibt erhalten: Bei `activate` wird der
+empfangene Batterie-`power_setpoint` mit umgekehrtem Vorzeichen an die
+Zielvariable uebergeben.
+
+## Strategien
+
+| Strategie | PV | Batterie |
 | --- | --- | --- |
-| `IsReady` | Boolean / Anzeige | Bestehender Bereitschaftsstatus. |
-| `IsRunning` | Boolean / Anzeige | Bestehender Bearbeitungsstatus. |
-| `MinSoC` | Float / Anzeige | Nur Batterie; untere Ladezustandsgrenze. |
-| `MaxSoC` | Float / Anzeige | Nur Batterie; obere Ladezustandsgrenze. |
-| `PowerSetpoint` | Integer / bedienbar | Bestehende Leistungsvorgabe und Testaktion. |
-| `Strategy` | String / bedienbar | Bestehende Strategie und Testaktion. |
-| `LastReadResponse` | String / Anzeige | Letzte Lese-Antwort. |
-| `LastWriteResponse` | String / Anzeige | Letzte Steuer-Antwort. |
+| `activate` | Setpoint zwischen 0 und Maximum | invertierter Setpoint |
+| `stop` | Freigabe auf konfiguriertes Maximum | 0 W |
+| `restore` | keine aktive Fernbegrenzung | Regelung auf `TargetSoC` |
+
+Im Batteriemodus verhindern `MinSoC` und `MaxSoC` eine Vorgabe in die
+falsche Richtung an der jeweiligen Ladezustandsgrenze.
 
 ## Properties
 
-| Technischer Ident | Typ | Standard / Beschreibung |
-| --- | --- | --- |
-| `Geraeteart` | Auswahl | `PV`; alternativ `Batterie`. |
-| `TopicSuffix` | String | leer; bestehender MQTT-Suffix. |
-| `ReqActionID` | Integer | `0`; bestehende Ausgabevariable/Nennleistung. |
-| `PowerProductionID` | Integer | `0`; aktuelle SDL-Leistung. |
-| `SoCID` | Integer | `0`; nur bei Batterie. |
-| `TargetSoC` | Float | `50` %; nur bei Batterie. |
-| `ChargePower` | Integer | `2500` W; nur bei Batterie. |
-| `DischargePower` | Integer | `2500` W; nur bei Batterie. |
-| `MaxPowerSetpoint` | Integer | `10000` W. |
+| Property | Standard | Beschreibung |
+| --- | ---: | --- |
+| `Geraeteart` | PV | PV oder Batterie |
+| `TopicSuffix` | leer | Unveraenderter MQTT-Suffix |
+| `ReqActionID` | 0 | Bedienbare Zielvariable |
+| `PowerProductionID` | 0 | Aktuelle SDL-/PV-Leistung |
+| `SoCID` | 0 | Ladezustand im Batteriemodus |
+| `TargetSoC` | 50 % | Zielwert fuer `restore` |
+| `ChargePower` | 2500 W | Ladeleistung fuer `restore` |
+| `DischargePower` | 2500 W | Entladeleistung fuer `restore` |
+| `MaxPowerSetpoint` | 10000 W | Begrenzung eingehender Setpoints |
+| `LoggingEin` | false | Debug-Ausgaben |
 
-## Verhalten und offene Punkte
+## Robustheit
 
-- MQTT-Parent, Auftragsauswertung, Timer, Aktionen und vorhandener Testknopf
-  bleiben fachlicher Ausgangspunkt.
-- Passende MQTT-Verbindung zuordnen oder bei der Instanziierung anlegen.
-- Keine neuen Zieladapter, Protokolle oder Datenqualitätsfelder in diesem Schritt.
-- Optionale EMS-Anbindung darf keine feste Repository-Abhängigkeit erzeugen.
+- Zielvariablen muessen numerisch und bedienbar sein.
+- MQTT-Antworten werden in einer FIFO-Warteschlange verarbeitet; schnelle
+  parallele Anfragen ueberschreiben sich nicht mehr.
+- Fehler der Zielaktion werden als Instanzstatus und Stoertext angezeigt.
+- Ungueltige JSON-Nutzdaten werden ohne Hardwareaktion verworfen.
+- MQTT-Payload und Topic-Vertrag bleiben dabei vollstaendig kompatibel.
+
+## Inbetriebnahme
+
+1. Vorhandenen MQTT-Parent zuordnen.
+2. Geraeteart und bisherigen `TopicSuffix` uebernehmen.
+3. Ziel- und Messvariablen konfigurieren.
+4. Im Batteriemodus die Variablen der virtuellen Batterie verwenden.
+5. `MinSoC`, `MaxSoC` und `TargetSoC` pruefen.
+6. Zuerst `feedback-request`, danach `stop`, `activate` und
+   gegebenenfalls `restore` testen.