# VGT-Schnittstelle

> Status: Implementiert fuer IP-Symcon 8.0. Fuehrt `MQTTPVSDL` und
> `MQTTBatterySDL` zusammen.

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.

## Feste MQTT-Schnittstelle

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

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

## Robustheit

- 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.