Skip to content

battery_sim v2.3.0: The overhaul

Choose a tag to compare

View all tags
@dewi-ny-je dewi-ny-je released this 17 May 12:31
v2.3.0
570e7bc
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Overview

This fork has evolved significantly beyond the upstream 1.3.11 release and now includes advanced battery simulation capabilities, improved realism, better state management, and expanded Home Assistant integration features.

⚠️ Breaking Changes

Battery operation modes migrated from switches to a select entity

Previous versions exposed multiple switches for battery modes. It was confusing. These have now been replaced with a single battery_mode select entity.

Why this changed

The old implementation could create inconsistent or undefined states because multiple mode switches could be enabled simultaneously. The new approach centralizes mode handling and greatly simplifies automations and dashboards.

Required user action

If you previously used mode switches in:

  • dashboards
  • automations
  • scripts

you must replace them with actions targeting the already existing battery mode selector.

Additional related changes

  • Internal mode handling was rewritten around a single state model
  • Override charging naming inconsistencies and typos were corrected
  • Deprecated mode switches were removed entirely

⚠️ Configuration Changes

Split charge and discharge efficiencies

Battery efficiency is now modeled separately for:

  • charging
  • discharging

instead of applying all losses during discharge only.

Backward compatibility

Existing installations automatically retain:

  • charge_efficiency = 1.0

to preserve previous behavior.

Recommended migration

For a more realistic simulation, redistribute losses between charge and discharge. See Readme

This models approximately the same total round-trip loss while producing more realistic state-of-charge calculations.

⭐ Major Features

Efficiency curves (power-dependent efficiency simulation)

The integration now supports non-linear battery efficiencies using configurable efficiency curves.

Instead of a single fixed efficiency value, users can define:

  • (power, efficiency) points
  • separate curves for charging and discharging
  • linear interpolation between points

This allows realistic simulation of batteries whose efficiency varies depending on charge/discharge rate.

Example configuration

0:0.90, 2.5:0.94, 5:0.95

Key improvements

  • Efficiency is calculated dynamically from actual transfer power
  • More accurate energy accounting
  • More realistic available battery capacity
  • Added support for real-world battery profiles

Additional sensors

New sensors expose:

  • last charge efficiency used
  • last discharge efficiency used

for debugging and visibility purposes.

Important behavior change

Rapid repeated mode or setting changes can create unrealistic oscillations due to extremely short update intervals.

To prevent this:

  • a minimum 5-second update debounce interval is now enforced

Further reading recommended

Users upgrading should review the updated README documentation for:

  • curve syntax
  • interpolation behavior
  • update interval handling

Battery degradation simulation

The integration can now simulate battery ageing over time.

As the battery accumulates cycles:

  • effective usable capacity decreases
  • 100% SOC corresponds to progressively less available energy

New settings

Users can configure:

  • rated cycle lifespan
  • remaining capacity at end-of-life

New sensor

A dedicated degradation sensor reports current battery wear level.

Solar-only charging limitation

The simulator can now limit charging energy to available solar production.

This models systems where:

  • batteries can only charge from DC-coupled solar panels
  • grid charging is physically impossible

Example:

  • SolarEdge HD-Wave systems

How it works

Users can specify a solar production entity.Battery charging is automatically capped to the available generated solar energy.

Benefits

This prevents unrealistic charging behavior such as:

  • charging from grid imports
  • charging from unrelated inverters on the same network

🔧 Core Simulation Improvements

Update handling improvements

  • Immediate sensor refreshes after settings or mode changes
  • Guaranteed periodic updates through async scheduling
  • Configurable maximum interval between updates
  • Improved idle-mode handling when no power transfer occurs

Battery status reporting

A dedicated battery status attribute now reports:

  • full
  • empty

independently from the active operating mode.

🏠 Home Assistant Integration Improvements

Improved configuration UI

  • Numeric selectors corrected in configuration pages
  • Better validation and parsing for efficiency curve input

Improved entity and device handling

  • Stable device identifiers based on config entry IDs
  • Cleaner service registration lifecycle
  • Improved restoration of persistent states after restart

Runtime reset capabilities

Battery runtime sensors can now be reset:

  • battery SOC reset to 50%
  • accumulated runtime counters cleared

Improved meter reset handling

The simulator now correctly rebases:

  • simulated sensors
  • accumulated readings

after source meter resets.

🛠 Stability and Reliability Improvements

A large number of internal fixes and hardening changes were introduced, including:

  • safer restored-state parsing
  • protection against unsupported source units
  • handling inactive efficiency sensors correctly
  • improved translation validation tooling
  • corrected tariff mapping behavior
  • elimination of duplicate energy calculations
  • initialization safety improvements
  • improved sensor attribute handling

These changes mainly improve:

  • long-term stability
  • consistency
  • resilience against edge cases
  • restart reliability

without changing user-facing functionality.

Full Changelog: Battery_sim_1.3.12...v2.3.0

Assets 2
Loading