Skip to content

Entities ​

This page lists every sensor and control the integration can create, with its name, unit and whether it starts on or off. Use it to find the right sensor for a dashboard card or an automation, or to check why a sensor is missing on your battery.

An entity is one sensor or control in Home Assistant, such as Battery level or Operating mode. Names below match the English names Home Assistant shows. The Key column is the internal name; you mostly need it when you read other pages or report a problem.

Not every battery gets every entity. Solar inputs, UPS mode and the depth of discharge, Bluetooth and LED controls are only created when your model and firmware support them. A missing entity is left off the device page instead of showing as unavailable forever. If a firmware update adds or removes one of these features, the integration reloads the battery by itself and the list updates. See Firmware updates.

NOTE

Some entities are Diagnostic and disabled by default. To turn one on, open it from the device page, select the gear icon, switch on Enabled, and select Update.

Battery detail sensors start disabled

Reading battery details is suspected to make some Marstek firmware restart by itself (issue #14). The five entities that need that reading are therefore disabled by default on new installations: Battery temperature, Battery remaining capacity, Battery rated capacity, Charge permission and Discharge permission. The integration only asks the battery for these details while at least one of them is enabled. On firmware 150 or newer, enabling any of them starts those requests again.

Firmware that can reset the Open API (Venus A, D, E 3.0 or Venus E mini below 150, Venus C or Venus E 2.0 below 156, or an unknown firmware number): those five entities are not created at all, even if you enabled them before, and the battery is never asked for these details. See Repairs. After a firmware update to 150 or newer, they come back (still disabled by default).

Upgrading an existing install on firmware 150 or newer? Entities that were already registered stay enabled; upgrades never disable entities on firmware that can safely use them. To stop the battery detail requests, disable the five entities above once by hand (device page → entity → ⚙️ → Enabled off).

Technical details

All entities are coordinator-backed (no per-entity polling): one shared update per battery feeds every entity.

Capability-gated entities (PV channels, UPS, SYS DOD/BLE/LED) are created only when the firmware profile supports them. After a firmware update that unlocks or removes those capabilities, setup, the scanner, or Reconfigure refreshes ver (unicast Marstek.GetDevice if broadcast cannot reach the device) and reloads the config entry so the entity set matches the new profile.

Meter input/output energy sensors are created when EM.GetStatus (or the Rev 3.1 ES.GetMode fallback) actually reports those fields. Control generation 148 and newer scales the wire unit 0.1 Wh → Wh when the device serves EM.GetStatus; older profiles leave a present value unscaled. SYS and UPS stay gated at generation 150.

The battery detail entities depend on the Bat.GetStatus call: Battery temperature (bat_temp), Battery remaining capacity (bat_capacity), Battery rated capacity (bat_rated_capacity), Charge permission (bat_charg_flag) and Discharge permission (bat_dischrg_flag). Enabling any of them resumes the call automatically on Control firmware 150+. On reset-prone firmware, Bat.GetStatus is never sent, and after a firmware update to 150+ setup or the scanner reloads the config entry so the entities can be created again.

Sensors ​

These are the main readings. Power is in watts (W), energy in watt-hours (Wh). Total power and the Phase A/B/C power sensors come from the Marstek CT meter at your fuse box, so they show your house's grid power, not the battery's. Despite their names, Total grid input energy and Total grid output energy count energy into and out of the battery itself; Energy dashboard explains where each one belongs.

Entity nameKeyUnitCategoryDefault
Battery levelbattery_soc%—Enabled
Battery powerbattery_powerW—Enabled
On-grid powerongrid_powerW—Enabled (if supported)
Off-grid poweroffgrid_powerW—Enabled (if supported). Optional clamp to 0 W for negative readings: see Options.
PV powerpv_powerW—Enabled (if supported)
Device modedevice_mode——Enabled
Battery statusbattery_status——Enabled
Total powerem_total_powerW—Enabled (not on Venus C below 155)
Phase A powerem_a_powerW—Enabled (not on Venus C below 155)
Phase B powerem_b_powerW—Enabled (not on Venus C below 155)
Phase C powerem_c_powerW—Enabled (not on Venus C below 155)
Meter input energyem_input_energyWh—Enabled (if reported)
Meter output energyem_output_energyWh—Enabled (if reported)
Total solar energytotal_pv_energyWh—Enabled (Venus A and D only)
Total grid output energytotal_grid_output_energyWh—Enabled
Total grid input energytotal_grid_input_energyWh—Enabled
Total load energytotal_load_energyWh—Enabled
Battery total capacitybat_capWh—Enabled (if reported; not created on Venus E mini, whose firmware reports remaining energy there)
Usable capacitybattery_usable_capacityWh—Enabled. Unknown until enough clean measurements exist; see Usable capacity.
Battery state of healthbattery_state_of_health%—Enabled (when the rated capacity is known)

Restarts ​

Entity nameKeyUnitCategoryDefault
Restartsdevice_restarts—DiagnosticEnabled

Counts how often the battery restarted. A battery that restarts often may have a firmware or Wi-Fi problem. Short network dropouts and brief network resets are listed on the card but not counted as restarts. See Restarts and dropouts for how the integration tells them apart.

Technical details

The Open API has no uptime field, so a restart is read from what a boot leaves in the polls the integration already makes; no request is added. A restart is told apart from Wi-Fi that answers late, a network dropout, or a brief network reset (listed, not counted). Attributes: restarts_30d, dropouts_30d, network_resets_30d, last_restart_at, tracked_since (when the log started), and outages (every outage of the last 30 days, for the card's Restarts tab; kept out of the recorder).

PV channel sensors (PV1 to PV4) ​

These show each solar panel input separately. They are created on every Venus A and Venus D, for all four channels, even if a channel has no panel. Other models don't get them. Power values are in watts. PV state is 1 while that input is producing power and 0 when it is not. It follows that channel's power; the battery does not send a separate status.

Technical details

Channel 1 is deciwatts (tenths of a watt) on observed firmware (including 148.3, 149, and 150.9); the parser divides by 10, matching 1.0.0. That PV1 scale is independent of the solar-energy ×10 used for #35. Do not skip the ÷10 (#57).

Entity nameKeyUnitCategoryDefault
PV1 powerpv1_powerW—Enabled (if supported)
PV1 voltagepv1_voltageV—Enabled (if supported)
PV1 currentpv1_currentA—Enabled (if supported)
PV1 statepv1_state——Enabled (if supported)
PV2 powerpv2_powerW—Enabled (if supported)
PV2 voltagepv2_voltageV—Enabled (if supported)
PV2 currentpv2_currentA—Enabled (if supported)
PV2 statepv2_state——Enabled (if supported)
PV3 powerpv3_powerW—Enabled (if supported)
PV3 voltagepv3_voltageV—Enabled (if supported)
PV3 currentpv3_currentA—Enabled (if supported)
PV3 statepv3_state——Enabled (if supported)
PV4 powerpv4_powerW—Enabled (if supported)
PV4 voltagepv4_voltageV—Enabled (if supported)
PV4 currentpv4_currentA—Enabled (if supported)
PV4 statepv4_state——Enabled (if supported)

Diagnostic sensors (disabled by default) ​

These help when you troubleshoot: Wi-Fi signal and network details, battery temperature and capacity, and how often the battery answers the integration's requests (API success rate). They start disabled. Enable the ones you need as described at the top of this page. The battery temperature and capacity sensors have extra conditions; see the warning at the top.

Entity nameKeyUnitCategoryDefault
WiFi signal strengthwifi_rssidBmDiagnosticDisabled
Wi‑Fi IP addresswifi_sta_ip—DiagnosticDisabled
Wi‑Fi gatewaywifi_sta_gate—DiagnosticDisabled
Wi‑Fi subnet maskwifi_sta_mask—DiagnosticDisabled
Wi‑Fi DNSwifi_sta_dns—DiagnosticDisabled
Battery temperaturebat_temp°CDiagnosticDisabled
Battery remaining capacitybat_capacityWhDiagnosticDisabled
Battery rated capacitybat_rated_capacityWhDiagnosticDisabled
Device IPdevice_ip—DiagnosticDisabled
Device versiondevice_version—DiagnosticDisabled
Wi‑Fi namewifi_name—DiagnosticDisabled
BLE MACble_mac—DiagnosticDisabled
Wi‑Fi MACwifi_mac—DiagnosticDisabled
MAC addressmac—DiagnosticDisabled
API success rate (overall, and one per request type: ES.GetMode, ES.GetStatus, EM.GetStatus, PV.GetStatus, Wifi.GetStatus, Bat.GetStatus, ES.SetMode)api_success_rate_*%DiagnosticDisabled

The percentage is what history keeps. The attempt, timeout, and latency counters shown on the sensor change on every poll, so they are left out of the recorder.

Battery low and charging ​

These two sensors are what Home Assistant's battery automations look for. Battery level (battery_soc, device class battery, unit %) is the target for Battery level, Battery level changed, and Battery level crossed threshold. There is one device per config entry, so there is no separate aggregate sensor.

Entity nameKeyDevice classOn meansDefault
Battery lowbattery_lowbatteryState of charge is at or under the low levelEnabled
Chargingbattery_chargingbattery_chargingBattery power is charging past the idle bandEnabled

Battery low is unavailable while the state of charge is unknown. The trip level follows the discharge cutoff when the device has one: depth of discharge is how far below 100% the pack may go, so a depth of discharge of 88 (the device default) stops discharge at 12%, and Battery low turns on at 17%. Devices without that setting use 15%. Either way it stays on until the level rises another 5 percentage points, so a reading that jitters around the line does not flap. Turn Follow the discharge cutoff off under Options to set a fixed level from 5% to 80%.

Charging uses battery power. Positive power is discharging and negative power is charging. It turns on at −50 W or below, so idle noise around 0 W stays off, and it is unavailable while power is unknown.

YAML for these sensors is in Automations and services. The same entities drive a Lock Screen progress bar in Lock Screen and Dynamic Island.

Binary sensors (diagnostic, disabled by default) ​

A binary sensor is on or off. CT connection shows whether the battery is connected to its CT meter. Charge permission and Discharge permission show whether the battery currently reports that it is allowed to charge or discharge; they belong to the battery detail group in the warning at the top of this page.

Entity nameKeyDevice classDefault
CT connectionct_connectionconnectivityDisabled
Charge permissionbat_charg_flag—Disabled
Discharge permissionbat_dischrg_flag—Disabled

Select ​

Operating mode shows the battery's current mode and lets you change it from a dashboard or automation. The glossary explains each mode.

Entity nameKeyOptions
Operating modeoperating_modeAuto, AI, Manual, Passive. UPS is added only when your model and firmware support it (see below).
AvailabilityUPS on the select
Venus A, D, E 3.0 and Venus E mini with firmware 150 or newerYes
Venus C and Venus E 2.0 (HMG-50), any firmwareNo. Firmware 158 accepts a UPS command and ES.GetMode then reports Manual, so the option is left out.
Venus E mini with a known firmware number below 150No (the depth of discharge, Bluetooth and LED controls still appear; UPS does not)
Unknown firmware numberNo

You can pick Auto, AI, and UPS (when listed) directly. Manual and Passive need extra settings, such as a power and a time, so you set them with an action instead (see Automations and services). Venus E mini firmware 301 has no Passive mode, so it is left out of the select and the Set passive mode action refuses it. Set.Ver and factory reset are not operating modes and are not offered here.

Number (configuration) ​

Depth of discharge sets how far the battery may discharge before it stops (DoD). A lower value keeps more charge in reserve.

This control, and the two switches below, only appear on supported firmware. Venus A, D and E 3.0 need firmware 150 or newer. Venus C and Venus E 2.0 (HMG-50) need firmware 158 or newer. Venus E mini needs a known firmware number (no 150 minimum). If the firmware number is unknown, these controls are left out.

Entity nameKeyUnitRangeCategoryDefault
Depth of dischargedepth_of_discharge%30–88, step 1ConfigEnabled (if supported). Shows 88 until a value this Home Assistant has written is restored.

The battery can't report its current depth of discharge back to Home Assistant. 88 is the firmware default, shown only before this Home Assistant has a saved write. After a write the battery accepts, a reload or a restart restores that value (RestoreNumber). A change made in the Marstek app or with another tool is not visible here. The control is marked assumed, because the number was not read from the battery.

Switch (configuration) ​

Same firmware and model availability as depth of discharge. The battery can't report these settings back. Until you set a switch once, it shows unknown with an assumed state. Inventing on or off would hide that the battery was never asked. After a write the battery accepts, a reload or a restart restores that on or off state (RestoreEntity).

Entity nameKeyCategoryNotes
Bluetooth advertisingbluetooth_advertisingConfigOn enables advertising; off disables it.
Panel LEDpanel_ledConfigOn turns the panel LED on; off turns it off.

The integration deliberately offers no control for a factory reset or for changing the firmware version (Reset.Factory and Set.Ver in the Open API).

Device grouping ​

Each battery's entities are grouped under one device. They keep their identity when the battery gets a new IP address, so history and automations keep working.

Meter input energy and Meter output energy are only created when your battery reports them. You can use them on the Energy dashboard.

Technical details

Meter input/output energy sensors are created only when EM.GetStatus (or Rev 3.1 ES.GetMode fallback) reports those lifetime totals. They use the same BLE-MAC unique ID pattern as other sensors and are suitable for the Energy Dashboard (device_class: energy, state_class: total_increasing, native unit Wh).

Venus A device page in Home Assistant with battery, grid, and four solar input sensors.