Marstek Smart-Home-Integration, kostenlos und Open Source
Marstek Venus batteries over their local Open API: charge, powers, energy and mode.
Veröffentlicht von LM1LC3N7
- Geräte
- Version 0.1.1
- Erfordert Gladys >=5.0.0
- ★ 0
Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.
This integration brings your Marstek home batteries (Venus E, Venus C, Venus D, Venus A) into Gladys: state of charge, powers, energy and operating mode, read live on your local network through Marstek's official Open API (JSON over UDP). Nothing goes through the Internet nor the Marstek cloud. Unofficial, not affiliated with Marstek.
Development version (0.1). Built from Marstek's Open API document (Rev 3.1) and the readings the community published, not tested with a real battery yet. Feedback is welcome on the GitHub repository.
What you get
Each battery becomes a Gladys device in the Discovery tab, named after its model ("Marstek Venus E 3.0"). A value only shows up when your battery gives it.
| In Gladys | Where it comes from |
|---|---|
| State of charge | % of the battery |
| Charge / discharge power | always positive; from the power balance when the firmware leaves it out |
| Charged / discharged energy (AC) | lifetime counters of the battery on its plug side, in kWh |
| On-grid output power | what the battery delivers to the home through its plug |
| Off-grid output power and energy | the backup (EPS) socket of the battery |
| Solar power and energy | Venus A and D (PV inputs), in kWh for the energy views |
| Grid power (CT) | the CT meter of the battery: positive when importing, negative when exporting |
| Phases A, B, C (CT) | three-phase installations only |
| Grid import / export (CT) | firmware 150 or later |
| Battery temperature | every 5 minutes, on the safe firmware (see below) |
| Operating mode | Self-consumption (Auto), AI optimisation, Manual, Passive, Backup (UPS) |
| Passive mode power and duration | the passive mode setpoint: negative to charge, positive to discharge |
The values use the Gladys energy categories (battery storage, home output, grid, production): they show in the energy views like any other brand.
What you can control:
- the mode: Self-consumption, AI, Passive, and Backup (UPS) from firmware 150. Manual runs the time schedule set in the Marstek app: choose it in the app;
- the passive mode: set the power first (for example
-1500to charge at 1,500 W,800to deliver 800 W) and the duration in minutes, then choose the Passive mode. In passive mode, a new power applies at once. Scene example: "charge at 2,000 W during off-peak hours".
Requirements
- A Marstek Venus E 3.0, Venus A or Venus D (or Venus C, Venus E 2.0: see the limits) on your network (Wi-Fi or Ethernet).
- The Open API turned on in the Marstek app for each battery, with its UDP port (30000 by default).
- A fixed IP address for each battery in your router (DHCP reservation), as Marstek recommends.
- Up-to-date firmware: 150 or later for the Venus E 3.0, A and D.
Installation
- In the Marstek app, turn on the Open API of each battery.
- In Gladys, open the Discovery tab of the integration: Gladys broadcasts a request on the network and lists the batteries that answer.
- A battery is missing? Type its IP address in the configuration (several
addresses separated by commas, with
:portwhen the Open API does not use 30000), then open Discovery again. - Add the batteries you want.
The Test the connection button lists the batteries that answer, with their firmware and Wi-Fi signal.
Options
| Option | Default | Role |
|---|---|---|
| IP addresses | empty | the batteries Discovery does not find |
| Reading interval | 30 s | from 10 to 300 s; 30 s like the Marstek app |
How it works
The batteries answer one request at a time: the integration sends a single
request at a time, waits 2 seconds after each answer, then reads at each round
the status (ES.GetStatus), the CT meter (EM.GetStatus) and the mode
(ES.GetMode); the PV inputs every minute, the temperature every 5 minutes and
the firmware every 10 minutes. A battery is followed by its Bluetooth MAC
address: Discovery finds it again when its IP address changes.
The transport badge of each battery shows local, with an orange dot when a request went unanswered or the firmware is fragile, and unreachable after three rounds without an answer.
Known limits
- Discovery does not find every battery. Gladys broadcasts the request from any port; several firmware builds only answer to port 30000 (Venus C, Venus E 2.0) and the Venus E mini ignores the broadcast: type their IP address.
- Firmware older than 150 (Venus E 3.0, A, D): gentle polling (one attempt per request, no temperature reading), because this firmware may turn its Open API off or lose its settings when polled. Update the battery from the Marstek app.
- Venus C and Venus E 2.0: their meter shares the Wi-Fi channel of the Open API; polling may lose the CT meter and stop self-consumption. They are read once a minute at most.
- Venus E mini (firmware 301): it answers in broadcast, which never reaches the container of the integration; not supported yet.
- The Manual mode and its time slots are set in the app.
Troubleshooting
- "No answer": the Open API is off (some firmware turns it off by itself: turn it on again in the app), the port is wrong, or the battery is on another network than Gladys.
- Missing values: some firmware leaves fields empty (solar energy at 0, off-grid energy always 0); the integration only shows what the battery gives.
- "the battery refused the mode": the firmware does not take that mode (Backup before firmware 150).
Privacy
Everything stays on your network: the integration only talks to your batteries, over UDP. Marstek's Open API has no password: any device on your network can read and control it.
Disclaimer
Unofficial integration, not affiliated with Marstek. Marstek and Venus are trademarks of their owners. Changing the mode or the charging power acts on a real electrical installation: do it knowingly.
Konfigurationseinstellungen
Diese Einstellungen fragt Marstek in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Your Marstek batteries in Gladys | section | Nein | Reads your Marstek home batteries (Venus E, C, D, A) on your local network through their Open API: state of charge, charge and discharge power, solar, on-grid and off-grid power, the CT meter, energy counters for the Gladys energy views, battery temperature, and the operating mode, which Gladys can change. In the Marstek app, turn on the Open API of each battery (UDP port 30000), then open Discovery, or type the IP addresses below. Nothing goes through the Internet nor the Marstek cloud. Unofficial, not affiliated with Marstek. |
| Battery IP addresses (optional) | string | Nein | Discovery finds the batteries that answer its broadcast. Type the others here, separated by commas, with :port when the Open API does not use 30000. Give them a fixed address in your router. |
| Reading interval (s) | number | Nein | How often each battery is read. The batteries answer one request at a time and some firmware turns its Open API off when read too often: 30 s, as the Marstek app, unless you need more. |
So installierst du Marstek in Gladys
- Öffne in Gladys Integrationen: Marstek erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/lm1lc3n7/gladys-marstek:0.1.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/LM1LC3N7/gladys-marstek.
Marstek benötigt Gladys >=5.0.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
Marstek ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von LM1LC3N7 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation