Marstek Venus Battery - Home Assistant Integration

July 14, 2026 · View on GitHub

GitHub Release GitHub Issues Downloads

This is a custom HACS-compatible integration for Marstek Venus battery systems, using Modbus TCP via an RS485-to-WiFi gateway or direct Ethernet where supported (e.g. Venus E3). No YAML required. The integration provides sensors, switches and number controls to monitor and manage the battery directly from Home Assistant.

🧩 Requirements

  • A configured Modbus RTU to Modbus TCP bridge connected to the battery's RS485 port
    • Alternativly: Ethernet Connection to Battery with Modbus TCP support
  • The IP address, port of the Modbus TCP (usually port 502) and Unit ID (also called Slave ID).
  • Home Assistant Core 2025.9 or later
  • HACS installed

🔧 Features

  • Native Modbus TCP polling via pymodbus
  • Polling is handled centrally via the DataUpdateCoordinator with dynamic intervals per entity type
  • Smart contiguous block polling groups adjacent registers into single Modbus requests where possible, with automatic fallback to per-entity reads on failure
  • Configurable scan intervals via the integration options UI
  • Dependency entities are always polled, even if the related entity is disabled
  • Fully asynchronous operation for optimal performance and responsiveness
  • Sensors for voltage, current, SOC, power, energy, and fault/alarm status (combined bits)
  • Diagnostic entities for communication health, firmware version, BLE MAC address and communication-module firmware
  • Switches for force charge/discharge control
  • Adjustable charge/discharge power (model-dependent, up to 2500W)
  • Entities grouped under a device in Home Assistant
  • Select entity support for multi-state control (e.g., force mode)
  • Select entity for control modes (e.g., force mode, grid standard)
  • Backup mode control and charge/discharge to SOC included
  • Includes calculated sensors: round-trip efficiency (total/monthly) and stored energy
  • Includes cycle sensors: native cycle counter (where available) and calculated cycle count (discharged_energy / capacity)
  • Reset button to allow manual reset of the battery management system via Home Assistant
  • Some advanced sensors are disabled by default to keep the UI clean
  • UI-based configuration (Config Flow)
  • Fully local, no cloud required

🚀 Installation

  1. Add this repository to HACS Integrations → Custom repositories Add repository to HACS
  2. Install the “Marstek Venus Modbus” integration
  3. Restart Home Assistant
  4. Add the integration via Settings → Devices & Services Open your Home Assistant instance and show the integration
  5. Enter the connection details:
    • IP address of your Modbus TCP gateway
    • Port (default: 502)
    • Unit ID / Slave ID (default: 1, valid range: 1-255)
  • Device version (A, D, E v1/v2 or E v3)

⚙️ Configuration

Polling Intervals

The integration uses intelligent polling with configurable intervals per entity type to balance responsiveness and network load.

Recent versions use two polling classes instead of four. The coordinator still respects per-entity priorities, but the user-facing options are simplified to the intervals that matter most.

Configurable via Options UI:

  • High priority (default: 10 seconds) - Fast-changing sensors such as power, voltage, current, SOC and state entities
  • Low priority (default: 60 seconds) - Slower-changing sensors such as totals, diagnostics, firmware and device information

Notes:

  • The coordinator will combine adjacent due registers into a single block read when possible.
  • If a block read fails, the integration falls back to individual reads for the affected entities.
  • Disabled entities are normally skipped, except when they are required as dependencies for calculated sensors.

✅ Tested Devices for Modbus TCP

The Marstek Venus Modbus integration has been tested with the following hardware:

  • Elfin EW11 WiFi to RS485 Converter
  • PUSR DR134 Modbus Gateway
  • Waveshare RS485 to RJ45 Ethernet Converter
  • M5Stack RS485 + Atom S3 Lite #25
  • A/D/E-v3 with ethernet cable (no adapter required) #46 #106

⚠️ Known Issues / Bugs

  • User Work Mode (AI Optimized) not reflected correctly
    Setting User Work Mode to 2 (Trade Mode) in Home Assistant may not correctly show the updated state.
    The Marstek app shows the correct mode, but Home Assistant may continue to display the previous state due to a discrepancy in the Modbus register response.
    This is a known issue with the current Modbus firmware and integration handling.

📘 Modbus Registers Used

Register definitions live in custom_components/marstek_modbus/registers/.

Below is a per-key table showing descriptive fields and the register defined in each YAML file. Columns Type, Bytes, Scale and Unit are taken from the YAML definitions when present.

