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:
applied == desired→ nothing to do.candidate != desired→ stage the new candidate and record the time (no write).- Candidate held for
switch_delay_s→ queue the switch, setapplied.
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)readsems_operation_modefromemsConfig/ems/ems_control_setting.json(normalised, soBACKUP_PEAK_SHAVINGandbackup_peakshavingboth match) and returns True for anybackup*mode.execute_sequence(..., action="mode_pq" | "mode_vf")raisesPowerSequenceErrorwhen backup is involved — unless the caller passesallow_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_pctis the reserve set aside for an outage. It can only tighten thegeneral_settings.pcs.<id>.soc_limits.min_soc_pctfloor, 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.enabledis false; the power half returns whenpower_dispatch.enabledis false. Both default to false, so a fresh install writes nothing. - The power half returns when
backup_power_setpoint_kwis missing or ≤ 0. - Every discharge setpoint still passes through the per-PCS
power_limitssafety 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_kwis 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 |