ha-modbus-akku-adapter

Home-Assistant-Blueprints, die einen abstrakten Steuerungs-Modus in die jeweils passenden Modbus-Register-Schreibbefehle für verschiedene Batterie-Hybrid-Wechselrichter übersetzen. Aktuell SMA STP SE Hybrid, geplant SMA SBS und später weitere Hersteller wie Huawei.

🎯 Idee: Strategie (wann soll geladen/entladen werden) und Hardware-Ansteuerung (wie wird es am konkreten WR umgesetzt) sind getrennt. Wer schon eine eigene Akkusteuerung hat, kann nur diesen Adapter nutzen, um seine Entscheidungen sauber auf Modbus umzusetzen. Das Bindeglied ist der Modus-Contract.

⚠️ Disclaimer: Inoffizielle Community-Lösung. Wird in keiner Weise von SMA Solar Technology AG begleitet, geprüft oder supportet. Das direkte Beschreiben von Modbus-Registern kann WR/Batterie/Anlage beschädigen, Garantie kosten oder gefährliche Betriebszustände erzeugen. Nutzung auf eigene Gefahr.

Das Blueprint ist nur der Übersetzer. Damit es etwas zu übersetzen hat, müssen in Home Assistant vorher drei Dinge existieren. Reihenfolge:

1. Modbus-Verbindung zum Wechselrichter – ein modbus:-Block in deiner configuration.yaml, der den SMA STP SE per TCP einbindet. (Modbus ist der einzige Teil, der zwingend YAML braucht – HA hat dafür keine Oberfläche.) → Vorlage: examples/sma_modbus.example.yaml (nur die IP eintragen).
2. Ein paar Helfer, die du komplett über die HA-Oberfläche anlegen kannst: ein Steuer-Dropdown input_select.akkusteuerung_modus mit 9 festen Optionen (Akku Automatisch, Akku Dynamisch, Akku Pause, Akku nur Laden, Akku Netzladen, Akku nur Entladen, Akku schnell Laden, Akku schnell Entladen, Akku 0.2C Laden) plus 6 Zahlen-Helfer (input_number.*) für die Lade-/Entlade-Leistungen in Watt. (Der 0.2C-Wert wird automatisch aus der Batteriekapazität berechnet – kein Feld nötig.) → Lieber kopieren statt klicken? examples/akkusteuerung_helpers.example.yaml.
3. Etwas, das das Dropdown umschaltet – also eine Strategie. Das kann eine eigene Automation sein oder das Schwesterprojekt ha-opti-akkusteuerung.

Erst danach importierst du das Blueprint (Schritt unten) und verbindest es mit diesen Helfern. Ohne Schritt 1–2 hat das Blueprint nichts, worauf es schreiben kann, und beschwert sich beim Speichern über fehlende Entitäten.

Strategie  →  input_select.akkusteuerung_modus  →  [ DIESES BLUEPRINT ]  →  Modbus-Register  →  SMA-WR
(setzt Modus)        (+ input_number.* in W)            übersetzt

Verbindliche Reihenfolge, wenn du beide Repos zusammen nutzt:

1. Modbus-Verbindung anlegen (Adapter-Repo, Schritt 1). Helfer NICHT hier anlegen, wenn du Schritt 2 nutzt — siehe Hinweis unten.
2. Opti-Packages aktivieren + opti_mapping.yaml ausfüllen (Opti-Repo)
3. Home Assistant neu starten — sensor.opti_* prüfen
4. Adapter-Blueprint importieren, Inputs prüfen: dynamic_charge_strength_sensor auf sensor.opti_charge_power_w setzen, dazu battery_capacity_sensor, inverter_status_sensor und inverter_ok_states auf deine echten Entitäten bzw. Status-Codes (nicht ungeprüft die Blueprint-Vorschlagswerte übernehmen, falls sie abweichen)
5. Strategie-Automation (automations/opti_strategie.yaml) aktivieren

