SunEnergyXT 500: fix battery control (#32866)

templates/definition/meter/sunenergyxt-500.yaml

@@ -1,23 +1,25 @@
 # Used API docs for SunEnergyXT 500 Series: https://github.com/SunEnergyXT/SunEnergyXT-500-Series/blob/main/API.en.md
 template: sunenergyxt-500
 products:
+  # single entry: the `model` param carries the Standard/PRO distinction
   - brand: SunEnergyXT
     description:
-      generic: SunEnergyXT 500
-  - brand: SunEnergyXT
-    description:
-      generic: SunEnergyXT 500 PRO
+      generic: SunEnergyXT 500 / 500 PRO
 capabilities: ["battery-control"]
 requirements:
   description:
     en: |
       The battery's local mode must be enabled in the manufacturer's app.
       Furthermore, the device's IP address must be set to a fixed, permanent IP address in the router.
-      If the `grid` mode is used, an external meter (e.g., Shelly) must be connected to the battery to measure the grid connection point (via the manufacturer's app).
+      An external meter (e.g., Shelly) measuring the grid connection point must be connected to the battery via the manufacturer's app.
+      It is required for the `grid` usage, and also for the `battery` usage, because the normal battery mode enables the device's
+      zero feed-in regulation, which reads this meter.
     de: |
       Der lokale Modus der Batterie muss in der Hersteller-App aktiviert werden.
       Des Weiteren muss die IP-Adresse des Geräts im Router auf eine feste, dauerhafte IP-Adresse eingestellt werden.
-      Wenn der `grid` Modus verwendet wird, muss mit der Batterie ein externer Zähler (z. B. Shelly) verbunden sein, der den Hausanschlusspunkt misst (dieser wird über die Hersteller-App hinzugefügt).
+      Mit der Batterie muss ein externer Zähler (z. B. Shelly) verbunden sein, der den Hausanschlusspunkt misst (dieser wird über die Hersteller-App hinzugefügt).
+      Er wird für die Verwendung `grid` benötigt und ebenso für die Verwendung `battery`, da der normale Batteriemodus die
+      Nulleinspeise-Regelung des Geräts aktiviert, die diesen Zähler ausliest.
 caveats:
   - description:
       de: |
@@ -27,25 +29,57 @@ caveats:
         Currently, each head storage must be individually added in EVCC.
         Connecting multiple head storages into one system has been announced by the manufacturer but is not yet implemented on the software side.
     # link:
+  - description:
+      de: |
+        `maxacpower` und `maxdischargepower` werden aus dem gewählten `model` abgeleitet, wenn sie leer bleiben.
+        Ein ausdrücklich gesetzter Wert hat Vorrang und wird nicht auf das Modell-Limit begrenzt.
+      en: |
+        `maxacpower` and `maxdischargepower` are derived from the selected `model` when left empty.
+        An explicitly configured value takes precedence and is not clamped to the model limit.
 params:
   - name: usage
     type: choice
     choice: ["grid", "pv", "battery"]
     required: true
+  - name: model
+    type: choice
+    choice: ["standard", "pro"]
+    required: true
+    description:
+      de: Modell
+      en: Model
+    help:
+      de: |
+        `standard` für die SunEnergyXT 500, `pro` für die SunEnergyXT 500 PRO.
+        Bestimmt die maximale AC- und Entladeleistung (800 W bzw. 2400 W).
+      en: |
+        `standard` for the SunEnergyXT 500, `pro` for the SunEnergyXT 500 PRO.
+        Determines the maximum AC and discharge power (800 W resp. 2400 W).
   - name: host
     required: true
+  # maxacpower/maxdischargepower: leave empty to derive the limit from `model`
   - name: maxacpower
-    default: 800.0
-  - preset: battery-params
+  - preset: battery-capacity
+  - preset: battery-minmaxsoc
+  # head unit alone; each extension pack adds another 5 kWh
   - name: capacity
-    default: 4.8
+    default: 5
+    help:
+      de: |
+        Gesamtkapazität des Speichers: Kopfspeicher 5 kWh, jede Erweiterung +5 kWh.
+        Also 5 (nur Kopfspeicher), 10 (+1 Erweiterung) oder 15 (+2 Erweiterungen).
+        Die Anzahl der erkannten Akkupakete steht im Feld `ON` unter `/read`.
+      en: |
+        Total storage capacity: head unit 5 kWh, each extension pack adds 5 kWh.
+        So 5 (head unit only), 10 (+1 extension) or 15 (+2 extensions).
+        The number of detected battery packs is reported in the `ON` field of `/read`.
+  # grid charging is limited to -2400..0 W on both models
   - name: maxchargepower
-    default: 2400.0
+    default: 2400
   - name: maxdischargepower
-    default: 800.0
   - name: cache
     advanced: true
-    default: 1s
+    default: 2s
   - name: timeout
     advanced: true
     default: 10s
@@ -84,8 +118,10 @@ render: |
         uri: http://{{ .host }}/write
         headers:
           - Content-Type: application/json
-        body: '{"state":{"MM":1}}'
-    - case: 2 # hold 
+        # GS must be reset explicitly: MM (zero feed-in regulation) and GS (manual
+        # setpoint) are independent, so a leftover GS would keep grid charging.
+        body: '{"state":{"MM":1,"GS":0}}'
+    - case: 2 # hold
       set:
         source: http
         method: POST
@@ -100,8 +136,12 @@ render: |
         uri: http://{{ .host }}/write
         headers:
           - Content-Type: application/json
+        # GS < 0 means grid import / grid charging
         body: '{"state":{"MM":0,"GS":-{{ .maxchargepower | int }}}}'
-  {{- include "battery-params" . }}
+  {{- include "battery-capacity" . }}
+  {{- include "battery-minmaxsoc" . }}
+  maxchargepower: {{ .maxchargepower | int }} # W
+  maxdischargepower: {{ if gt (.maxdischargepower | int) 0 }}{{ .maxdischargepower | int }}{{ else }}{{ ternary 2400 800 (eq .model "pro") }}{{ end }} # W
   {{- end }}
   {{- if eq .usage "pv" }}
   power:
@@ -110,4 +150,5 @@ render: |
     cache: {{ .cache }}
     timeout: {{ .timeout }}
     jq: .state.reported.PV
+  maxacpower: {{ if gt (.maxacpower | int) 0 }}{{ .maxacpower | int }}{{ else }}{{ ternary 2400 800 (eq .model "pro") }}{{ end }} # W
   {{- end }}