Marstek Modbus Suite

Die Marstek Modbus Suite ist eine Home-Assistant-Integration für Marstek-Venus-Speicher. Sie spricht ausschließlich lokal über Modbus TCP mit dem Speicher: kein Marstek-Konto, keine Cloud, kein MQTT-Broker, kein YAML. Eingerichtet wird sie über HACS und die Oberfläche von Home Assistant. Das Projekt ist inoffiziell. Es ist als Fork der Integration Marstek Venus Modbus von ViperRNMC entstanden und geht seit Version 1.4 eigene Wege.

Was sie kann

Die Integration liest und schreibt. Gelesen werden Ladezustand, Leistung, Spannung und Strom, die AC-Seite und der Off-Grid-Ausgang, Energiezähler für Tag, Monat und Lebensdauer, Wirkungsgrade, Temperaturen, Firmwarestände sowie Fehler- und Alarmregister mit Klartext. Bei Venus A und D kommen die MPPT-Eingänge, Ladezustand, Zyklen und Zellspannungen je Pack hinzu, bei der D bis zu sieben Packs mit 112 Zellspannungen auf einer gemeinsamen Achse. Geschrieben werden Lade- und Entladeleistung, Grenzwerte, Betriebsmodi, die Schalter für Backup und RS485 und bis zu sechs Zeitpläne mit beliebigen Wochentagen.

Dazu kommen einige abgeleitete Werte, die das Gerät nicht selbst meldet: nutzbare Energie und Energie bis voll gegen eine einstellbare Entladegrenze, Laufzeiten, die nur in Flussrichtung zählen, Verschleiß und Gesundheit aus dem Zykluszähler des BMS sowie die Reserve, die nur über die Notstromsteckdose erreichbar ist. Bei Venus A und D folgt die Ladeprognose der Reihenfolge, in der das BMS die Packs lädt.

Das Panel

Sobald ein Speicher eingerichtet ist, erscheint in der Seitenleiste ein eigenes Panel, ganz ohne zusätzliche Karten. Es hat Reiter für Übersicht, Zellen, Packs, Solar, Energie, Steuerung und System; ein Reiter erscheint nur, wenn das Modell etwas hineinzustellen hat. Hinter dem Zahnrad liegen sieben Farbschemata in je einer hellen und dunklen Fassung (eines nimmt die Farben des Home-Assistant-Themes), die Wahl des Starttabs, Skalierung und Inhaltsbreite. Die Oberfläche gibt es auf Englisch, Deutsch und Niederländisch und folgt der Sprache von Home Assistant. Das Panel findet seine Werte über das Register hinter einer Entität und nicht über deren Namen, ein Umbenennen stört es also nicht.

Unterstützte Modelle

• Venus A: bis zu sieben Packs mit je 13 Zellen und MPPT-Eingänge.
• Venus D: bis zu sieben Packs mit je 16 Zellen und MPPT-Eingänge.
• Venus E v3: ein fest eingebautes Pack, keine Solareingänge.
• Venus E v1/v2: ein fest eingebautes Pack, keine Solareingänge, andere Firmware-Basis.

Venus A, D und E v3 teilen sich eine Firmware-Basis. Die Venus E v1/v2 baut auf einer völlig anderen auf, deshalb gelten Registerbefunde aus A-, D- und E3-Firmware dort nicht, bis sie bestätigt sind.

Voraussetzungen und Installation

• Eine Modbus-RTU-zu-TCP-Bridge am RS485-Port des Speichers oder eine Ethernet-Verbindung direkt zu einem Speicher, der selbst Modbus TCP spricht. Getestet sind Elfin EW11, PUSR DR134, Waveshare RS485 auf RJ45 und M5Stack RS485 mit Atom S3 Lite; Venus A, D und E v3 funktionieren über Ethernet ohne Adapter.
• IP-Adresse, Port (meist 502) und Unit ID des Gateways.
• Home Assistant 2025.9 oder neuer und HACS.

1. Das Repository in HACS unter Integrationen → Benutzerdefinierte Repositories hinzufügen (Kategorie: Integration).
2. Marstek Modbus Suite installieren und Home Assistant neu starten.
3. Die Integration unter Einstellungen → Geräte & Dienste hinzufügen. Eine Venus im lokalen Netz wird beim Einrichten gefunden, Modell, Adresse und Registerkarte sind dann vorausgefüllt.

Im zweiten Schritt vergibt man den Gerätenamen. Er steckt in jeder Entity-ID und greift nur einmal; ein späteres Umbenennen ändert den Anzeigenamen, nicht die IDs. Zwei Speicher brauchen zwei verschiedene Namen.

Modbus TCP läuft bei der Venus nur über den LAN-Anschluss, Port 502 ist über WLAN nicht erreichbar. Ein Modbus-Proxy ist nicht nötig; wer einen einsetzt, weil ein zweiter Client denselben Speicher nutzt, nimmt das gepatchte Add-on, denn ein ungepatchter Proxy trennt bei den fehlerhaften Ausnahmeantworten der Firmware die Verbindung.

Umstieg von Marstek Venus Modbus

Beide Integrationen teilen die Domain marstek_modbus und lassen sich nicht parallel installieren; das alte Repository muss vorher aus HACS entfernt werden. Am einfachsten tauscht man nur das HACS-Repository und lässt den Konfigurationseintrag stehen: Entity-IDs und Verlauf bleiben erhalten. Wurde der Eintrag schon gelöscht, trägt man beim Neuanlegen den Namen des alten Eintrags ein, standardmäßig Marstek Venus Modbus, dann entstehen dieselben Entity-IDs.

Grenzen und bekannte Eigenheiten

• Der Speicher nimmt nur eine Modbus-Verbindung gleichzeitig an. Ein zweiter Client, etwa ein Energiemanager, der dieselben Register schreibt, gewinnt binnen Sekunden gegen Werte, die man im Panel setzt.
• RS485-Steuermodus und Benutzer-Arbeitsmodus sind dasselbe Firmware-Byte aus zwei Blickwinkeln und heben sich gegenseitig auf. Man steuert den Speicher besser über eines von beiden.
• Die Firmware setzt in festem Rhythmus ihren Netzwerkchip zurück, wenn sie die Cloud des Herstellers nicht erreicht; der Speicher verschwindet dann für einige Sekunden aus dem Netz. Die Integration übersteht das, verhindern kann sie es nicht.
• Zeitpläne speichert die Firmware nur dann im EEPROM, wenn sie aus der App kommen. Über Modbus gesetzte Zeitpläne sind nach einem Neustart möglicherweise weg. Das ist aus der Firmware gelesen, aber noch nicht getestet.
• Ein Speicher, der über den Winter ausgeschaltet wird, lässt sich pro Gerät pausieren, wahlweise mit nicht verfügbaren oder mit eingefrorenen Entitäten.

Die Abbildungen im Repository sind Illustrationen, keine Fotos einer laufenden Instanz. Das Repository ist unter MIT-Lizenz veröffentlicht; in den Releases stehen zu jeder Version ausführliche Notizen, und die Register mit ihren Gruppen und Intervallen sind in docs/ dokumentiert.