SMA MQTT Bridge: Wechselrichter und eCharger in openHAB integrieren

Mit der SMA MQTT Bridge integrierst du Wechselrichter, Home Manager, eCharger und BYD-Speicher per MQTT in openHAB – mit einfachem Docker-Setup.

Wer die Daten seiner SMA-Anlage im eigenen Smart Home verwenden möchte, braucht vor allem eines: eine zuverlässige Verbindung zwischen den Geräten und der Hausautomation. Genau dafür ist die SMA MQTT Bridge gedacht. Sie liest Messwerte und ausgewählte Einstellungen aus und veröffentlicht sie über MQTT.

Die Bridge läuft als einzelner Docker-Service, beispielsweise auf einem Raspberry Pi oder einem Linux-Server. Durch die Homie-Konvention kann openHAB die bereitgestellten Geräte automatisch entdecken. Passende Widgets für Energiefluss, Tageswerte und die Wallbox sind ebenfalls im Repository enthalten.

Das Projekt findet ihr hier:

SMA MQTT Bridge auf GitHub

Was macht die SMA MQTT Bridge?

Die Bridge verbindet mehrere Datenquellen mit einem vorhandenen MQTT-Broker. Je nach angeschlossenen Geräten stehen unter anderem folgende Informationen zur Verfügung:

PV-Anlage: aktuelle Leistung, Ertrag und weitere Wechselrichterdaten.
Batteriespeicher: Ladezustand, Lade- und Entladeleistung sowie Energiezähler.
Sunny Home Manager: Netzbezug, Einspeisung und abhängig vom gewählten Zugriff weitere Messwerte.
SMA eCharger: Ladeleistung, Fahrzeugstatus, Sitzungsenergie und Ladeeinstellungen.
BYD Battery-Box: optional direkte Batteriedaten sowie zusätzliche Zell-, Temperatur- und Diagnosedaten.
Anlagenberechnungen: optional Hausverbrauch, Tagesenergien, Stromkosten und Einspeisevergütung.

Jede Datenquelle wird einzeln aktiviert. Für den Einstieg reicht deshalb ein einzelner unterstützter Wechselrichter. Home Manager, Wallbox und weitere Geräte können später ergänzt werden.

Die Geräteanbindung erfolgt überwiegend lokal. Für den Mindest-PV-Anteil des eChargers gibt es zusätzlich eine optionale Anbindung an Sunny Portal ennexOS. Dieser Portalzugriff wird separat eingerichtet.

Unterstützte Geräte

Für folgende Geräte sind Profile beziehungsweise Adapter enthalten:

Gerät	Modell / Umfang	Verbindung
Sunny Tripower 8.0	STP8.0-3AV-40	Modbus TCP
Sunny Boy Storage 3.7	SBS3.7-10	Modbus TCP
Sunny Boy 4.0	SB4.0-1AV-41	Modbus TCP
Sunny Home Manager 2.0	Messwerte über Modbus TCP oder UDP	Lokales Netzwerk
SMA eCharger	EVC22-3AC-20	Lokale HTTPS-API, optional SEMP
BYD Battery-Box Premium HVS	Unterstütztes HVS-Profil mit vier Modulen	Lokaler Diagnosezugriff

Wichtig: Ein ähnlicher Modellname bedeutet nicht automatisch, dass ein Gerät kompatibel ist. Vor der Einrichtung sollten Modell, Firmware und Profil zusammenpassen. Besonders die direkte BYD-Anbindung ist an die dokumentierte Topologie und Firmware gebunden und keine allgemeine Unterstützung aller HVS- oder HVM-Systeme.

Weitere Wechselrichter lassen sich durch verifizierte JSON-Profile ergänzen. Die Profile enthalten die benötigten Registerzuordnungen und Metadaten; Zugangsdaten und Geräteadressen gehören in die eigene Konfiguration.

Details dazu:

Architektur kurz erklärt

Der Weg der Daten sieht so aus:

SMA Wechselrichter ─┐
Home Manager ───────┤
SMA eCharger ───────┼── SMA MQTT Bridge ── MQTT-Broker ── openHAB
BYD Battery-Box ────┘

Die Bridge veröffentlicht die Daten nach Homie 4. Damit werden neben den Messwerten auch Informationen wie Bezeichnungen, Datentypen und Einheiten über MQTT bereitgestellt.

openHAB kann daraus Geräte und Channels erkennen. Anschließend werden die gewünschten Channels mit eigenen Items verknüpft.

Ein MQTT-Broker und eine eigene Weboberfläche sind im Bridge-Container nicht enthalten. Für die Anzeige verwenden wir in dieser Anleitung openHAB. Andere MQTT-Anwendungen können die Topics ebenfalls nutzen.