⚠️ Helfer nur aus einer Quelle: Bei kombinierter Nutzung liefert ha-opti-akkusteuerung/packages/sma_helpers.yaml bereits alle Helfer (Modus-Dropdown, 6 Leistungs-Helfer, 2 Schreib-Diagnose-Helfer). Die Adapter-GUI-Anleitung bzw. das Adapter-Package dann NICHT zusätzlich verwenden — zwei Packages mit denselben Entity-IDs führen zu einem Duplicate-Key-Fehler im HA-Log. Nutzt du den Adapter ohne das Opti-Repo (eigene Strategie), gilt die Adapter-Anleitung normal.

Dieser Schritt geht nur über YAML – Home Assistant bietet für die Modbus-Integration keine grafische Oberfläche. Kopiere den modbus:-Block aus examples/sma_modbus.example.yaml in deine configuration.yaml (oder ein Package) und trage die IP-Adresse deines Wechselrichters ein. Der Hub heißt dort sma-sr_wr – diesen Namen brauchst du gleich beim Blueprint wieder.

Die Beispieldatei bringt auch den Sensor Batterie-Nennkapazität (Register 40187) mit. Daraus berechnet der Adapter den Modus „Akku 0.2C Laden" automatisch (0,2 × Kapazität) – du musst dafür nichts von Hand eintragen.

ℹ️ Seit Mitte 2025 reicht aktuelle, offizielle WR-Firmware (ab ca. 3.06.xx) — kein Beta, kein Grid Guard Code mehr nötig. Bei sehr alten, nicht aktualisierten Firmware-Ständen zuerst ein reguläres Update einspielen.

Diese Helfer legst du komplett per GUI an – kein YAML nötig. Pfad: Einstellungen → Geräte & Dienste → Helfer → ➕ Helfer erstellen.

⚠️ Wichtig: Das Blueprint sucht die Helfer an exakten Entity-IDs. Tippe die Namen genau wie unten (mit ae statt ä!), dann erzeugt HA automatisch die richtige ID. Sonst macht HA aus „Ladestärke" die ID …ladestarke… statt …ladestaerke… und der Adapter findet den Helfer nicht. (Die Entity-ID lässt sich notfalls nachträglich im Helfer über das Zahnrad korrigieren.)

a) Das Steuer-Dropdown – Typ „Auswahl", Name Akkusteuerung Modus. Trage als Optionen exakt diese 9 Werte ein (Reihenfolge egal, Schreibweise nicht):

Akku Automatisch
Akku Dynamisch
Akku Pause
Akku nur Laden
Akku Netzladen
Akku nur Entladen
Akku schnell Laden
Akku schnell Entladen
Akku 0.2C Laden

⚠️ Kein initial: am Dropdown setzen (Fix 2026-07-18): Ein initial: (z. B. Akku Automatisch) überschreibt bei jedem HA-Neustart den wiederhergestellten Modus. Der Adapter gibt den WR dann nach jedem Restart kurz in seine interne Eigenverbrauchsregelung frei – der lädt ~30–60 s mit voller PV-Leistung über der dynamischen Soll-Ladestärke, bis die Strategie den Modus zurücksetzt (live belegt, mehrere Anlagen). Bestandsnutzer bitte prüfen: Bei YAML-Helfern die Zeile initial: entfernen (ältere Versionen von akkusteuerung_helpers.example.yaml enthielten sie!). Bei per GUI angelegten Helfern gegebenenfalls den Eintrag "initial" zum Helfer akkusteuerung_modus in /config/.storage/input_select entfernen (HA vorher stoppen oder direkt danach neu starten).

b) Die 6 Leistungs-Helfer – jeweils Typ „Zahl", Einheit W, Min 0, Max z. B. 11000. Name genau so eintippen → ergibt die benötigte Entity-ID:

0.2C braucht keinen eigenen Helfer – der Wert kommt automatisch aus der Kapazität (Schritt 1).

c) Der WR-Status-Sensor

Empfohlen (kein Jinja nötig): den rohen Modbus-Register-Sensor direkt als inverter_status_sensor eintragen (Register 33003, typisch sensor.sma_stp_se_33003_betriebsstatus) und die bei dir betriebsbereiten Status-Codes als Strings in inverter_ok_states auflisten, z. B. ["235", "1463", "2119"] (235 = Netzparallelbetrieb, 1463 = Backup, 2119 = Abregelung wegen der 70%-Einspeisebegrenzung). Welche Codes bei dir auftreten, siehe docs/modbus-register-referenz.md oder die eigene Historie unter Entwicklerwerkzeuge → Verlauf. Kein zusätzlicher Sensor nötig, keine Text-Übersetzung, die veralten kann.

