Marstek2ioBroker

Marstek2ioBroker liest Leistungs- und Batteriedaten aus der inoffiziellen Hame/Marstek-Cloud-API und überträgt sie über den ioBroker Simple API Adapter an bestehende States.

Übertragene Werte

Cloud-Feld	ioBroker-State
discharge	javascript.0.Variablen.Marstek_discharge
load	javascript.0.Variablen.Marstek_load
pv	javascript.0.Variablen.Marstek_pv
soc	javascript.0.Variablen.Marstek_soc
berechnet aus soc	javascript.0.Variablen.Marstek_soc_kwh

Marstek_soc_kwh wird mit SOC × BATTERY_CAPACITY_KWH / 100 berechnet und auf zwei Nachkommastellen gerundet. Die voreingestellte Gesamtkapazität von 2,228571 kWh ergibt sich aus der Vorgabe, dass 0,78 kWh einem SOC von 35 % entsprechen.

Die States werden derzeit an den Simple API Adapter unter http://10.0.1.122:8087 gesendet. Bei mehreren Cloud-Geräten verwendet das Skript den ersten Eintrag der Geräteliste.

Voraussetzungen

• Python 3.10 oder neuer
• Netzwerkzugriff auf https://eu.hamedata.com
• erreichbarer ioBroker Simple API Adapter auf Port 8087
• Hame-/Marstek-Konto mit Zugriff auf das gewünschte Gerät

Das Skript verwendet ausschließlich Module aus der Python-Standardbibliothek. Eine Installation zusätzlicher Python-Pakete ist nicht erforderlich.

Für den Dauerbetrieb empfiehlt sich ein separates Marstek-Konto, für das das Gerät in der Marstek-App freigegeben wurde. Dadurch konkurriert das Skript nicht mit der mobilen App um dieselbe Cloud-Sitzung.

Installation unter Linux

Repository klonen und Konfiguration anlegen:

git clone https://git.hintergasse.de/hubobel/Marstek2ioBroker.git
cd Marstek2ioBroker
cp .env.example .env
nano .env
chmod 600 .env

Anschließend einen einzelnen Testlauf ausführen:

python3 hame_cloud_api.py --once

Wenn der Test erfolgreich ist, den Dauerbetrieb starten:

python3 hame_cloud_api.py

Mit Strg+C wird das Skript sauber beendet.

Installation unter Windows

git clone https://git.hintergasse.de/hubobel/Marstek2ioBroker.git
Set-Location Marstek2ioBroker
Copy-Item .env.example .env
notepad .env
python hame_cloud_api.py --once

Konfiguration

Die Datei .env liegt neben hame_cloud_api.py und wird beim Start automatisch geladen:

HAME_MAILBOX=second-account@example.com
HAME_PASSWORD=replace-me
HAME_BASE_URL=https://eu.hamedata.com
BATTERY_CAPACITY_KWH=2.228571

LOG_LEVEL=INFO
LOG_FILE=logs/hame_cloud_api.log
LOG_MAX_BYTES=5242880
LOG_BACKUP_COUNT=5

Variable	Bedeutung	Standard
HAME_MAILBOX	E-Mail-Adresse des Cloud-Kontos	interaktive Eingabe
HAME_PASSWORD	Passwort des Cloud-Kontos	interaktive Eingabe
HAME_BASE_URL	regionale Hame-Cloud-URL	https://eu.hamedata.com
BATTERY_CAPACITY_KWH	nutzbare Gesamtkapazität für die SOC-kWh-Berechnung	2.228571
LOG_LEVEL	Mindeststufe des Loggings	INFO
LOG_FILE	relative oder absolute Logdatei	logs/hame_cloud_api.log
LOG_MAX_BYTES	maximale Größe einer Logdatei	5242880 (5 MB)
LOG_BACKUP_COUNT	Anzahl rotierter Sicherungslogs	5

.env enthält Zugangsdaten und wird deshalb durch .gitignore vom Repository ausgeschlossen. Die Datei darf nicht committed oder weitergegeben werden.

