Battery¶

Batteries are energy storage devices that can charge (store energy) and discharge (release energy). HAEO optimizes when to charge and discharge based on electricity prices, solar availability, and economic preferences.

Internally, HAEO represents batteries as a single storage element and applies SOC preferences via connection pricing. This provides flexible, economically-rational battery behavior without partitioning the battery model.

For mathematical details, see Battery Modeling.

Configuration¶

Overview¶

A battery in HAEO represents:

• Energy storage with a maximum capacity (kWh)
• Power limits for charging and discharging (kW)
• State of Charge (SOC) tracking via a Home Assistant sensor
• Charge and discharge efficiency losses during power conversion
• Operating range preferences guided by economic costs (min/max SOC)

Configuration process¶

Battery configuration uses a sectioned flow where you enter the name, connection, and configure each input field. For each field, select "Entity" to link to a sensor, "Constant" to enter a fixed value, or "None" for optional fields you don't need. If you enable battery partitions, HAEO guides you to a second step to configure undercharge and overcharge values.

Fields configured with "Constant" create input entities that you can adjust at runtime without reconfiguring. Optional fields set to "None" are omitted from the optimization entirely.

Configuration Fields¶

If not specified, power is unconstrained (limited only by other system constraints).

Name¶

Choose a descriptive, friendly name. Home Assistant uses it for sensor names, so avoid symbols or abbreviations you would not want to see in the UI.

Capacity¶

Enter the usable capacity in kWh from your battery or inverter documentation. The optimizer uses this value when calculating state of charge.

Current charge percentage¶

Select the Home Assistant sensor that reports the battery's current SOC. HAEO expects values between 0 and 100.

Min and max charge percentage¶

Set the preferred operating range for routine battery use. HAEO will normally keep the battery within this range. These are the inner bounds of normal operation. If you leave them unset, HAEO allows the full 0-100% range. A typical starting point is 10-90% unless your manufacturer recommends otherwise.

Charge and discharge efficiency¶

Enter separate charge and discharge efficiencies as percentages (0-100). Charge efficiency applies when power flows from the network into the battery. Discharge efficiency applies when power flows from the battery into the network. If you only have a round-trip figure, use the same value for both directions or approximate a symmetric value with \(\sqrt{\text{round-trip}}\). Most modern lithium batteries have efficiencies in the 95-98% range, while older chemistries may be lower. Refer to your battery or inverter specifications for the most appropriate values.

Max charge and discharge power¶

Add limits based on your battery's charge/discharge rating. Leave the fields blank when no practical limit applies.

Salvage Value¶

Value in $/kWh assigned to stored energy at the end of the optimization horizon. This prevents the optimizer from draining the battery to zero when future value is still expected.

Default: 0 $/kWh (no terminal value)

How it works: The optimizer credits the final stored energy by this amount. Higher values encourage retaining energy for periods beyond the horizon.

Configure battery partitions¶

Enable this option to configure undercharge and overcharge partitions. When enabled, HAEO opens a second step where you set the undercharge and overcharge percentage and cost values.

Undercharge Configuration¶

Undercharge settings are configured on the battery partitions step.

Configure an extended low SOC range with economic penalties to model battery behavior below normal operating limits. This section is optional and can be used independently of overcharge configuration.

Undercharge Percentage¶

Define the hard minimum SOC limit (absolute floor). This is the lower bound of the battery's operating range.

Ordering requirement: Must be less than min_charge_percentage.

Example:

undercharge percentage=5% < min_charge_percentage=10%

This allows operation between 5-10% SOC with an added undercharge cost penalty when discharging below min_charge_percentage.

Overcharge Configuration¶

Overcharge settings are configured on the battery partitions step.

Configure an extended high SOC range with economic penalties to model battery behavior above normal operating limits. This section is optional and can be used independently of undercharge configuration.

Overcharge Percentage¶

Define the hard maximum SOC limit (absolute ceiling). This is the upper bound of the battery's operating range.

Ordering requirement: Must be greater than max_charge_percentage.

Example:

max_charge_percentage=90% < overcharge percentage=95%

