Skip to content

About

Home Assistant custom component to integrate with Marstek devices using the local API.

Topics

Resources

Contributing

Stars

42 stars

Watchers

2 watching

Forks

Latest commit

 

History

631 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Marstek Home Assistant Integration

License: MIT Home Assistant HACS Docs

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.

See it

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.

Marstek device page in Home Assistant with battery sensors and controls.

Automation editor with a Marstek device action to charge, discharge, or stop the battery.

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.

Quick start

  1. In the Marstek app, enable Open API on the battery. Home Assistant has to be on the same network. The usual port is 30000.
  2. Install the integration with HACS (or copy it in by hand) and restart Home Assistant.
  3. 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.

Installation

HACS (recommended)

  1. Open HACS in Home Assistant.
  2. Open the three-dot menu and choose Custom repositories.
  3. Add this repository's URL and choose Integration.
  4. Search for Marstek and install it.
  5. Restart Home Assistant.

Manual installation

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/

Removing the integration

  1. Go to Settings → Devices & services.
  2. Open Marstek.
  3. On the device, open the three-dot menu and choose Delete. Repeat for each battery. Each battery is its own config entry.
  4. 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.

What you can do

  • 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_mode and manual schedules (0–9 on Venus A, C, D, and E, 0–5 on 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.

Use cases

  • Dynamic tariff arbitrage. Drive marstek.set_manual_schedule from 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_mode sets 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.

Dashboard cards

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: Mode

name 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.

Venus E live dashboard with short names: battery level, power, mode, and 12 hours of charge and discharge.

Requirements

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.

Options

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

Supported devices

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.

Compared with other community integrations

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 marstek domain: Marstek's own HACS integration uses the same marstek domain, so only one of the two can be installed. Home Assistant Core PR #179635 adds homeassistant/components/marstek under 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.

Automations

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.

Lock Screen and Dynamic Island

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.

Battery health (optional)

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.

Battery health dashboard. Your batteries compares two packs on one kWh scale, with a weekly capacity chart on the battery that already has an estimate.

The Runs tab, the Energy tab, the phone layout, and the card picker are in Battery health and the visual tour.

Known limitations

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.

Troubleshooting

  • 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?.

For developers

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.

License

MIT. See LICENSE.

Acknowledgments

Protocol documentation: Marstek Open API specification.

Disclaimer

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.

About

Home Assistant custom component to integrate with Marstek devices using the local API.

Topics

Resources

Contributing

Stars

42 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages