Energy Compass — states and strategies guide

English · Polski

This guide explains what Energy Compass does, every state its entities can report and the conditions that produce each state, and the six dispatch strategies. It describes release 0.1.43. The mathematical contract behind each rule lives in model and limitations; installation is described in the Installation section, and dashboards in the installation guide.

Energy Compass is advisory. It computes a plan and publishes it as Home Assistant entities. It sends no messages by itself, and it writes inverter settings only when you enable the optional Deye controller (off by default), which does so through the Solarman integration; notification blueprints and other controllers decide for themselves whether to act on the plan. See Deye inverter controller.

Contents

1. Installation
2. How it works
3. Entity overview
4. Optimizer status — calculation lifecycle
5. Alert and forecast validity
6. Operating modes — the planned battery state
7. Consumption levels — BOOST, CHEAP, NORMAL, LIMIT
8. Windows and flexible energy depth
9. Dispatch strategies
10. Automatic strategy switching
11. Window notifications
12. Cost card
13. Deye inverter controller (Solarman)
14. Energy Atlas (optional)
15. Offline replay tool
16. Reason code reference

Installation

This section takes you from an empty Home Assistant to the first plan, step by step. You need a running Home Assistant and, for the full benefit, an inverter with a battery; you do not need to know Energy Compass first. Polish households are the main path (PLN, tariff G12, RCE sell price, net billing), and the same steps apply to any other currency and tariff.

Requirements

• Home Assistant 2026.9.1 or later.
• scipy, the numerical solver. The integration installs the exact pinned version from its manifest (scipy==1.18.1); you install nothing yourself.
• Raspberry Pi and other ARM64 hosts work. The tested ARM64 Core/Python/solver combination and representative benchmark results are in runtime validation.

Install the integration

1. HACS (recommended). In HACS open Custom repositories and add https://github.com/datamindzio/ha-energy-compass as an Integration. Download Energy Compass, then restart Home Assistant.
2. Manual. Copy this repository's custom_components/energy_compass directory into the custom_components folder of your Home Assistant configuration directory, then restart.

Add the integration

Open Settings → Devices & services → Add integration → Energy Compass. The setup is a short wizard; nothing is saved until its last step.

1. First form. Fill in Name, Currency (no automatic conversion) and Timezone, choose the optional Preset (provider profile) and set Pv enabled and Battery enabled. The same form offers three optional starting profiles: Prosumer settlement, Polish distribution tariff and Inverter. They pre-fill editable tuning values once, for this new installation only, and never set a price; Polish profiles require currency PLN. See Setup profiles for what each profile fills in.
2. Detected sources. Energy Compass looks for Solcast, rce_pse, Solarman (Deye) and your Energy dashboard sources by integration identity, not by entity name, and offers them as rows. Keep the ones you want and continue: they are bound and Preview and save opens. Nothing found, or nothing kept, opens the main menu instead. See Detected sources; PV can also use the Energy dashboard solar forecast.
3. Main menu. Work through the groups you need; each can be revisited later in Configure. - Tariffs → Buy source for the buy price. For Polish G11/G12/G12w choose Polish tariff schedule, which needs no YAML: pick the operator and group, then type the peak rate (Buy rate) and, for G12/G12w, the Off-peak buy rate in Tariffs → Fixed rates and transformations. Zones, clock and holidays are in Built-in Polish tariffs. - Tariffs → Sell source for the sell price. For Poland choose RCE market price (PSE), which takes the sensor of the rce_pse integration. - Load forecasting holds the numbers behind the household consumption forecast. A new installation starts from the daily estimate you type there (Daily load kwh, 10 kWh/day by default). Recorder history is used once a household load source is bound: keep the Household load history row in Detected sources, or use Sources → Add source → Load. Load forecasting then tunes the history window (Lookback days, Minimum samples, Recency half-life days) and the fallback. - Sources reviews and edits every bound source, including PV; Battery and Hardware capabilities hold the battery limits and the grid import limit. The planning, outlook, performance and presentation groups appear after Show expert settings (see Expert settings).
4. Preview and save. The preview normalizes the inputs, shows their coverage, units and ages, and solves a bounded base plan before anything is saved. The base plan must be feasible to save. On first setup you also tick the confirmations for the displayed buy source and household load source (a fixed buy rate of zero means free import; the default household estimate is 10 kWh/day), then confirm the save.

To try Energy Compass without any provider entities, create a synthetic setup: name Synthetic, currency EUR, timezone UTC, preset Generic, PV and battery off; the README (English, Polski) lists the remaining values.

After installation

The integration creates one device with the native sensors, binary sensors and the Strategy select described in Entity overview. Right after saving, the Optimizer status sensor reads calculating and turns ready when the first validated plan is published. If it reports invalid_input, timeout or infeasible, see Optimizer status for the reason.

After an update through HACS, restart Home Assistant and reload the browser page (on the mobile app, restart it). The frontend caches the integration's labels; without a reload, new options such as Energy Atlas can show as blank items.

Optional next steps

Each step is independent; the linked section has the details. Options and Configure are the same button on the integration's page in Settings → Devices & services.

• Deye inverter controller. To let Energy Compass write the plan to a Deye inverter through Solarman, open Options → Deye controller. Off by default; see Enabling the controller.
• Notifications. Turn on Notify enabled in Notification preferences, then copy the notification blueprint, which lives outside the HACS-installed folder. See Window notifications and Opt-in notifications.
• Automatic strategy switching. The strategy_switch blueprint picks one dispatch strategy per day. See Automatic strategy switching and Import the strategy switch blueprint.
• Dashboards and cost card. Ready-made dashboard examples and the cost card are described in Dashboard examples and the Cost card.
• Energy Atlas. The optional telemetry service is under Configure → Energy Atlas; see Energy Atlas.

How it works

Each calculation proceeds as follows:

1. Snapshot and validate inputs. Prices, PV forecast, load forecast (from recorder history), battery SOC and daily counters are read and checked for freshness, units and plausibility.
2. Build the problem. Native tariff slots (typically 15 min) over the planning horizon (24 h by default), hardware limits, SOC bounds, the carried operating-mode commitment and the active strategy bundle.
3. Solve the base plan. A mixed-integer linear program minimizes cost (plus strategy weights) under energy balance, battery, grid, mode-duration and export/charge-policy constraints. The proven optimum is published; when solve_time_limit_s runs out first, the best validated solution found so far is published instead and marked time_limited with its mip_gap.
4. Probe consumption. For each display interval, the solver is rerun with 1 kWh of extra load; the cost difference is the incremental cost of one more kWh, which is classified into a consumption level.
5. Profile flexible loads. Separate solves for 3, 5, 10, 15 and 20 kWh blocks measure how much flexible energy can be scheduled before the price degrades.
6. Publish. One coherent generation updates all entities; unchanged entities are not rewritten.

Recalculation cadence

• Periodic: refresh_minutes (default 15, max 60) aligned to the wall clock; the Deye hybrid setup profile pre-fills 60.
• Input-driven: at most once per minimum_replan_seconds (default 900 s, 0 disables) while a valid plan is retained; SOC counts as changed only after moving soc_trigger_percent (default 5 %) from the value that started the last calculation.
• Boundaries: at each native settlement boundary the existing plan advances (consumed rows are dropped, mode clocks tick) without a solve.
• Plan lifetime: a new plan is valid until generated_at + 2 × refresh_minutes, capped by forecast coverage.

Load forecast

The history forecast is a per-hour mean of complete hours of the last lookback_days, in the local timezone, grouped weekday/weekend (group_weekends) and needing minimum_samples hours per bucket. A plain mean follows a level change only as fast as the window turns over: after a 28-day lookback a house that started heating this week is still forecast at mostly last month's level, and the morning is the first to show it.

forecast_half_life_days (Recency half-life days, default 0 = off, range 0-60) weights each sample by 0.5^(age / half-life), with the age counted from the start of the forecast. The result is still a mean, so margins stay in the reserve logic (Peak-period reserve). minimum_samples counts samples, not weight. With 0 the forecast is the plain mean as before.