This allows operation between 90-95% SOC with an added overcharge cost penalty when charging above max_charge_percentage.

Undercharge Cost¶

Economic penalty in $/kWh for discharging below min_charge_percentage. Required when the undercharge percentage is configured.

Setting the cost: Consider the economic value of avoiding deep discharge:

• Battery degradation from deep cycles
• Manufacturer warranty conditions
• Your risk tolerance for low SOC states

Typical values: $0.50-$2.00/kWh

How it works: The optimizer compares grid revenue against the undercharge cost penalty. If grid prices are $0.40/kWh and the undercharge cost is $0.50/kWh, the battery won't discharge into the undercharge range. If grid prices spike to $0.80/kWh, the optimizer will economically justify deep discharge because the $0.30/kWh profit makes it worthwhile.

Applies to: Energy discharged below min_charge_percentage. The battery will not discharge below the undercharge percentage under any circumstance.

Overcharge Cost¶

Economic penalty in $/kWh for charging above max_charge_percentage. Required when the overcharge percentage is configured.

Setting the cost: Consider the economic value of avoiding high SOC:

• Battery degradation from high SOC levels
• Cell balancing concerns
• Your risk tolerance for high SOC states

Typical values: $0.50-$2.00/kWh

How it works: The optimizer compares available energy value against this penalty.

From grid: The battery will only charge into the overcharge range from the grid if grid prices are negative (you get paid to consume) by more than the overcharge cost. For example, if overcharge cost is $1.00/kWh, grid prices would need to be below -$1.00/kWh.

From solar: The battery will charge into the overcharge range from solar if the forecasted future export value exceeds the overcharge cost. For example, if export prices tomorrow are $0.50/kWh and overcharge cost is $0.20/kWh, HAEO will overcharge today to maximize export revenue tomorrow.

Applies to: Energy charged above max_charge_percentage. The battery will not charge above the overcharge percentage under any circumstance.

Configuration Examples¶

Basic Battery Configuration¶

A typical battery configuration with just the essential parameters:

This creates a battery that operates in the 20-90% range with no economic penalties for staying within that range.

Battery with Extended Operating Range¶

A battery configured with undercharge and overcharge ranges for conditional extended operation:

Enable Configure battery partitions to access the undercharge and overcharge fields.

In this example:

• Undercharge range: 5-10% (available with $1.50/kWh discharge penalty)
• Normal range: 10-90% (preferred operation)
• Overcharge range: 90-95% (available with $1.00/kWh charge penalty)
• Total usable range: 5-95% (90%)
• Higher undercharge cost reflects greater degradation risk at low SOC
• Optimizer will use extended ranges only when grid conditions justify the penalties

Input Entities¶

Each configuration field creates a corresponding input entity in Home Assistant. Input entities appear as Number entities with the config entity category.

When both undercharge and overcharge partitions are configured, Home Assistant adds a suffix to keep entity IDs unique.

The charge and discharge cost inputs are surfaced from the policy rules they create. They appear on both the battery device and the Policies device; editing either updates the same stored value.

Input entities include a forecast attribute showing values for each optimization period. See the Input Entities developer guide for details on input entity behavior.

Sensors Created¶

Sensor Summary¶

A Battery element creates a single device in Home Assistant:

• Battery device ({name}): Always created with total power, energy, SOC, and shadow price sensors

Battery Device Sensors¶

These sensors appear on the battery device:

Charge Power¶

The optimal charging power for this battery at each time period.

Values represent the average power during the period. Positive values indicate energy flowing into the battery. A value of 0 means the battery is not charging.

Example: A value of 3.2 kW means the battery is charging at an average rate of 3.2 kW during this period, limited by the configured max charge power or other system constraints.

Discharge Power¶

The optimal discharging power for this battery at each time period.

Values represent the average power during the period. Positive values indicate energy flowing out of the battery. A value of 0 means the battery is not discharging.

Example: A value of 2.5 kW means the battery is discharging at an average rate of 2.5 kW during this period, providing power to loads or exporting to the grid.

Energy Stored¶

The total energy currently stored in the battery across all SOC regions.

This represents the absolute energy level in kWh. Multiply by 100 and divide by capacity to get state of charge percentage.

Example: A value of 12.5 kWh in a 15 kWh battery means 83.3% state of charge.

State of Charge Sensor¶

The battery's state of charge as a percentage (0-100%).

This is calculated from the energy stored divided by total capacity. Provides a convenient percentage view of the battery level.

Example: A value of 75% means the battery has 75% of its capacity available.

Power Balance Shadow Price¶

The marginal value of power at the battery terminals. See the Shadow Prices modeling guide for general shadow price concepts.

This shadow price represents the economic value of 1 kW of additional power capacity at the battery. It reflects the cost of power flowing through the battery connection point.

Interpretation:

• Positive value: Power at the battery terminals has value (usually during discharge periods)
• Negative value: Additional power would increase costs (usually during charging periods)
• Magnitude: Higher absolute values indicate the battery connection is more valuable to the system

Example: A value of 0.15 means 1 kW of additional power capacity at the battery would save $0.15 per time period.

Each sensor includes forecast attributes with future timestamped values for visualization and automations.

How It Works Internally¶

HAEO models batteries using a single storage element with SOC-aware connections:

1. Battery element: Tracks stored energy within the configured SOC bounds
2. SOC pricing: Applies undercharge and overcharge penalties when enabled
3. Network connections: Separate charge and discharge connections apply efficiency and power limits

This architecture allows HAEO to:

• Prefer staying within the min/max SOC range when penalties are configured
• Trade off extended SOC operation when prices justify it
• Preserve hard SOC bounds defined by undercharge and overcharge percentages

When to Use Extended Operating Ranges¶

Configure undercharge and overcharge ranges when you want to:

1. Economic flexibility for extreme conditions: Allow the battery to operate in extended SOC ranges when grid conditions make it economically worthwhile (e.g., very high grid prices justify deep discharge despite degradation costs).

2. Model degradation economics: Reflect the real economic cost of battery degradation at extreme SOC levels. The optimizer will automatically trade off grid savings against battery wear costs.

3. Capture opportunistic value: Enable the battery to charge above normal limits when excess solar is available or grid prices are negative, while still discouraging routine overcharging.

4. Flexible protection: Maintain conservative normal operation (e.g., 10-90%) while allowing economically-justified excursions (e.g., 5-95%) rather than imposing hard limits.

When NOT to use extended ranges:

• When the normal operating range is sufficient for your use case
• When you want absolute hard limits that cannot be violated under any circumstances (cost-based boundaries are economic, not physical)
• When you cannot estimate appropriate penalty costs relative to your grid price volatility
• For new batteries where the degradation cost structure is uncertain

Key difference from hard limits: Extended ranges create economic trade-offs, not absolute constraints. The battery can operate in these ranges when conditions justify it, providing flexibility while still protecting against unnecessary degradation.

Troubleshooting¶

Battery Not Charging/Discharging¶

If your battery remains idle:

1. Check price forecasts: HAEO needs price variation to optimize. See the forecasts page for details.
2. Verify SOC sensor: Ensure it's reporting correctly
3. Review constraints: Too-tight SOC limits may prevent operation
4. Check connections: Battery must be connected to the network

Unrealistic SOC Predictions¶

If forecast SOC values seem wrong:

1. Verify capacity: Ensure capacity matches your actual battery
2. Check efficiency: Confirm charge and discharge efficiencies are set (use the same value in both directions if you only have a round-trip figure)
3. Review power limits: Ensure they match your battery rating

SOC Sensor Issues¶

Common problems:

• Not updating: Check sensor entity in Developer Tools → States
• Wrong units: Must be 0-100%, not 0-1 decimal
• Incorrect values: Calibrate battery management system

See the troubleshooting guide for more solutions.

Multiple Batteries¶

HAEO supports multiple batteries in the same network:

1. Add each battery with a unique name
2. Connect each battery to the network (typically via a node)
3. HAEO will optimize all batteries together

This allows HAEO to:

• Balance charging across batteries
• Optimize total system cost
• Handle different battery characteristics

Next steps¶

Build on your battery configuration with these guides.