Voraussetzungen

Für die Einrichtung benötigen wir:

Einen Linux-Host mit Docker und Docker Compose ab Version 2.24.
Git zum Herunterladen des Repositorys.
Einen erreichbaren MQTT-Broker, beispielsweise Mosquitto.
Mindestens ein unterstütztes Gerät mit aktivierter benötigter Schnittstelle.
Für die mitgelieferten dateibasierten Widgets: openHAB ab Version 5.2.

Die veröffentlichten Docker-Images unterstützen amd64 und arm64. Damit kann derselbe Imagename auf einem üblichen x86-Server und einem Raspberry Pi mit 64-Bit-System verwendet werden.

Bei Wechselrichtern muss Modbus TCP gegebenenfalls zuerst in der Gerätekonfiguration aktiviert werden. Die Bridge übernimmt diese Freischaltung nicht.

Installation mit Docker Compose

Für den ersten Start richten wir zunächst einen Wechselrichter ein. Sobald dessen Werte ankommen, lassen sich weitere Geräte ergänzen.

1. Repository herunterladen

In einem Verzeichnis eurer Wahl:

git clone https://github.com/alaub81/sma-mqtt-bridge.git
cd sma-mqtt-bridge

mkdir -p data/sma-mqtt-bridge
touch smab.env
chmod 600 smab.env

Die Datei smab.env enthält unsere Einstellungen und Zugangsdaten. Sie liegt direkt neben den Compose-Dateien und bleibt lokal.

Für einen normalen Start ist keine zusätzliche JSON-Konfiguration notwendig. Alle verfügbaren Einstellungen sind in smab.example.env beschrieben. Diese Datei dient als Nachschlagewerk; für den Einstieg müssen nicht sämtliche Optionen übernommen werden.

2. MQTT und Wechselrichter konfigurieren

Die Datei smab.env mit einem Texteditor öffnen und folgende Einstellungen eintragen:

SMAB_MQTT_HOST=mqtt.example.invalid

SMAB_INVERTER1_ENABLED=true
SMAB_INVERTER1_HOST=inverter.example.invalid
SMAB_INVERTER1_PROFILE=sma-stp8-0-3av-40

SMAB_LANGUAGE=de

Die Beispieladressen müssen durch die eigenen Hostnamen oder IP-Adressen ersetzt werden. Das Profil im Beispiel gehört zum Sunny Tripower STP8.0-3AV-40.

Für die drei mitgelieferten Wechselrichterprofile stehen folgende IDs zur Verfügung:

Modell	Profil-ID
STP8.0-3AV-40	`sma-stp8-0-3av-40`
SBS3.7-10	`sma-sbs3-7-10`
SB4.0-1AV-41	`sma-sb4-0-1av-41`

Mit SMAB_LANGUAGE=de werden die bereitgestellten Geräte- und Messwertbezeichnungen auf Deutsch veröffentlicht.

Wichtig bei MQTT: Standardmäßig verwendet die Bridge TLS auf Port 8883 mit Zertifikatsprüfung.

Wenn euer Broker ausdrücklich ohne TLS auf Port 1883 betrieben wird, müssen zusätzlich beide Einstellungen gesetzt werden:

SMAB_MQTT_TLS=false
SMAB_MQTT_PORT=1883

Falls der Broker eine Anmeldung verlangt:

SMAB_MQTT_USERNAME=bridge-user
SMAB_MQTT_PASSWORD='PASSWORT_EINTRAGEN'

Einfache Anführungszeichen erhalten auch Sonderzeichen wie $ oder # im Passwort.

Bei einer privaten Zertifizierungsstelle wird das vertrauenswürdige CA-Zertifikat unter data/sma-mqtt-bridge/certificates/ abgelegt und über SMAB_MQTT_TLS_CA_FILE ausgewählt. Die genaue Einrichtung steht in der Installationsanleitung.

Der Broker muss aus dem Container erreichbar sein. localhost bezeichnet dort den Bridge-Container selbst. Läuft Mosquitto in einem anderen Docker-Container, benötigt die Verbindung beispielsweise ein gemeinsames Docker-Netzwerk oder einen erreichbaren Zugang über den Host.

3. Image laden und Konfiguration prüfen

Wir verwenden die Compose-Datei für das veröffentlichte Image. Ein eigener Build ist dafür nicht notwendig:

docker compose -f compose.example.yml pull

docker compose -f compose.example.yml run --rm --no-deps \
  sma-mqtt-bridge --check-config

Für unser Beispiel mit einem aktivierten Wechselrichter sollte die Prüfung sinngemäß Folgendes ausgeben:

{"valid": true, "enabledSources": 1, "readOnly": true}

Die Prüfung kontrolliert Einstellungen und benötigte lokale Dateien. Dabei wird noch keine Verbindung zum Wechselrichter oder MQTT-Broker aufgebaut.

enabledSources: 0 bedeutet, dass keine Datenquelle aktiviert ist. Eine eingetragene IP-Adresse allein reicht dafür nicht aus; die zugehörige ENABLED-Einstellung muss ebenfalls gesetzt sein.

4. Container starten und Werte kontrollieren

Nach erfolgreicher Prüfung:

docker compose -f compose.example.yml up -d

docker compose -f compose.example.yml ps sma-mqtt-bridge

docker compose -f compose.example.yml logs --tail=100 sma-mqtt-bridge

Für die ersten Abfragen etwas Zeit einplanen. Anschließend lassen sich die MQTT-Nachrichten beispielsweise mit einem MQTT-Viewer kontrollieren.

Der erste Wechselrichter verwendet standardmäßig diesen Topic-Bereich:

homie/sma-inverter1/

Darunter befinden sich Homie-Metadaten, der Gerätezustand und die Messwerte.

Ein laufender oder als healthy gemeldeter Container allein bestätigt noch keine aktuellen Gerätedaten. Deshalb immer auch Logs, Quellenstatus und tatsächliche Messwerte prüfen.

Weitere Geräte ergänzen

Die folgenden Einstellungen werden ebenfalls in smab.env ergänzt. Anschließend die Konfiguration erneut prüfen und den Container mit up -d übernehmen. Ein einfacher Container-Neustart lädt geänderte Umgebungsvariablen nicht neu.

Weitere Wechselrichter

Für zusätzliche Wechselrichter wird der jeweilige Block mit einer anderen Nummer wiederholt:

SMAB_INVERTER2_ENABLED=true
SMAB_INVERTER2_HOST=storage.example.invalid
SMAB_INVERTER2_PROFILE=sma-sbs3-7-10

SMAB_INVERTER3_ENABLED=true
SMAB_INVERTER3_HOST=solar.example.invalid
SMAB_INVERTER3_PROFILE=sma-sb4-0-1av-41

Die Nummer legt das Modell nicht fest. Entscheidend ist das ausgewählte Profil. Dasselbe passende Profil kann auch für mehrere Geräte verwendet werden.

Sunny Home Manager 2.0

Für die standardmäßige Modbus-TCP-Anbindung:

SMAB_HOME_MANAGER_ENABLED=true
SMAB_HOME_MANAGER_HOST=home-manager.example.invalid
SMAB_HOME_MANAGER_SERIAL=DEINE_NUMERISCHE_SERIENNUMMER

Adresse und Seriennummer durch die tatsächlichen Werte ersetzen. Die Seriennummer wird zur Gerätezuordnung benötigt.

Alternativ können UDP-Metertelegramme verwendet werden. Auch zusätzliche Phasenmesswerte neben Modbus sind möglich. Dafür müssen Netzwerk und Multicast-Empfang passen; für Linux enthält das Repository die separate Vorlage compose.host.example.yml.

Die Varianten sind in der Home-Manager-Anleitung beschrieben.

SMA eCharger

Für die lokale API werden der lokale Benutzer und das lokale Passwort der Wallbox benötigt:

SMAB_ECHARGER_ENABLED=true
SMAB_ECHARGER_HOST=echarger.example.invalid
SMAB_ECHARGER_USERNAME=LOKALER_BENUTZER
SMAB_ECHARGER_PASSWORD='LOKALES_PASSWORT'
SMAB_ECHARGER_EXPECTED_SERIAL=DEINE_WALLBOX_SERIENNUMMER

Die lokalen Zugangsdaten sind unabhängig vom Sunny-Portal-Konto.

Auch hier ist die TLS-Prüfung standardmäßig aktiv. Wenn das Wallbox-Zertifikat nicht bereits vertrauenswürdig ist, muss ein passendes vertrauenswürdiges Zertifikat beziehungsweise CA-Zertifikat eingebunden werden. Zertifikat und verwendeter Hostname müssen zusammenpassen.

SEMP und der optionale ennexOS-Portalzugriff werden separat aktiviert. Die vollständigen Einstellungen stehen in der Konfigurationsreferenz.

BYD Battery-Box

Die direkte BYD-Anbindung ergänzt die Messwerte des SMA-Batteriewechselrichters um eigene Batterieinformationen.