Key / NameDescriptionTypeBytesScaleUnitade_v12e_v3
device_nameDevice name (string)char20--31000310003100031000
sn_codeDevice serial / SN codechar20--31200
software_versionDevice software versionuint1620.01-31100
bms_versionBMS firmware versionuint162--30204302043110230204
vms_versionVMS firmware versionuint162--302023020230202
ems_versionEMS firmware version (special formatting)uint1621-30200302003110130200
firmware_versionCombined firmware version stringcalculated---
ble_mac_addressBLE MAC addressmac12--30304303043040230304
comm_module_firmwareCommunication module firmwarechar12--30350303503080030350
wifi_signal_strengthWiFi RSSIuint162-1dBm30303303033030330303
bluetooth_statusBluetooth connectivity/statusuint162--30301303013030130301
wifi_status (binary)WiFi connected (0/1)uint1621-30300303003030030300
cloud_status (binary)Cloud connected (0/1)uint1621-30302303023030230302
battery_socState of chargeuint1620.1/1%34002340023210434002
battery_total_energyTotal stored energyuint1620.001kWh32105321053210532105
battery_voltageBattery voltageuint1620.01V30100301003210030100
battery_currentBattery currentint1620.1/0.01A30101301013210130101
battery_powerBattery powerint16/322/41W30001300013210230001
total_charging_energyTotal charging energyuint3240.01kWh33000330003300033000
total_discharging_energyTotal discharging energyint3240.01kWh33002330023300233002
total_daily_charging_energyTotal daily charging energyuint3240.01kWh33004330043300433004
total_daily_discharging_energyTotal daily discharging energyint3240.01kWh33006330063300633006
total_monthly_charging_energyTotal monthly charging energyuint3240.01kWh33008330083300833008
total_monthly_discharging_energyTotal monthly discharging energyint3240.01kWh33010330103301033010
battery_cycle_countNative cycle counteruint1621-340033400334003
ac_voltageAC voltageuint1620.1V32200322003220032200
ac_currentAC currentint1620.004/0.01A37004370043220137004
ac_powerAC powerint16/322/41W30006300063220230006
ac_frequencyAC frequencyint1620.1/0.01Hz32204322043220432204
ac_offgrid_voltageAC offgrid voltageuint1620.1V32300323003230032300
ac_offgrid_currentAC offgrid currentuint1620.01A32301323013230132301
ac_offgrid_powerAC offgrid powerint3241W32302323023230232302
internal_temperatureInternal device temperatureint1620.1°C35000350003500035000
internal_mos1_temperatureMOS1 internal temperatureint1620.1°C35001350013500135001
internal_mos2_temperatureMOS2 internal temperatureint1620.1°C35002350023500235002
max_cell_temperatureMax cell temperatureint1620.1/1°C35010350103501035010
max_cell_voltageMax cell voltageuint1620.001V37007370073700737007
min_cell_voltageMin cell voltageuint1620.001V37008370083700837008
battery_1_cell_1_voltageBattery pack 1 cell 1 voltageint1620.001V340183401834018
battery_1_cell_2_voltageBattery pack 1 cell 2 voltageint1620.001V340193401934019
battery_1_cell_3_voltageBattery pack 1 cell 3 voltageint1620.001V340203402034020
battery_1_cell_4_voltageBattery pack 1 cell 4 voltageint1620.001V340213402134021
battery_1_cell_5_voltageBattery pack 1 cell 5 voltageint1620.001V340223402234022
battery_1_cell_6_voltageBattery pack 1 cell 6 voltageint1620.001V340233402334023
battery_1_cell_7_voltageBattery pack 1 cell 7 voltageint1620.001V340243402434024
battery_1_cell_8_voltageBattery pack 1 cell 8 voltageint1620.001V340253402534025
battery_1_cell_9_voltageBattery pack 1 cell 9 voltageint1620.001V340263402634026
battery_1_cell_10_voltageBattery pack 1 cell 10 voltageint1620.001V340273402734027
battery_1_cell_11_voltageBattery pack 1 cell 11 voltageint1620.001V340283402834028
battery_1_cell_12_voltageBattery pack 1 cell 12 voltageint1620.001V340293402934029
battery_1_cell_13_voltageBattery pack 1 cell 13 voltageint1620.001V340303403034030
battery_1_cell_14_voltageBattery pack 1 cell 14 voltageint1620.001V3403134031
battery_1_cell_15_voltageBattery pack 1 cell 15 voltageint1620.001V3403234032
battery_1_cell_16_voltageBattery pack 1 cell 16 voltageint1620.001V3403334033
battery_2_cell_1_voltageBattery pack 2 cell 1 voltageint1620.001V34031
battery_2_cell_2_voltageBattery pack 2 cell 2 voltageint1620.001V34032
battery_2_cell_3_voltageBattery pack 2 cell 3 voltageint1620.001V34033
battery_2_cell_4_voltageBattery pack 2 cell 4 voltageint1620.001V34034
battery_2_cell_5_voltageBattery pack 2 cell 5 voltageint1620.001V34035
battery_2_cell_6_voltageBattery pack 2 cell 6 voltageint1620.001V34036
battery_2_cell_7_voltageBattery pack 2 cell 7 voltageint1620.001V34037
battery_2_cell_8_voltageBattery pack 2 cell 8 voltageint1620.001V34038
battery_2_cell_9_voltageBattery pack 2 cell 9 voltageint1620.001V34039
battery_2_cell_10_voltageBattery pack 2 cell 10 voltageint1620.001V34040
battery_2_cell_11_voltageBattery pack 2 cell 11 voltageint1620.001V34041
battery_2_cell_12_voltageBattery pack 2 cell 12 voltageint1620.001V34042
battery_2_cell_13_voltageBattery pack 2 cell 13 voltageint1620.001V34043
battery_3_cell_1_voltageBattery pack 3 cell 1 voltageint1620.001V34044
battery_3_cell_2_voltageBattery pack 3 cell 2 voltageint1620.001V34045
battery_3_cell_3_voltageBattery pack 3 cell 3 voltageint1620.001V34046
battery_3_cell_4_voltageBattery pack 3 cell 4 voltageint1620.001V34047
battery_3_cell_5_voltageBattery pack 3 cell 5 voltageint1620.001V34048
battery_3_cell_6_voltageBattery pack 3 cell 6 voltageint1620.001V34049
battery_3_cell_7_voltageBattery pack 3 cell 7 voltageint1620.001V34050
battery_3_cell_8_voltageBattery pack 3 cell 8 voltageint1620.001V34051
battery_3_cell_9_voltageBattery pack 3 cell 9 voltageint1620.001V34052
battery_3_cell_10_voltageBattery pack 3 cell 10 voltageint1620.001V34053
battery_3_cell_11_voltageBattery pack 3 cell 11 voltageint1620.001V34054
battery_3_cell_12_voltageBattery pack 3 cell 12 voltageint1620.001V34055
battery_3_cell_13_voltageBattery pack 3 cell 13 voltageint1620.001V34056
battery_4_cell_1_voltageBattery pack 4 cell 1 voltageint1620.001V34057
battery_4_cell_2_voltageBattery pack 4 cell 2 voltageint1620.001V34058
battery_4_cell_3_voltageBattery pack 4 cell 3 voltageint1620.001V34059
battery_4_cell_4_voltageBattery pack 4 cell 4 voltageint1620.001V34060
battery_4_cell_5_voltageBattery pack 4 cell 5 voltageint1620.001V34061
battery_4_cell_6_voltageBattery pack 4 cell 6 voltageint1620.001V34062
battery_4_cell_7_voltageBattery pack 4 cell 7 voltageint1620.001V34063
battery_4_cell_8_voltageBattery pack 4 cell 8 voltageint1620.001V34064
battery_4_cell_9_voltageBattery pack 4 cell 9 voltageint1620.001V34065
battery_4_cell_10_voltageBattery pack 4 cell 10 voltageint1620.001V34066
battery_4_cell_11_voltageBattery pack 4 cell 11 voltageint1620.001V34067
battery_4_cell_12_voltageBattery pack 4 cell 12 voltageint1620.001V34068
battery_4_cell_13_voltageBattery pack 4 cell 13 voltageint1620.001V34069
battery_5_cell_1_voltageBattery pack 5 cell 1 voltageint1620.001V34070
battery_5_cell_2_voltageBattery pack 5 cell 2 voltageint1620.001V34071
battery_5_cell_3_voltageBattery pack 5 cell 3 voltageint1620.001V34072
battery_5_cell_4_voltageBattery pack 5 cell 4 voltageint1620.001V34073
battery_5_cell_5_voltageBattery pack 5 cell 5 voltageint1620.001V34074
battery_5_cell_6_voltageBattery pack 5 cell 6 voltageint1620.001V34075
battery_5_cell_7_voltageBattery pack 5 cell 7 voltageint1620.001V34076
battery_5_cell_8_voltageBattery pack 5 cell 8 voltageint1620.001V34077
battery_5_cell_9_voltageBattery pack 5 cell 9 voltageint1620.001V34078
battery_5_cell_10_voltageBattery pack 5 cell 10 voltageint1620.001V34079
battery_5_cell_11_voltageBattery pack 5 cell 11 voltageint1620.001V34080
battery_5_cell_12_voltageBattery pack 5 cell 12 voltageint1620.001V34081
battery_5_cell_13_voltageBattery pack 5 cell 13 voltageint1620.001V34082
battery_6_cell_1_voltageBattery pack 6 cell 1 voltageint1620.001V34083
battery_6_cell_2_voltageBattery pack 6 cell 2 voltageint1620.001V34084
battery_6_cell_3_voltageBattery pack 6 cell 3 voltageint1620.001V34085
battery_6_cell_4_voltageBattery pack 6 cell 4 voltageint1620.001V34086
battery_6_cell_5_voltageBattery pack 6 cell 5 voltageint1620.001V34087
battery_6_cell_6_voltageBattery pack 6 cell 6 voltageint1620.001V34088
battery_6_cell_7_voltageBattery pack 6 cell 7 voltageint1620.001V34089
battery_6_cell_8_voltageBattery pack 6 cell 8 voltageint1620.001V34090
battery_6_cell_9_voltageBattery pack 6 cell 9 voltageint1620.001V34091
battery_6_cell_10_voltageBattery pack 6 cell 10 voltageint1620.001V34092
battery_6_cell_11_voltageBattery pack 6 cell 11 voltageint1620.001V34093
battery_6_cell_12_voltageBattery pack 6 cell 12 voltageint1620.001V34094
battery_6_cell_13_voltageBattery pack 6 cell 13 voltageint1620.001V34095
mppt1_voltageMPPT1 array voltageuint1620.1V3002030020
mppt1_currentMPPT1 array currentuint1620.1A3002430024
mppt1_powerMPPT1 array poweruint1620.1W3003730037
mppt2_voltageMPPT2 array voltageuint1620.1V3002130021
mppt2_currentMPPT2 array currentuint1620.1A3002530025
mppt2_powerMPPT2 array poweruint1620.1W3003830038
mppt3_voltageMPPT3 array voltageuint1620.1V3002230022
mppt3_currentMPPT3 array currentuint1620.1A3002630026
mppt3_powerMPPT3 array poweruint1620.1W3003930039
mppt4_voltageMPPT4 array voltageuint1620.1V3002330023
mppt4_currentMPPT4 array currentuint1620.1A3002730027
mppt4_powerMPPT4 array poweruint1620.1W3004030040
inverter_stateInverter / device stateuint1621-35100351003510035100
fault_statusFault status bitsuint648--36100
alarm_statusAlarm status bitsuint324--36000
modbus_addressModbus slave/unit iduint162--41100411004110041100
rs485_control_mode (switch)RS485 control mode (write commands)uint162--42000420004200042000
backup_function (switch)Backup function controluint162--41200412004120041200
force_mode (select)Force mode (None/Charge/Discharge)uint162--42010420104201042010
user_work_mode (select)User Work Mode (manual/anti_feed/trade)uint162--43000430004300043000
discharge_limit_mode (binary)Discharge limit mode (diagnostic)uint162--41010
modbus_connection (binary)Modbus connection healthderived---
grid_standard (select)Grid standard / region selectionuint162--44100
charge_to_soc (number)Charge/discharge to SOC (0-100%)uint1621%42011420114201142011
set_charge_power (number)Forcible charge power setpointuint162-W42020420204202042020
set_discharge_power (number)Forcible discharge power setpointuint162-W42021420214202142021
max_charge_power (number)Max allowed charge poweruint162-W44002440024400244002
max_discharge_power (number)Max allowed discharge poweruint162-W44003440034400344003
charging_cutoff_capacity (number)Charging cutoff (percentage)uint1620.1%44000
discharging_cutoff_capacityDischarging cutoff (percentage)uint1620.1%44001
reset_device (button)Reset device commanduint162--41000410004100041000
factory_reset (button)Factory reset commanduint162--41001410014100141001
schedule_1_daysSchedule 1 days (bitmask)bit2--43100431004310043100
schedule_1_startSchedule 1 start (HHMM)uint2-min43101431014310143101
schedule_1_endSchedule 1 end (HHMM)uint2-min43102431024310243102
schedule_1_modeSchedule 1 mode (numeric)int162-W43103431034310343103
schedule_1_enabledSchedule 1 enabled (0/1)uint2--43104431044310443104
schedule_2_daysSchedule 2 days (bitmask)bit2--43105431054310543105
schedule_2_startSchedule 2 start (HHMM)uint2-min43106431064310643106
schedule_2_endSchedule 2 end (HHMM)uint2-min43107431074310743107
schedule_2_modeSchedule 2 mode (numeric)int162-W43108431084310843108
schedule_2_enabledSchedule 2 enabled (0/1)uint2--43109431094310943109
schedule_3_daysSchedule 3 days (bitmask)bit2--43110431104311043110
schedule_3_startSchedule 3 start (HHMM)uint2-min43111431114311143111
schedule_3_endSchedule 3 end (HHMM)uint2-min43112431124311243112
schedule_3_modeSchedule 3 mode (numeric)int162-W43113431134311343113
schedule_3_enabledSchedule 3 enabled (0/1)uint2--43114431144311443114
schedule_4_daysSchedule 4 days (bitmask)bit2--43115431154311543115
schedule_4_startSchedule 4 start (HHMM)uint2-min43116431164311643116
schedule_4_endSchedule 4 end (HHMM)uint2-min43117431174311743117
schedule_4_modeSchedule 4 mode (numeric)int162-W43118431184311843118
schedule_4_enabledSchedule 4 enabled (0/1)uint2--43119431194311943119
schedule_5_daysSchedule 5 days (bitmask)bit2--43120431204312043120
schedule_5_startSchedule 5 start (HHMM)uint2-min43121431214312143121
schedule_5_endSchedule 5 end (HHMM)uint2-min43122431224312243122
schedule_5_modeSchedule 5 mode (numeric)int162-W43123431234312343123
schedule_5_enabledSchedule 5 enabled (0/1)uint2--43124431244312443124
schedule_6_daysSchedule 6 days (bitmask)bit2--43125431254312543125
schedule_6_startSchedule 6 start (HHMM)uint2-min43126431264312643126
schedule_6_endSchedule 6 end (HHMM)uint2-min43127431274312743127
schedule_6_modeSchedule 6 mode (numeric)int162-W43128431284312843128
schedule_6_enabledSchedule 6 enabled (0/1)uint2--43129431294312943129
round_trip_efficiency_totalRound-trip efficiency (total charge/discharge energies)calculated--%
round_trip_efficiency_monthlyRound-trip efficiency (monthly charge/discharge)calculated--%
conversion_efficiencyConversion efficiency (battery ↔ AC)calculated--%
stored_energyStored battery energy (SOC × capacity)calculated--kWh
battery_cycle_count_calcCycle count calculated from total discharge and capacitycalculated---