Aufrufoptionen

--interval SEKUNDEN   Zeit zwischen Cloud-Abfragen (Standard: 60)
--once                genau eine Abfrage durchführen und beenden
--timeout SEKUNDEN    Zeitlimit je HTTP-Aufruf (Standard: 15)
--retries ANZAHL      Wiederholungen bei temporären Fehlern (Standard: 3)
--base-url URL        Cloud-Basis-URL überschreiben
--visible-password    Passwort bei interaktiver Eingabe sichtbar anzeigen

Beispiele:

# Dauerbetrieb mit dem empfohlenen 60-Sekunden-Intervall
python3 hame_cloud_api.py

# Abfrage alle 30 Sekunden
python3 hame_cloud_api.py --interval 30

# Einmaliger Funktionstest
python3 hame_cloud_api.py --once

Das Skript erzwingt ein Mindestintervall von zehn Sekunden. Es meldet sich einmal an und verwendet den Cloud-Token für weitere Abfragen. Wenn die Cloud den Token mit Code 8 ablehnt, erfolgt automatisch eine neue Anmeldung. Bei Fehlern wächst die Pause zwischen weiteren Versuchen bis auf fünf Minuten.

Logging

Standardmäßig erscheinen Meldungen in der Konsole und gleichzeitig in:

logs/hame_cloud_api.log

Der relative Pfad wird immer vom Verzeichnis des Python-Skripts aus aufgelöst. Unter Linux kann das Log beispielsweise live verfolgt werden:

tail -f logs/hame_cloud_api.log

LOG_LEVEL=DEBUG schreibt zusätzlich die vollständige JSON-Geräteantwort in das Log. Diese Antwort enthält Gerätekennungen wie MAC-Adresse, Seriennummer und salt, jedoch weder das Cloud-Passwort noch den Token.

Verfügbare Logstufen sind DEBUG, INFO, WARNING, ERROR und CRITICAL. Das Logging rotiert die Datei automatisch, sobald LOG_MAX_BYTES erreicht ist.

Automatischer Start mit systemd

Auf Linux kann der Dienst automatisch aus dem geklonten Projektverzeichnis installiert werden:

chmod +x install-systemd.sh
sudo ./install-systemd.sh

Das Installationsskript:

• verwendet den Benutzer, der sudo aufgerufen hat,
• erkennt eine vorhandene .venv oder verwendet python3,
• schützt .env mit Dateirechten 0600,
• erstellt und aktiviert marstek2iobroker.service,
• startet den Dienst sofort und zeigt seinen Status an.

Status und Dienstjournal können anschließend so angezeigt werden:

sudo systemctl status marstek2iobroker.service
sudo journalctl -u marstek2iobroker.service -f

Neustart und Beenden:

sudo systemctl restart marstek2iobroker.service
sudo systemctl stop marstek2iobroker.service

Falls das Skript direkt als root und nicht über sudo aufgerufen wird, muss der gewünschte Benutzer angegeben werden:

sudo SERVICE_USER=deinbenutzer ./install-systemd.sh

Manuelle Einrichtung

Beispiel für /etc/systemd/system/marstek2iobroker.service – Benutzername und Pfad müssen an den eigenen Server angepasst werden:

[Unit]
Description=Marstek Cloud to ioBroker bridge
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/opt/Marstek2ioBroker
ExecStart=/usr/bin/python3 /opt/Marstek2ioBroker/hame_cloud_api.py
Restart=on-failure
RestartSec=15

[Install]
WantedBy=multi-user.target

Dienst aktivieren:

sudo systemctl daemon-reload
sudo systemctl enable --now marstek2iobroker.service
sudo systemctl status marstek2iobroker.service

Hinweise

Die verwendete Hame/Marstek-Cloud-API ist nicht offiziell dokumentiert und kann sich ohne Ankündigung ändern. Das Projekt sollte die API nicht unnötig häufig abfragen. Das voreingestellte Intervall von 60 Sekunden ist für den Dauerbetrieb vorgesehen.