⚠️ Der Blueprint-Vorgabewert "Ok" passt nicht zum Rohsensor. Register 33003 liefert Zahlencodes; bleibt inverter_ok_states auf "Ok" stehen, ist das Gate dauerhaft zu und der Adapter schreibt nie ein Register. Beim Rohsensor also immer die Codes eintragen.

Der Wert 16777213 (0x00FFFFFD) gehört nicht in die Liste: er heißt bei SMA „Information liegt nicht vor“ und ist kein bestätigter Betriebszustand. Taucht er regelmäßig auf, liegt die Ursache in der Modbus-Verbindung oder im WR-Zustand - die gehört behoben, statt den Wert freizuschalten.

Alternative: eigener Vorlage-Sensor. Wer lieber mit Text statt Zahlencodes arbeitet, kann sich stattdessen einen Template-Sensor bauen, der "Ok" liefert, wenn der WR bereit ist:

{% set s = states('sensor.sma_stp_se_33003_betriebsstatus') | int(0) %}
{{ 'Ok' if s in [235, 1463] else 'nicht bereit' }}

⚠️ Blueprint-Input inverter_ok_states (ab v1.5.0) – Aushunger-Falle beim WR-Status-Gate: Das Blueprint schreibt Register nur, wenn inverter_status_sensor einen Wert aus inverter_ok_states liefert (Standard: nur "Ok"). Nutzt du die Vorlage-Alternative, muss inverter_ok_states jeden Status kennen, den die Vorlage nach "Ok" übersetzt - fehlt z. B. 2119 (Abregelung) in der Vorlage ODER in inverter_ok_states, blockiert das ALLE Adapter-Läufe, auch den Keepalive. Läuft dadurch die SMA-Fremdsteuerung in ihren Timeout, fällt der WR in seinen internen Modus zurück und lädt/entlädt eigenmächtig, unabhängig vom in HA gewählten Modus. Der empfohlene Weg oben (Rohsensor + Status-Codes direkt in inverter_ok_states) umgeht dieses Problem, weil keine zusätzliche Text-Übersetzung mehr dazwischenliegt.

d) Der Sensor „Dynamische Ladestärke" (Watt) kommt nicht aus diesem Repo, sondern von deiner Strategie (Schritt 3) bzw. dem Schwesterprojekt – oder du baust einen eigenen Template-Sensor, der einfach eine Watt-Zahl ausgibt.

💡 Lieber kopieren statt klicken? Dieselben Helfer (Dropdown + 6 Zahlen) gibt es fertig als YAML in examples/akkusteuerung_helpers.example.yaml – dort sind die Entity-IDs garantiert korrekt.

e) Zwei Schreib-Diagnose-Helfer (ab v1.2.0) – der Adapter protokolliert darin die BMS-Wertregister jetzt nur noch bei Änderung oder abgelaufenem Keepalive. Dafür braucht er zwei Helfer, die er selbst pflegt (nichts manuell eintragen):

Auch hier gilt: per Copy-Paste aus examples/akkusteuerung_helpers.example.yaml geht es schneller als per GUI.