Vor der Aktivierung unbedingt die BYD-Anleitung prüfen. Das mitgelieferte Profil gilt für das dort beschriebene HVS-System mit vier Modulen und den passenden Firmwareständen.

Die BYD-Anbindung ist optional und ersetzt nicht die bisherigen SMA-Batteriewerte oder die Anlagenberechnung.

Geräte in openHAB einbinden

Sobald die Bridge Daten veröffentlicht, kann openHAB die Homie-Geräte entdecken:

Das MQTT-Binding installieren und ein MQTT-Broker-Thing einrichten oder das vorhandene verwenden.
Prüfen, ob das Broker-Thing verbunden ist.
In der Inbox einen Scan des MQTT-Bindings starten.
Die gefundenen Homie-Geräte dem passenden Broker zuordnen und hinzufügen.
Unter den Channels die gewünschten Messwerte mit eigenen Items verknüpfen.

Für Leistungswerte eignet sich Number:Power, für Energie Number:Energy. Die Einheiten liefert die Bridge mit. Zusätzliche Umrechnungen sind nur erforderlich, wenn die eigene weitere Verarbeitung sie tatsächlich benötigt.

Die Bridge und openHAB benötigen jeweils ihre eigene funktionierende Verbindung zum MQTT-Broker.

Bei einer bestehenden Installation können vorhandene Itemnamen und deren Historie erhalten bleiben. Vor dem Umstellen eines Links die bisherigen und neuen Werte vergleichen. Eigene Regeln und Berechnungen werden durch die Geräteerkennung nicht automatisch übertragen.

Weitere Informationen:

Fertige Widgets für die MainUI

Im Repository sind Widgets für folgende Ansichten enthalten:

Live-Energiefluss: aktuelle Leistungen von PV, Haus, Netz, Batterie und optionalen Verbrauchern.
Tagesenergieübersicht: Tagesertrag, Verbrauch, Netzbezug und Einspeisung sowie Batterieladung und -entladung.
PV-Dachproduktion: DC-Leistung für drei konfigurierte Modulflächen.
PV-Prognose: Tagesprognosen mit einstellbaren Ampelgrenzen.
eCharger: Fahrzeugstatus, Ladeleistung, Sitzungsanzeige und optional Bedienelemente.
Ladeplan: separate Karte und Listeneintrag für Zielenergie und Endzeit.

Die Prognose-Widgets verwenden bereits vorhandene Prognose-Items. Die Bridge berechnet keine eigene Wetter- oder PV-Prognose.

Import über die MainUI

Für den Einstieg können die vorbereiteten Dateien unter openHAB/mainui/widgets/ verwendet werden:

In openHAB als Administrator Entwicklerwerkzeuge → Widgets öffnen.
Mit + ein neues Widget anlegen.
Den vollständigen Inhalt der passenden Importdatei in den YAML-Editor übernehmen.
Die mitgelieferte UID beibehalten und speichern.
Das Widget einer Seite hinzufügen und in dieser Instanz die eigenen Items auswählen.

Alternativ lassen sich die kanonischen Dateien aus openHAB/yaml/widgets/ unter $OPENHAB_CONF/yaml/widgets/ installieren. Diese Variante wird über Dateien gepflegt und ist in der MainUI schreibgeschützt.

Pro Widget-UID nur eine Installationsmethode verwenden. Die Dateiinstallation und der manuelle Import sind zwei Varianten derselben Widgetdefinition.

Für eine erste Ansicht kann bei den unterstützten Widgets demoMode aktiviert werden. Damit werden gekennzeichnete Beispielwerte angezeigt. Für die eigenen Messwerte den Demomodus wieder ausschalten und die passenden Items auswählen.

Das Installieren eines Widgets legt keine Items, Links oder Regeln an. Die Zuordnung erfolgt bewusst über die Widget-Einstellungen.

Anleitungen und Beispiele:

Wallbox steuern und Ladepläne verwenden

Die Bridge startet mit deaktivierten Geräte-Schreibzugriffen. Wer zunächst nur Messwerte anzeigen möchte, kann es dabei belassen.

Für lokale eCharger-Befehle müssen zusätzlich zur aktivierten lokalen Anbindung beide Schreibfreigaben gesetzt werden:

SMAB_COMMANDS_ENABLED=true
SMAB_ECHARGER_COMMANDS_ENABLED=true

Damit können unterstützte Einstellungen wie Ladefreigabe, Lademodus oder maximale Ladeleistung genutzt werden. Ladepläne übertragen Zielenergie und Endzeit gemeinsam. Die Bridge prüft die Gerätevorgaben und liest Änderungen zurück, bevor sie einen bestätigten Zustand veröffentlicht.

