Architecture¶
This page maps the current Omnibattery codebase for contributors. It shows where hardware support ends, where shared control begins, and which modules own each part of a telemetry or setpoint cycle.
System map¶
Omnibattery creates one MarstekVenusDataUpdateCoordinator for each configured battery. The class keeps its historical name, but it coordinates every supported brand. Each coordinator owns one concrete BatteryDriver, its connection lock, telemetry cache, polling schedule, health state, and effective limits.
A config entry also creates one ChargeDischargeController for the fleet. The controller reads the Home Assistant grid sensor, combines feature blockers and overrides, calculates the fleet command, asks PowerDistribution to select batteries and allocate power, then writes through each coordinator and driver.
flowchart TD
GRID[Home Assistant grid sensor] --> CTRL[ChargeDischargeController]
PRICE[PricingManager and feature managers] --> CTRL
TRACK[Consumption and solar tracking] --> PRICE
CTRL --> GUARDS[residual_load.apply_guards]
GUARDS --> PD[PD calculation and controller safeguards]
PD --> DIST[PowerDistribution]
ORDER[charge_order and phase limits] --> DIST
DIST --> COORD[MarstekVenusDataUpdateCoordinator per battery]
COORD --> DRIVER[BatteryDriver semantic contract]
DRIVER --> M[MarstekModbusDriver]
DRIVER --> Z[ZendureLocalDriver]
DRIVER --> A[AnkerModbusDriver]
DRIVER --> E[EsphomeEntityDriver]
DRIVER --> S[SessyLocalDriver]
DRIVER --> Y[HoymilesMqttDriver]
DRIVER --> H[HuaweiSolarDriver]
DRIVER -->|read_telemetry| COORD
COORD --> ENT[Home Assistant entities]
The controller and entity platforms do not use register addresses, HTTP paths, or MQTT topics. Those details stay inside drivers/ and the transport clients in infra/.
The driver boundary¶
custom_components/omnibattery/drivers/base.py defines the semantic hardware boundary:
BatteryDriverrepresents one physical battery and owns its transport.DriverCapabilitiesdescribes static traits that shared code may branch on.ReadGroupgroups logical telemetry keys by polling cadence.TelemetrySnapshotis a flat mapping of logical keys to decoded values.SetpointResultreports the applied signed command, confirmation state, measured delivery, failure reason, and any native state to merge into the coordinator cache.
The contract uses signed net power throughout: positive watts charge, negative watts discharge, and 0 W requests idle. A driver translates that meaning into its own modes, limits, registers, services, or entities.
Abstract BatteryDriver surface¶
| Area | Member | Responsibility |
|---|---|---|
| Identity | capabilities |
Return the immutable DriverCapabilities for this device. |
| Lifecycle | connected, connect(), close(), set_shutting_down() |
Own connection state and release transport resources. |
| Telemetry | read_groups, read_telemetry(keys) |
Schedule and return decoded logical values; omit failed values. |
| Net control | apply_setpoint(net_power_w, mode_hint=None, read_back=True) |
Clamp and translate a signed fleet command into device operations. |
| Entity control | write_control(key, value) |
Handle a logical number, select, switch, or button write. |
| Command echo | net_power_from_data(data) |
Reconstruct the currently echoed command for skip-if-unchanged logic. |
| Dependencies | control_dependency_keys |
Keep control-critical telemetry polling even when its entity is disabled. |
The base class also provides optional hooks for DC coupling, model and serial identity, balance dependencies, supplemental discharge measurement, and a dynamic discharge ceiling.
The coordinator currently calls these concrete-driver methods by convention even though they are not abstract members of BatteryDriver: apply_config(), set_charge_cutoff(), standby(), set_rs485_control(), and, for drivers with an external-control gate, get_rs485_control(). A new driver must implement the applicable behavior and return a controlled False for unsupported write operations.
Capabilities¶
Shared code reads coordinator.capabilities; it should not branch on a brand or firmware string. DriverCapabilities currently contains all of these fields:
| Group | Capability | Meaning |
|---|---|---|
| Control | hardware_soc_cutoff |
The device itself enforces the configured state-of-charge (SOC) cutoffs. |
| Control | has_force_mode |
The device exposes a distinct forced charge/discharge/idle mode. |
| Control | has_rs485_control |
An external RS-485 or Modbus control gate can be toggled. |
| Power | max_charge_power_w, max_discharge_power_w |
Inclusive per-device power envelope. |
| Power | min_charge_power_w, min_discharge_power_w |
Lowest reliable non-zero command in each direction. |
| Timing | actuator_latency_s |
Approximate physical response time used by direction-change protection. |
| Timing | readback_latency_s |
Time before command telemetry is settled; falls back to actuator latency. |
| Timing | engage_grace_s |
Optional allowance for a slow idle-to-active transition. |
| Telemetry | push_telemetry |
The driver reads a push-fed cache rather than polling hardware live. |
| Telemetry | telemetry_liveness_checked |
A push-cache read verifies freshness and can prove recovery. |
| Telemetry | setpoint_confirm_reliable |
Immediate readback reliably reflects the command just written. |
| Solar | has_mppt_pv |
Individual maximum power point tracking (MPPT) channels are available. |
| Solar | has_solar_telemetry |
Independent aggregate solar telemetry is available. |
| Energy | has_energy_counters |
Native cumulative energy counters are available. |
| Energy | has_daily_energy_counters |
Native counters that reset daily are available. |
| Energy | has_nominal_capacity |
The device reports nominal battery capacity. |
| Energy | cycles_from_discharge_only |
Equivalent cycles use discharged energy rather than total throughput. |
| Diagnostics | has_alarm_registers |
Native alarm or fault status is available. |
| Cutoffs | charge_cutoff_range, discharge_cutoff_range |
Inclusive ranges exposed by hardware cutoff controls. |
The default values in DriverCapabilities preserve the older register-backed behavior. New drivers should declare every field deliberately; an inherited default is still a product decision.
Supported drivers¶
The package exports seven concrete drivers, and MarstekVenusDataUpdateCoordinator.__init__() constructs all seven from the configured brand.
| File | Class | Hardware and transport |
|---|---|---|
drivers/marstek.py |
MarstekModbusDriver |
Marstek Venus families over Modbus TCP or Modbus RTU. |
drivers/zendure.py |
ZendureLocalDriver |
Zendure SolarFlow families through the local HTTP API. |
drivers/anker.py |
AnkerModbusDriver |
Anker SOLIX Solarbank families over Modbus TCP. |
drivers/esphome.py |
EsphomeEntityDriver |
Marstek hardware behind a LilyGo RS-485 bridge, using ESPHome entities in Home Assistant. |
drivers/sessy.py |
SessyLocalDriver |
Sessy through its authenticated local HTTP API. |
drivers/hoymiles.py |
HoymilesMqttDriver |
Hoymiles MS-A2 through Home Assistant MQTT entities. |
drivers/huawei.py |
HuaweiSolarDriver |
Huawei SUN2000 with LUNA2000: native Modbus telemetry and service-based or direct setpoint writes. |
Each driver also owns its platform definition lists: sensor_definitions, number_definitions, select_definitions, switch_definitions, binary_sensor_definitions, button_definitions, and all_definitions. The coordinator exposes these lists to sensor.py, number.py, select.py, switch.py, binary_sensor.py, and button.py. This keeps unsupported entities out of the registry and keeps hardware metadata beside its decoder.
See Add a battery driver for the implementation and review checklist.
Coordinator and telemetry flow¶
infra/coordinator.py::MarstekVenusDataUpdateCoordinator is the per-device adapter between Home Assistant and a driver. It:
- Constructs the selected concrete driver.
- Connects it and applies setup configuration.
- Iterates
driver.read_groups, skips disabled non-dependency keys, and serializes I/O with its lock. - Merges successful
read_telemetry()values intocoordinator.data. - Tracks failures, availability, reconnect backoff, stale energy readings, and transient fast polling.
- Exposes the driver’s definitions and capabilities to entities and shared control.
- Sends signed commands through
apply_power()todriver.apply_setpoint()and merges the returnedSetpointResult.applieddata.
The nominal read-group cadences come from const/integration_const.py:
| Cadence | Interval | Typical data |
|---|---|---|
high |
2 s | Power, mode, and SOC values used by control. |
medium |
5 s | Voltage, current, and temperature. |
low |
30 s | Energy counters and slower diagnostics. |
very_low |
600 s | Device identity and firmware. |
A driver chooses the cadence for each ReadGroup. During a real command change, the coordinator can temporarily accelerate only groups that contain delivered-power telemetry.
Control pipeline¶
__init__.py::ChargeDischargeController owns fleet orchestration. Its main cycle is async_update_charge_discharge(). The path from a grid update to hardware is:
- Validate and normalize the configured grid sensor.
- Refresh feature managers, blockers, manual ownership, and any active setpoint override.
- Apply target, capacity-protection, and excluded-load adjustments.
- Use
control/residual_load.py::apply_guards()for feedforward, solar-surplus blocking, and the residual-demand discharge ceiling. - Calculate the incremental proportional–derivative (PD) command and apply controller-level deadband, direction-change, minimum-power, relay-dwell, SOC, and non-delivery safeguards.
- Ask
PowerDistributionto select eligible batteries and split the command within effective limits. - Let
PhasePowerLimiterreduce the final per-battery allocation when three-phase protection is enabled. - Call
_set_battery_power(), thencoordinator.apply_power(), thendriver.apply_setpoint()for each selected battery; idle batteries receive an explicit zero where the active control path requires it.
Modules in control/¶
| Module | Class or public helpers | Role in the pipeline |
|---|---|---|
power_distribution.py |
PowerDistribution |
Selects the minimum useful battery set and allocates charge or discharge within limits. |
charge_order.py |
charge_order(), charge_allocation_weights() |
Orders mixed AC/DC fleets and weights charging by remaining capacity. |
residual_load.py |
residual_demand_w(), apply_guards(), guards_pending() |
Reconstructs uncovered load and applies the shared guard pipeline. |
phase_power_limit.py |
PhasePowerLimiter, PhaseSensorReading |
Constrains final allocations from per-phase current measurements. |
pack_soc.py |
pack_socs(), soc_vs_ceiling(), control_vmax() |
Normalizes pack-level SOC and cell-voltage decisions. |
charge_delay.py |
ChargeDelayManager |
Owns solar charge-delay state, forecasts, persistence, and release decisions. |
max_soc_charge.py |
MaxSocChargeManager |
Applies top-of-charge taper, recalibration, and cell-delta measurement. |
weekly_full_charge.py |
WeeklyFullChargeManager |
Schedules and persists periodic full-charge behavior and temporary cutoff changes. |
temperature_limit.py |
TemperatureChargeLimitManager |
Derates per-battery charge and optional discharge limits from temperature. |
discharge_reserve.py |
DischargeReserveManager |
Reserves energy for a later high-price period through discharge blockers. |
high_price_discharge.py |
HighPriceDischargeManager |
Builds and applies deliberate high-price discharge overrides. |
surplus_price_hold.py |
SurplusPriceHoldManager |
Delays solar absorption when exporting now is more valuable. |
Pure pricing calculations live under pricing/. pricing/engine.py::PricingManager coordinates price sources and evaluations, while pricing/chronological.py performs the chronological energy simulation without Home Assistant or device I/O. Runtime adapters in control/ turn those plans into blockers or setpoint overrides.
Tracking and entities¶
The tracking/ package owns persisted observations and projections:
ConsumptionTrackercomposes consumption history, daily counters, recorder backfill, and the consumption profile.ConsumptionProfileTrackerstores local-day interval data and produces weighted forecasts.SolarProfileTrackerlearns a normalized solar-production shape.BalanceMonitorrecords cell-voltage spread around full charge.NonResponsiveTrackertracks failed delivery episodes and recovery.HourlyBalanceManagercalculates hourly net-balance accounting.DailyOperationTimelineManagerbuilds the diagnostic daily timeline.
The Home Assistant platform files are thin consumers of coordinator data and driver definitions. Shared derived entities live under sensors/; system-wide totals use sensors/aggregate_sensors.py, while calculated and restored values use sensors/calculated_sensors.py.
Rules for architectural changes¶
- Put protocol, register, endpoint, topic, scaling, and sign conversion inside a concrete driver or its transport client.
- Express shared hardware differences through
DriverCapabilitiesor semantic driver hooks. - Keep the coordinator responsible for scheduling, locking, cache updates, and health; keep transport lifecycle inside the driver.
- Keep fleet decisions in
ChargeDischargeControllerandcontrol/; do not make a driver choose system policy. - Return unknown or omit a telemetry key when a value cannot be trusted. Do not synthesize zero for a valid missing measurement.
- Add pure planning code under
pricing/ortracking/and a runtime adapter only where Home Assistant state or controller ownership is required.