> For the complete documentation index, see [llms.txt](https://docs.voltmasters.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voltmasters.io/control-algorithms/cost-optimization/battery-schedule.md).
# Battery schedule
The **battery schedule** is the forward-looking plan the EMS makes for the battery: when to **charge**, when to **discharge**, and when to stay idle over the coming period.
It is produced when both of the following are true:
* the project's control strategy is set to **Cost optimization**, and
* **no external signal is active**, that is, no [external partner](/external-signal/external-signal.md) is currently steering the installation.
{% hint style="info" %}
If an external signal partner is actively steering the battery, that signal takes precedence and the battery schedule does not apply. When the partner is on standby, the battery falls back to the cost-optimization schedule.
{% endhint %}
## What it optimizes for
Under the cost-optimization strategy, the schedule aims to **minimize the energy cost** of the installation: energy is stored when it is cheap and used when it is expensive.
To build the plan, the EMS combines:
* **Forecasted energy prices**: the dynamic (day-ahead) electricity prices for the project.
* **Forecasted PV production**: the expected solar output.
* **Forecasted consumption**: the expected load of the installation.
From these it determines the charge/discharge plan with the lowest cost, while respecting:
* the battery's **state-of-charge limits** (minimum and maximum SoC), and
* the **grid connection limits** (maximum injection and consumption).
## How the schedule is built
The schedule is planned **ahead of time** over the forecast horizon and is **recomputed every control cycle** as new price and production forecasts come in.
Each cycle the EMS:
1. **Looks ahead** at the forecasted prices, PV production and consumption.
2. **Identifies the periods worth covering from the battery**, typically the expensive consumption slots (and attractive injection slots).
3. **Plans the charging beforehand** (from PV surplus where available, otherwise from the grid during cheaper periods) so the energy is already stored before it is needed.
4. **Checks that it is worthwhile.** Charging and discharging are only planned when the price difference between the cheap and expensive periods is large enough to outweigh the battery's round-trip losses (a configurable minimum price difference). Cycling the battery for a marginal gain is avoided. Concretely:
* A consumption period **cheaper than the minimum price difference** is never covered from the battery: even a free recharge could not leave the margin the site demands per cycle, so that period simply imports from the grid.
* A discharge that the battery would **refill right afterwards** (planned cheap charging or solar inflow just after it) is a full extra charge/discharge cycle. It is only planned when the avoided purchase price also beats the **recharge price** plus the minimum price difference; otherwise the battery stays idle instead of alternating between charging and discharging for a marginal gain.
5. **Respects the limits**: the battery's minimum/maximum state of charge and the grid connection limits (maximum injection and consumption).
Every entry is tracked from **planned** to **in progress** to **done**, so the actual charging/discharging can be compared against what was planned and the remaining plan adjusted if reality differs from the forecast.
{% hint style="info" icon="lightbulb" %}
The resulting plan is shown per quarter-hour on the [project dashboard](/voltmasters-platform/2.-project-dashboard-ems.md#battery-plan), where you can also **override individual quarter-hours** and ask the controller for its **projected charge level**.
{% endhint %}
## Stored energy goes where it earns most
Stored energy usually has **more candidate uses than the battery can serve**: today's expensive evening, tonight's consumption, tomorrow's peak, and, when [selling energy to the grid](/control-algorithms/cost-optimization/selling-energy-to-the-grid.md) is enabled, moments with a high injection price. The schedule assigns the stored energy to the use where it earns the most, and it recognizes that a **cheap charging window** between two of those uses changes the picture:
* A future need that can be **refilled from a cheap window in between** (for example tomorrow evening's consumption, with cheap night hours before it) does **not** hold on to today's stored energy. It is covered by charging in that window instead.
* The stored energy that this frees up goes to the uses that **cannot** be refilled cheaply — typically the period **before** the window: today's expensive evening or injection peak.
The practical result: during a high evening peak the battery can discharge at **full power for the whole peak**, selling everything above the site's own consumption, and end the peak near its minimum state of charge. The needs of the next day are met by recharging in the cheap night hours instead of by holding energy back through the peak. Holding back only happens when it genuinely pays: when the later need is worth more than the sale and cannot be refilled affordably in time.
## Scheduled events
The schedule is a sequence of timed entries. Each entry describes a single planned event with two parts: an **action** (what the battery does during that period) and a **goal** (why it does it).
### Actions
| Action | What the battery does |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Follow scheduled power** | Follows the exact planned power setpoint, used for grid charging and for discharging to inject into the grid. |
| **Charge at max power** | Charges at the maximum available power. |
| **Compensate PV surplus** | Charges with the current PV surplus only (no grid charging). |
| **Compensate production deficit** | Discharges to cover the current production deficit. |
| **Idle** | No activity is planned; the battery may stay idle. |
### Goals
| Goal | Meaning |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Charge for expensive slot** | Charge now, while it is cheap, to cover an upcoming expensive period. |
| **Charge (negative price)** | Charge because the electricity price is negative, so you are paid to consume. |
| **Charge for injection** | Charge cheap grid energy now specifically to sell it back later at a high injection price (see [selling energy to the grid](/control-algorithms/cost-optimization/selling-energy-to-the-grid.md)). |
| **Discharge expensive slot** | Discharge during an expensive period to avoid buying from the grid. |
| **Discharge before negative** | Discharge ahead of a negative-price period, so there is room to charge during it. |
| **Discharge for injection** | Discharge to inject (sell) into the grid when the injection price is attractive. |
| **No action** | Nothing to do for this period. |
For example, an event can be **"follow scheduled power"** with the goal **"discharge for injection"**: the battery follows a planned discharge setpoint in order to inject energy into the grid during an attractive injection price.
## Example: evening high prices
The chart below shows the **evening high prices** scenario from the simulator. Electricity is cheap during the day and becomes much more expensive in the evening: the consumption price jumps to roughly 450 €/MWh between about 18:00 and 00:00.
The battery charges during the cheap, sunny daytime and discharges during the expensive evening peak.
What the schedule does:
* **Daytime (≈ 08:00–16:30): charging.** While prices are low and PV is producing, the battery charges (positive battery power). Most of this is **PV surplus** being stored; the goal is to *charge for the expensive slot* later in the day. The state of charge climbs from near-empty to its maximum (≈ 95%).
* **Evening peak (≈ 18:00–00:00): discharging.** When the consumption price spikes, the battery discharges (negative battery power) to cover the load instead of buying from the grid. This is the *discharge during an expensive slot* goal, and the state of charge drops steeply.
* **Overnight: winding down.** Once prices return to normal, the battery is left to settle back towards its minimum state of charge.
By shifting the stored energy from the cheap daytime into the expensive evening, the installation avoids buying at the peak price, exactly what the cost-optimization schedule is designed to do.
{% hint style="info" %}
With [selling energy to the grid](/control-algorithms/cost-optimization/selling-energy-to-the-grid.md) enabled, the same scenario goes further: the battery discharges at **full power** through the entire peak, selling everything above the site's own consumption at the high injection price, and recharges in the cheap night hours for the next day.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.voltmasters.io/control-algorithms/cost-optimization/battery-schedule.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.