Skip to content

BACKUP

Runs for any backup-involving operation mode. Does two things, each behind its own enable flag: keeps the PCS grid mode (PQ ↔ VF) in step with live grid state, and discharges the configured back-up power while the grid is down.

Mode string BACKUP (BACKUP_PEAK_SHAVING, BACKUP_FREQUENCY_REGULATION also match)
Registered Yes — all three are in ALL_EMS_OPERATION_MODES, so they are selectable
Dispatcher ems_main.py → control_logic_updated.control_step_backup (pre-dispatch)
Config block functions.Backup
Queue actions mode_pq / mode_vf and set_power_kw
Queue source tags backup_grid_mode (grid mode), backup_power (power)
Status Grid-mode governor and power dispatch, each disabled by default

Purpose

While backup is involved:

  • grid present → PQ (grid-following) and the back-up discharge is released
  • grid lost → VF (grid-forming / island) and the PCS discharge the configured back-up power, so the islanded load stays supplied

Both are runtime decisions, deliberately not read from general_settings.pcs.<id>.grid_mode.

Where it runs

Unlike other modes it is not an elif branch. ems_main.py calls it before the mode dispatch chain, for any mode whose name contains backup:

if mode_involves_backup(mode):
    try:
        backup_control_step(merged)
    except Exception as e:
        print(f"[EMS][WARN] BACKUP grid-mode switch failed: {e}")

So it runs for BACKUP, BACKUP_PEAK_SHAVING and BACKUP_FREQUENCY_REGULATION, and the normal dispatch chain still runs afterwards.

How it decides

desired = grid_mode_for_values(values, switch_cfg)
  avg grid L-N voltage < grid_loss_voltage_v            -> "vf"  (grid lost)
  grid frequency outside [low, high]                    -> "vf"  (grid lost)
  voltage telemetry missing                             -> None  (do nothing)
  otherwise                                             -> "pq"  (grid present)

Per active PCS, with switch_delay_s dwell and per-PCS state:

  1. applied == desired → nothing to do.
  2. candidate != desired → stage the new candidate and record the time (no write).
  3. Candidate held for switch_delay_s → queue the switch, set applied.

The dwell exists so a flapping grid reading cannot toggle the PCS between PQ and VF.

Actuation path

The switch is not written over Modbus by the control logic. It is queued and executed by the PCS client through pcs_power_sequence.change_mode_pcs(), i.e. the mode_pq / mode_vf sequences in emsConfig/pcs/power_sequences/<model>.json, which write register 0x5066:

"mode_pq": [{"operation": "write_single", "address": "0x5066", "value": 0, "encoding": "u16", "verify": true}],
"mode_vf": [{"operation": "write_single", "address": "0x5066", "value": 1, "encoding": "u16", "verify": true}]

0x5066 (= 20582 decimal) is named on_off_grid_mode in the PCS register map — 0 = on-grid/PQ, 1 = off-grid/VF.

Guard in the sequence layer

Because backup owns the grid mode at runtime, pcs_power_sequence refuses to apply pq / vf from configuration while backup is involved:

  • pcs_power_sequence.backup_involved(mode=None) reads ems_operation_mode from emsConfig/ems/ems_control_setting.json (normalised, so BACKUP_PEAK_SHAVING and backup_peakshaving both match) and returns True for any backup* mode.
  • execute_sequence(..., action="mode_pq" | "mode_vf") raises PowerSequenceError when backup is involved — unless the caller passes allow_during_backup=True.

So the configured mode cannot flip the PCS during backup, while the backup controller still can: change_mode_pcs() defaults allow_during_backup=True, and the queued command carries "allow_during_backup": true so the PCS client forwards it. set_power_kw and the other actions are unaffected by the guard.

Power dispatch

While the grid is lost the PCS discharge functions.Backup.backup_power_setpoint_kw, a plant total allocated across the active PCS with _equal_allocate_with_caps against each unit's power_limits.max_discharge_kw — the same allocation Manual_Operation uses. +kW means discharge.

State is per PCS in _BACKUP_POWER_APPLIED, so a cycle that computes the same setpoint as last time queues nothing. When the grid returns the hold is released with a single 0 kW, source backup_power.

SOC handling:

  • min_soc_pct is the reserve set aside for an outage. It can only tighten the general_settings.pcs.<id>.soc_limits.min_soc_pct floor, never loosen it.
  • Reaching the floor stops the discharge and disarms the controller, printing SOC floor reached -> backup discharge disarmed until SOC recovers.
  • While disarmed, further outages do not discharge. The controller re-arms only once grid-present telemetry shows SOC ≥ recovery_soc_pct. That latch is what stops a repeated outage from walking the battery further down each time.

Unknown grid state (no voltage telemetry) or a missing SOC reading means no action: the PCS are left exactly as they are rather than guessed at.

Configuration

functions.Backup

Key Live value Meaning
enabled false Backup mode master switch, reported by the UI.
backup_power_setpoint_kw null Back-up discharge power to hold while the grid is lost, in kW (plant total). Must be > 0 or nothing is dispatched.
min_soc_pct null SOC reserve for an outage. Tightens the general floor; reaching it disarms the discharge.
recovery_soc_pct null SOC the pack must reach before the discharge re-arms after hitting the floor.
response_time_ms null Recorded; not used.
black_start_enable true Black-start intent flag.
priority_rule backup_overrides_all Documented precedence.

functions.Backup.grid_mode_switch

Key Live value Meaning
enabled false Master switch for the PQ/VF governor. Off ⇒ no action at all.
grid_loss_voltage_v 100.0 Average L-N voltage below which the grid counts as lost.
grid_loss_frequency_hz_low 47.0 Lower frequency bound.
grid_loss_frequency_hz_high 53.0 Upper frequency bound.
switch_delay_s 3.0 Dwell before a staged switch is queued.

Note there is deliberately no PQ/VF target value in this block — the target is derived from live grid state. If grid_loss_voltage_v or the frequency bounds are omitted, the code falls back to 100 V / 47–53 Hz.

functions.Backup.power_dispatch

Key Live value Meaning
enabled false Master switch for the power dispatch. Off ⇒ no power is dispatched, whatever backup_power_setpoint_kw says.

Safety

  • Returns when is_external_control_active().
  • The grid-mode half returns when grid_mode_switch.enabled is false; the power half returns when power_dispatch.enabled is false. Both default to false, so a fresh install writes nothing.
  • The power half returns when backup_power_setpoint_kw is missing or ≤ 0.
  • Every discharge setpoint still passes through the per-PCS power_limits safety clamp inside _pcs_connect_and_set_power_kw, so the backup request can never exceed the unit's rating.
  • Returns when grid voltage telemetry is missing, leaving the PCS mode untouched rather than guessing.
  • Dwell plus per-PCS state prevents PQ/VF flapping.
  • Only the newest unapplied grid-mode switch is kept in the queue; other queued commands (including operator/manual ones) are preserved.
  • A rejected switch is logged as an error and dropped by the PCS client, not retried forever.

Not implemented: deriving the back-up power automatically from the measured island load. backup_power_setpoint_kw is an operator-set constant, not a closed-loop follow of the backed-up load. Recharging back up after an outage is likewise left to the normal grid-connected mode.

Outputs

Call Queue action Source
_pcs_connect_and_set_grid_mode(cfg, pcs_id, mode) where mode is pq or vf mode_pq / mode_vf backup_grid_mode
_pcs_connect_and_set_power_kw(cfg, pcs_id, ±kW, source=_BACKUP_POWER_SOURCE) set_power_kw backup_power