⚠️ Nur verwenden, wenn du ha-opti-akkusteuerung NICHT nutzt: Das Opti-Repo liefert Modus-Dropdown, die 6 Leistungs-Helfer und die 2 Schreib-Diagnose-Helfer bereits über packages/sma_helpers.yaml (siehe „Wer liefert was" oben). Zwei Packages mit derselben Entity-ID führen zu einem Duplicate-Key-Fehler im HA-Log, und eine der beiden Definitionen wird verworfen — leicht zu übersehen, wenn man die Logs nicht prüft. Wer beide Repos zusammen nutzt: nur die sma_helpers.yaml aus dem Opti-Repo aktivieren, hier nichts zusätzlich einbinden.

Irgendetwas muss input_select.akkusteuerung_modus setzen – sonst steht der Adapter still. Das ist deine eigene Automation oder das Schwesterprojekt ha-opti-akkusteuerung. Zum Testen reicht es, das Dropdown von Hand umzuschalten.

Erst jetzt – wenn Schritt 1–2 stehen – das Blueprint importieren. Es wird HA-nativ per Raw-URL importiert (kein HACS nötig – HACS hat keine Blueprint-Kategorie): Einstellungen → Automatisierungen & Szenen → Blueprints → Blueprint importieren → Raw-URL einfügen, dann eine Automation aus dem Blueprint anlegen und die Helfer aus Schritt 1–2 auswählen. Alle Inputs haben sinnvolle Defaults – prüfe sie und passe sie bei abweichenden Entity-Namen an:

• Hub-Name (modbus_hub)
• WR-Status-Sensor (inverter_status_sensor) + inverter_ok_states (Status-Codes, siehe Schritt 2c – Standard nur "Ok", bei Abregelung o.ä. unbedingt erweitern)
• Batterie-Nennkapazität (battery_capacity_sensor)
• Dynamik-Sensor (dynamic_charge_strength_sensor)
• Modus-Select (mode_select)
• die beiden Schreib-Helfer (last_write_value_helper, last_write_time_helper, Schritt 2e) – seit der Härtung 2026-07 wieder funktional: der Wert-Helfer dient als Modus-Tracker für die CmpBMS-Freigabe, der Zeit-Helfer als Datenquelle des Wächter-Blueprints
• Keepalive-Intervall (keepalive_seconds): seit v1.6.0 deprecated und ohne Funktion – der Adapter schreibt den vollen Registersatz bei jedem Lauf unconditional (Zyklus alle 2 Minuten, SMA-Fenster 300 s)

💡 Stabile URL statt main: Die Tabelle unten verlinkt auf das aktuelle Release-Tag v1.7.0, nicht auf den main-Branch. main ist beweglich und kann unfertige Zwischenstände enthalten - auf einem produktiven Wechselrichter will man das nicht. Für ein Update auf eine neue Version: Blueprint erneut mit der URL des neuen Tags importieren (HA zeigt dann den Diff). Alle Releases: siehe CHANGELOG.md bzw. Tags.

🛡️ Wächter-Blueprint (empfohlen, ab Härtung 2026-07): Die SMA-Schreibregister lesen als 0/null zurück – ein Write-Verify pro Register ist unmöglich. Der Wächter (sma_stp_se_wachter.yaml) überwacht stattdessen die Wirkung: er meldet, wenn der Akku in einem Sperr-Modus (Pause / nur Laden / nur Entladen) trotzdem lädt/entlädt, wenn der Adapter länger als 6 Minuten kein Register geschrieben hat (Status-Gate/ Modbus-Störung → SMA-Keepalive-Risiko) oder wenn seine Leistungssensoren unavailable sind. Er braucht zwei Sensoren auf den Registern 31393/31395 (aktuelle Lade-/ Entladeleistung) und denselben Schreibzeitpunkt-Helfer wie der Adapter.

Details zu Registern/Quellen: docs/modbus-register-referenz.md. Bug gefunden oder ein anderes Setup zum Laufen gebracht? Bitte als GitHub-Issue melden, damit die Tabelle hier aktuell bleibt.

• docs/modus-contract.md – die stabile Schnittstelle Strategie ⇄ Adapter (Modus-Vokabular).
• docs/modbus-register-referenz.md – inoffizielle SMA-Modbus-Registerreferenz (Community).

• Single-Writer: Zu jedem Zeitpunkt darf nur EINE Automation den WR via Modbus schreiben. Alten Adapter/Steuerung deaktivieren, bevor dieser aktiviert wird.
• Min < Max: Der Adapter setzt Min-Ladeleistung vor der Max-Leistung (Guard).
• Werte vor Produktivbetrieb an der eigenen Anlage prüfen (Register/Encoding können je Firmware abweichen).

MIT – Nutzung auf eigene Gefahr (siehe Disclaimer oben).