From f47dd16e61a3ac76b882df6dc8d852f10d4d50f3 Mon Sep 17 00:00:00 2001
From: Thorben Carl <thorben.carl@gmail.com>
Date: Fri, 14 Aug 2026 12:06:01 +0200
Subject: [PATCH] SunEnergyXT: add SunEnergyXT 500 template (#30852)

---
 .../definition/meter/sunenergyxt-500.yaml     | 113 ++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 templates/definition/meter/sunenergyxt-500.yaml

diff --git a/templates/definition/meter/sunenergyxt-500.yaml b/templates/definition/meter/sunenergyxt-500.yaml
new file mode 100644
index 000000000..65eb09e5e
--- /dev/null
+++ b/templates/definition/meter/sunenergyxt-500.yaml
@@ -0,0 +1,113 @@
+# Used API docs for SunEnergyXT 500 Series: https://github.com/SunEnergyXT/SunEnergyXT-500-Series/blob/main/API.en.md
+template: sunenergyxt-500
+products:
+  - brand: SunEnergyXT
+    description:
+      generic: SunEnergyXT 500
+  - brand: SunEnergyXT
+    description:
+      generic: SunEnergyXT 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).
+    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).
+caveats:
+  - description:
+      de: |
+        Aktuell muss jeder Kopfspeicher einzeln in EVCC angelegt werden.
+        Mehrere Kopfspeicher in ein System zu verbinden, ist vom Hersteller angekündigt, jedoch softwareseitig noch nicht umgesetzt.
+      en: |
+        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:
+params:
+  - name: usage
+    type: choice
+    choice: ["grid", "pv", "battery"]
+    required: true
+  - name: host
+    required: true
+  - name: maxacpower
+    default: 800.0
+  - preset: battery-params
+  - name: capacity
+    default: 4.8
+  - name: maxchargepower
+    default: 2400.0
+  - name: maxdischargepower
+    default: 800.0
+  - name: cache
+    advanced: true
+    default: 1s
+  - name: timeout
+    advanced: true
+    default: 10s
+render: |
+  type: custom
+  {{- if eq .usage "grid" }}
+  power:
+    source: http
+    uri: http://{{ .host }}/read
+    cache: {{ .cache }}
+    timeout: {{ .timeout }}
+    jq: .state.reported.GP
+    scale: -1
+  {{- end }}
+  {{- if eq .usage "battery" }}
+  power:
+    source: http
+    uri: http://{{ .host }}/read
+    cache: {{ .cache }}
+    timeout: {{ .timeout }}
+    jq: .state.reported.BP
+    scale: -1
+  soc:
+    source: http
+    uri: http://{{ .host }}/read
+    cache: {{ .cache }}
+    timeout: {{ .timeout }}
+    jq: .state.reported.SC
+  batterymode:
+    source: switch
+    switch:
+    - case: 1 # normal
+      set:
+        source: http
+        method: POST
+        uri: http://{{ .host }}/write
+        headers:
+          - Content-Type: application/json
+        body: '{"state":{"MM":1}}'
+    - case: 2 # hold 
+      set:
+        source: http
+        method: POST
+        uri: http://{{ .host }}/write
+        headers:
+          - Content-Type: application/json
+        body: '{"state":{"MM":0,"GS":0}}'
+    - case: 3 # charges
+      set:
+        source: http
+        method: POST
+        uri: http://{{ .host }}/write
+        headers:
+          - Content-Type: application/json
+        body: '{"state":{"MM":0,"GS":-{{ .maxchargepower | int }}}}'
+  {{- include "battery-params" . }}
+  {{- end }}
+  {{- if eq .usage "pv" }}
+  power:
+    source: http
+    uri: http://{{ .host }}/read
+    cache: {{ .cache }}
+    timeout: {{ .timeout }}
+    jq: .state.reported.PV
+  {{- end }}