Home Assistant entities¶
This reference lists the entity families Omnibattery can create. Your installation shows only the entities supported by its battery driver and the features you configured.
Find the entity you need¶
- Start with the everyday table.
- Search the complete catalogue for the visible name or key.
- Read When it appears before using an entity in an automation.
Home Assistant may preserve an older entity ID or add a suffix. Fresh system entities use omnibattery_; upgraded installations can retain marstek_venus_system_ so history and automations keep working. Use the entity picker or entity registry instead of assuming an exact ID.
Everyday entities¶
| Visible name | Typical fresh-install pattern | Use |
|---|---|---|
| System SOC | sensor.omnibattery_system_soc |
Combined state of charge (SOC) of the batteries under automatic control (all of them if every battery is in manual mode) |
| System Charge Power | sensor.omnibattery_system_charge_power |
Total charging power |
| System Discharge Power | sensor.omnibattery_system_discharge_power |
Total discharging power |
| Home Consumption | sensor.omnibattery_home_consumption |
Current household demand |
| Integration Status | sensor.omnibattery_integration_status |
Current control mode and blockers |
| PD Control Quality | sensor.omnibattery_system_pd_control_quality |
Grid-tracking quality |
| Active Batteries | sensor.omnibattery_active_batteries |
Batteries currently participating |
| Non-Responsive Batteries | sensor.omnibattery_non_responsive_batteries |
Batteries temporarily removed from control |
| Predictive Charging Active | binary_sensor.omnibattery_predictive_charging_active |
Predictive plan and charging state |
| Allow Charge / Allow Discharge | switch.*_battery_allow_charge, switch.*_battery_allow_discharge |
Per-battery participation |
| Manual Battery Control | switch.*_battery_manual_mode |
Manual ownership of one battery |
Positive battery power means charging and negative battery power means discharging. System Charge Power and System Discharge Power are separate unsigned values.
How IDs are formed¶
Per-battery entities normally use <domain>.<battery-name>_<key>, shown below as <domain>.*_<key>. System entities use <domain>.omnibattery_<key> on fresh installs. Existing registry entries keep their current IDs, including translated IDs and the legacy marstek_venus_system_ prefix.
System device¶
These entities belong to Omnibattery System rather than one battery.
Power, energy, and learning sensors
| Keys | When they appear |
|---|---|
system_soc, system_charge_power, system_discharge_power, system_battery_cell_power, system_total_energy, system_stored_energy |
Core system measurements |
home_consumption, system_daily_home_energy, system_daily_grid_import_energy, system_daily_grid_export_energy, system_daily_grid_at_min_soc_energy |
Grid meter and controller available |
system_daily_charging_energy, system_daily_discharging_energy |
Core aggregate energy |
system_solar_power, system_daily_solar_energy |
Supported battery solar telemetry or configured solar source, as applicable |
expected_home_consumption_profile, consumption_profile_capture |
Consumption learning available |
balance_neto |
Hourly net balance configured |
Control and diagnostic sensors
| Keys | When they appear |
|---|---|
integration_status, active_batteries, non_responsive_batteries, discharge_window, three_phase_protection_status, system_pd_control_quality, daily_operation_timeline |
Controller available |
predictive_charging_active |
Predictive charging has been configured |
curtailment_status, surplus_price_hold_status, discharge_reserve_status, high_price_discharge_status |
Relevant Dynamic Pricing feature available |
capacity_protection_active |
Capacity protection configured |
weekly_full_charge |
Weekly full charge enabled |
charge_delay_status |
Charge delay configured |
system_alarm_status |
At least one battery exposes alarm registers |
System numbers
Feature controls appear only when that feature or pricing mode is configured.
- PD control:
pd_controller_kp,pd_controller_kd,pd_controller_deadband,pd_controller_max_power_change,pd_controller_direction_hysteresis,pd_min_charge_power,pd_min_discharge_power,pd_relay_cooldown,pd_min_cycle_interval,pd_target_grid_power,no_pd_command_delay - Fleet limits:
system_max_charge_power,system_max_discharge_power,max_contracted_power - Capacity protection:
capacity_protection_limit,capacity_protection_soc_threshold - Charge delay:
delay_safety_margin_min,charge_delay_balance_deadband_kwh,delay_soc_setpoint - Temperature:
temp_charge_limit_c,temp_charge_limit_band_c,temp_charge_limit_floor_pct - Predictive charging:
predictive_safety_margin_kwh,predictive_min_soc_floor - Dynamic Pricing:
max_price_threshold,discharge_price_threshold,min_arbitrage_margin,round_trip_efficiency,negative_injection_threshold,predischarge_reserve_soc,surplus_hold_min_saving,discharge_reserve_min_saving - Hourly net balance:
hourly_balance_target_net_wh,hourly_balance_max_offset_w,hourly_balance_deadband_wh,hourly_balance_hysteresis_w - Excluded load:
excluded_device_exclusion_pct, one per compatible configured device
System switches
- Always available controller choices:
manual_mode,no_pd_mode,three_phase_protection,weekly_full_charge_enabled,vacation_mode - Conditional features:
offgrid_mode,primary_feedforward,system_power_limits,predictive_charging,predictive_charging_notifications,min_soc_floor_enabled,charge_delay,delay_soc_setpoint_enabled,weekly_full_charge_delay,temp_charge_limit,temp_charge_limit_discharge,capacity_protection,capacity_protection_excluded_devices,hourly_balance - Pricing controls:
price_discharge_control,smart_predischarge,negative_price_charging,surplus_price_hold,discharge_reserve - Generated controls:
time_slotfor each configured time slot;excluded_device_enabled,excluded_device_solar_surplus,excluded_device_dynamic_power_control, andexcluded_device_cover_homefor each applicable excluded device - External automation compatibility:
automation_charging_active
System selects and buttons
| Key | When it appears |
|---|---|
pd_tuning_profile |
Controller available |
weekly_full_charge_day |
Controller available |
battery_phase |
Per battery, for phase assignment |
primary_battery, charge_priority |
More than one battery configured |
high_price_sale |
Dynamic Pricing predictive mode |
reevaluate_dynamic_pricing |
Dynamic Pricing or Time Slot predictive mode |
Battery devices¶
Battery entities depend on the driver. A missing entity usually means that the driver cannot supply or safely control that field; it does not mean setup failed.
Battery state, power, and energy sensors
| Purpose | Keys |
|---|---|
| Charge and health | battery_soc, battery_soh, battery_total_energy, stored_energy, battery_runtime_estimate, battery_cycle_count, battery_cycle_count_calc |
| Power | battery_power, ac_power, battery_cell_power, grid_power, inverter_ac_power, ac_offgrid_power, max_charge_power, max_discharge_power, inverter_max_power, inverter_rated_power, output_limit, input_limit, power_restriction |
| Energy | total_charging_energy, total_discharging_energy, total_daily_charging_energy, total_daily_discharging_energy, pv_total_generation, round_trip_efficiency_total |
| Electrical state | battery_voltage, max_cell_voltage, min_cell_voltage, cell_voltage_delta, internal_temperature, internal_mos1_temperature, internal_mos2_temperature, max_cell_temperature, min_cell_temperature |
| Operating state | inverter_state, battery_status, operating_mode, user_work_mode, ac_mode, remain_discharge_time, balancing_mode, backup_function |
Daily energy can come from a native counter, a cumulative-counter delta, or power integration. The source depends on driver capabilities.
Pack and solar sensors
Pack telemetry is created only for drivers and live pack counts that expose it.
- Pack charge:
battery_soc_pack_1throughbattery_soc_pack_7 - Pack voltage extremes:
max_cell_voltage_pack_1throughmax_cell_voltage_pack_7, andmin_cell_voltage_pack_1throughmin_cell_voltage_pack_7 - Pack metadata:
pack_count,pack1_firmware_version,pack2_firmware_version,pack3_firmware_version,pack1_serial_number,pack2_serial_number,pack3_serial_number - Solar input:
solar_power,mppt1_powerthroughmppt4_power, andpv1_voltagethroughpv4_voltage
Device and connection sensors
Driver-provided diagnostics include device_name, sn_code, software_version, bms_version, ems_version, vms_version, inverter_software_version, comm_module_firmware, power_module_serial_number, power_module_firmware_version, inverter_serial_number, mac_address, wifi_signal_strength, esp_ip, esp_ssid, esp_version, esp_wifi_signal_strength, bt_status, fault_level, fault_status, and alarm_status.
Cell balance monitor sensors
When the cell balance monitor is enabled, each supported battery can expose cell_delta, balance_status, delta_trend, last_balance_read, and delta_avg_4w. See cell balance monitor.
Battery binary sensors
Connection states are wifi_status, cloud_status, and esp_wifi_status. Driver alarms can include pll_abnormal_restart, overtemperature_limit, low_temperature_limit, fan_abnormal_warning, low_battery_soc_warning, output_overcurrent_warning, abnormal_line_sequence_detection, wifi_abnormal, ble_abnormal, network_abnormal, ct_connection_abnormal, grid_overvoltage, grid_undervoltage, grid_overfrequency, grid_underfrequency, grid_peak_voltage_abnormal, current_dcover, voltage_dcover, bat_overvoltage, bat_undervoltage, bat_overcurrent, bat_low_soc, bat_communication_failure, and bms_protect.
balancing_mode and charge_hysteresis appear only when the driver or configuration supports them.
Battery numbers, switches, selects, and buttons
| Platform | Keys | Condition |
|---|---|---|
| Number | set_charge_power, set_discharge_power |
Register control or software manual control |
| Number | max_charge_power, max_discharge_power, inverse_max_power |
Supported hardware or software limit |
| Number | charging_cutoff_capacity, discharging_cutoff_capacity, charge_to_soc, soc_set, min_soc |
Hardware cutoff or software limit, depending on driver |
| Number | backup_offgrid_threshold, charge_hysteresis_percent, battery_capacity |
Relevant driver/configuration |
| Switch | battery_allow_charge, battery_allow_discharge, battery_manual_mode |
Every controlled battery |
| Switch | full_charge_voltage_taper |
Compatible cell telemetry |
| Switch | backup_function, rs485_control_mode, lamp_switch |
Driver exposes the control |
| Select | force_mode, grid_off_mode, user_work_mode |
Driver exposes the control |
| Button | reset_device |
Driver exposes the command |
Status and diagnostic attributes¶
Integration Status states and blockers
Integration Status reports the highest-priority active condition. Its states cover predictive charging, weekly full charge, charge delay, price controls, electric-vehicle pauses, cell-balance hold, capacity protection, hourly net balance, backup mode, manual time-slot control, closed charging or discharging windows, normal charging or discharging, standby, manual mode, and initialization.
| Attribute | Meaning |
|---|---|
charge_blocked, discharge_blocked |
Effective system permission |
charge_blockers, discharge_blockers |
Global reasons, details, and timestamps |
battery_charge_blockers, battery_discharge_blockers |
Reasons grouped by battery |
manual_batteries |
Batteries under manual ownership |
non_responsive_batteries |
Batteries excluded after communication or delivery failures |
balance_hold_batteries |
Batteries held by cell-balance protection |
backup_cooldown_batteries |
Batteries held after backup output activity |
ev_chargers_active, ev_pause_until |
Active charger exclusions and pauses |
hourly_balance_status, hourly_balance_offset_w, hourly_balance_net_kwh |
Net-balance controller state |
temperature_charge_limit |
Current thermal-limit decision |
Predictive Charging Active attributes
Common attributes include charging_needed, reason, price_data_status, forecast and consumption values, selected price slots, target energy, and current progress.
Dynamic Pricing can also expose chronological_planning_active, energy_horizon_end, overnight_consumption_kwh, earliest_projected_depletion, deadline_shortfall_kwh, cheaper_to_import_kwh, cheapest_rejected_slot, energy_deadlines, slot_deadlines, and chronological_plan_reason. The diagnostics also expose round_trip_efficiency_used and round_trip_efficiency_source (configured, measured or default). They describe planning intent; live battery, grid, and safety limits remain authoritative.
High-Price Sale Status attributes
These attributes appear when the corresponding Dynamic Pricing policy has a plan. See Dynamic Pricing for the decision rules.
| Attribute | Meaning |
|---|---|
trigger_1_budget_kwh |
Battery energy that High-Price Sale (Surplus only or above) may sell after preserving the forecast need before sunrise and the safety margin |
refill_price |
Export-price reference for solar refilling the battery tomorrow |
trigger_1_reason |
Why surplus export is active or inactive |
surplus_export_enabled |
Whether High-Price Sale is set to Surplus only or above |
surplus_kwh |
Energy assigned to surplus export in that price period |
Other diagnostic attributes
PD Control Quality uses stable, oscillating, sluggish, battery_limited, blocked, or collecting_data. Its attributes expose tracking error, oscillation rate, metric age, active proportional–derivative (PD) settings, and profile.
Daily Operation Timeline exposes bounded local-day series, operations, and sources data. See the daily operation timeline.
Expected Home Consumption Profile exposes source, maturity, coverage, sample counts, and forecast data. Vacation Mode exposes its baseline and excluded learning periods.
Control safety¶
Raw Force Mode, Set Charge Power, and Set Discharge Power require global Manual Mode or per-battery Manual Battery Control. Automatic control rejects competing writes. Battery configuration controls remain writable when the driver supports them.
Use multiple batteries for ownership and participation behavior, and troubleshooting when a status or blocker does not explain the result.
No time entity is currently created
automation_charging_end_time remains in translation resources, but the integration has no time platform and does not create that entity.