Bring your Marstek batteries into Home Assistant through HACS. This unofficial integration is a fork of the original Marstek integration. It connects locally to supported Marstek energy storage devices over UDP using OpenAPI rather than Modbus TCP, and exposes their status as native Home Assistant sensors.
Installation runs through HACS as a custom repository. The button below adds the repository to HACS.
- Select the button above, or open HACS > ⋮ > Custom repositories and add
https://github.com/hawkinslabdev/ha_marstekwith type Integration. - Download Marstek (unofficial) and restart Home Assistant.
- Add the Marstek integration or open Settings > Devices & services > Add integration > Marstek (unofficial).
- Select a setup method:
- Search for devices on the local network: UDP broadcast discovery.
- Enter device IP address: manual setup.
Setup requires the device to be powered on, reachable from Home Assistant, and running with Open API enabled (on any port).
- Home Assistant Core 2026+
- Home Assistant and the Marstek device must be on the same local network.
- Open API must be enabled on the Marstek device.
The integration currently supports these device types. A device may report either its model name or one of the protocol identifiers below:
| Device | Supported | Reported device type |
|---|---|---|
| Venus A | Yes | VNSA-0, VenusA, Venus A |
| Venus C | No | — |
| Venus D | Yes | VNSD-0, VenusD, Venus D |
| Venus E 1.0 | No | — |
| Venus E 2.0 | No | — |
| Venus E 3.0 | Yes | VNSE3-0, VenusE 3.0, Venus E 3.0 |
| Venus E mini | No | — |
Support depends on the device firmware exposing the Marstek Open API. Other device types are rejected during setup until they are explicitly supported.
Tip
With Marstek releasing new devices, we need your help testing and adding support for unreleased models. If you have an unsupported device, please open an issue or submit a pull request!
Sensors, controls, and data sources
| Entity | Type | Source |
|---|---|---|
| State of charge | Sensor (%) | ES.GetStatus / ES.GetMode bat_soc |
| Battery power, battery status | Sensor (W), enum (charging, discharging, idle) |
ongrid_power magnitude and sign |
| Charging power, discharging power | Sensor (W) | ongrid_power, split by direction; 0 for the inactive direction |
| Battery energy in, battery energy out | Sensor (kWh, total increasing) | ES.GetStatus total_grid_input_energy, total_grid_output_energy (AC side) |
| Stored energy | Sensor (kWh) | bat_cap × bat_soc |
| Battery cycles | Sensor (diagnostic) | Equivalent full cycles: total_grid_output_energy ÷ bat_cap; AC-side energy, so slightly below the BMS count |
| Device mode | Sensor (enum) | ES.GetMode mode |
| PV1–PV4 power, voltage, current, state; lifetime PV energy | Sensor | PV.GetStatus, total_pv_energy; created for Venus A/D only |
| Operating mode | Select (Auto, AI, Passive, UPS) |
ES.SetMode; Manual requires an app schedule and reports as unknown |
| Passive power | Number (W, −2500 to 2500) | passive_cfg.power; negative charges, positive discharges |
| Passive duration | Number (s, 60 to 86400) | passive_cfg.cd_time |
| Depth of discharge | Number (%, 30 to 88, default 88) | DOD.SET; firmware 150 and later |
| Error state | Sensor (enum, diagnostic) | Outcome of the latest poll |
Passive power and duration are stored in Home Assistant and restored after restart. Changes apply immediately while the device is in passive mode, otherwise on the next switch to Passive.
Features by firmware version
Some settings require a specific minimum device firmware, as detailed in Marstek's Open API specification. During setup, the integration checks your device's firmware version and creates only the supported entities. If the version cannot be read, these entities are skipped and no changes are written to your device.
| Firmware | Entity | Behavior |
|---|---|---|
| 150+ | Depth of discharge (DOD.SET) |
Shows the last value written from Home Assistant (restored after a restart). App changes are not reflected because the API lacks a read command. |
After updating your firmware, remember to reload the integration so new entities are created.
Energy dashboard
Since integrations cannot directly register Energy dashboard sources and Home Assistant lacks a dedicated battery entity type, add the battery manually:
- Navigate to Settings > Dashboards > Energy.
- Select Battery systems.
- Map the dialog fields:
- Energy discharged from the battery:
sensor.marstek_venus_e_3_0_battery_energy_out - Energy charged into the battery:
sensor.marstek_venus_e_3_0_battery_energy_in - Power measurement type: two sensors
- Discharge power:
sensor.marstek_venus_e_3_0_discharging_power - Charge power:
sensor.marstek_venus_e_3_0_charging_power - State of charge sensor:
sensor.marstek_venus_e_3_0_state_of_charge - Usable capacity (kWh): optional; only weights the combined state of charge across multiple batteries
Data quality
Readings that drop to implausible values are replaced with the previous value: energy counters that decrease, bat_cap of 0, and a battery level of 0 % after a reading of 10 % or more.
Repairs and diagnostics
A repair issue is raised after 10 consecutive polls (10 minutes) without an Open API response, a common result of firmware updates resetting Open API. The issue clears on the next successful poll. Entities keep their last values through one missed poll and report unavailable after 2 consecutive missed polls (2 minutes).
The Error state diagnostic sensor reports the outcome of the latest poll (none, no_response, network_error, invalid_data) and stays available during outages. Log entries identify the device by <ip>:<port>; setup logs the model, reported device type, firmware version, and Open API revision (3.1).
Download diagnostics on the device page exports device information, normalized status, error state, Open API revision, and the latest raw reply per Open API request. MAC addresses, Wi-Fi name, and src identifiers are redacted.
The device is polled locally every 60 seconds. No cloud account or external service is required.
This is a fork of MarstekEnergy/ha_marstek, thus inheriting its proprietery license.