Der Mindest-PV-Anteil nutzt die separate Portal-Anbindung und deren eigene Freigabe.

Im eCharger-Widget werden Bedienelemente zusätzlich über enableControls freigegeben. Schreibbare openHAB-Items sollten autoupdate=false verwenden, damit eine Bedienung nicht bereits als bestätigte Geräteänderung erscheint.

Der Sunny Home Manager bleibt für die Laderegelung zuständig. Die Bridge ermöglicht die dokumentierten Einstellungen und stellt Messwerte bereit.

Anlagenwerte und Tagesbilanzen

Die optionale Anlagenberechnung kann mehrere Quellen zusammenführen. Dazu gehören beispielsweise Hausverbrauch, täglicher Netzbezug, Einspeisung und getrennte Tageswerte für Batterieladung und -entladung.

Dafür müssen die beteiligten Quellen und ihre Rollen passend konfiguriert sein. Die Einrichtung ist in der Anleitung zur Anlagenberechnung beschrieben.

Bei Tageswerten beachten: Nach der ersten Einrichtung beginnen einige Zählerdifferenzen mit der ersten gespeicherten Ausgangsmessung. Der erste Tag kann deshalb nur einen Teil des Tages abdecken. Der zugehörige Abdeckungsstatus hilft, diese Werte einzuordnen.

Die Tagesübersicht zeigt die bereitgestellten Energiewerte an. Sie berechnet keine eigenen Tagesdifferenzen aus Gesamtzählern.

Updates und Backup

Die Beispiel-Compose-Datei verwendet standardmäßig das veröffentlichte Image mit dem Tag latest. Wer eine bestimmte Version festhalten möchte, kann SMAB_BRIDGE_VERSION in der optionalen root-Datei .env setzen. Die Geräte- und MQTT-Einstellungen bleiben in smab.env.

Vor einem Update sollten mindestens folgende Daten gesichert werden:

smab.env und gegebenenfalls .env.
Eigene Konfiguration, Profile und Zertifikate unter data/sma-mqtt-bridge/.
Das persistente Zustandsvolume data_smab_state; Docker stellt dem tatsächlichen Volumenamen normalerweise den Compose-Projektnamen voran.

Im Zustandsvolume liegen unter anderem gespeicherte Ausgangswerte für Energiebilanzen und die Verwaltung bereits veröffentlichter MQTT-Topics. Es sollte beim Austausch des Containers erhalten bleiben.

Das normale Update erfolgt im bisherigen Projektverzeichnis:

git pull --ff-only

docker compose -f compose.example.yml pull

docker compose -f compose.example.yml run --rm --no-deps \
  sma-mqtt-bridge --check-config

docker compose -f compose.example.yml up -d

Vor dem Start die Versionshinweise lesen und die erfolgreiche Konfigurationsprüfung abwarten. Bei fest eingestelltem Image-Tag muss dieser für einen Versionswechsel entsprechend angepasst werden.

Compose-Projektname und Zustandsvolume beibehalten. docker compose down -v würde die zugehörigen benannten Volumes löschen.

Details:

Troubleshooting

Problem	Was prüfen?
Der Container startet nicht.	Zuerst `--check-config` und anschließend die Container-Logs prüfen. Häufig fehlen Pflichtangaben einer aktivierten Quelle.
Keine Verbindung zum MQTT-Broker.	Adresse aus Sicht des Containers, Port, TLS-Einstellung, Zertifikate und Zugangsdaten kontrollieren.
Keine Wechselrichterwerte.	Passendes Modellprofil, Geräteadresse und aktivierte Modbus-Schnittstelle prüfen. Eine Adresse allein aktiviert den Adapter nicht.
openHAB findet keine Geräte.	Prüfen, ob die Bridge tatsächlich unter `homie/` veröffentlicht und openHAB denselben Broker sowie den passenden Homie-Präfix verwendet.
Ein Widget zeigt nur Striche.	Item-Zuordnung, Itemzustand und Einheit prüfen. Tagesenergie benötigt Energie-Items, keine Leistungswerte oder Gesamtzähler.
Das Widget zeigt weiterhin Beispielwerte.	`demoMode` in der verwendeten Seiteninstanz ausschalten.
Änderungen an `smab.env` greifen nicht.	Die Konfiguration erneut prüfen und den Container mit derselben Compose-Datei über `up -d` neu erstellen lassen.
Home-Manager-Phasenwerte fehlen.	UDP-Konfiguration, Seriennummer, Netzwerkmodus und Multicast-Erreichbarkeit prüfen.

Ausführlichere Hinweise stehen in der Betriebs- und Fehlerbehebungsanleitung.

Weiterführende Links