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 using multiple interconnected sections (undercharge, normal, overcharge) with cost-based preferences to guide operation. This provides flexible, economically-rational battery behavior.

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
• Efficiency losses during charge/discharge cycles
• Operating range preferences guided by economic costs (min/max SOC)

Configuration process¶

Battery configuration uses a two-step flow (see Configuration for details):

1. Step 1: Enter name, connection, and select input mode for each field (Constant, Entity Link, or Not Configured)
2. Step 2: Enter values or select sensors based on your mode selections

For each field, you choose whether to use a constant value or link to Home Assistant sensors. Optional fields can be set to "Not Configured" to disable that functionality.

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. Leaving the defaults (10-90%) is a good starting point unless your manufacturer recommends otherwise.

Efficiency¶

Enter the round-trip efficiency as a percentage (0-100). HAEO automatically converts this to one-way efficiency internally for accurate charge/discharge modeling. Most modern lithium batteries have round-trip efficiencies in the 95-98% range, while older chemistries may be lower. Refer to your battery or inverter specifications for the round-trip efficiency value.

Max charge and discharge power¶

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

Early Charge Incentive (Advanced)¶

Creates a small time-varying cost that prefers charging earlier in the optimization window when all else is equal. Default is 0.001 $/kWh (0.1 cents).

How it works: The incentive varies linearly from a small negative cost (encourages charging) at the beginning of the optimization window to zero at the end. This prevents arbitrary timing decisions when grid prices are flat.

When to adjust:

• Keep the default (0.001) for most systems
• Increase slightly (0.002-0.005) if the battery seems to delay charging unnecessarily
• Decrease (0.0005) if you want more flexibility in timing

Discharge Cost¶

Base cost in $/kWh applied to all battery discharge operations. Models battery degradation from cycling.

Setting the cost: Consider the cost of battery wear per cycle. A typical value is $0.00-$0.05/kWh depending on battery chemistry and expected lifetime.

Leave at zero if you don't want to model degradation costs.

Undercharge Configuration¶

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 creates an "undercharge section" between undercharge_percentage and min_charge_percentage.

Ordering requirement: Must be less than min_charge_percentage.

Example:

undercharge_percentage=5% < min_charge_percentage=10%

Creates an undercharge section from 5-10% where discharging incurs the undercharge_cost penalty in addition to the normal discharge_cost.

Overcharge Configuration¶

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 creates an "overcharge section" between max_charge_percentage and overcharge_percentage.

Ordering requirement: Must be greater than max_charge_percentage.

Example:

max_charge_percentage=90% < overcharge_percentage=95%

Creates an overcharge section from 90-95% where charging incurs the overcharge_cost penalty.

Undercharge Cost¶

Economic penalty in $/kWh for discharging from the undercharge section. Required when undercharge_percentage is configured. This penalty applies in addition to the normal discharge_cost.

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 combined penalties (discharge_cost + undercharge_cost). If grid prices are $0.40/kWh and total cost is $0.50/kWh (e.g., $0.02 discharge + $0.48 undercharge), the battery won't discharge into the undercharge section. If grid prices spike to $0.80/kWh, the optimizer will economically justify deep discharge because the $0.30/kWh profit ($0.80 - $0.50) makes it worthwhile.

Applies to: Energy discharged from the undercharge section (below min_charge_percentage). The battery will not discharge below undercharge_percentage under any circumstance - that is the hard limit.

Overcharge Cost¶

Economic penalty in $/kWh for charging into the overcharge section. Required when 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 section 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 section 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 into the overcharge section (above max_charge_percentage). The battery will not charge above overcharge_percentage under any circumstance - that is the hard limit.

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 sections for conditional extended operation:

In this example:

• Undercharge section: 5-10% (available with $1.50/kWh discharge penalty)
• Normal section: 10-90% (preferred operation, only $0.02/kWh discharge cost for degradation)
• Overcharge section: 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 sections 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.

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 1-4 devices in Home Assistant depending on configuration:

• Aggregate device ({name}): Always created with total power, energy, and SOC sensors
• Undercharge device ({name}:undercharge): Created when undercharge_percentage is configured
• Normal device ({name}:normal): Created when multi-section operation is active
• Overcharge device ({name}:overcharge): Created when overcharge_percentage is configured

Aggregate Device Sensors¶

These sensors appear on the main battery device:

Region Device Sensors¶

These sensors appear on region-specific devices (undercharge, normal, overcharge) when configured:

Balance Power (by region)¶

Shows the power flowing through balance connections with adjacent battery sections.

• Balance power down: Power flowing into this section from balance connections (entering)
• Balance power up: Power flowing out of this section via balance connections (leaving)

For a three-section battery:

• Undercharge: Has balance connection to normal section above
• Normal: Has balance connections to both undercharge (below) and overcharge (above)
• Overcharge: Has balance connection to normal section below

Balance power is typically zero during normal operation. Nonzero values occur when section capacity changes force energy redistribution, such as when capacity sensors update.

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.

Energy Stored (by region)¶

Shows energy stored in each region: undercharge (below min SOC), normal (min to max SOC), or overcharge (above max SOC). A nonzero value in undercharge or overcharge regions indicates the battery is operating outside its normal range.

Charge/Discharge Power (by region)¶

Shows power flowing into or out of each region. Undercharge discharge incurs penalties; overcharge charge incurs penalties. Moving toward normal operation (charging undercharge, discharging overcharge) has no penalty.

Energy Flow (by region)¶

Shows cumulative energy flowing into or out of each region during the optimization horizon. These sensors help track energy movement between regions.

SOC Bounds (by region)¶

Shows the configured SOC boundaries for each region. Useful for verifying configuration and debugging.

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 multiple interconnected sections:

1. Section creation: Your battery is split into 1-3 sections (undercharge, normal, overcharge) based on your SOC percentage configuration
2. Central junction: All sections connect to a central node that aggregates their power
3. Cost-based preferences: Each section has different charge/discharge costs that guide the optimizer's behavior
4. Network connection: The central node connects to your network with efficiency and power limits

This architecture allows HAEO to:

• Prefer charging lower sections first (undercharge → normal → overcharge)
• Prefer discharging higher sections first (overcharge → normal → undercharge)
• Make economically rational trade-offs when grid conditions justify using extended ranges

When to Use Extended Operating Ranges¶

Configure undercharge and overcharge sections 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 you've entered round-trip efficiency (HAEO converts internally)
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.