benchmarks/load_forecast_backtest.py forecasts each day at local midnight from the hours before it and reports MAE and bias (forecast − measured, kWh per hour) for the morning (06-13) and evening (15-22). It takes a Home Assistant recorder (--recorder-db, --statistic-id), a CSV of hours or a synthetic scenario. Measured on the synthetic scenarios (70 days, 28-day lookback, evaluated over the 20 days after a step of the morning level; not the household's own history):

Evening columns after the first are changes against the plain mean. A half-life of 5 days is the shortest that keeps the evening within 5 % on both scenarios, and recency weighting cuts the morning error by a third; a single level ratio over the whole day (last N days / lookback) moves the evening the wrong way and was not built. The default stays off until the numbers are reproduced on the household's own recorder with the command above; set 5 to turn it on.

Setup profiles (new installations)

Three axes on the first (User) setup form, Prosumer settlement, Polish distribution tariff (buy_tariff) and Inverter, pre-fill editable tuning for a brand-new installation. Each axis is chosen once; all default to Generic or None (no assignments), and picking a profile applies its assignments to the draft immediately. This is revision 3 of the setup profiles; an entry created under revision 1 or 2 keeps its record and is never re-resolved. The pinned values below (0.20, 0.60, 0.13) were measured or backtested on one site — a G12 buy tariff, net-billing RCE sell and a Deye LFP battery — and are a starting point, not a universal default.

Settlement axis:

Polish distribution tariff axis (buy_tariff): the profile only pre-selects Tariffs → Buy source → Polish tariff schedule for the chosen tariff; it assigns no setting and no price, and the rates stay at 0 until you type them. Every catalog profile requires PLN.

Inverter axis:

Every pre-filled value stays fully editable and is never re-applied once the entry exists — not by Configure, not by Reconfigure. While a new installation is still being set up, changing the preset on the Installation step re-resolves the settlement profile: the 1.23 sell multiplier is added or dropped to track the preset (or an RCE market price sell source saved in the meantime) unless you have already edited it. Binding a pre-filled key to a helper overrides the pre-fill at save time; the Preview lists that key as edited, naming the helper and its effective value.

Polish settlement and tariff profiles require currency PLN; choosing one with another currency is rejected, on the field that caused it. Setup profiles never set a tariff price (buy_rate, buy_off_peak_rate, buy_distribution_rate, buy_distribution_off_peak_rate, sell_rate, buy_addition, sell_addition, monthly_charge) and never touch a strategy-owned setting. They never enable the deposit model either: every installation starts with it off.

Sell only PV (limit_export_to_pv) stays on with every settlement profile — a Polish prosumer may only sell energy produced by their own PV — and is turned off either by switching to the max_export strategy or by setting limit_export_to_pv to off directly; the explicit setting persists across strategy changes.

The 1.23 deposit multiplier applies together with a raw-RCE preset (pse, pse_solcast) or a raw-RCE sell source (Tariffs → Sell source → RCE market price (PSE): a forecast with a price floor and every binding in PLN/MWh). New-entry saves re-evaluate it until the installation is created; Configure and Reconfigure never do. With examples/rce-sell-price.yaml, which already applies the floor and the 1.23 factor itself, keep the sell multiplier at 1 (see tariff helper).

Revision 3 adds one rule to this: when the sell source is a forecast entity that already applies its own settlement (a settlement attribute that names a multiplier, as in the sell template of examples/rce-sell-price.yaml), the 1.23 multiplier is not assigned, even with preset pse or pse_solcast, and binding such a source later removes a 1.23 you did not edit. Binding that template through Detected sources also sets the sell multiplier to 1.

Net-metering's sell_multiplier is a one-time copy of the ratio, not a link to the buy price: it is an approximation (the yearly kWh bank and G12 band mismatch are not modelled), and a later edit to the buy price does not update it.

A net-metering installation runs the battery in the inverter's own self-use mode. Set the inverter to self-use (load first, no grid charging, no battery export), keep allow_grid_charge off and allow_battery_export off (both are off by default and stay off with these profiles), and do not enable the Deye controller. Net-metering is not settled per hour: under the Renewable Energy Sources Act (consolidated text Dz.U. 2026 poz. 68, art. 4) fed-in energy is settled against energy drawn at the ratio 1 : 0.8 (1 : 0.7 above 10 kW) and the balance is carried forward for 12 months, so an exported kWh is worth ratio kWh of a later import — nothing once the year's credit covers the year's import — and the fixed part of the bill steps with the annual draw (capacity-fee bands at 500, 1 200 and 2 800 kWh). None of that is a price per hour or lies inside a 24-48 h horizon, so the plan cannot lower the yearly bill. The planner stands down there: no engine, strategy or profile change, and the costs shown (expected_net_cost, consumption_cost, the cost card, tools/replay.py) stay hourly prices — the kWh are exact, the money is an approximation.

Measured on 40 simulated homes (G11 and G12, ratio 0.8, 10 kWh battery, one year re-planned every hour against the same battery in plain self-consumption, valued with the annual bill, ADR-0008): the default plan (cost_min, as the profile ships) has a yearly gain against self-use, bill plus battery wear, of −93…+70 PLN (mean −1; + = cheaper, − = dearer), never lowers the bill by more than 10 PLN, and raises the annual import by +33…+704 kWh. Priced hour by hour, as Home Assistant reports it, the same G12 plan shows a gain of +343 PLN per year that the settlement does not pay. With Allow grid charge on (13 homes) the yearly gain against self-use, bill plus battery wear, is −209…+139 PLN (same sign convention), and the import rises by +897 kWh (median). Limits: simulated homes, one battery size (10 kWh), one year of prices, hourly intervals, G12 zones netted as one mean rate.

Preview shows setup-profile provenance for a profiled new entry: which keys each axis pre-filled, the buy source pre-selected by a buy_tariff profile, any value edited after pre-fill (including a helper-bound key, with the helper's effective value), and settlement notes — Sell only PV off, a sell source that already applies its own settlement multiplier, raw RCE prices not floored at 0 (with the RCE market price shortcut as the fix) or floored while the 1.23 multiplier is missing, or a net-metering sell that no longer tracks buy — shown only for installations that used a setup profile. For a net-metering profile Preview always adds one more note, and a second when Allow grid charge or Allow battery export is on (English only):

• "Note: net-metering is settled on yearly kWh (an exported kWh takes back 0.8 kWh within 12 months), not on hourly prices: price-driven dispatch does not lower the yearly bill and the costs shown are an hourly approximation. Run the battery in the inverter's own self-use mode and do not let a controller follow this plan." (0.7 on the 70 % profile.)
• when Allow grid charge or Allow battery export is on, "Note: Allow grid charge is on: under net-metering energy sent through the grid comes back at 0.8 and raises the yearly import; turn it off." (naming the one that is on, or "Allow grid charge and Allow battery export are on").

The selection, together with the setup-profiles revision that resolved it, is stored on the config entry (setup_profiles) and included in diagnostics.

Built-in Polish tariffs

For a Polish household, Tariffs → Buy source → Polish tariff schedule (G11/G12/G12w) replaces the tariff helper YAML (the YAML example stays the fallback). Pick one of eleven catalog entries; the zones come from the distributor's 2026 tariff, and you type the rates: Tariffs → Fixed rates and transformations holds Buy rate (G11, or the peak rate) and Off-peak buy rate (G12/G12w). Both rates must be above zero or the calculation fails closed with a message naming those fields. The price of a slot is rate × multiplier × VAT factor + addition, as for a fixed rate. The schedule needs no entity and does not limit the planning horizon. It requires currency PLN.

Free days of G12w are Saturdays, Sundays and statutory holidays (1 and 6 January, Easter Sunday and Monday, 1 and 3 May, Pentecost, Corpus Christi, 15 August, 1 and 11 November, 24 December from 1 February 2025, 25 and 26 December); there are no substitute days. A meter that was not reprogrammed can ignore a newly added holiday such as 24 December; the YAML fallback's off_peak_dates covers that.

Clock. By default the zones follow local time (the Home Assistant time zone): a remote-read meter billed after hourly balancing uses wall-clock zones, so a day can have 23 or 25 local hours. An old non-remote meter keeps a fixed internal clock on winter time (the tariff clause in the sources above); turn on Old non-remote meter on winter time (fixed UTC+1) for it. To choose, compare your invoice's monthly day/night kWh with your hourly import data split by the windows Preview prints; if the summer months are off by about one hour, enable the winter clock. Season and weekday are classified on the date of the chosen clock. Preview prints the clock, today's off-peak windows and, for G12w, the statutory holidays in the horizon.

Enea G12. Enea sets the hours per meter: 8 hours within 22–7 (start 22 or 23) and 2 hours within 13–17 (start 13, 14 or 15). The default is 22 and 13 (Enea FAQ); the extra form asks for both, so check your meter or bill.

Distribution tariff. A buy source that is not a tariff schedule (a fixed rate, an entity, or a dynamic energy price from a forecast) can still take the distributor's zones: Tariffs → Buy source → Distribution tariff (zones for the distribution rates) (currency PLN) offers the same catalog, winter-clock flag and Enea hours, or None (single zone). The zones apply to the two distribution rates of the deposit model (buy_distribution_rate, buy_distribution_off_peak_rate); their band edges become interval boundaries for the planner, as for a schedule. They do not change the buy source. A schedule source keeps its own zones, so choosing a tariff schedule drops a stored distribution tariff. Preview shows both parts of the first interval's buy price, the energy part and the distribution part. The buy row of Sources → Review and edit sources shows the distribution mode, the zones and the rate per zone.

RCE sell price. Tariffs → Sell source → RCE market price (PSE) saves the sensor of the rce_pse integration (attribute prices, value rce_pln, end dtime, PLN/MWh, 15 minutes) as a forecast source with a price floor of 0: the raw value is floored at 0 per kWh before the multiplier, VAT and addition (max(RCE, 0) × 1.23 with the net-billing multiplier). The floor is visible in Preview and is dropped when the source is switched away from forecast or edited so that it is no longer a raw PLN/MWh RCE source. For a new installation, the PL net-billing profile then assigns the 1.23 multiplier; in Configure and Reconfigure set the sell multiplier yourself. Without the rce_pse integration use examples/rce-sell-price.yaml.

Detected sources (new installations)

After the first (User) form of a new installation, Detected sources looks for sources Energy Compass can use, binds the ones you keep and opens Preview: the quick path to a first plan. It never runs in Configure or Reconfigure, never changes the preset or a setup profile, and never touches the buy source (the buy_tariff profile and Tariffs stay the only buy path). Candidates are recognised by integration identity (the integration, the entity's translation key and the Energy dashboard preferences), never by entity id or name, so renamed or localized entities are found too. If nothing is found, or you keep nothing, the main menu opens as before. Every bound source stays editable in Sources.

Energy dashboard first. Energy Compass should read the same data as the Energy dashboard. For every role the dashboard covers (lifetime counters, solar, grid and battery power, battery SOC and the solar forecast) the dashboard's choice ranks first; the integration signals below are the fallback. For power it uses the normalized power sensor the dashboard stores. When both exist and differ, both are offered, the dashboard one is preselected and the line names both. The same entity found twice is offered once.

Controls. A row with one candidate is a single checkbox, ticked (BMS SOC: unticked). A row with several candidates is a drop-down: the preselected candidate, the others in order of preference and Do not bind last. A tie that cannot be resolved offers Do not bind preselected. Among equally ranked candidates the single Deye Solarman config entry breaks the tie, for example the dashboard's two grid meters resolve to the inverter's counter.

• Solarman. Only config entries with at least one device from manufacturer Deye count. The inverter and its BMS packs are devices of one config entry. With several Deye entries every Solarman row has several candidates and no default. The sign conventions (battery + is discharge, grid + is import) were verified on one Deye profile only; the offered value is shown so you can check it.
• Validation. Each candidate is checked with the parsers Preview uses, on the exact binding that would be stored. Forecasts must parse (tomorrow may be unpublished); counters and power need a numeric state in W, kW, Wh or kWh; a SOC must be a finite value from 0 to 100 (a state SOC needs unit %); a load statistic needs a cumulative state class and kWh or Wh. An unusable candidate is not offered; the notes list it with the reason.
• Sell template. Binding it sets the sell multiplier to 1, because the template already applies its floor and multiplier. Setup profiles revision 3 then does not add 1.23 again (see Setup profiles). A stale template is not offered.
• rce_pse. The sensor must report PLN/MWh (the integration default); the PLN/kWh price unit option is rejected here and in Tariffs → Sell source → RCE market price (PSE), because it would price energy a thousand times too low.
• Solcast. detailedForecast exists only while the option Include detailed forecast half-hourly is on. The day 3–7 sensors, the hourly detail and the rooftop-site sensors are never used.
• BMS SOC. It is offered unticked. With imbalanced battery cells the BMS SOC and the battery SOC can differ by more than Battery → Soc disagreement percent (default 5 %), and then every plan is blocked. Tick it only if both agree over a full day.
• Counter estimator. It is offered unticked next to the BMS row, as Counter estimator (recommended when the BMS SOC is unreliable), when exactly one Solarman Deye config entry has the four sources. Ticking it replaces the soc and bms_soc rows (a ticked BMS SOC moves to the estimator as a comparison reading) and opens its settings before Preview (see Counter SOC estimator). The BMS SOC can be wrong even at 100 %, which is the case the estimator is for.
• Gates. sell appears only with currency PLN. With PV off there are no pv, pv_power or pv_energy rows; with the battery off no soc, bms_soc, soc_estimator or battery_power rows. The two daily counters are never gated.
• Stored age limits of the measurements: 3600 s for battery_power, grid_import_power and grid_export_power; 86400 s for pv_power, the lifetime counters, the battery charge and discharge energy counters and the daily counters (a constant 0 W at night never updates the state).
• Never detected: buy; throughput_today (to use daily_cycles provide one entity with the AC-side charge plus discharge since midnight, see source requirements); battery_energy, battery_charge_power, battery_discharge_power, battery_charge_energy and battery_discharge_energy (the optional measured calibration counters); and helpers.

Preview then shows the usual acknowledgements for a new entry. Its Back to the main menu checkbox leaves Preview without validating or saving anything. The matching reference tables are in source requirements.

Energy dashboard solar forecast

Sources → Add source → PV → Energy dashboard solar forecast (mode solar_forecast) reads the same solar forecast as the Energy dashboard, from every integration with an Energy solar-forecast platform (Solcast, Forecast.Solar, Open-Meteo and others). Pick one or more loaded integrations; their forecasts are added, as the dashboard adds them. The form defaults to the integrations in the dashboard's solar settings. Detected sources offers the same mode first when the dashboard has a forecast.

• Hourly dashboard rule. Every value is Wh in the local hour that contains its key; values in one hour are summed. The plan sees hourly energy from the current hour to the last hour with a key, up to 49 hours ahead; keys older than two days are ignored.
• Night hours that the provider omits count as 0 Wh. A gap inside the day is also 0, so a provider gap makes the plan more conservative.
• Provider notes. Solcast's platform uses the forecast type chosen in its options (key_estimate, for example the 10th percentile) in 30-minute steps, while the Solcast sensor mode reads pv_estimate. Forecast.Solar reports irregular keys; Energy Compass reads them as the dashboard does.
• No age check. wh_hours carries no publication time. A forecast update is picked up at the next recalculation (scheduled or event-triggered), not by itself.
• Failures act like a missing entity: an integration that is missing, not loaded, without a platform or without data makes the inputs invalid with a message naming its domain.
• No mixing. Entity forecast arrays and Energy dashboard forecasts cannot be combined (both typically come from the same provider, so the energy would be counted twice). Saving one removes the other. Turning PV off in Installation clears both.

Preview adds a line PV source: Energy dashboard solar forecast … for this mode.

Counter SOC estimator

Some packs report a BMS SOC that is wrong even at 100 % (imbalanced cells, a BMS that re-anchors on its own). The counter SOC estimator is a second way to get the battery SOC: instead of reading an SOC entity, Energy Compass computes it inside the integration from the battery's lifetime charge and discharge energy counters. Choose it under Configure → Battery SOC source (sources.soc_mode = counter_estimator); the default stays Entity, the SOC source bound in Sources. The estimator then replaces the SOC and BMS SOC sources for the planner, for the LFP balance and for the native Deye controller. The BMS SOC is not trusted anywhere: there is no BMS-based anchor or fallback, and a BMS SOC source, if you add one in the expert settings, is only shown beside the estimate for comparison.

The arithmetic. The estimator carries an anchor, a known energy above the pack's 0 % point at known counter values, and adds what the counters have moved since:

E = anchor energy − (discharge − anchor discharge) + eta × (charge − anchor charge) + pending

E is clamped to 0 … capacity and the SOC is E / capacity. eta is the charge efficiency of the counters (the counters sit at the battery terminals, the plan's efficiencies are AC-side). pending integrates the battery power between two counter steps, so the value moves smoothly although the counters report in coarse steps (a step is integrated for at most 120 s, pending is held within ±2 kWh and restarts at zero whenever a counter changes). A counter that goes down re-anchors at the current energy (anchor kind reset); a rise faster than 100 kW since the counter's previous step (at most one hour back) is ignored as a glitch unless it repeats. The estimate never jumps on its own.

Zero is a voltage. 0 % is the pack voltage you enter as Pack voltage that is 0 % (empty_voltage, in the pack-voltage scale of the voltage sensor, for example the inverter's cutoff). It is a property of your pack, so there is no default and the step refuses to save without it. The capacity is the usable energy between that point and full; it defaults to the battery capacity of the Battery group (an expert override exists) and the planner scales the estimator fraction by the battery capacity, so keep the two equal.

A full pack is a voltage too. A full anchor needs the charge to have reached Pack voltage a charge reaches at full (full_min_voltage, the same scale as the 0 % voltage). It is a property of your pack, so there is no default and the step refuses to save without it (it must also be above the 0 % voltage). A pack reaches this voltage only while charge current flows and relaxes a few volts once the charge stops (one site: 556 V at the stop, 546 V at rest), so a full candidate starts only within 30 minutes of a reading at or above it, and a running one only needs the resting pack to stay at or above 97 % of it; below that it breaks (logged as below_full_voltage). This voltage, not the counters, says the pack is full: counters that have drifted low must not be able to keep a full pack from correcting them.

Anchors: physical evidence only.

The full anchor needs the charge current limit (the native controller's entity, or the expert source Charge current limit) and the grid power with the PV power (or the load power); the grid path needs the native controller's program and grid-charge entities. Without them it never fires and the estimate stays an unanchored count. Without the native Deye controller (disabled, or the blueprint engine) the dispatch state and the TOU program are invisible to the estimator, so the full rule rests on the measured grid export (or the derived surplus where export is capped or zero) alone: grid charging never anchors, and the options step says so. For the first 14 days after the estimator starts (or is seeded), full candidates are only logged in the full_candidates attribute, unless Anchor on candidates from day one is on, because the hold has never been seen on a real taper. A candidate shows the start, the values, which path held (export, surplus, grid or balance) and its outcome (anchored, or candidate for one not applied) beside energy_before_kwh, the energy the counters gave just before.

Charging stays allowed during the hold. While a full candidate runs (from its first reading until it qualifies or breaks), the native Deye controller does not close the charge path: where the profile would lower or zero the battery charge current (CHARGE_PV and SELF_CONSUME once the SOC reads 100 %, HOLD, the full-pack rule and the CHARGE_GRID stop at 100 %) it keeps the charge current at the charge cap (limited by max_current, max_power_w / V and the current-ceiling hysteresis), and the program direction stays as the profile sets it: nothing is added, grid charging is never opened for it, and HOLD keeps its own Grid program and grid current. Without this a taper that the controller itself cut would end the evidence and the hold would never complete. A candidate also continues while the plan moves to HOLD (a candidate never starts in HOLD): the charge limit in force, at least 2 A, shows that the controller is holding the path open, and in HOLD only the export and surplus paths count, since its Grid program only holds the SOC. Leaving for CURTAIL, BASE or DISCHARGE_GRID, a charge limit under 2 A for more than 120 s (the controller itself writes 0 A for a moment when the program direction changes, which a running candidate lives through; the limit never starts one), or a voltage under the full voltage ends the candidate, and the profile goes back to its own values. The blueprint engine is unchanged and closes the charge path where its profile says so, so the hold may break there.

Staleness. The estimate is stamped with the newest report of the voltage, current and power sources, but never fresher than its counters allow: once the counters are older than their observed update step, taken as 1.5 times the largest of the last five (at least one minute, at most 15; 15 minutes until a step was seen), the estimate is as old as the counters even while power is fresh. After a restart the first step does not integrate the power stored before the downtime.

Never 100 % by guess. Clamping at the top never creates an anchor. A count that reaches the capacity without a full anchor shows 99.9 % with unanchored_top: true; the energy above the capacity is kept (it is not dropped) and shown as excess_kwh, and leaving the top first spends it. 100 % is shown only after a full anchor, until the pack falls 0.1 kWh below the top. While the top is confirmed, charge counted above the capacity is losses and float, not stored energy: the anchor stays a full one from its original time and takes the current counters, so excess_kwh stays 0 and the energy does not carry a phantom surplus into the next discharge. A full anchor is an upward jump and goes through the same rebase as a BMS recalibration (a retained plan for up to 300 s while fresh reports confirm it).

What reads the estimate.

• Planner. The coordinator reads the estimate through the same validation as an SOC entity (age, range, jump check), stamped with the newest report of the voltage, current and power sources. There is no entity between them, so a template reload or a restart no longer makes the source unavailable.
• Deye controller. With the estimator on, the native controller's SOC fact is the estimate: the telemetry gate, the Voltage-mode full-pack rule and the reached checks use it. The controller also reads whether a full candidate runs and then keeps charging allowed (see Charging stays allowed during the hold). Capacity mode is not supported with the estimator: in that mode the inverter compares the SOC thresholds of its programs with its own BMS SOC, so a target in the estimator's scale would be wrong. Saving the estimator is refused (the inverter is in Capacity mode) while a native controller is enabled and the inverter's battery operation mode reads Capacity; switch the inverter to Voltage first. While the estimator is the source the controller also treats Capacity as not commissioned, so a later switch of the inverter to Capacity parks it in the base profile (mode_not_commissioned) instead of writing SOC thresholds. Voltage mode is unaffected (its thresholds are voltages). The deprecated blueprint engine keeps its own soc_entity input and is not changed.
• LFP balance. A balance counts a pack as full only on physical evidence, not at SOC ≥ the threshold: a full or full_balance anchor, or a standing full candidate (one that has held the full hold, also while the first 14 days only log candidates and apply no anchor). A reading the arithmetic pushed to the threshold never credits a balance. A balance row whose Grid program reaches its voltage and tapers is such evidence, so a completed balance is recorded and not planned again every day. The balance hold (balance_hold_minutes) starts counting only once that evidence has held for the full hold, so with the estimator the planner asks for a window of the balance hold plus the full hold (two hours at the defaults). During the first hour the plan shows that window as an ordinary balance row (the controller charges, the tracker is not yet holding); once the candidate qualifies the tracker holds and the remaining minutes of the balance hold are planned from now. A window of the balance hold alone ends before the evidence qualifies and completes nothing.

Diagnostics. The diagnostic sensor sensor.<name>_soc_estimator (SOC estimator, %, device class battery) exists while the estimator is on or in shadow. Its state is recorded; of its attributes only anchor_kind is recorded: energy_kwh, anchor_at, anchor_age_h, throughput_since_anchor_kwh, pending_kwh, unanchored_top, excess_kwh, full_candidate, measured_capacity_kwh, eta_charge, capacity_kwh, mode (counter_estimator or shadow), bms_soc (comparison only), full_candidates (the last 20) and anchors (the last 20). When the throughput since the last anchor exceeds Warn after this many capacities (drift_warn_cycles, 3) times the capacity, the repair issue The SOC estimator has gone a long time without an anchor appears; it only warns, plans are not blocked, and it clears at the next anchor. The diagnostics download has a soc_estimator block with the same detail and no entity ids.

Settings (Configure → Battery SOC source; Expert settings adds the second table):

Every source is read in the base unit its entity declares (kWh or Wh, W or kW, V, A).

Setup and detection. On a new installation the Detected sources step offers Counter estimator (recommended when the BMS SOC is unreliable) unticked when one Solarman Deye device has the charge and discharge counters, the pack voltage and the pack current. Ticking it replaces the SOC rows and opens the estimator's settings before Preview, where the pack voltage that is 0 % and the lowest pack voltage of a full pack are required.

Migrating from a template estimator. A site that runs a YAML template estimator can move without a jump:

1. Open Configure → Battery SOC source, keep Entity, tick Shadow run, enter the counters, the voltage, the current and the 0 % voltage, and tick Start from the anchor of the existing SOC template (offered when the bound entity has the attributes anchor_kwh, anchor_charge, anchor_discharge, anchor_kind, anchor_at; pending_kwh is optional). The planner keeps using the template while sensor.<name>_soc_estimator runs beside it.
2. After at least one day compare them with tools/soc_shadow.py on the recorder history of both entities (or a directory of state dumps as tools/shadow_compare.py reads them). The acceptance is that the energy differs by at most 0.2 kWh in 95 % of the minutes and that no full or empty anchor of one is missing from the other.
3. Switch Battery SOC source to Counter estimator, then remove the template's YAML block and reload the templates. Reloading templates makes the template SOC unavailable for a moment; the estimator no longer depends on it.

Limits of this version. Detection offers the estimator for Solarman Deye devices only (other inverters: set the sources in the expert group); efficiency and capacity are never learned or changed automatically; the Capacity-mode restriction above applies.

Expert settings

The main menu of Setup, Configure and Reconfigure starts with the common groups only: Installation, Sources, Battery, Hardware capabilities, Battery SOC source (with a battery), Tariffs, Load forecasting and Notification preferences. Show expert settings adds the four expert groups, Planning, Consumption outlook, Performance and input quality and Presentation, and Numeric helper bindings; Hide expert settings hides them again. The view is per flow and is not stored. Hidden settings keep their values and keep working. A script that drives the options flow over REST must post show_expert before it selects a hidden group, otherwise Home Assistant rejects the step.

Saving options

Saving Configure is applied live. The integration adopts the new settings, sources, helpers and tariffs without reloading the entry, so no entity becomes unavailable and the published plan keeps running as a retained plan (plan_retained=true, refreshing=true, optimizer calculating) until the recalculation publishes its replacement. The Deye controller keeps executing that plan and accepts the new one when it is published; it does not fall back to the base profile. Source and helper bindings are re-subscribed at the same time. The entry still reloads, with the previous plan lost until the first new calculation (the controller keeps executing its accepted plan meanwhile), when the save changes which entities exist or how they are named: Periodic LFP balance charge (lfp_balance), Enable flexible energy depth (flexible_load_enabled), Expose costs (expose_costs), Expose windows (expose_windows), turning the counter SOC estimator (or its shadow run) on or off, the installation name or the currency. A running Energy Atlas is refreshed in place (state tracking and site attributes), without a restart of its sink. Reconfigure always reloads.

Entity overview

<name> is the integration entry's title.

Cost sensors can be disabled with Presentation → Expose costs, window timestamps with Expose windows, and flexible depth with Consumption outlook → Enable flexible energy depth. Battery balance is disabled by default and enabled with the LFP balance setting; its attributes carry last_completed, next_due, days_overdue, planned_start, planned_end, planned_mode, pv_series, hold_progress_minutes, hold_required_minutes and threshold_percent.

Availability rule

Optimizer status — calculation lifecycle

Attributes: last_calculation_started_at, calculations_since_load, expired_previous_generated_at, and measured_calibration when calibration counters are bound (see Measured calibration). Diagnostics add calculations_last_hour and calculations_last_24h.

Measured calibration (optional)

Plans carry calibration and capacity_calibration, which stay unvalidated until you set them and say nothing about how far the configured values are from reality. Two read-only diagnostics compare them with your own counters. They never change a plan. A block appears only while its sources are bound; with none bound, measured_calibration is absent from the Optimizer status attributes (excluded from the recorder) and from the integration diagnostics.

How it is measured:

• Hour boundaries. Each counter reading is stamped with the source's own report time and reduced to its value at every full UTC hour by interpolating between consecutive readings. An unchanged counter is exact however long the gap; a moving one across a gap longer than 2 hours gives no value. Energy of an hour is the difference of its two boundaries.
• Idle counters. A counter that writes its state only when it moves (a template, utility meter or integration helper) does not report while idle. One that has not changed for more than 2 hours is taken to hold its value up to now, as long as its last report is no older than the source's maximum age (24 hours by default; with the age check off, no limit), so its idle hours count. Only that age tells a frozen source from an idle one: past it the hours drop out. Idle hours appear 2 hours late, and a source that holds a steady non-zero rate without writing its state is read as idle.
• Missing hours, resets and glitches. An hour without both boundaries is skipped, never filled. A counter that goes down is a reset or a glitch: neither the step down nor the segment that recovers from it yields a boundary, so the hours on both sides drop out of both ratios (a counter that restarts after a reset is used again from its second reading). A rise faster than 100 kW (plus 1 kWh) between two readings is rejected the same way, as is an hour delta above 101 kWh, so a single absurd reading costs a few hours and never skews a ratio.
• Rebinding. Stored counter values belong to the entity, attribute, multiplier and unit they were read from. Binding the role to something else clears that counter's history (the other counter keeps its own) and the ratio fills again from then on.
• Forecast as used. Each published plan records its PV forecast for the current hour (scaled up from the remainder when the plan was solved mid-hour). The fullest plan of the hour is kept; a plan that covers less than half of the hour is not recorded. The current, unfinished hour is not compared.
• Storage. One small row per hour: about 31 days of counter values and 15 days of forecasts, kept in the integration's own store (energy_compass.<entry_id>.calibration), saved at each new hour and on unload, restored on start. An invalid store is dropped with a warning.

Superseded results

If inputs change while a solve runs, the finished result is still published when only inputs (not configuration) changed — it is fresher than the retained plan — and a new solve follows. Configuration, registry and invalid-input changes discard in-flight results.

Alert and forecast validity

Forecast valid (binary_sensor.<name>_forecast_valid)

Attribute current_guidance_valid is true only when the consumption probe for the current interval produced a known level. Other attributes: coverage_end, requested_end, coverage_complete, input_ages, missing_sources, load_quality.

Alert (binary_sensor.<name>_alert)

Attributes: code, reason, since, plan_retained, last_successful_plan_at. A retry does not clear the alert; only a successful new plan does.

Plan retention

A retained plan is never extended beyond its original coverage and is not carried across an integration reload or Home Assistant restart. Saving Configure does not reload the integration, so it does not end the plan: see Saving options. The Deye controller keeps its own accepted copy of the plan across an entry reload, but drops it at a restart.

Operating modes — the planned battery state

The Energy compass sensor shows the operating mode of the current interval; every row of the plan's intervals attribute carries dispatch_mode. There are six modes. Per interval of h hours: activity = minimum_mode_power_kw × h (default 0.1 kW) and surplus = max(PV − load, 0).

When mode duration is disabled (minimum_mode_minutes = 0), the display state is derived from flows by precedence: CURTAIL → CHARGE_GRID → CHARGE_PV → DISCHARGE_GRID → SELF_CONSUME → HOLD.

A planned LFP balance hold does not add a mode: its rows reuse CHARGE_PV or CHARGE_GRID and carry balance_hold: true in the plan's intervals attribute.

Transitions and minimum duration

The diagram is simplified with HOLD as a hub: after its minimum duration any mode may be followed directly by any other available mode.

Rules (defaults: 60 min, 0.1 kW):

• Every newly started mode — including HOLD and CURTAIL — lasts at least minimum_mode_minutes. Only a final passive HOLD/CURTAIL run may be clipped by coverage. The coordinator persists the accepted mode and its start; recalculation and restart preserve the clock.
• SELF_CONSUME follows the load. The inverter discharges whatever the house draws, so the plan never pairs a small discharge with grid import: in a SELF_CONSUME interval the battery covers the whole demand, and import appears only once the discharge is at its interval power limit or the battery has been emptied to its reserve. Otherwise the row is HOLD with full import. The rule also holds with minimum_mode_minutes = 0: there are no modes then, and the discharge in any interval the flows label SELF_CONSUME is bound the same way. A carried CHARGE_PV/SELF_CONSUME commitment is executed the same way. If the battery runs out before it ends, the rest of the commitment is HOLD with full import (it starts no clock of its own: the commitment's deadline stays the only one). The same happens — from the first interval if need be — when the battery cannot cover the house and still keep the inverter standby loss (idle_drain_kw) of the later intervals, with no PV or grid charge to pay it in time. HOLD starts only in an interval without a PV surplus the pack could take, in every committed interval: with one, the row stays CHARGE_PV. A committed interval in which neither mode has anything to follow (net load and PV surplus both below minimum_mode_power_kw × h, for example a night base load under 100 W) is HOLD by classification and does not end the commitment: the plan bridges it (no HOLD clock starts, and the persisted commitment keeps its mode and start) or, when the battery is spent or full, starts a real HOLD run there as in any other interval (dispatch_policy.carried_idle_starts lists the bridged intervals). With a full battery on a site that cannot pass the PV, such an interval may be CURTAIL as well, like any other committed interval; it is then not bridged. When the terminal rule cannot be met afterwards (preserve_initial with no later PV or grid charge to refill what the house drew) the interval is a HOLD with full import, as for a spent battery, and the battery ends where it began. The plan is infeasible until the commitment ends when the daily throughput budget cannot pay the minimum activity the commitment asks for; the rare remaining cases (a standby loss or the preserve_initial terminal requirement that only PV surplus the plan cannot bank could cover) are listed in model and limitations. A direction the legacy direction guard blocks (initial_battery_mode) is not open: a pack that may not charge has no CHARGE_PV to follow and one that may not discharge has no SELF_CONSUME, so an interval with only that direction to follow is bridged too. A flexible-load probe is bridged the same way, as long as the probe it takes leaves the interval idle; a PV surplus it takes below the minimum activity is not one the pack could take, so HOLD may start on it.
• CHARGE_PV follows the surplus. The inverter charges with every watt the house does not use, so the plan never pairs a partial charge with grid export: in a CHARGE_PV interval the battery takes the whole PV surplus, and export appears only once the charge is at its interval power limit or the battery has been filled to its upper bound. Otherwise the row is not CHARGE_PV. The rule also holds with minimum_mode_minutes = 0: there are no modes then, and the charge in any interval the flows label CHARGE_PV is bound the same way. A carried CHARGE_PV/SELF_CONSUME commitment is held to the same rule. If the battery is full before it ends (the next interval could not take even the minimum activity above the upper bound), the rest of the commitment is HOLD with the surplus exported, or CURTAIL where the site cannot pass the surplus (above the export cap or the inverter rating), as the inverter does with a full pack. The released HOLD starts no clock of its own — the commitment's deadline stays the only one — so it may turn to CURTAIL (which starts its own clock) before then. A released HOLD goes back to CHARGE_PV/SELF_CONSUME in any later interval of the commitment while the pack is still depleted: the pack takes the surplus, and a HOLD could not pass the PV above the export cap (on a site with grid_export_kw = 0 that is every sunrise). A HOLD released from a depleted pack also goes back in an interval whose PV the site cannot pass, where a HOLD has no legal flow: a plan followed one interval would otherwise reach the next boundary with a carried commitment and no plan. A HOLD released from a full pack does not go back there: it keeps its own clock across the boundary, and where the site cannot pass the PV it is CURTAIL (above). Nor does it go back because the terminal rule has spent the pack: that counts for the release and for the return of a HOLD that began on a depleted pack (the coordinator carries it as released), not for this one, which returns only when the pack is depleted in itself. A pack exactly at the reserve (the inverter's usual empty state) is depleted in this sense, not a safety exception: a carried SELF_CONSUME there is released and charges like one 0.01 kWh above the reserve. Where that released HOLD has no plan (a commitment no plan can keep) the house is still never left without one. The plan is the first of these that has a solution, each tried only when the one before has none and all within the recalculation's one time budget: the release; the commitment's own HOLD with its clock, as the safety exception below, which curtails where curtailment is allowed; the plan without the commitment (only for a carried CHARGE_PV or SELF_CONSUME, which a plan followed one interval can leave in a state its own minimum duration then makes infeasible). After that last plan a first mode that is still CHARGE_PV or SELF_CONSUME keeps the commitment and its clock; any other first mode starts a clock of its own. The return is the commitment going on, not a new run: the commitment's deadline stays the only clock. A pack that empties again inside the same commitment is released again and goes back again, as often as the commitment lasts. The release survives the interval boundary: the plan marks the rows of such a HOLD (dispatch_policy.released_hold_starts) and the coordinator keeps the commitment and its start, flagged as released, instead of recording a HOLD with a clock of its own, so the next plan goes back to CHARGE_PV as the first one published. That HOLD may go on past the commitment's deadline without a clock; a return to CHARGE_PV/SELF_CONSUME after the deadline is a run of its own and gets a fresh start. The first committed interval is judged the same way against the observed state of charge: a pack already within the lowered ceiling of that interval (for example after the interval that filled it was carried out) may be HOLD or CURTAIL at once, in either member mode. An observed state of charge at the upper bound is the safety exception below. A committed interval in which the pack fills while the rest of the surplus is still above the export cap or the inverter rating is planned: CHARGE_PV cannot fill the pack and curtail in the same interval, so the pack counts as full for the next interval, which may be HOLD or CURTAIL, once it is within that interval's curtail need of the ceiling (the PV that must go to the pack or be curtailed, at least the minimum activity). With minimum_mode_minutes = 0 the rule costs solve time (see the table in model and limitations). A site that cannot curtail (allow_curtailment off) with grid export capped, or the inverter rated below the PV, would be left with PV that has nowhere to go once the pack is full. In most cases it is planned rather than reported as infeasible (measured below): the PV above what the cap and the inverter can pass (the curtail need; with a minimum duration at least the minimum activity) is spilled in an interval whose pack cannot take it, labelled CURTAIL (the inverter throttles by itself; the Deye controller runs the PV charge profile at the planned current on a row that charges and its HOLD profile on one that charges nothing). The gate is the room of the pack: the interval starts at or above the ceiling less what the pack would have to absorb, so a pack with a little room that cannot take the surplus spills too, and a pack that can take it never does, whatever the sell price. The part the pack cannot take by its charge power (the curtail need less charge_kw × h) is spilled whatever the room: the pack charges at its power and the inverter throttles the rest in the same interval, so a pack with room and a charge power below the surplus has a plan. With a minimum duration a CURTAIL run keeps the next interval's gate open (it discharges nothing, so the pack only drifts down by its standby loss, or rises where the row charges), a CHARGE_PV or SELF_CONSUME run may end in CURTAIL when the pack fills inside it (or in HOLD when the PV it had to take is over as well), and room left below the gate stays empty during a CURTAIL interval until the next replanning reads the real state of charge. A CURTAIL run carried into the next plan keeps spilling while the need lasts, also when the pack has dropped below full meanwhile. A site that can pass its PV is unchanged. Measured on seeded sweeps (2400 problems solved once): with the spill 533 of 589 are planned at minimum duration 0, 565 of 606 at 15 minutes, 582 of 620 at 30 minutes and 503 of 585 at 60 minutes (without it 171, 160, 149 and 97). A bell-shaped day followed interval by interval to its end keeps a plan all the way in 207 of 214 days at 15 minutes, 172 of 189 at 30 minutes and 158 of 197 at 60 minutes (without the spill 27, 23 and 23); most of the others have no plan from the first interval. The rest stay without a plan, as before, mainly for two reasons the plan does not cover: a HOLD run that the plan itself starts and that meets PV the site cannot pass while the pack has room (the spill there would be the plan's own choice), more often at 60 minutes, and some draws with a flexible-load probe. The forced part (T-066) cut the 2400 problems solved once without a plan from 226 to 76, and the rolling draws not followed from 190 to 57 of 1800, with no problem solved once that main planned newly infeasible; of 3600 days followed interval by interval on four seeds one that main follows to its end stops at a boundary with no plan on any site. A carried HOLD or CURTAIL commitment more often leaves a plan (T-082): where the site cannot pass the PV, a CURTAIL takes the carried HOLD over with room in the pack, in the intervals of that run where nothing is forced, and a CURTAIL run goes on through an interval with no need, while it is inside its minimum duration, into a need that comes back smaller than the room; that cut the 2400 draws without a plan from 76 to 38 and the rolling draws not followed from 57 to 16 of 1800, with none newly infeasible (counts, better and worse draws and commits in the model document) (model and limitations).
• CURTAIL goes on through a PV gap. A CURTAIL run lasts the minimum duration, and PV can drop inside it. A HOLD in an interval with PV below the minimum activity (minimum_mode_power_kw × h) inside that duration is the run going on, not a new HOLD: the inverter has nothing to curtail and the pack and the grid do what HOLD does. It counts for the CURTAIL clock, starts no HOLD clock, and ends with the run's duration; the HOLD after it starts its own clock. It applies to a run begun by PV that the export cap or the inverter cannot pass, and to a CURTAIL carried in; dispatch_policy.carried_idle_starts lists these rows too, and the persisted commitment keeps its mode and start there. It holds inside a carried CHARGE_PV/SELF_CONSUME commitment as well (a CURTAIL released from it goes on through a PV gap within the commitment's own duration), and for an interval with a load below the minimum activity.
• CURTAIL takes over a HOLD that cannot pass the PV. HOLD takes no curtailment, so a HOLD that has to last (a carried HOLD, the HOLD that the safety exception below puts in place of a CHARGE_PV at the maximum state of charge, or a HOLD that began earlier in the plan, for example after a CURTAIL run that ended in a PV gap) has no legal mode in an interval whose PV, after the house, is above the export cap (grid_export_kw) or above the inverter rating. There the inverter curtails by itself and the interval is CURTAIL: it takes the HOLD over and from then on is an ordinary CURTAIL run with its own minimum duration (which outlasts the HOLD's remainder; a PV gap inside it is bridged as above). Only where the site cannot pass the PV: anywhere else CURTAIL inside a HOLD's duration would be a label to leave it with, and is not offered. The HOLD after the run starts its own clock. A HOLD released from a carried CHARGE_PV/SELF_CONSUME commitment has no clock of its own and is not taken over. A flexible-load probe counts: its load is part of what the site passes, so the takeover is offered only for the probe loads that leave PV above the cap.
• CURTAIL charges what the pack can take. When the PV above what the site passes (above the export cap after the house, or above the inverter rating) is more than the pack takes by its charge power in one interval, neither CHARGE_PV (which curtails nothing) nor a CURTAIL that charged nothing could hold it; the inverter charges at the charge power and curtails the rest, and so does the plan: the interval is CURTAIL, with the charge between zero and the PV left after the house. What the pack takes there is PV only: a CURTAIL interval that charges imports nothing, not even for the house. Where the pack is at the reserve under a carried CHARGE_PV/SELF_CONSUME commitment (a sunrise on a zero-export site with a 1 kW pack and 3.6 kW of PV) this is the plan itself, not a fallback. In a carried commitment CURTAIL is offered in such an interval whatever the pack held before; with a flexible-load probe, only for the probe loads that leave PV beyond the pack. The CURTAIL that opens such a run goes on through the run's minimum duration: the later intervals of the commitment offer CURTAIL while it is under way, also where the PV is no longer beyond the pack (it does not charge there, so a pack at the reserve waits for the end of the run: up to 105 minutes after the first interval at a minimum duration of 120), because the run may not change mode inside its duration and the commitment's CHARGE_PV is not a way out of it. With allow_curtailment off such an interval is planned only as a forced spill, where the pack has less room than the PV the site cannot pass: the CURTAIL interval then charges what the pack takes and spills the rest. The same holds for a pack with room: it charges at its power and spills the PV beyond it, whatever its room.
• PV-follow group: CHARGE_PV and SELF_CONSUME share one clock — in both the inverter charges from surplus and covers a deficit from the battery, so flipping between them is not a mode change.
• Any other change (source, destination, HOLD or CURTAIL) starts a new clock, except the HOLD released from a full pack or an empty battery above, which has none. Idle HOLD cannot fund an active run.
• Coverage: a new active mode needs a full duration of forecast coverage remaining.
• Safety exception (pause, not reset): during an unexpired active commitment the current row shows HOLD when the observed SOC is already at the upper bound (charging modes — observed_soc_maximum) or at/below the reserve (discharge modes — observed_soc_minimum; not a carried SELF_CONSUME, which is released as a depleted pack above, unless that release has no plan), or when a carried CHARGE_GRID meets a price above the ceiling before its deadline (grid_charge_price_limit). The interrupted mode and deadline stay stored; no other mode may start before that deadline, except the CURTAIL that takes the HOLD over where the site cannot pass the PV (above). Exposed in dispatch_policy.safety_exception.
• Strategy change (reset): writing a new strategy drops the carried commitment for the next plan, which starts unlocked (see strategy-switch release).
• Setting minimum_mode_minutes = 0 disables duration and minimum-power rules; the SELF_CONSUME and CHARGE_PV load-following rules stay on.

Policies that gate modes

Setup profiles can pre-fill the import penalty, standby loss and terminal rule for new installations; see Setup profiles.

Net-billing deposit value

Under Polish net billing the value of exported energy is booked on the prosumer deposit, and the deposit pays only what you owe the seller for energy; distribution charges are paid in cash. After 12 months the unused part is refunded, but a month's refund cannot exceed ρ × the value exported in that month (ρ = 30 % with hourly RCE settlement, 20 % with monthly RCEm), where the value is the export value without the 1.23 coefficient; the rest is void. While the deposit is short, or its unused part still fits under the cap, one currency unit of export or of energy-part import is worth exactly one unit of cash and the planner needs no correction. Once the cap binds, one more unit of export is worth only ρ/1.23 of a sell price that contains the 1.23 coefficient (0.244 for ρ = 30 %, 0.163 for 20 %) and the energy part of an import costs nothing in cash (it is paid from money that would expire). The deposit model lets the planner see that, but it does not pay off: off is the setting for every site, also a site whose deposit is forfeited, and manual is experimental. The auto model was withdrawn; a stored auto is read as off without an error or an Alert. off is the default and then the plan is byte-identical to a build without the model.

What was measured, on a one-year replay of 40 hourly-RCE homes with a 10 kWh battery, billed by the yearly formula and by the monthly ledger:

• no factor lowered the yearly bill by more than 44 PLN, and the factor at the cap raised it in all 40 homes, by 68–431 PLN (yearly formula) or 21–306 PLN (monthly ledger);
• with monthly RCEm the factor changes the bill by less than 10 PLN;
• a site whose deposit is forfeited sets nothing: deposit_model stays off. Switching battery export off because of a forfeited deposit cost 154–662 PLN a year in all 16 homes measured (with grid charging and battery export allowed).

Two parts of the buy price. The model must know which part of a buy price is energy (payable by the deposit) and which is distribution (paid in cash). The buy price of an interval is the sum of the two, and you give the distribution part as rates, never the energy part:

included:  buy = buy source price                  (the source is an all-in price, e.g. a tariff schedule)
added:     buy = buy source price + distribution   (the source is the energy price only)
energy part = clamp(buy − distribution, 0, max(buy, 0))

Use added for a dynamic energy price (a forecast such as RCE-based tariffs) or a price list typed as on the invoice. It changes the buy price itself, for the planner and for reported costs, and works with the deposit model off. Example: dynamic energy price 0.25 at midday and 0.95 in the evening peak plus the G12 distribution rate 0.540 give buy prices 0.79 and 1.49; at night 0.45 + 0.143 give 0.593. When the cap binds the planner sees only the distribution part: 0.540, 0.540 and 0.143. A negative energy price keeps its real price and has no energy part to waive.

The cap pressure π (0 = deposit short or within the cap, 1 = cap binding) gives two factors that exist only inside the optimizer:

export value factor  φx = 1 − π × (1 − ρp)    1 → ρp,  ρp = ρ / 1.23
import energy factor φe = 1 − π               1 → 0
planning buy  = buy − (1 − φe) × energy part of buy
planning sell = φx × max(sell, 0) + min(sell, 0)

• manual (experimental): φx is your export_value_factor as typed, even below ρp. Only π is derived from it, π = clamp((1 − φx) / (1 − ρp), 0, 1), so φe = 1 − π follows (a value at or below ρp devalues the energy part of imports fully). At the cap (π = 1) φx is ρp = ρ / 1.23, not ρ: 0.244 for 30 %, 0.163 for 20 %. With deposit_refund_percent 100 it is 1/1.23, not 1; the setting that never cancels anything is deposit_model: off.
• No distribution part (the distribution rates are 0): the whole buy price would count as deposit-payable and an import would look free. With π above 0 φe is therefore forced to 1 and reason is split_missing; φx still applies. Set the distribution rates to use the model.
• Negative sell prices stay whole: the factor scales only the positive part, because a negative price is a real charge.
• Reported costs do not change. Net cost, Plan.grid_cost, the cost sensors, consumption levels and the maximum_grid_charge_price ceiling all stay at invoice prices; only the planning objective uses the factors, under every strategy and before the strategy weights.
• Battery sale threshold, worked example (PGE G12 2026 gross prices, round trip 0.89, wear 0.05 per kWh): selling from the battery and buying the energy back at night pays above about 0.73 currency/kWh while the cap is not binding. With the cap binding the threshold is about 0.88 at ρ = 30 % and about 1.31 at ρ = 20 % (a seller that refunds 36.9 % / 24.6 % of the deposit: about 0.71 / 1.07). What changes with the cap binding is the use of surplus PV (worth 0.40 × ρp = 0.10 instead of 0.40 at a sell price of 0.40 and ρ = 30 %, so it goes to the battery and flexible load first) and night grid charging, which stays profitable.

Diagnostics are in the plan attribute dispatch_policy.settlement:

Peak-period reserve

The load forecast is a mean, so a plan that drains the battery exactly to the reserve by the end of an expensive period falls short on roughly every second day. peak_reserve_margin_kwh asks the solver to enter each expensive period with that much energy on top of the forecast need. It requires Limit grid-charging price: an expensive period is a run of intervals whose buy price is above maximum_grid_charge_price, i.e. where the battery cannot be refilled from the grid. The target applies to the end of the cheap interval right before the run:

entry target = min(usable capacity, reserve + peak_reserve_margin_kwh + run deficit / η_discharge)

where the deficit sums max(0, load − PV) over the run. Intervals inside the run carry no target: the plan is recalculated during the run, and a target there would make it buy at the expensive price to rebuild the buffer once the house had used it — the opposite of what the buffer is for. For the same reason a run that is already in progress when the plan is calculated gets no target, nor does a run where PV covers the house. The target is soft: a shortfall is billed at the median expensive price minus the ceiling and reported as peak_reserve_shortfall_kwh; reported costs never include it. Inside the run the buffer is ordinary stored energy, so the plan may still export it when selling pays more than the later purchase — down to the forecast need, plus export_reserve_margin_kwh when that is set, not below (next paragraph). It works in every strategy, next to the autonomy floor. Warnings: peak_reserve_requires_grid_charge_ceiling (setting above 0 while the ceiling is off) and peak_reserve_inactive (no upcoming expensive run with a deficit in the horizon).

Buffer under an export. export_reserve_margin_kwh (default 0 = off) is its own setting: it does not follow peak_reserve_margin_kwh, and a site that already runs the entry buffer keeps its plans and solve times until this one is set. It needs battery export and Limit grid-charging price (warnings export_reserve_requires_battery_export and export_reserve_requires_grid_charge_ceiling). It applies inside the run, but only to an interval in which the plan exports from the battery: there the battery must keep reserve + export_reserve_margin_kwh + deficit until the next cheap interval / η_discharge after the interval. An interval without an export has no target, so a recalculation during the run never buys at the expensive price to rebuild the buffer; the plan simply stops exporting. The target is soft, billed at the median buy price of those intervals (what a missing kWh of buffer costs when the load runs above the forecast) and counted in peak_reserve_shortfall_kwh. The plan therefore keeps the buffer as long as the export earns less than that purchase would cost: the cheapest export interval shrinks first. Only intervals where sell price × η_discharge is above the grid-charging ceiling carry a target, and a run that no cheap interval follows in the horizon has none. Cost: it adds rows, and the solve is slower where the buffer binds. In the benchmark sweep (40 days of 96 and 192 intervals, binding days only) 0.5 kWh gave up 0.7 of 3.6 kWh of battery export on the evening-window days, left the slowest solve at 2.4 to 3.9 s at 96 intervals (5.0 to 6.1 s at 192) and ended none at the 10 s limit; from 0.75 kWh the solve of a long evening run took 4 to 6 times longer at its median and some days reached the limit (1 of 40 at 96 intervals and 0.75 kWh, 4 of 40 at 192 intervals and 1.0 kWh). Raise the setting in steps and check time_limited on the plan (details in model.md); at 0 nothing changes.

Sizing of the entry buffer: 0.25–0.75 kWh is a reasonable start. In a backtest on one household with a two-zone tariff, 0.5 kWh halved the mornings that ran out before PV (42 % → 21 %) at roughly neutral cost: the buffer is not lost, it is used later or valued at the end of the horizon.

Consumption levels — BOOST, CHEAP, NORMAL, LIMIT

The Consumption compass answers "how attractive is using one more kWh in this interval?". For each display interval (default 60 min over 24 h) the solver reruns with probe_kwh (default 1 kWh) of extra load. Consumption cost = (probe plan cost − base plan cost) ÷ added kWh. Because the battery and grid are re-optimized, this is the true marginal cost — it can differ from the tariff price (e.g. solar that would otherwise be exported costs its lost export value).

Percentiles come from successful probe costs across the reference horizon (default 24 h) using linear interpolation. If a full reference probe fails, short_coverage decides: absolute_fallback (default: keep BOOST/LIMIT absolute rules and the minimum-tariff CHEAP rule) or unavailable.

Limit: probes that do not finish in time. Every probe is a full, exact solve of the whole planning horizon and is known only when it finishes within probe_time_limit_s (default 2 s); the probes run one after another inside total_time_limit_s (default 60 s). A probe that does not finish stays unknown — it is never replaced by an approximate cost. One unknown full reference probe is enough for short_coverage (reason is reference_probe_failed), and an interval whose own probe is unknown has no level.

How long a probe takes depends on the strategy and on the number of intervals in the planning horizon. self_sufficiency and backup_ready keep SELF_CONSUME on through the night, and the load-following rule makes their probes many times slower. Probes with a known cost at the default limits, quarter-hour prices and hourly display intervals, measured on a fast desktop CPU (Apple M4 Max):

So with self_sufficiency or backup_ready the consumption levels are unknown for nearly every interval already on the default 24 h horizon, and on a 48 h horizon no strategy completes its probes (with a 15-minute display interval 18–67 of 96 are known). At 48 h the base plan of these two strategies also runs into solve_time_limit_s and is published as time_limited. minimum_mode_minutes = 0 does not lift the limit: at 24 h 1 of 24 (self_sufficiency) and 8 to 17 of 24 (backup_ready) probes are known, which is still short_coverage. A slower host, such as a Raspberry Pi, reaches each limit at a shorter horizon.

The flexible energy depth is bound by the same two settings: each of its five solves gets probe_time_limit_s, inside what the probes left of total_time_limit_s. With self_sufficiency or backup_ready at 24 h none of the five finished within the default 2 s, so the depth is unknown (profiles UNKNOWN, reason timeout); cost_min at 24 h and self_sufficiency at 12 h got all five.

What was measured to help on the same host, at the default 24 h horizon:

• backup_ready: probe_time_limit_s 10 and total_time_limit_s 120 gave all 24 probes (47 s of probing per recalculation) and, with the same probe limit, all five flexible-depth solves (21 s more). With probe_time_limit_s 5 one probe was still late and the levels stayed on short_coverage.
• self_sufficiency: only the maximum of both settings, probe_time_limit_s 30 and total_time_limit_s 300, gave all 24 probes, after 199 s of probing per recalculation, and the five flexible-depth solves took 48 s more. That leaves no headroom for a slower host or a harder day.
• A 12 h planning horizon gave all 12 probes for both strategies at the default limits, with the slowest self_sufficiency probe at 1.5 s of the 2 s limit; the plan then looks 12 h ahead only.

The table, the per-probe times and the command that reproduces them are in docs/runtime-validation.md.

Windows and flexible energy depth

Windows

Adjacent intervals of the same level merge into windows. next_boost_start, next_cheap_start and next_limit_start show the start of the active or next window of that kind; next_change shows the next known different level.

start_basis is forecast, or first_observed when an already active window keeps its first observed start across recalculations and restarts. next_change stops at unknown coverage rather than guessing.

Flexible energy depth

Answers "how much deferrable energy can I use cheaply?". The solver independently places 3, 5, 10, 15 and 20 kWh blocks at up to flexible_load_max_power_kw (default 3 kW).

Groups: small (3/5 kWh), medium (10/15 kWh), large (20 kWh).

A block that has no solution on the problem the plan was solved for is tried again on the later rungs of the plan's own ladder (the commitment's HOLD, then the plan without the commitment), each against the plan of that rung, so a level is never priced against a plan of another problem. It is only a carried CHARGE_PV/SELF_CONSUME commitment whose plan sits on the edge of a full pack that needs this. Two neighbouring levels solved on different rungs have no block cost between them, and a level on another rung than the first (anchor) level is not judged against the anchor's allowed price: both are UNKNOWN. A level is published with the reason that ended it: infeasible only if every rung it reached had no solution, while a timeout or another solver error ends it at once as that error.

Dispatch strategies

select.<name>_strategy chooses which objective bundle the solver uses. Every strategy keeps all hard physical constraints; strategies change only planning weights and a small set of policy flags. Reported costs (expected_net_cost, consumption cost) always stay real currency — strategy penalties never appear in them.

What each strategy changes

The solver minimizes

grid     = Σ ( import_weight × buy × import + import_kwh_weight × import
               − export_weight × (sell − pv_export_margin) × export )
           + battery_export_penalty_per_kwh × battery_export
autonomy = soc_target_weight × Σ (deepest shortfall per window below the autonomy floor)
peak     = peak_import_weight × max(import power)
caps     = cap_violation_weight × Σ (import/export above soft caps)
objective = grid + wear + episode hurdles + autonomy + peak + caps − terminal credit

"User setting" means the strategy leaves the option as configured. Forced values apply only to options the user has not set explicitly: any strategy-owned option that deviates from its shipped default is recorded in explicit_strategy_fields and is never overridden by a bundle.

All numbers above are defaults of Planning options: self_sufficiency_import_price_per_kwh (5.0), self_sufficiency_export_penalty_per_kwh (0.20), backup_target_soc_percent (80), backup_shortfall_price_per_kwh (2.0), pv_swap_margin_per_kwh (0.05), peak_import_price_per_kw (0.50), cap_violation_price_per_kwh (2.0), grid_friendly_import_cap_kw / _export_cap_kw (0 = site connection limit), autonomy_margin_per_kwh (0.10).

Autonomy floor (used by self_sufficiency, backup_ready, pv_swap)

The floor asks: will the battery carry the house through the next period where load exceeds PV? The horizon is split into windows by cumulative net surplus; within each window the target is

soc_target[t] = min(usable capacity, reserve + (1 / η_discharge) × Σ deficit until window end)

The deepest shortfall below the target is billed once per window at soc_target_weight = expected night rebuy price (median night buy price) + autonomy_margin_per_kwh. The floor looks 48 h ahead on PV/load forecasts even before tomorrow's prices are published. It is soft: violations become autonomy_shortfall_kwh on the plan instead of an infeasible solve. It needs a PV source (autonomy_floor_requires_pv otherwise).

LFP balance charge

LFP packs need a periodic full charge and a short hold at the top so the BMS can balance cells and re-anchor its SOC. With Periodic LFP balance charge (lfp_balance) on, Energy Compass tracks the last completed balance and plans the next one. The tracker itself keeps observing SOC and advancing its state even while lfp_balance is off; turning the setting on only starts publishing balance windows and the diagnostic sensor.

A balance completes after SOC stays at or above the threshold for the whole hold. A reading below the threshold restarts the hold. Only observed time counts: an unavailable or stale SOC gives no credit, and two full readings more than soc_max_age_seconds apart restart the hold from the later one (a hold whose last full reading is older than that is neither holding nor complete). Completion is evaluated lazily — while full readings keep arriving, the hold completes on the next check without needing a state change. Phases: ok → eligible (the earlier of 2 days or half the interval before due) → due; holding overlays whichever phase is active while a hold is running. A hold that starts while the balance is still ok (for example SOC back at 100 % the day after a balance) is tracked and completes, but is not scheduled: the optimizer gets no hold window and no miss cost for it.

The optimizer may pick one hour-aligned hold window: candidate windows start only on the whole hour, and while due, only within the next 24 h (an eligible balance may look anywhere across the horizon). Inside the chosen window SOC stays at or above the threshold and the battery does not discharge. Skipping costs 10 % of balance_value while eligible — small, so the planner normally balances only on cheap or free energy, but it still picks a grid window that costs less than that — balance_value × (1 + days overdue) once due, and 10 × balance_value during a hold that is eligible or due. A window is published as CHARGE_PV only when PV covers load in every one of its slots; otherwise (mixed PV/grid or pure grid, such as a night window) it is CHARGE_GRID, which additionally requires grid charging to be allowed and the grid-charge price ceiling (if any) to pass in every slot — with balance_hold: true on every row. With an optional pessimistic PV source the PV test is stricter. From the slot before the earliest candidate window to the horizon end, the battery's energy may rise up to full capacity instead of the configured SOC ceiling, so a hold is never blocked by soc_ceiling below 100 %; that lift only matters when the ceiling is below 100 %. Consumption probes keep the chosen window fixed so a probe's extra load prices the load, not the balance choice.

The Battery balance diagnostic sensor (sensor.<name>_battery_balance) reports ok, eligible, scheduled, holding or overdue, with last_completed, next_due, days_overdue, planned_start, planned_end, planned_mode, pv_series, hold_progress_minutes, hold_required_minutes, threshold_percent.

Pessimistic PV for the balance window

The balance window is chosen on the median PV forecast, so a low-PV day can leave the pack short of the threshold and the balance missed again. Sources → Add source → PV pessimistic (optional) binds a second, lower forecast of the same site (for Solcast, pv_estimate10; the Solcast presets propose that field). It takes the same interval-forecast mapping as a PV source; Review and edit sources lists, edits, extends with a continuation and removes it. It needs PV enabled. It can accompany either kind of PV source; the Energy dashboard solar forecast has no pessimistic series, so bind this one separately.

With it configured, a CHARGE_PV window is offered only if both hold on the pessimistic series:

1. Pack: charging from PV surplus alone (pv − load, at eta_charge and charge_kw, no discharge) lifts the pack to the balance threshold by the window start.
2. Window: PV covers load in every slot of the window.

Otherwise the start is offered only as CHARGE_GRID, subject to the usual grid-charge and price-ceiling rules, so the solver can pick a cheap grid window instead. The dispatch plan itself keeps using the median series. Without the source nothing changes.

The solver prices every window on the median series, where PV surplus can pay for a vetoed CHARGE_GRID window, so several starts would cost the same. To avoid a tie-break landing on an expensive slot, every CHARGE_GRID window offered while the pessimistic series is present (also one that is CHARGE_GRID on the median series alone) carries a ranking cost: the energy the pessimistic series leaves to the grid, that is what the pack still lacks to reach the threshold at the window start plus the load PV does not cover inside the window, at the window's buy prices. The solver adds 5 % of each window's excess over the cheapest window the solver can pick to that window's cost, so a window the pessimistic series still supports (CHARGE_PV) beats a vetoed one and, among vetoed ones, the cheapest wins. The addition never exceeds half the cost of skipping the balance. A start-0 window the pack cannot reach (it starts below the threshold) is left out of that comparison, so it never shifts the other windows towards a skip; the ranking can still tip a close call against the balance. It is a preference, not a strict tie-break: a start that is cheaper on the median series by more than 5 % of the difference in ranking cost still wins. It is not part of the plan's cost.

Trade-off: the pack test counts PV surplus only. A start the pack would reach only by charging from the grid before the window is offered as CHARGE_GRID alone, and is dropped when the grid-charge price ceiling blocks a slot of the window, so balance_no_window_in_horizon can appear where a window existed without the source.

The pv_series attribute of the Battery balance sensor and the balance_pv_series attribute of the plan sensor say which series decided the candidate windows: pessimistic when the source is configured and usable, median otherwise (also without the source); null when lfp_balance is off or there is no battery. The source is optional input and never invalidates the plan. If it is unavailable, stale, malformed, negative or does not cover the horizon, the windows fall back to the median series and the plan carries the balance_pessimistic_pv_unavailable warning. A source going stale raises no state change, so the fallback takes effect at the next periodic recalculation (refresh_minutes) or source change.

cost_min — cost minimisation

• Goal: lowest forecast cost: purchases − sales + battery wear − terminal credit.
• Changes: nothing; byte-identical to the plain model when import_penalty_per_kwh = 0.
• Behaviour: charges when energy is cheap (grid or PV), discharges into expensive hours, exports only when the spread beats losses, wear and the export-benefit hurdle.
• Choose when: everyday operation; the default and the fallback of the switch blueprint.
• Watch out: it may leave the battery low before a cheap-looking night if forecasts are wrong — no autonomy reserve.

self_sufficiency — self-sufficiency

• Goal: minimize grid kWh, not currency.
• Changes: every imported kWh costs at least max(5.0, highest |buy price| + 0.50, import_penalty_per_kwh), so import always dominates price differences; battery export costs an extra 0.20/kWh; autonomy floor on.
• Behaviour: fills the battery from PV, avoids grid charging and battery export unless needed, keeps enough energy for the next deficit window.
• Choose when: day/night price spread is small (the blueprint picks it when the spread is below 0.15 PLN/kWh), when prices are zero or negative, or when independence matters more than cost.
• Watch out: reported costs stay real — this strategy can cost more money than cost_min.

backup_ready — backup ready

• Goal: keep a large reserve for an outage.
• Changes: autonomy floor on and raised to at least backup_target_soc_percent (80 %) of capacity; its weight is at least backup_shortfall_price_per_kwh (2.0/kWh).
• Behaviour: refills to ~80 % and avoids discharging below it unless the shortfall is worth more than 2.0/kWh; the floor stays soft, so a plan always exists.
• Choose when: storm or grid-outage warnings, planned maintenance, cold winter nights. The blueprint's alert rule selects it when your alert entity is on.
• Watch out: combining it with a low grid-charge ceiling raises grid_charge_ceiling_below_autonomy_weight — the floor could be emptied but never refilled.

pv_swap — PV swap

• Goal: in low-PV seasons, buy cheap at night and sell the day's real PV output at a later, higher price.
• Changes: pv_export_margin (0.05/kWh) is subtracted from every sell price (the export must beat the night buy by at least that margin); Sell only PV forced on (daily export ≤ daily PV); grid-charge ceiling forced off (so night charging is not blocked); autonomy floor on.
• Behaviour: grid-charges overnight, lets the day's PV cover the house, then exports up to the day's generated PV in the evening peak.
• Choose when: tomorrow's PV forecast is below the daily load and evening sell × round-trip efficiency ≥ night buy + margin (the blueprint's pv_swap rule).
• Watch out: Sell only PV counts energy, not provenance — exported battery energy is limited in total to the day's PV, not traced to its origin.

max_export — maximum export

• Goal: pure arbitrage, maximize revenue from exports.
• Changes: export-benefit hurdle forced to 0, Sell only PV forced off (grid-charged energy can be resold), grid-charge ceiling forced off, autonomy floor off.
• Behaviour: charges whenever buy is low, discharges into the grid whenever the spread covers losses and wear; may do several export episodes a day.
• Choose when: exceptional sell prices, a tariff that rewards export.
• Watch out: most battery cycles; check whether your contract allows reselling grid energy. Never selected automatically.

grid_friendly — grid friendly

• Goal: flatten the grid profile — avoid high import peaks and limit export power.
• Changes: peak import term peak_import_price_per_kw (0.50/kW of the highest import power); soft import/export caps grid_friendly_import_cap_kw / grid_friendly_export_cap_kw (0 = site limit), each kWh above them costs cap_violation_price_per_kwh (2.0); autonomy floor off.
• Behaviour: spreads grid charging over longer windows, uses the battery to shave import peaks, keeps export under the cap.
• Choose when: capacity/power-based tariffs, a weak connection or a fuse near its limit.
• Watch out: caps are soft; excess is reported in cap_violation_kwh instead of failing. Never selected automatically.

Plan attributes for strategies

Strategy-switch release

A strategy change is a reset: the carried mode commitment is released so the new strategy is not trapped in the old mode's minimum duration. A current export episode is kept so its hurdle is not charged twice.

Automatic strategy switching

The optional blueprint strategy_switch.yaml picks one strategy per day. It runs at 14:05 (after RCE next-day prices and Solcast), retries hourly until 20:00 if next-day prices are missing, and reconciles a half-applied write at Home Assistant start.

A manual change of the select blocks the economic rules until the next successful scheduled run; the alert rule is never blocked. max_export and grid_friendly are manual-only. Setup details: installation guide.

Window notifications

The optional blueprint notifications.yaml tells the household when extra use is cheap (favorable window) or when an expensive LIMIT window is starting. Energy Compass itself never sends anything; Notify enabled in the integration options is the master switch. Setup: installation guide.

The message names the window's local times and suggests moving laundry, the dishwasher or car charging. The action receives notification_title, notification_message and event_kind.

Cost card

The optional card custom:energy-compass-cost-card (cards/cost/) shows the purchase cost of grid energy, the value of exported energy (the prosumer deposit in Polish net-billing) and the balance purchase − deposit: today measured and planned to midnight, and month and year from statistics. Install and full description: cost card guide.

The month and year deposit comes from the export value counter blueprint: it adds every increase of the export meter (export_energy), valued at the price forecast (export_prices), to a Number helper (counter); jumps above max_step_kwh are ignored.

Deye inverter controller (Solarman)

Energy Compass is advisory by default and writes to an inverter only when you enable the optional Deye controller (Options → Deye controller, off by default). The controller executes the plan on a Deye hybrid inverter through the Solarman integration: it writes three battery currents and the six time-of-use (TOU) programs, and reads every write back from the holding registers. With the native engine it runs inside the integration: no blueprint, automation, package, helper or configuration.yaml edit is needed, the accepted plan survives an entry reload, and Energy Compass owns the mode, the accepted plan, the session and the revocation, the timing of the next run and the stored runtime. It needs Energy Compass 0.1.38 or newer. Setup steps are in the installation guide. The deye_hybrid setup profile pre-fills idle_drain_kw 0.13 and refresh_minutes 60 for a new installation; see Setup profiles.

The earlier executor, the blueprint deye_solarman_controller.yaml, is deprecated. It still works in this release as the blueprint engine (the value of every entry created before 0.1.38) and is removed in the release after next, together with its generator tools/deye_controller/build.py, the energy_compass.controller_runtime and energy_compass.controller_import_package services and the sections below that describe it. Move to the native engine as described in Migrating from the blueprint.

Enabling the controller

Open Options → Deye controller, switch Enable the Deye controller on and choose the Solarman inverter device (it is preselected when there is only one). Energy Compass finds the six TOU programs (time, power, voltage, SOC and charging, 30 entities) on that device by the Solarman translation keys program_1_time … program_6_charging, derives the entity ID prefix they share and tracks them. It refuses the device when a program is missing or disabled, when the entity IDs do not share one prefix, or when another Energy Compass entry already controls it. Enabling reloads the entry once; moving the controller to another device applies live. Both are refused while the mode is not Off or a restore is pending: select Off and wait until restore_pending is off first, otherwise nothing could restore the base profile. The step is visible without the expert toggle.

Engine. The step has an Engine field. native (the default for a new enable) lets Energy Compass execute the plan itself and write the inverter through the Solarman entities and the solarman.read_holding_registers service; no blueprint or automation is needed. blueprint (deprecated; the value of every entry created before 0.1.38) keeps the Deye controller blueprint as the executor. Changing the engine reloads the entry and is refused while the mode is not Off or a restore is pending. The native engine finds the battery currents, operation mode, SOC, voltage and discharge counter on the same device by the Solarman keys battery_max_charging_current, battery_max_discharging_current, battery_grid_charging_current, battery_operation_mode, battery, battery_voltage and total_battery_discharge, and names what is missing. Only high-voltage packs (400–610 V) are supported: a pack measured below 400 V is refused.

Limits and takeover (expert settings). The maximum battery power defaults to the smaller of the charge and discharge power in the Energy Compass settings; the currents default to the entity's own maximum, capped at that power divided by 400 V. Hold, reached-discharge and balance currents, the grid-charge voltage ceiling, the commissioned battery modes, the previous automations to wait for, the telemetry entities, the discharge counter and an override for each entity can be set; an empty field keeps its default. Limits apply on the next run without a reload. When one blueprint automation exists, its inputs are loaded into these fields for you to review before saving.

Do not enable the controller on a net-metering installation: the right plan there is the inverter's own self-use mode (see Setup profiles).

An installation that ran the 0.1.36 package, has one Energy Compass entry and exactly one Solarman device with all six programs gets the controller enabled automatically at the first start of 0.1.37. The mode starts at Off, so nothing is written until you choose one; see Migrating from the package.

Supported hardware

The tested unit is a SG0*HP3 with control board firmware 3002-1095-11408. Firmware versions are recorded in the hardware attribute but not compared: nothing is known about per-firmware differences. A device whose type and protocol are not on the list is not blocked. It raises the repair issue "Deye inverter not verified" (a dismissible warning) and sets hardware.verified to false; use Simulation first, as for every installation.

Layout probe. Before the first write that forces a profile in a session, the native engine reads registers 108–177 and compares them with the states of the 27 entities it writes (the three currents and the 24 TOU values). Numbers and selects must agree; a select whose register holds a value outside the known map (Disabled, Grid, Sell) says nothing about the layout and is skipped, because the controller rewrites it anyway. Any other difference, a missing register or an unavailable entity stops the run with the runtime code blocked and the reason layout_mismatch, which lists the entities; nothing is written and the check repeats on the next run, because entities can lag one Solarman poll behind a manual change. The probe also runs in Simulation, so a wrong layout shows before Auto. A passed probe holds for the session, the device and the set of entities read: a changed device or an entity override probes again. Restoring the base profile does not wait for the probe, because it writes through Solarman's own entities and only the read-back depends on the layout; forcing a profile does.

Controller entities

Three entities exist only while the controller is enabled, a fourth with the native engine; they sit on the Energy Compass device. <name> is the entry title.

The IDs depend on the entry name and the language the entities were created in (a Polish instance gets names such as …_sterownik_deye); read them from the device page. The blueprint engine needs only the controller sensor; it finds the mode entity and the TOU prefix through its attributes.

The runtime sensor carries the recorded attributes restore_pending, reason, state, requested_mode, confirmed_mode, since, warning, takeover_blocked and accepted_generation, plus runtime and updated_at, which are not recorded. It is written at once when its code or one of the recorded attributes changes and at most once a minute for other changes. Acceptances, revocations, session drops, mode changes, imports and device changes go to a history of 50 entries in the store and in the integration's diagnostics (deye_controller); no events are fired.

With the native engine the runtime sensor also has last_run (not recorded): what triggered the last run, the decision, the planned commands, each write with its outcome (sent, failed, confirmed or blocked), the register layout probe result when one ran (probe: passed or failed: <entities>) and how the run ended. The last 50 runs are kept in memory, not in the store, and appear in the diagnostics as run_history; the last 20 runs that sent a command or ended with a runtime code other than ok are kept separately as run_history_notable, so routine runs cannot push them out. The engine runs when something it reads changes (a plan, the mode, a pause, the TOU facts, the next row or TOU boundary), on each full minute and when an inverter value changes; it does not run on every refresh of Energy Compass. A logbook entry names the old and new runtime code and confirmed mode whenever either changes.

Services

Modes

Auto writes; Simulation computes every target and records it in runtime without touching the inverter; Off releases control. Leaving Auto for Off restores the base profile once, confirms it, then leaves later manual settings alone. Disabling the automation skips that restore. A switch to Simulation while a restore is pending is refused: the mode goes to Off, the base profile is restored, and Simulation can then be chosen again.

Plan acceptance

Energy Compass accepts a plan inside the callback that publishes it, so the plan, status, validity and alert are one atomic view and there is no split publication. A publication is accepted only when all of these hold: its intervals are contiguous, every row has a known state, a boolean balance_hold and finite non-negative energies (prices may be negative), and one row covers now; the dispatch policy is present; it was generated after the session start and no later than now, it is newer than the accepted plan and it was generated after the last revocation; Forecast valid is on; there is no Alert; the status is ready with no refresh or retention in progress, or calculating while retaining a complete plan; and valid_until is in the future. The mode does not matter: acceptance runs in Off and Simulation too.

An optimizer status other than ready/calculating or an Alert revokes the accepted plan at the time of the publication, so a plan computed before the revocation is never accepted. While the error persists, each publication revokes again but keeps the time of the first revocation of that plan. An entry unload or reload is not an error: the accepted plan is kept in the integration's store and executes while Energy Compass recalculates. After a Home Assistant restart the controller stays on the base profile until the first plan of the new session, because a plan accepted in an earlier run is dropped when the session changes. Saving the integration options does not reload the entry in most cases (Saving options), and when it does, the accepted plan is kept.

plan_reason summarizes the verdict; the blueprint maps it to its (Polish) reasons in this order:

Control also requires fresh telemetry: every entity in telemetry_entities numeric and reported within 30 s, battery voltage 400–610 V and SOC 0–100 %. Every automation in old_writers must be off and not running. A snapshot without battery parameters blocks control with the reason plan: brak parametrów baterii (pojemność, sprawność) w planie.

Profiles

The cap is min(max_current, max_power_w / V) for charging and min(max_current, max_power_w × eta_discharge / V) for discharging. The cap has hysteresis: the current already on the inverter is kept while it still fits the power cap, and the next ampere step is taken only with 2 % voltage headroom (about 10 V at 530 V), so a pack voltage crossing a step boundary does not rewrite the ceiling on every sag and rebound. The power cap is never exceeded. At 100 % SOC the charge current of CHARGE_PV, SELF_CONSUME and CHARGE_GRID becomes 0 A; in battery operation mode Voltage only CHARGE_GRID does, because the other two follow the full-pack rule at the end of this paragraph. Planned currents convert interval kWh with eta_charge (charging) or eta_discharge (discharging) over the full interval. Target SOC uses the accepted plan's capacity_kwh; target voltage follows a fixed high-voltage LFP curve (496–536 V for 10–90 %, 584 V charging or 544 V discharging at 100 %). A reached target in CHARGE_GRID/DISCHARGE_GRID is latched for that plan interval. A reached DISCHARGE_GRID interval switches the direction to Disabled but keeps reached_discharge_current (1 A, about 530 W at 530 V, never above the cap) on discharge, so the battery covers the house base load without selling and larger loads come from the grid; 0 A would send the whole house load to the grid at a full battery. An interval whose planned discharge_kwh is below the 0.05 kWh tolerance (export planned from PV) is reached at once. In an LFP balance row (balance_hold: true) the charge current stays on at 100 %, CHARGE_GRID targets 100 % and the grid current is at least balance_grid_current. In Voltage mode the inverter ends charging on pack voltage, and a counter-based SOC source can read 100 % before the pack is full. So at SOC ≥ 100 % in HOLD, CHARGE_PV and SELF_CONSUME the controller keeps the normal charge current cap (with the same hysteresis, so there are no 0 A rewrites around the ceiling) instead of 0 A (or the hold_grid_current of HOLD). The grid current is 0 A, so PV is the only source, discharge follows the plan row (0 A in HOLD), and no SOC target is written and no "reached" state is latched. In HOLD the switch has hysteresis: the full-pack profile starts at SOC ≥ 100 % and stays through the following HOLD runs until SOC is 99 % or lower, so an SOC source that dithers between 99.9 % and 100 % does not rewrite the profile on every crossing. Each switch is one write transaction that begins with charge 0 A, and there is at most one per percentage point of SOC movement; without PV the pack drifts down on the inverter's own draw and HOLD tops it up from the grid, a cycle of hours. CHARGE_PV and SELF_CONSUME need no hysteresis, because below 100 % they write the same values. CHARGE_GRID (it keeps voltage_grid_charge_ceiling and its 0 A charge current at 100 %), the balance hold and Capacity mode behave as before. A CURTAIL row that charges (charge_kwh above 0.000001 kWh: the PV above what the site passes is more than the pack takes at the charge power) runs like CHARGE_PV without discharge, at the planned current: the charge current is charge_kwh × eta_charge / (h × V) rounded up to the step of the charge entity, at least hold_grid_current and at most the cap, the grid current 0 A, the discharge current 0 A, all programs Disabled, so the pack takes PV at that current and the inverter curtails the rest by itself. A row that plans the charge power over its whole interval gets the whole cap. A row that plans less (the charge of such a row is free between zero and the PV left after the curtailment and the house, and the plan took less) charges less than the cap would, so the pack ends where the plan says and not above it. The controller never buys grid energy for such a row. At 100 % SOC it follows CHARGE_PV (0 A in Capacity mode, the cap in Voltage mode) and it raises no warning. The threshold is the 0.000001 kWh the plan's own classifier reads as zero: the plan publishes the solver's flows unrounded, and a CURTAIL row that does not charge can carry up to about 5e-13 kWh there (about one such row in twelve in the sweep of ADR-0005), which must not charge. Any other CURTAIL row (charge_kwh up to 0.000001 kWh) runs the HOLD profile with the warning CURTAIL is not supported: HOLD applied, because the controller cannot limit PV: it writes hold_grid_current (1 A by default) as the charge current and the grid current and holds the planned end state of charge.

Only battery modes listed in commissioned_battery_modes are controlled; any other mode (for example Voltage before its thresholds were proven) keeps the base profile. With Voltage allowed, a target outside 495–560 V is refused.

With the counter SOC estimator as the SOC source the controller reads its SOC from the estimator instead of the Solarman battery entity (the telemetry gate, the Voltage-mode full-pack rule and the reached checks), and Capacity is dropped from the modes it controls, whatever commissioned_battery_modes says: in Capacity mode the inverter compares the programs' SOC thresholds with its own BMS SOC, so the plan's target would be in the wrong scale. The inverter then stays on the base profile with mode_not_commissioned if it is switched to Capacity.

In Voltage mode the pack voltage sags under discharge (about 0.7 V at 7 kW) and the LFP curve is flat (515–528 V spans roughly 30–70 %), so a DISCHARGE_GRID voltage target is reached within seconds of starting. With a numeric discharge_energy_entity, a DISCHARGE_GRID interval in Voltage mode instead ends once the counter has risen by the planned discharge_kwh (0.05 kWh tolerance) since the controller's first run in that interval (runtime.slot_energy); the TOU program voltage is then 49.6 (496 V), so the inverter only stops on its own at that floor. Solarman reports the counter only when it changes, so its freshness comes from the telemetry_entities heartbeat of the same inverter. Without a numeric counter the voltage target applies as before. Capacity mode is unchanged.

Charging lifts the pack voltage the other way: about 2 V at 4 A within seconds, and the inverter stops grid charging as soon as the pack reaches the TOU voltage. A CHARGE_GRID target from the curve (51.4 V for 27 % at a 512 V rest voltage) therefore ended the charge after a few seconds, and a rest voltage above the curve point latched the interval as reached at once. In Voltage mode CHARGE_GRID (outside a balance row) writes voltage_grid_charge_ceiling (55.2 V, 552 V) as the TOU voltage instead; the planned grid current sets how much each interval charges, and the interval is reached only when the pack reaches the ceiling. The Solarman charge counter refreshes about every 10 minutes, too slowly to end a 15-minute interval, so it is not used. Keep the ceiling at or below the BMS charge voltage limit.

Writes and confirmation

Each change writes one entity through number.set_value or select.select_option, then reads holding registers 108–177 from the controller's Solarman device (device_id) and compares the raw value. A register that does not confirm is listed in runtime.uncertain and retried; a direction or target change first zeroes the currents, then sets thresholds, then enables the direction.

runtime.reason_code is a stable code and runtime.reason its text. The native engine writes the text in the Home Assistant language (Polish for pl, English otherwise); the blueprint engine's texts are Polish.

Every runtime update of the blueprint engine goes through energy_compass.controller_runtime; when that call fails, the run stops before the next register is written. The native engine rejects that service, so a blueprint run that slips through stops before its first write.

Following a run (native engine)

The blueprint left an automation trace per run; the native engine replaces it with:

• the runtime sensor's reason and reason_code, and its attribute last_run (not recorded): trigger, decision, planned commands, each write with its outcome (sent, failed, confirmed, blocked) and how the run ended;
• the integration's diagnostics (deye_controller): engine, hardware, run_history, the last 50 runs, and run_history_notable, the last 20 that wrote or ended with a code other than ok (both kept in memory, so a restart empties them);
• a logbook entry on the runtime sensor whenever the runtime code or the confirmed mode changes;
• the runtime code error and the repair issues "Deye controller runs are failing" and "Deye blueprint automation is still on", so a stopped controller is visible without reading logs.

When Energy Compass is unavailable

Without Energy Compass neither the mode nor the runtime can be read, so no write could be proven safe or recorded. The blueprint therefore stops at its first step, without any write or service call, when the controller sensor is missing or unavailable, reports another controller_schema or has no mode_entity: the trace says Energy Compass niedostępny: sterowanie wstrzymane bez zapisów. The native engine does the same without a trace: the run ends without a write, the runtime code is error with the reason controller_unavailable, and a repair issue appears after three such runs. The inverter keeps its last profile; a forced TOU direction ends at the next TOU program boundary, while the battery currents stay as they are. If Energy Compass disappears in the middle of a run, the next runtime call fails and the run stops before another register is written. Home Assistant reports the failed entry; repair it or release the inverter by hand.

Limits and defaults (native engine)

The expert group Limits and takeover of the options step sets these; an empty field keeps its default, and a change applies on the next run without a reload. No household value is built into the code.

When the power or a current limit would come out as zero (for example a charge power of 0 in the battery settings), the options step does not store it: it shows the group and asks you to enter the limits. Enabling the native engine also needs a numeric battery voltage reading, because the pack is told from a 48 V one by it.

Inputs

These are the inputs of the deprecated blueprint, with the blueprint's own defaults; the native engine takes the values above.

Capacity and the charge and discharge efficiencies are no longer inputs: the blueprint uses the values the accepted plan was computed with (capacity_kwh, eta_charge, eta_discharge), so a retained plan never runs with settings saved after it. max_power_w, max_current, max_grid_current and relinquish_current stay hardware caps in the blueprint; keep max_power_w consistent with the Energy Compass charge and discharge power, because the two are not linked.

Migrating from the package (0.1.36 and older)

Release 0.1.37 removes packages/energy_compass_deye.yaml. Energy Compass 0.1.36 and older ignore the controller options and store, so the controller needs 0.1.37 and the new blueprint together.

1. Install 0.1.37 and restart. The controller is enabled automatically when the package helpers exist, there is one Energy Compass entry and one usable Solarman device; otherwise enable it in Options → Deye controller. The old blueprint and package keep controlling until you swap them.
2. Optional shadow check. The controller sensor's generation should equal the state of the package's plan sensor after each acceptance.
3. Compare efficiency and capacity first. The old blueprint used its own eta (default 0.9747) and capacity_kwh (default 25); the new one uses the plan's eta_charge, eta_discharge and capacity_kwh, which come from the Energy Compass battery settings (efficiency 1.0 unless set). Make eta_charge and eta_discharge equal to the old eta before the swap, or the first run rewrites the grid-charge and discharge currents by that ratio; a capacity difference moves only SOC thresholds, as below.
4. Swap in a quiet window (a CHARGE_PV or SELF_CONSUME row, not near a full hour, with no other writer running). Turn the old automation off without stopping its actions, call energy_compass.controller_import_package for the controller sensor and check the answer (the package's session, accepted generation, mode and restore flag). It copies the state, adopts the package session and drops stale runtime keys. Then replace the blueprint, select the controller sensor in the automation, drop the eight removed inputs (plan_entity, optimizer_entity, valid_entity, alert_entity, compass_entity, solarman_device, capacity_kwh, eta) and turn it on. The first run changes nothing on the inverter when the capacity is unchanged; a capacity change moves only the active program's SOC and voltage threshold in a HOLD or grid row.
5. Repoint dashboards and your own automations: the mode helper is now a select, the restore flag and the session are attributes, and the dashboard roles are deye_controller, deye_mode and deye_runtime.
6. Remove the package include from configuration.yaml. It takes effect at the next restart; do not reload template or the input helpers meanwhile. Afterwards delete the ten orphaned registry entries.

Without the import, swap the blueprint anyway and accept one stretch on the base profile until the next plan. Rollback before the package is removed: turn the new automation off, restore the old blueprint and inputs and turn it on; the package helpers were never written by the import. A downgrade to 0.1.36 needs the old blueprint and the package back first.

Migrating from the blueprint to the native engine

The two engines never write together. Selecting native in Options → Deye controller → Engine is refused until the mode is Off and the restore is done. While the engine is native:

• the mode select refuses to leave Off (the error names the automation) while an automation that uses the blueprint is on;
• a run that would write (mode Auto, or Off with a restore pending) stops when such an automation is on: nothing is written, the runtime reason is blueprint_active (naming the automation) and a repair issue stays until the automation is switched off. Not even the restore to BASE is written meanwhile, so the inverter keeps the last profile it was given; once the automation is off, the controller continues (or restores BASE) on its next run. Mode Off with nothing to restore and Simulation run as usual and are not blocked. This also covers a reload with mode Auto and a blueprint that was never updated;
• energy_compass.controller_runtime rejects every call, so a blueprint run that slips through stops before its first write.

When exactly one automation uses the blueprint on the same Solarman device (its charge, discharge, grid and operation entities belong to that device), its limits and entity overrides are loaded into the expert group for you to review; nothing is applied until you save. An automation on another inverter prefills nothing.

1. Select the mode Off and wait until restore_pending is off and the runtime code is restored (or the run reports released).
2. Turn the blueprint automation off. Do not stop its actions mid-run; wait for them to finish.
3. Options → Deye controller: set the engine to native, review the prefilled limits and save. The entry reloads.
4. Select Simulation, compare runtime.desired with what the blueprint wrote for a while, then select Auto in a CHARGE_PV or SELF_CONSUME row.
5. After a week delete the automation and the blueprint file.

Rollback: select Off, wait for restored, set the engine to blueprint, turn the automation on, then choose the mode. A paused flag is cleared when the engine returns to blueprint.

Dashboard examples

Generated by tools/dashboards/build.py with placeholder entity IDs:

The panel uses native cards plus ApexCharts Card for its SOC forecast; the two charts need ApexCharts Card. The YAML builder fills any of them with your entity IDs, capacity and language. See the installation guide.

The controller examples take four roles: deye_controller, deye_mode, deye_runtime and deye_pause (defaults sensor.energy_compass_deye_controller, select.energy_compass_deye_mode, sensor.energy_compass_deye_controller_runtime and switch.energy_compass_pause_inverter_writes). The panel shows the pause switch only while the entity exists, that is with the native engine. Pass --entity deye_mode=select.my_mode to the generator or fill them in the YAML builder when your IDs differ; the session, the restore flag, the next TOU change and the TOU prefix are read from the controller's attributes.

Energy Atlas (optional)

Energy Atlas is a separate Datamindz service that aggregates anonymised telemetry across sites for research and benchmarking. Sending data to it is opt-in and off by default: with it off, Compass behaves and performs exactly as it does without this section — no network calls, no new background thread, no new files.

Turn it on in Settings → Devices & services → Energy Compass → Configure → Energy Atlas:

No secret to enter. This release registers with a shared public enrollment credential baked into the integration itself — the same one for every install of this version — so anyone running Energy Compass can register a site with it; the site is unverified until you send Energy Atlas: show ownership proof (below) to the Energy Atlas bot. The credential rotates by release: each new Compass version may ship a different one, and the old one is eventually revoked (already registered sites keep working — they authenticate by their own site key, not the enrollment credential).

Saving the form applies live: it does not reload the entry or touch your plan, and it starts or stops the delivery thread immediately. The form's description shows a status line so you can see it worked from your phone: off, or registered on <environment> · last delivery <time | never> · waiting <n> (plus halted: <kinds> if delivery is stuck).

What is sent, only while enabled and only the entities you have bound in Sources: PV, grid import/export and battery power, household load power (recorder mode only), battery SOC, and PV/import/export energy counters (only counters whose Home Assistant state_class is total/total_increasing); each Compass solve's plan and its price/PV/load inputs; a handful of installation attributes (PV kWp, grid connection power in kW if you entered it, battery capacity and usable capacity, SOC floor, the Compass version) and the municipality (gmina) your Home Assistant home zone lies in, as its 7-digit id. Atlas shows the municipality by name next to your home's values. Compass finds the municipality inside Home Assistant: it reads the public outline files that Atlas serves (the same files for every home, found through GET /v1/public/geo) and compares them with your home's position there, so your coordinates stay in Home Assistant and no request carries them. The only things derived from them that leave are the voivodeship id in the name of the municipalities file Compass fetches and the municipality id in the attributes. A home within about 50 m of a municipal border may be shown in the neighbouring municipality, because the outlines are simplified. A home outside every Polish municipality (abroad, at sea) or without coordinates sends no location and is counted in the fleet total only. The files are fetched again only when Atlas publishes a new version or your home moves (Atlas is asked for the version at start and at most once per 24 h); if Atlas cannot be reached, the last municipality found is kept — also across a Home Assistant restart, in the integration's storage next to the site key together with the coordinates and the geometry version it was found for, never sent — and the lookup is retried at most once per hour, without ever delaying telemetry. Nothing else is sent — no tariff text or inverter model, and the enrollment credential itself is never stored, only the site key issued in exchange for it.

How values are sent: powers in W. Bind Battery power with + = discharge (as in the dashboard examples); Atlas receives it as + = charge. Readings outside the collector's ranges are corrected, not sent as errors: a negative grid import/export power is sent as 0, SOC below 0 % or above 100 % as 0 %/100 %, and a negative energy counter or a non-numeric reading is not sent.

Where the key lives: .storage/energy_compass_atlas/<entry id>/<environment>/ inside your Home Assistant config directory, one subdirectory per environment so staging and production never share a key, a site or a queue. It is included in Home Assistant backups. Removing the integration deletes it.

Switching environment: staging and production are independent — each keeps its own key, site and queued data. Switching to an environment that was already registered resumes it live (no reload, no re-registration, no lost queue); switching to one that has never been registered registers it automatically with the baked-in credential, without asking for anything.

When the collector is down: telemetry and solves queue locally (up to 30 days) and are sent once it is reachable again; Compass's own plan is unaffected — Atlas delivery runs on its own background thread and never shares the optimizer's schedule. Diagnostics (Devices & services → Energy Compass → ⋮ → Download diagnostics) report the energy_atlas section: enabled, environment, registration status, queue depth and any halted delivery.

Recovery: forget a site: if a site's key was revoked or conflicts with another source, check Forget site on this environment on the same Energy Atlas form and save. This deletes the selected environment's key and queued data on this device only — the site itself is not removed at the collector, an operator can revoke it separately — so the next save with sending still enabled registers a new site there automatically, again without asking for anything.

Show ownership proof: once a site is enabled and registered, the options menu offers an extra entry, Energy Atlas: show ownership proof. It generates a short-lived signed proof (valid 15 minutes, single use) and displays it to send to the Energy Atlas bot to link the site to your Datamindz account. The proof is shown only — it is never stored and never appears in options, diagnostics or logs.

Backfill history: the service Energy Atlas: backfill history (energy_compass.atlas_backfill, optional field Days, 1–3650, default: all available history) sends past telemetry from Home Assistant's own recorder history for every entity you have bound — 5-minute statistics where the recorder still keeps them, hourly statistics for older history — to every entry that currently has sending enabled and a registered site, using the same value corrections as live delivery. It fails with an error if no entry currently qualifies.

Offline replay tool

tools/replay.py answers "what does this setting change do to the real cost?" without Home Assistant. It imports the optimizer from custom_components/energy_compass/engine and replays recorded days; it needs the same Python and SciPy as the integration (run it in the test image or any environment where import scipy works) and plots nothing. For every day and in total it prints, in the installation's currency:

python tools/replay.py tools/replay_sample.json --currency PLN
python tools/replay.py tools/replay_sample.json --set allow_grid_charge=false

--set key=value (repeatable) overrides any planner setting by its key (the keys of Options, as in settings.py; strategy-owned flags set this way are treated as explicit). Run twice and compare the plan column to measure a change. --json prints the numbers (with solve_failures, the number of failed plan solves of the day) instead of the table; --timezone and --initial-soc apply to CSV input only. A bad file, value or override ends with error: … naming the place and exit code 2.

Input format

One JSON file (or a CSV, below). tools/replay_sample.json is a complete two-day synthetic example.

Each interval has six numbers: buy and sell (currency/kWh, the final tariff prices), pv_forecast and load_forecast (kWh in the interval, as known at plan time) and pv and load (kWh actually produced and consumed). The six values must be finite and the four energies not negative (clip the small negative values that rounding in statistics can leave, e.g. in import + PV − export); an error names the place, days[n][i] (day n from 1, interval i from 0) or line n of a CSV.

An interval may also carry buy_energy (CSV column too): the energy part of buy, the part the deposit can pay (the rest of buy is distribution), in the same units, as invoiced, so it may be negative (a draw at a negative energy price, dynamic offer without an index floor); it is not above max(buy, 0), and when negative not above buy; empty or missing means 0. The planner uses max(buy_energy, 0) (capped at max(buy, 0), as the engine does). It matters only with the deposit model, which you switch on with --set deposit_model=manual --set export_value_factor=0.3 (experimental). buy stays the invoice price, so buy_distribution_mode, buy_distribution_rate and buy_distribution_off_peak_rate are not read — prices come from the file — and a warning says so. Costs are reported at the file's prices whatever the factors are.

Days are independent: each is planned and measured on its own and ends at its last interval, even when the file holds consecutive days. The horizon therefore shrinks to the end of the day, so horizon_hours beyond the day and the carry of energy over midnight are not measured.

CSV has one row per interval with the columns start, buy, sell, pv_forecast, load_forecast, pv, load and optionally buy_energy and initial_soc_percent (read on the first row of a day). Rows are grouped into days by the local date of start; settings come only from --set.

Reading the result

• Day-end energy is valued, because a day boundary is arbitrary for a battery. Every solve values the final SOC at terminal_value_per_kwh when terminal_mode is value, else at the day's mean buy price, so the plan may end a day below its initial SOC. The reported cost prices the difference between the final and the initial SOC at the day's mean buy price whatever the settings are, so terminal_mode and terminal_value_per_kwh change the plan but not the measuring stick: self_use is identical in every run, and two runs differing in the terminal value are comparable.
• wear_per_kwh is part of the reported cost (half of the charged plus discharged energy), so runs with different wear_per_kwh are not comparable.
• hindsight is the optimum of the shaped objective (strategy weights, import penalty and the terminal value of the solves included) priced in real currency. For cost_min with no import penalty and a terminal value equal to the day's mean buy price it is a lower bound of plan; for other strategies it is the best that strategy could do. With terminal_mode value and a lower value than the mean buy price, hindsight may drain the battery and report more than plan, which is a sign that the terminal value undervalues stored energy.
• The executed plan follows the controller (tools/deye_controller/build.py) against realized data. SELF_CONSUME and CHARGE_PV follow the load: all PV surplus charges the battery and a deficit is covered from it. In CHARGE_GRID only the grid share follows the plan — the planned charge minus the surplus the forecast promised. Grid and the realized PV surplus charge together until the row's planned end SOC; then the grid stops, as the controller does, and PV keeps charging for the rest of the slot. PV above the forecast therefore shrinks the grid import (the SOC may end above plan, by PV only), and PV below it charges less — a shortfall is never bought from the grid, nor a start SOC below plan caught up. DISCHARGE_GRID discharges the planned energy, HOLD parks the battery. Grid export beyond grid_export_kw is curtailed, and stored energy is not exported beyond the PV produced so far when Sell only PV (limit_export_to_pv) is on.
• On a net-metering file the costs are hourly prices, not the settlement. Net-metering is settled on yearly kWh (Setup profiles), so plan − self_use is not a saving there; do not compare strategies by it.
• The peak-period reserve (peak_reserve_margin_kwh and export_reserve_margin_kwh) is replayed as in the integration: it needs limit_grid_charge_price (its ceiling is the cheap price), else a warning says it has no effect.
• Not replayed: LFP balance windows, the autonomy tail beyond the data, and carried export or grid-charge commitments. A warning names the enabled ones. A failed plan solve runs that step as self-consumption and is reported under the table and as solve_failures; a failed hindsight solve or inconsistent settings stop the run with error: <date>: ….

Exporting the data from Home Assistant

buy and sell are the final prices the planner sees: from your tariff, or from the history of the price entities Energy Compass reads. The realized energy comes from long-term statistics: the Energy dashboard's menu offers Download data (CSV, hourly). The same hourly change values the replay needs are returned by the recorder/statistics_during_period WebSocket command with "period": "hour" and "types": ["change"] (tools/export_value_backfill.py shows the call). Take pv from the PV production statistic and load from the home consumption statistic (energy in = grid import + PV − grid export, when no consumption sensor exists). pv_forecast and load_forecast are what your forecast entities said before the interval — the Compass plan attribute intervals (or the Solcast/forecast history) recorded at plan time; using the realized value as the forecast gives an idealised plan with no forecast error. Use interval_minutes: 60 for hourly statistics.

Annual settlement oracle

tools/replay_year.py is the yearly counterpart of the day replay, for the questions a day cannot answer: what a deposit setting does to the bill of a year. It replays consecutive hours as the integration runs them: a receding horizon_hours (24 h) window, re-planned every --refresh-hours hours (default 6) on the forecast, the state of charge carried over midnight, the daily PV-export counters reset at local midnight, every plan executed on the realized series, a failed solve run as self-consumption. The hourly import and export it produces are valued by two bills:

python tools/replay_year.py site.json --set deposit_model=manual --set export_value_factor=0.3
python tools/replay_year.py site.csv --timezone Europe/Warsaw --rho 0.2 --fixed 310 --self-use

It prints (or, with --json, returns) both bills, wear, the SOC drift (initial minus final SOC at the mean buy price), K = annual bill + wear + SOC drift (KL with the ledger), D, V, E (signed), E_owed (E⁺; the text output labels it E+ liability), and the refund and the void of each bill. Compare two runs by the difference of K (or KL); --self-use gives the no-planner reference. The input is one JSON object (timezone, start, rho, fixed, initial_soc_percent, settings and hours[]) or a CSV, one row per hour with start, buy, sell, buy_energy, pv_forecast, load_forecast, pv, load — the same values as above; the format is in the tool's docstring, --rho, --fixed and --initial-soc override the file. buy_energy is the energy part as invoiced, with its sign: the bills sum it per month (a draw at a negative energy price lowers the month, and a month that ends below zero stays in the bill at full value and adds nothing to E_owed), while the planner sees max(buy_energy, 0), so the plan does not depend on the negative values. Hours must be consecutive real hours, one row each; a JSON row may carry its own start, which must then match its position. --refresh-hours must not exceed horizon_hours. The number of failed plan solves is printed on stderr in both output formats.

Timestamps are real instants, so a year across the two clock changes (a 25-hour and a 23-hour local day) is read correctly; the local date and month (counter reset, ledger month) come from timezone. A stamp with an offset (+02:00, Z) is exact. A naive stamp is local to timezone: in the repeated autumn hour it is the first occurrence, unless the row before it is that first occurrence (then it is the second), so a CSV of consecutive naive local stamps reads right — a naive JSON start in that hour is the first occurrence; give it an offset to mean the second.

Limits: the fixed part of the bill is one number from the input and does not follow the flow, so a charge band that depends on the annual import is not modelled (take fixed from the no-battery bill and expect a small constant error where the band differs); a stretch shorter than a year is read as a year with empty months; the settlement period is the calendar month; a seller that bills a longer period nets across its months, which the tool does not model; energy is valued per hour; the result is only as good as the forecast series you give it.

Reason code reference

Coverage / quality reasons (reason, reasons attributes)

Autonomy warnings

Safety exceptions (dispatch_policy.safety_exception.reason)

Balance warnings

These are raw codes, not translated.