Monitor and control Marstek batteries from Home Assistant over local UDP. Read live state of charge and power, send battery and solar energy to the Energy dashboard, set the operating mode, and drive passive power or manual schedules from automations. Usable capacity and battery health are optional once a pack has been measured. See Battery health.
This is an independent community project. It is not affiliated with or endorsed by Marstek.
New to this? The documentation website at marstek.rhino-inquisitor.com has a step-by-step getting started guide, a supported devices check, and a comparison with other integrations.
The device page shows state of charge, power, operating mode, and the controls. An automation can charge, discharge, or stop the battery with a device action.
Setup, options, and the Energy dashboard are in the visual tour. The Runs tab, the Energy tab, the phone layout, and the card picker are in Battery health and that tour.
- In the Marstek app, enable Open API on the battery. Home Assistant has to be on the same network. The usual port is 30000.
- Install the integration with HACS (or copy it in by hand) and restart Home Assistant.
- Go to Settings → Devices & services → Add integration, search for Marstek, and pick the discovered battery. If nothing is found, enter the IP address and port.
Polling intervals, power limits, and the optional Battery health sidebar are under Configure on the device. See Options.
- Open HACS in Home Assistant.
- Open the three-dot menu and choose Custom repositories.
- Add this repository's URL and choose Integration.
- Search for Marstek and install it.
- Restart Home Assistant.
Copy custom_components/marstek into your Home Assistant config as config/custom_components/marstek, then restart.
cd /config
mkdir -p custom_components
cp -r /path/to/has-marstek-local-api/custom_components/marstek custom_components/- Go to Settings → Devices & services.
- Open Marstek.
- On the device, open the three-dot menu and choose Delete. Repeat for each battery. Each battery is its own config entry.
- Deleting the entry removes its device, its entities and their history, releases the UDP socket, and clears Repairs issues that entry raised. The network scanner stops once the last entry is gone.
To remove the integration as well:
- HACS: HACS → Integrations → Marstek → three-dot menu → Remove, then restart Home Assistant.
- Manual install: delete
config/custom_components/marstek/and restart.
Open API can stay enabled in the Marstek app. A battery you delete while it is still on the network is offered again under Settings → Devices & services. Choose Ignore on that discovery card to leave it out.
More detail: Installation.
- Live battery state. State of charge, charge and discharge power, status, and operating mode (Auto, AI, Manual, Passive, and UPS on firmware that supports it).
- Control from automations. Charge, discharge, and stop device actions, plus
marstek.set_passive_modeand manual schedules (0–9on Venus A, C, D, and E,0–5on Venus E mini). Battery low and Charging are the sensors Home Assistant's battery conditions use (Battery is low, Battery is charging, Battery level). - Energy dashboard. Grid and off-grid power, per-phase meter power, solar PV on Venus A and Venus D, and lifetime energy totals.
- Device controls on supported firmware. Depth of discharge, Bluetooth advertising, and the panel LED.
- Finding and diagnosing the battery. Wi-Fi RSSI, CT connection status, automatic IP discovery, diagnostics, and Repairs.
- Battery health, optional. Usable capacity, state of health, the built-in Lovelace cards, the sidebar dashboard, and a linked smart-plug meter. See Battery health.
Battery temperature and the other battery-detail sensors start disabled, because the request behind them has been suspected of resetting some batteries (#14). Enable them from the device page when you want them. See Entities.
- Dynamic tariff arbitrage. Drive
marstek.set_manual_schedulefrom a price integration (Nord Pool, Tibber, EPEX) so the battery charges on cheap hours and discharges on expensive ones. - Closed-loop power.
marstek.set_passive_modesets a watt setpoint with a countdown, so an automation can follow house load or a solar forecast. - Solar self-consumption. On Venus A and Venus D the PV sensors feed the Energy dashboard. See Energy dashboard.
- Grid-peak avoidance. Meter sensors expose import and export per phase, so an automation can discharge when the house would otherwise set a new peak.
- Make room for an EV or a heat pump. Charge, Discharge, and Stop are device actions in the automation editor.
- Alerts without a cloud account. State of charge, temperature, firmware, and Wi-Fi RSSI stay available when Marstek's servers do not.
Copy-paste YAML is in Automations and services.
State of charge, power, and operating mode are ordinary sensors, so the built-in gauge and tile cards are enough. Replace <battery> with the prefix from your battery's entity id. Open Battery level on the device page: in sensor.venus_e_3_0_battery_level the prefix is venus_e_3_0. Venus A and Venus D also have PV power. Temperature and Wi-Fi start disabled.
type: vertical-stack
cards:
- type: gauge
entity: sensor.<battery>_battery_level
name: Battery level
min: 0
max: 100
- type: tile
entity: sensor.<battery>_battery_power
name: Power
- type: tile
entity: select.<battery>_operating_mode
name: Modename is optional. It keeps the label short. Leave it out to use the full entity name.
The Venus A layout, the history graph, and the visual-editor steps are in Dashboard cards.
| Requirement | Details |
|---|---|
| Home Assistant | Core 2025.10.0 or newer |
| Network | Same LAN segment as the battery |
| Marstek app | Open API enabled |
| UDP port | 30000 by default. The port is configurable per device in the Marstek app. Discovery also probes 30001–30004 and 30030 |
Warning: Venus E 2.0 support is experimental. Setup asks you to confirm before the battery is added, then Home Assistant shows a repair warning you can ignore. It uses the same feature gates as Venus C. Polling can disconnect the device from CT003, because the Local API and the meter share one Wi-Fi receive channel. See troubleshooting.
Warning: Venus C shares one Wi-Fi receive channel between the Local API and the device's own meter, so polling can stop Self-consumption (Auto) from charging on excess solar (#82). Use slow polling intervals, and read grid power from the meter directly if Auto mode stalls. See troubleshooting.
Open the device and choose Configure.
- Polling Intervals. Fast (default 30 seconds) reads mode, battery status, and meter power. Medium (default 60 seconds) reads solar on Venus A and Venus D. Slow (default 300 seconds) reads Wi-Fi and battery diagnostics, and only while a sensor that needs them is enabled.
- Network Settings. Delay between requests (default 5 seconds), request timeout (default 10 seconds), and failures before entities go unavailable (default 3). Parallel API requests stay off.
- Power Settings. Default charge power is -1300 W and default discharge power is 800 W. A Charge or Discharge action uses those when the field is left empty. Enforce 800 W discharge limit is on by default for Venus C, D, E, and Venus E mini, and off for Venus A. While it is on, validated discharge stays at or below 800 W.
- Battery health dashboard. Off by default. Show Battery health in the sidebar adds the optional page. The cards stay available from Add card either way. See Battery health.
- Energy meter (optional). Link a smart plug's total-energy sensors to measure the round trip and standby draw. Leave both fields empty to use the battery's own readings.
Ranges, firmware gates, and screenshots are in Options.
- Documentation website. The same pages with search, plus beginner guides.
- Documentation index. Every page, grouped by what you are trying to do.
- Visual tour
- Installation · Configuration · Options
- Battery health · Energy dashboard · Dashboard cards · Automations and services · Lock Screen and Dynamic Island
- Entities · Repairs · Troubleshooting
- Why a battery goes offline: restarts, network resets, and dropouts in plain language
Capabilities depend on the model and the firmware version. A feature the battery cannot do is left off the device page.
| Device | Status | Notes |
|---|---|---|
| Venus A | Supported, with solar | SYS and UPS from firmware 150 |
| Venus D | Supported, with solar | SYS and UPS from firmware 150 |
| Venus C | Supported, with a caveat | Depth of discharge, Panel LED, and Bluetooth advertising from firmware 158. UPS is not offered. Polling can stall Auto-mode charging on the shared Wi-Fi channel (#82) |
| Venus E 3.0 | Supported | SYS and UPS from firmware 150. Ten manual schedule slots (0–9) |
| Venus E mini | Supported | Reports VNSEM-0. Six manual schedule slots (0–5). Add it by IP |
| Venus E 2.0 | Experimental | Same gates as Venus C. Setup asks you to confirm, then shows a repair warning you can ignore |
| Other Open API devices | May work, untested | Treated as an unknown model, with the safest feature set |
Per-firmware energy scaling, schedule limits, and the Docker test matrix are in Development. If your model or firmware is missing, open a firmware coverage issue.
Other ways to connect a Marstek battery include Marstek's own HACS integration (marstekEnergy/ha_marstek) and other Open API integrations, Modbus integrations such as Omnibattery (a wired option when Open API polling is a poor fit for Venus E 2.0), and hm2mqtt for B2500 and Jupiter. The comparison on the documentation site covers models, features, and activity for each, and which one fits your setup.
Heads-up on the
marstekdomain: Marstek's own HACS integration uses the samemarstekdomain, so only one of the two can be installed. Home Assistant Core PR #179635 addshomeassistant/components/marstekunder that domain too. Custom components take precedence over built-in ones, so an installed copy of this integration keeps working if that PR merges. Remove it first if you want to try the built-in one.
Every service targets a device with device_id, except marstek.request_data_sync, where leaving it out refreshes every battery.
| Service | What it does |
|---|---|
marstek.set_passive_mode |
Hold a charge or discharge setpoint for a number of seconds. Negative power charges. |
marstek.set_manual_schedule |
Write one schedule slot. |
marstek.set_manual_schedules |
Write several slots from a YAML list. |
marstek.clear_manual_schedules |
Clear the slots. |
marstek.request_data_sync |
Refresh now. |
Charge, Discharge, and Stop are also device actions in the automation editor. Parameters, YAML examples, and the screenshots are in Automations and services.
A Live Activity is a Companion app notification, not a feature of this integration. The automation below starts when Charging turns on, updates when Battery level enters a new 5% band, and clears when charging stops. It does not run on every poll.
Copy each Entity ID from the entity page. After a rename or an area change, the entities on one battery can use different prefixes, so the single <battery> placeholder fits only when Charging, Battery level, and Battery power still share it. On one install, Charging was binary_sensor.attic_utility_room_venus_e_3_0_charging while Battery level and Battery power stayed sensor.marstek_venuse_3_0_v145_battery_level and sensor.marstek_venuse_3_0_v145_battery_power. When they still share a prefix, a Venus E 3.0 named Venus E (3.0) is often venus_e_3_0. The action: line is the Companion action from Developer tools → Actions: search for notify.mobile_app and pick the phone, for example notify.mobile_app_thomass_iphone_13_pro. A name such as notify.thomass_iphone_13_pro_2 is a notify entity. Using that entity, or a suffix such as _2 or _kiosk that the list does not show, fails with Unknown action.
# Confirm each entity_id in the UI. One <battery> prefix fits only when they still match.
alias: Marstek charging on the Lock Screen
description: Live Activity while the battery charges. Updates about every 5%.
mode: queued
max: 10
triggers:
- trigger: state
id: started
entity_id: binary_sensor.<battery>_charging
to: "on"
not_from: "on"
- trigger: state
id: level
entity_id: sensor.<battery>_battery_level
- trigger: state
id: stopped
entity_id: binary_sensor.<battery>_charging
from: "on"
to: "off"
actions:
- choose:
- conditions:
- condition: trigger
id: stopped
sequence:
- action: notify.mobile_app_<your_device_id_here>
data:
message: clear_notification
data:
tag: marstek_<battery>_charging
- conditions:
- condition: trigger
id: level
- condition: state
entity_id: binary_sensor.<battery>_charging
state: "on"
- condition: template
value_template: >-
{{ trigger.from_state is not none
and trigger.to_state.state | is_number
and trigger.from_state.state | is_number
and (trigger.to_state.state | int // 5)
!= (trigger.from_state.state | int // 5) }}
sequence:
- action: notify.mobile_app_<your_device_id_here>
data:
title: Marstek
message: >-
Charging at {{ states('sensor.<battery>_battery_power') | float(0) | abs | round(0) }} W
· {{ states('sensor.<battery>_battery_level') | int(0) }}%
data:
tag: marstek_<battery>_charging
live_update: true
silent: true
alert_once: true
critical_text: "{{ states('sensor.<battery>_battery_level') | int(0) }}%"
progress: "{{ states('sensor.<battery>_battery_level') | int(0) }}"
progress_max: 100
notification_icon: "mdi:battery-charging"
notification_icon_color: "#4CAF50"
color: "#4CAF50"
- conditions:
- condition: trigger
id: started
sequence:
- action: notify.mobile_app_<your_device_id_here>
data:
title: Marstek
message: >-
Charging at {{ states('sensor.<battery>_battery_power') | float(0) | abs | round(0) }} W
· {{ states('sensor.<battery>_battery_level') | int(0) }}%
data:
tag: marstek_<battery>_charging
live_update: true
critical_text: "{{ states('sensor.<battery>_battery_level') | int(0) }}%"
progress: "{{ states('sensor.<battery>_battery_level') | int(0) }}"
progress_max: 100
notification_icon: "mdi:battery-charging"
notification_icon_color: "#4CAF50"
color: "#4CAF50"Requirements, a discharge example, and the iOS update limits are on Lock Screen and Dynamic Island.
After a few long charge or discharge runs, the integration estimates usable capacity and state of health. The same cards can go on a dashboard you already have. The sidebar page and a smart-plug meter stay off until you turn them on.
The Runs tab, the Energy tab, the phone layout, and the card picker are in Battery health and the visual tour.
These are constraints of the Open API or of this integration's design.
- Polling only. The battery pushes nothing. A change made in the Marstek app shows up on the next poll (30 seconds by default for live power).
- No authentication. Open API is plain UDP. Anyone on the same LAN can read and write the battery. The integration has no password to refresh. Its reauth step only updates a changed IP address.
- One request at a time per battery by default. A batch such as clearing every schedule slot takes one round trip per slot.
- LAN only. Discovery uses UDP broadcast. A battery on another VLAN needs its IP entered by hand.
- Depth of discharge, Bluetooth advertising, and the panel LED cannot be read back. Home Assistant shows the last value the battery accepted.
- Passive and Manual can't be chosen from the mode dropdown. They show there so the current mode is visible, but both need a power, a duration, or time slots, so set them with services or device actions.
- One device per config entry. Several batteries are several entries. The fleet card is the on-screen comparison.
- Venus E 2.0 support is experimental. The battery can be added. Home Assistant shows a repair warning. It uses the same feature gates as Venus C.
- Features the firmware lacks are omitted. Depth of discharge, Bluetooth advertising, the panel LED, and UPS need firmware 150 or newer on Venus A, D, and E 3.0. On Venus C and Venus E 2.0 those three controls need firmware 158 or newer, and UPS is not offered. PV sensors exist on Venus A and Venus D.
- Battery-detail entities start off. See Entities.
- Energy totals stay monotonic. When firmware reports a lower lifetime total than a moment ago, the integration keeps the last plausible value. A genuine counter reset on the device needs a statistics correction in Home Assistant.
- The battery is not discovered. Confirm Open API is on, that Home Assistant is on the same network, and that UDP port 30000 is reachable. You can always type the IP and port.
- Entities go unavailable. Short UDP failures keep the last values until Failures before unavailable (default 3) is reached. Then check the device, and try
marstek.request_data_sync. - Panel LED, Bluetooth, depth of discharge, or UPS is missing. Those controls depend on firmware. The device page omits what the battery will reject. See Troubleshooting.
- Venus C stops charging from excess solar in Auto mode. Polling shares the meter's Wi-Fi channel. See Troubleshooting.
- The health card says Still measuring. It needs three 20-point runs in one direction. See Why does my card say Still measuring?.
Tests, the firmware emulator matrix, the repository map, and the Changesets release flow are in Development. The protocol note is Open API Rev 3.1.
Contributions are welcome. See CONTRIBUTING.md.
MIT. See LICENSE.
Protocol documentation: Marstek Open API specification.
This integration is provided as is, without warranty. The authors are not responsible for damage to your devices or for data loss. This project is not affiliated with, endorsed by, or connected to Marstek.