Notes:

  • Columns a, d, e_v12 and e_v3 correspond to the YAML files under custom_components/marstek_modbus/registers/.
  • Bytes shows the typical byte size for the key (each Modbus register = 2 bytes).
  • Blank cells mean that YAML does not define that key (or the value is calculated and has no direct Modbus register).
  • firmware_version is assembled from the raw version registers. E v1/v2 uses ems + bms; A, D and E v3 use ems + vms + bms.
  • ble_mac_address is decoded and formatted as a normal MAC address string such as 00:9B:08:05:D9:0A.
  • modbus_connection is a diagnostic binary sensor derived from recent successful Modbus reads, not from a separate device register.
  • The rs485_control_mode switch (register 42000) uses write commands (command_on=21930, command_off=21947) to trigger RS485 control operations; use with caution.
  • For access to registers in the 42000–42999 range, the battery must be set to RS485 control mode.
  • Schedule Time format: start and end are entered as HHMM 24-hour integers (for example 0830 = 08:30). Use values within the valid range shown in the YAML for each device; ensure start is earlier than end for a single active period.
  • Schedule Day selection: the underlying schedule_*_days register uses a bitmask to represent multiple days, but the integration currently exposes it as a single-select option in Home Assistant. Due to this limitation you cannot select multiple days from the integration UI.
  • Energy Dashboard caveat (Venus A / Venus D with PV input): reported battery charge/discharge energy registers may include energy that flows to household loads via the inverter path, not only net battery-in/out energy. This can lead to misleading Home Assistant Energy Dashboard battery statistics. For accurate dashboard usage, prefer custom derived sensors (for example from power integration) and validate behavior on your firmware/device.
  • Schedule Mode values: schedule_*_mode accepts the following ranges:
    • -1 = Self consumption mode
    • Charge/discharge range is model-dependent.
    • Venus A (fw v148+): -100 to -1500 (charge), 100 to 1500 (discharge)
    • Venus D / Venus E: -100 to -2500 (charge), 100 to 2500 (discharge)