Welcome to the BESS Manager! This guide will help you understand the interface, interpret optimization results, and get the most out of your battery storage system.
For a full explanation of why the optimizer decides what it decides — the economics, the reasoning model, and what the intent labels mean — see ALGORITHM_EXPLAINED.md.
Once installed and configured, access your BESS Manager dashboard through:
- Home Assistant: Add-ons → BESS Manager → Open Web UI
- Direct URL:
http://your-home-assistant:8080(if configured for external access)
The main dashboard provides a real-time overview of your energy system:
- Current SOC: Battery charge percentage and energy (kWh)
- Power Flows: Real-time power in/out of battery, solar, and grid
- System Health: Green/Yellow/Red indicators for all components
- Active Strategy: Current optimization strategy (Grid Charging, Solar Storage, etc.)
- Solar Production: Total solar energy generated today
- Home Consumption: Energy consumed by your home
- Battery Activity: Energy charged/discharged
- Grid Interaction: Energy imported/exported
- Savings: Estimated cost savings vs. no optimization
An hourly (or 15-minute) chart of your whole day, today and tomorrow. Energy sources stack above the zero line, consumption stacks below it, and price is plotted on its own axis on the right:
- 🌞 Solar Production, 🔋 Battery Discharge, ⚡ Grid Import — where your energy came from, stacked together
- 🏠 Home Load, 🔋 Battery Charge, ⚡ Grid Export — where it went, stacked below the zero line
- Buy Price (and, if enabled, Sell Price) — a dashed line against the right-hand axis
A shaded band marks the hours that have already elapsed today; a second shade marks tomorrow's forecast, once available.
Home Load, split into Planned Load
If you've declared a Planned Consumption Change (e.g. tonight's EV session — see "Planned Consumption Changes" below), the chart splits Home Load into two stacked pieces for the hours the plan covers:
- Home Load — your normal forecast for that hour, from whichever consumption strategy you've configured
- Planned Load — the extra (or reduced) energy the declaration adds on top
Together they still stack to the same total the optimizer planned against — the split is purely so you can see how much of an hour's forecast is "normal" versus "because of what I told it to expect."
Forecast Total — checking a plan against what happened
Once an hour with a declared plan has passed, the chart keeps showing what was actually measured (the solid Home Load area), but adds a dashed Forecast Total line marking what had been planned for that hour. A gap between the solid area and the dashed line means the plan didn't play out as declared — the EV charged less (or more) than announced, for instance. Hours with no plan attached never show this line; it's there to check a specific declaration, not to grade general forecast accuracy — the Insights page's Forecast Accuracy view is for that.
Shows battery charge level throughout the day with strategic context:
- Purple periods: Grid charging (storing cheap electricity)
- Yellow periods: Solar storage (storing free solar energy)
- Blue periods: Load support (using battery to power home)
- Green periods: Export arbitrage (selling stored energy for profit)
- Gray periods: Idle (no significant battery activity)
Reading the strategy:
- GRID_CHARGING: Buying cheap electricity to store
- SOLAR_STORAGE: Storing excess solar production
- LOAD_SUPPORT: Using battery to power your home
- BATTERY_EXPORT: Selling stored battery energy at high prices
- SOLAR_EXPORT: Solar surplus going directly to grid, battery idle
Comprehensive breakdown of your savings:
- Grid-Only Cost: What you would pay without optimization
- Optimized Cost: Actual cost with BESS Manager
- Total Savings: Money saved (can be negative during investment periods)
- ROI Tracking: Progress toward return on investment
The system status card provides key metrics and health information:
- Battery SOC: Current charge level (percentage and kWh)
- Real-time Power: Current power flows (solar, battery, grid, consumption)
- System Health: Component status indicators (sensors, integrations)
- Today's Totals: Energy flows and estimated savings for today
- Strategic Intent: Current optimization strategy being executed
- What: Charging battery from grid during low-price periods
- Why: Store cheap energy to use/sell later
- When: Typically night hours with low electricity prices
- Indicator: Battery charging, grid import high
- What: Charging battery with excess solar production
- Why: Store free solar energy for evening/night use
- When: Sunny midday hours with solar surplus
- Indicator: Battery charging, minimal grid activity
- What: Using battery to power home consumption
- Why: Avoid purchasing expensive grid electricity
- When: Evening hours with high prices and home consumption
- Indicator: Battery discharging, minimal grid import
- What: Selling stored battery energy to grid during peak prices
- Why: Maximize revenue from stored energy
- When: Peak price hours when selling is more profitable
- Indicator: Battery discharging, high grid export
- What: Solar surplus exporting directly to grid, battery idle
- Why: No battery action needed — solar production exceeds home load
- When: Sunny hours when battery is full or storing is not profitable
- Indicator: High solar production, grid export, battery holding
- What: Minimal battery activity
- Why: No profitable charging/discharging opportunity
- When: Price differences too small to justify battery wear
- Indicator: Low battery activity, direct solar consumption
- 🟢 Green: System operating normally
- 🟡 Yellow: Minor issues or suboptimal conditions
- 🔴 Red: Attention required (sensor offline, communication issues)
- Total Savings: Daily cost reduction
- Energy Efficiency: How much energy was optimized vs. total consumption
- Battery Utilization: Percentage of battery capacity used effectively
- Savings Rate: Percentage of electricity costs saved
- ROI Progress: Time to recover optimization system investment
- Seasonal Variations: How performance changes with weather patterns
When reporting issues or debugging problems, check the add-on logs for detailed information:
- Go to Home Assistant → Settings → Add-ons → BESS Manager
- Click on the Log tab
- Review the logs for errors or warnings
The logs show:
- Sensor data collection and validation
- Optimization algorithm decisions and reasoning
- Schedule creation and inverter communication
- Price data fetching and processing
- Component health checks and errors
Tip: Use the Refresh button to see the latest log entries. For historical logs, you can use the Home Assistant system log viewer.
Symptoms: Battery stays at same level, no strategic intents Causes:
- Price differences too small to justify battery wear
- Battery already at optimal level
- System in learning mode (first few days)
Solutions:
- Check electricity price integration is working (Nordpool or Octopus Energy)
- Verify price spread is significant enough to justify battery wear
- Wait for price volatility periods
Symptoms: Dashboard shows negative savings Causes:
- System is investing in battery charge for future savings
- Battery wear costs temporarily exceed immediate benefits
- Learning period with suboptimal decisions
Solutions:
- Look at weekly/monthly totals instead of daily
- Check if system is building charge for upcoming peak prices
- Verify battery wear cost settings are reasonable
Symptoms: Energy in ≠ energy out in charts Causes:
- Sensor timing differences
- Recorder history gaps for the affected hours
- Battery efficiency losses
Solutions:
- Check all sensors are reporting correctly
- Verify Home Assistant's recorder is retaining these sensors (not excluded,
purge_keep_days≥ 2) - Small imbalances (<5%) are normal due to efficiency losses
Symptoms: Battery behavior doesn't match predicted schedule Causes:
- Home consumption higher/lower than predicted
- Solar production different than forecast
- Grid power limitations
- Inverter safety overrides
Solutions:
- Check if actual consumption matches predictions
- Verify solar forecast accuracy
- Review inverter settings and error logs
- System will auto-adapt within 1-2 hours
- Total Capacity: Match your actual battery capacity exactly
- Min SOC: Set safety margin (10-20% recommended)
- Cycle Cost: Balance between battery wear and optimization aggressiveness
BESS needs hourly spot prices to decide when to charge and discharge. Four price providers are supported — pick the one that matches the integration you have installed in Home Assistant.
Recommended for most European users. This is the official Nord Pool integration built into Home Assistant (available since HA 2024.10).
- Prerequisites: Add Nord Pool under Settings → Devices & Services → Add Integration → Nord Pool. Configure your market area (e.g. SE4, NO1, DK1, FI) and currency there.
- How it works: BESS calls the
nordpool.get_prices_for_dateservice using the Config Entry ID to fetch today's and tomorrow's hourly spot prices. - Config Entry ID: A unique identifier for your Nord Pool integration instance. Auto-detected by Auto-Configure. You can also find it in the HA URL when viewing the integration (the long hex string).
- Area & Currency: Determined by the integration's own configuration and shown read-only in BESS. These are not configurable in BESS — change them in the HA Nord Pool integration settings if needed.
For users with the Nord Pool HACS custom integration (installed from github.com/custom-components/nordpool).
- Prerequisites: Nord Pool installed via HACS. The integration creates a single sensor entity whose name encodes the area and currency, e.g.
sensor.nordpool_kwh_se4_sek_3. - How it works: BESS reads the
raw_todayandraw_tomorrowattributes from your Nord Pool sensor to get hourly spot prices. Both today's and tomorrow's prices live on the same sensor entity. - Sensor: The entity ID of your Nord Pool sensor. Auto-detected by Auto-Configure, or enter it manually.
- Area & Currency: Inferred from the sensor name and shown read-only in BESS.
For UK users on the Octopus Energy Agile tariff.
- Prerequisites: The Octopus Energy HACS integration installed and configured. It creates event entities that update with upcoming half-hourly rates.
- How it works: BESS reads four event entities — today's and tomorrow's import rates, and today's and tomorrow's export rates. Prices are already VAT-inclusive in GBP/kWh.
- Entities: Four event entity IDs for import/export today/tomorrow. All are auto-detected by Auto-Configure.
For European users on a day-ahead dynamic tariff that follows the ENTSO-e Transparency Platform — including Belgian Belpex prices (Luminus dynamic and others).
- Prerequisites: The ENTSO-e Transparency Platform HACS integration installed and configured with your area (e.g. Belgium). It creates an "Average electricity price" sensor, e.g.
sensor.belpex_h_average_electricity_price. - How it works: BESS reads the
prices_todayandprices_tomorrowattributes from that single sensor. Each is a list of{"time", "price"}entries. Hourly data (PT60M, 24/day) is expanded to the internal 15-minute resolution; native quarterly data (PT15M, 96/day) is used as-is. - Sensor: The entity ID of the ENTSO-e average-price sensor. Auto-detected by Auto-Configure, or enter it manually.
- Prices & VAT: ENTSO-e prices are wholesale spot prices in EUR/kWh and VAT-exclusive by default, so BESS applies the markup/VAT/fees below — just like Nord Pool.
⚠️ If you configured a custom VAT modifyer inside the ENTSO-e integration, its prices already include VAT; in that case set the BESS VAT Multiplier to 1.0 to avoid double-counting.
Once BESS has the raw spot price from your provider, it applies your configured fees and taxes to compute the actual buy and sell prices used for optimization:
- Markup Rate: Your energy provider's margin fee, applied before VAT. E.g. Tibber charges ~0.08 SEK/kWh, Ellevio ~0.15.
- VAT Multiplier: The VAT factor. 1.25 = 25% (Sweden/Norway), 1.24 = 24% (Finland), 1.22 = 22% (Estonia), 1.20 = 20% (UK).
- Additional Costs: Grid transfer fee + energy tax, summed as a single per-kWh value including VAT. E.g. E.ON: (0.2584 + 0.3600) × 1.25 = 0.773 SEK/kWh.
- Export Compensation: Per-kWh payment from your grid operator when you sell surplus electricity. Check your energy bill, e.g. E.ON under "Producent/Självfaktura": 0.1988 SEK/kWh.
The formulas:
- Buy price = (spot + markup) × VAT multiplier + additional costs
- Sell price = spot + export compensation
For Octopus Energy, prices are already final (VAT-inclusive, GBP/kWh). Markup, VAT, and Additional Costs are not applied — only Export Compensation is used.
BESS needs a forecast of your home consumption to plan the battery schedule. Four strategies are available, configured via home.consumption_strategy in your add-on settings:
This strategy is selectable only once the 48h_avg_grid_import sensor is configured: it is the one strategy with no fallback, so choosing it without that sensor means no schedule can be built at all and the dashboard never leaves "Initializing". New installs default to fixed; ha_statistics is the recommended choice (see INSTALLATION.md, Step 3).
BESS reads a Home Assistant sensor named *48h_avg*grid_import* (the exact entity ID is auto-discovered by name pattern). This sensor should be a 48-hour rolling average of your grid import power, filtered to exclude periods when the battery is active. See INSTALLATION.md, Step 3 for how to create it.
The same flat value is used as the predicted consumption for all 96 periods of the day — it is an average, not a time-of-day profile.
Why filter out battery activity? When the battery discharges, it reduces grid import. Without the filter, battery-active periods would lower the average and cause the optimizer to under-predict consumption.
EV charging — include or exclude?
- Exclude (recommended for most users): The average reflects pure home consumption. The optimizer does not plan for EV charging load, but the discharge inhibit sensor (see below) prevents the battery from discharging while the car charges. This is the more robust choice when EV charging is irregular.
- Include: The optimizer sees the total actual load and may hold back battery capacity in anticipation. This works well only if you charge the car on a very predictable schedule (same time, same amount every night).
The 48h window is a sensible default. If your consumption varies strongly with season (e.g. heat pump), you can create the sensor with a shorter window (12–24h) so it adapts faster — just keep the 48h_avg_grid_import naming so BESS discovers it correctly.
Uses a single fixed kWh/hour value set in home.default_hourly. No sensor required. Useful as a fallback or for very predictable consumption, but does not adapt to actual usage.
Reads the past 7 days of your local load power sensor from Home Assistant's recorder and builds a 96-period average profile (one value per 15-minute slot, averaged across the same slot for the last 7 days). This gives a time-of-day shaped forecast — higher during evening peaks, lower overnight — rather than a flat value.
Requires the local_load_power sensor configured in your add-on sensor settings. Unlike ha_statistics it does not need a lifetime_load_consumption entity, so it works on platforms (e.g. SolaX Native, Solis) that only derive that value. (Was named influxdb_7d_avg before it moved to the recorder; the old id is still accepted.)
Uses Home Assistant's built-in Recorder long-term statistics to build a 96-period time-of-day consumption profile from the past 7 days. Like load_power_7d_avg, this produces a shaped forecast — higher during evening peaks, lower overnight — but from the cumulative load-energy statistics rather than instantaneous power samples.
Requires the lifetime_load_consumption sensor configured in the Sensors tab (under Consumption Forecast). This should be a cumulative energy sensor (kWh) tracked by HA's long-term statistics — for example sensor.load_energy_total from your inverter integration.
How it works: BESS queries the HA Recorder for hourly change statistics over the past 7 days, groups them by hour-of-day, and computes a trimmed mean (dropping the highest and lowest values) for each hour. This filters out outlier spikes like occasional EV charging sessions while preserving the true daily consumption shape. The hourly averages are then split into 15-minute periods.
Safeguards:
- The option is greyed out in Settings if the required sensor is not configured.
- If the sensor is configured but HA has not yet accumulated enough history (fewer than 12 hours of data), BESS automatically falls back to the fixed profile and shows a warning on the dashboard. Once HA accumulates sufficient data (typically within 12-24 hours of first configuring the sensor), the system self-heals and the warning auto-dismisses.
This is the recommended strategy for most users — it adapts to your actual usage patterns with no extra integrations or configuration beyond a cumulative load sensor.
The trimmed mean above filters out an occasional spike, but not a regular one — if you charge your EV most nights, ha_statistics learns that as part of your normal pattern and forecasts it every night, whether or not you're actually charging. Managed Loads is how you tell BESS to exclude a load entirely and announce it yourself instead.
In the Home settings tab, under ha_statistics, add the load's own cumulative/lifetime energy sensor (e.g. sensor.ev_charger_energy_total — most EV chargers expose one; tools like evcc can synthesize one for chargers that don't) to Managed load sensors. BESS subtracts that sensor's energy from the historical data before computing the baseline, so the learned "normal" becomes the residual — your house load with the managed load excluded.
With the load excluded, it simply isn't forecast at all unless you say otherwise — the recommended setup is to exclude it here, then announce expected sessions via Planned Consumption Changes below (e.g. "EV needs 8 kWh by 06:30"). This is the same residual-plus-announcement pattern EMHASS uses for controllable loads.
Only ha_statistics supports this today — load_power_7d_avg draws from a different data source and would need its own mechanism.
The Insights page includes a Consumption Forecast Comparison section that evaluates all available strategies against your actual consumption. Each strategy shows its hourly profile overlaid on actual data, along with a Mean Absolute Error (MAE) metric. Use this to verify which strategy best matches your real consumption patterns before committing to one.
Every strategy above describes your normal usage. None of them can know the EV is charging tonight, that you're skipping the pool pump, or that a heatwave will have the AC running all afternoon. Planned Consumption Changes is how you say so.
It is not a fifth strategy — it applies on top of whichever one you use. If you never configure it, nothing changes.
Create a template sensor whose blocks attribute lists what differs, then point BESS at it in the Sensors tab under Planned Consumption Changes.
template:
- sensor:
- name: "BESS Planned Consumption Changes"
# `state` is cosmetic -- BESS reads the `blocks` attribute below
# regardless of it, precisely so a helper this depends on going
# temporarily "unknown" can't block your schedule. Anything
# human-readable works; a fixed literal is simplest.
state: "ok"
attributes:
blocks: >
{% set blocks = [] %}
{# The EV charges overnight: 40 kWh between 22:00 and 06:00.
Anchor to YESTERDAY's 22:00 in the small hours, otherwise
today_at('22:00') rolls forward at midnight and the running
session vanishes from the forecast exactly when it matters. #}
{% if is_state('input_boolean.ev_charging_tonight', 'on') %}
{% set ev_start = today_at('22:00') - timedelta(days=1)
if now() < today_at('06:00') else today_at('22:00') %}
{% set blocks = blocks + [{
'start': ev_start.isoformat(),
'end': (ev_start + timedelta(hours=8)).isoformat(),
'energy_kwh': 40.0
}] %}
{% endif %}
{# Away for the day: hold the whole daytime near zero #}
{% if is_state('input_boolean.away_today', 'on') %}
{% set blocks = blocks + [{
'start': (today_at('08:00')).isoformat(),
'end': (today_at('18:00')).isoformat(),
'energy_kwh': 1.0,
'mode': 'set'
}] %}
{% endif %}
{{ blocks }}Each entry is a time span plus the energy for that whole span:
| Field | Meaning |
|---|---|
start, end |
ISO-8601 timestamps. Must include a UTC offset — isoformat() on a HA template time gives you one. |
energy_kwh |
Total kWh across the span, spread over the periods it covers. Not a per-period value. |
mode |
add (default) adds to your normal forecast; a negative value subtracts. set replaces it across the span. |
Use add for things that are happening on top of normal (the EV tonight), a negative add for a regular load that isn't happening (the EV is away, so subtract the usual evening session), and set for the blunt cases where you don't know what the baseline holds — away for a week, or forcing a window near zero.
Entries can be timestamped for tomorrow; BESS places them on the real horizon, so an entry that starts at 22:00 and runs to 06:00 is correctly split across midnight.
One trap when writing overnight entries: today_at() re-evaluates against the current day, so an entry anchored at today_at('22:00') jumps forward a full day the moment midnight passes — taking the still-running session out of the forecast just as the optimizer needs it. Anchor to the previous day while you are still inside the window, as the example above does.
If the declaration is broken, BESS says so rather than ignoring it. A missing, unavailable or malformed entity is reported as an error on the system health check — declaring an EV session and having it silently dropped would be worse than a clear failure. The one thing BESS corrects rather than rejects: if a subtraction removes more load than your forecast contains, that period is clamped to zero and a warning is raised, because negative consumption isn't physical.
BESS does not control EV charging — it is designed to work alongside it. Under normal circumstances there is no conflict: when electricity is cheap, both the car and the battery charge at the same time.
The exception is grid reward programs such as Tibber grid rewards. These programs can start EV charging for grid balancing reasons, even when the spot price is not at its lowest. If BESS were to discharge the battery at the same time, that energy would flow toward the car instead of from the grid — you would miss the grid reward income and also lose the battery capacity you would otherwise have had available for the home.
To prevent this, BESS auto-detects any binary_sensor whose entity ID ends with _charging or _is_charging (for example binary_sensor.zap263668_charging), or contains discharge_inhibit, and treats it as a discharge inhibit signal. When the sensor is on, battery discharging is paused regardless of what the schedule says.
The discharge inhibit only affects discharging — it does not change the TOU schedule, trigger battery charging, or interfere with the EV charging session in any way.
Some grid tariffs charge for your highest power draw rather than only for the energy you use — the Swedish effektavgift, the Flemish capaciteitstarief, and similar. A single quarter-hour or hour of high import can then cost far more than the spot-price saving that caused it. Left alone, BESS optimizes only for energy cost, so it can happily grid-charge at full power in the cheapest hour and set a new peak.
Peak shaving limits how much BESS may import from the grid. Enable it in Settings → Home → Peak Shaving:
- Max grid import — the cap, in kW. During the window the battery covers any load above it, and grid-charging is throttled so that house load plus charging stays under it.
- Only during a time window — on (the default), the cap applies between the start and end times on the days you tick, for tariffs that only measure certain hours (for example weekdays 07:00–19:00). Off, it applies around the clock on the days you tick, for tariffs that measure every quarter-hour.
This is a fixed cap. It doesn't know what your tariff costs, so set it to the level you want to stay under.
Letting the cap follow your month's peak (optional). On a tariff billed on the month's highest import, importing below the peak you have already set this month costs nothing extra — the bill is already at that level. Only importing above it raises the bill. If your meter exposes a "highest import this month" value (on a Belgian P1 meter, maximum demand current month), map it in Settings → Sensors → Peak Shaving Month Peak. BESS then uses, for each period:
cap = the larger of your free peak level and this month's peak so far — but never more than Max grid import
- Free peak level is the peak your tariff doesn't charge for — 2.5 kW in Flanders, where a month below that counts as 2.5 kW. Set it in the Peak Shaving settings. Leave it at 0 if your tariff has no free level.
- Max grid import stays the hard ceiling, for months where winter heating, an EV or night charging genuinely need more.
For example, with Max grid import 5 kW and a free level of 2.5 kW: early in a month where your peak is 1.4 kW, BESS holds imports to 2.5 kW instead of charging at 5 kW and setting a new 4.8 kW peak. Later in the month, after a cold evening has pushed your peak to 4 kW, the cap rises to 4 kW and BESS can use that headroom freely. On the 1st the peak resets and the cap drops back to the free level.
A few things to know:
- The entity must report kW or W. If it is missing, unavailable or reports anything else, BESS stops planning and shows an error on the dashboard rather than guessing — planning against the wrong peak could set a new one. Remove the entity mapping to go back to the fixed cap.
- The cap shapes BESS's plan. A load BESS did not forecast, such as an EV starting, is not held back by it.
- If your forecast load alone is above the cap, BESS cannot avoid importing — it imports as little as it can, and the next run sees the higher peak.
Access detailed explanations of optimization decisions:
- Why specific charging/discharging was chosen
- Alternative options considered
- Profit calculations and risk assessment
- Compare different time periods
- Analyze seasonal patterns
- Track long-term ROI progress
- Export data for external analysis
- Create automations based on BESS strategies
- Display key metrics on your HA dashboard
- Set up notifications for significant savings or issues
- Monitor weekly trends rather than daily fluctuations
- Adjust settings seasonally as usage patterns change
- Keep sensors updated for accurate optimization
- Review monthly reports to track ROI progress
- Ensure price integration is working - this is critical
- Verify all sensors are accurate - garbage in, garbage out
- Let the system learn - performance improves over first month
- Consider larger battery if consistently hitting capacity limits
- Check this guide for common issues
- Review logs in Home Assistant for specific error messages
- Check GitHub issues for known problems and solutions
- Post in Home Assistant Community with specific symptoms
- Share your results - help others understand benefits
- Report bugs with detailed logs and system configuration
- Request features based on your usage patterns
- Help others in the community forums
For installation and configuration details, see INSTALLATION.md
For developers interested in contributing, see DEVELOPMENT.md