Skip to content

PEAK_SHAVING

Discharges the battery to cap site import below a threshold, and recharges during cheap windows.

Mode string PEAK_SHAVING (EMS_OP_PEAK_SHAVING)
Dispatcher ems_main.py → control_logic_updated.control_step_peak_shaving
Config block functions.Peak_Shaving
Queue source tag control_logic (the writer's default)
Status Implemented

This is the only power mode shipped enabled (enabled: true).

Purpose

Watches grid-meter import. When import rises above peak_threshold_kw, it discharges the battery to shave the peak. It can also charge — during charge_windows — to replenish the battery ahead of a peak, and it charges whenever the site is exporting.

How it decides

Runs roughly in this order each cycle:

  1. Time windows. Resolve whether now falls in an enabled discharge_windows and/or charge_windows entry, honouring days_of_week in the configured timezone. in_band is determined by comparing import against peak_threshold_kw ± optional.hysteresis_kw.
  2. Candidate actions.
  3. discharge_pre — import is (or is about to be, with prefer_next_slot-style lookahead) above peak_threshold_kw inside a discharge window.
  4. charge_pre = in_charge_window and (import_kw < peak_threshold_kw - hysteresis_kw)
  5. want_charge_export_always = export_kw > 0.0 — exporting always justifies charging.
  6. Conflict rule. If both charge and discharge want to act, optional.conflict_rule (discharge_overrides_charge) decides — discharge wins by default.
  7. HOLD-LAST. When the computed action is none and the site is in_band, the function returns without actuating, leaving the previous setpoint in place. The same hold applies when a discharge/charge is computed as ≤ 1e-6 kW while in_band. This prevents needless churn.

Configuration

functions.Peak_Shaving

Key Live value Meaning
enabled true Master switch.
peak_threshold_kw 50 Import threshold above which the battery discharges.
discharge_power_limit_kw 50 Plant-wide discharge ceiling for peak shaving.
min_soc_pct 10 Discharge floor.
recovery_soc_pct 67 Target SOC to recover to when recharging.
response_time_ms 90 Recorded; not used by the control step.
timezone Europe/Stockholm Timezone for window evaluation.
discharge_windows[] 5 entries start, end, enabled, power_cap_kw, days_of_week.
charge_windows[] 5 entries start, end, enabled, charge_cap_kw, days_of_week.
optional.hysteresis_kw 2 Deadband around the threshold to stop flapping.
optional.conflict_rule discharge_overrides_charge Tie-break when both directions qualify.

Windows with empty start/end are treated as always-on for the listed days.

Safety

  • Returns when is_external_control_active(), when enabled is false, or with no active PCS.
  • SOC gating uses the direction implied by the last action taken, so a charge is judged against max_soc_pct and a discharge against min_soc_pct; SOC-blocked PCS are force-written to 0 kW.
  • Per-PCS allocation via _equal_allocate_with_caps, bounded by each PCS's power_limits.max_charge_kw / max_discharge_kw and any active window's power_cap_kw / charge_cap_kw.
  • Final clamp inside _pcs_connect_and_set_power_kw.

Check: every window in the shipped config lists Monday–Friday only, so this mode is inert at weekends. power_cap_kw / charge_cap_kw are all null in the live file.

Outputs

_pcs_connect_and_set_power_kw(cfg, pcs_id, ±kw) → queue action set_power_kw, source control_logic.