VOLTAGE_SUPPORT
Volt-VAR (Q(U)) reactive support at the point of interconnection.
| Mode string | VOLTAGE_SUPPORT (EMS_OP_VOLTAGE_SUPPORT) |
| Dispatcher | ems_main.py → control_logic_updated.control_step_voltage_support |
| Config block | functions.Voltage_Support |
| Queue action | set_reactive_kvar (via _pcs_connect_and_set_reactive_power_kvar) |
| Queue source tag | voltage_support |
| Status | Implemented, actuation gated off by default |
Purpose
Reads grid voltage from the grid meter (per-phase L-N, averaged), converts to per-unit using
nominal_voltage_v, and evaluates a four-breakpoint Q(U) curve to decide how much reactive power to
inject or absorb.
The curve
v_pu = avg(L1, L2, L3 grid L-N voltage) / nominal_voltage_v
v_pu <= v_low_pu -> Q = +q_max_kvar (full capacitive injection)
v_low_pu < v_pu <= v1_pu -> linear +q_max_kvar -> 0
v1_pu <= v_pu <= v2_pu -> Q = 0 (deadband)
v2_pu < v_pu <= v_high_pu-> linear 0 -> -q_max_kvar
v_pu > v_high_pu -> Q = -q_max_kvar (full inductive absorption)
Sign convention: +kvar = inject (capacitive), −kvar = absorb (inductive).
A missing or invalid q_max_kvar, or breakpoints that cross, cause a return with no action.
Configuration
functions.Voltage_Support
| Key | Live value | Meaning |
|---|---|---|
enabled |
false |
Master switch. |
nominal_voltage_v |
230 |
Base for the per-unit conversion. |
v_low_pu |
0.9 |
Lower breakpoint — full injection below this. |
v1_pu |
0.98 |
Start of the deadband. |
v2_pu |
1.02 |
End of the deadband. |
v_high_pu |
1.1 |
Upper breakpoint — full absorption above this. |
q_max_kvar |
null |
Max reactive power per direction. null ⇒ no action. |
ramp_rate_limit_kvar_s |
null |
Ramp limit for the reactive setpoint. |
response_time_ms |
null |
Recorded; not used. |
soc_limits |
{null, null} |
SOC bounds. |
power_caps_kw |
{null, null} |
Active-power caps (reserved). |
priority_rule |
voltage_support_over_pf_correction |
Outranks PF correction. |
reactive_power_actuation |
enabled: false |
See below. |
The actuation gate
"reactive_power_actuation": {
"enabled": false,
"register": null,
"scale_kvar_per_unit": null,
"sign_convention": "positive_capacitive",
"rated_kva": null
}
The control step computes and logs the required kvar every cycle, but queues nothing unless
reactive_power_actuation.enabled is true and register is non-null. This exists because the
commissioned PCS power sequence does not yet define a verified reactive-power setpoint register —
writing an unverified register on a live BESS is not acceptable.
Two things are required to activate this mode:
- A verified reactive-power setpoint register in
emsConfig/pcs/power_sequences/<model>.json. reactive_power_actuation.enabled: truewith that register number filled in.
Safety
- Returns when
is_external_control_active(), whenenabledis false, or with no active PCS. - Returns when grid voltage is unavailable — never guesses.
- Total kvar is split equally across active PCS (
q_total / len(pcs_ids)). - Each PCS's reactive capability is checked against
general_settings.pcs.<id>.reactive_power_limits(max_capacitive_kvar/max_inductive_kvar);nulllimits ⇒ the writer refuses. The setpoint is clamped to those limits before queueing. - The writer refuses any value outside the configured capability and only ever keeps the newest unapplied reactive setpoint.
Shared reactive slot: Volt-VAR and PF correction share one reactive queue slot (
_REACTIVE_QUEUE_SOURCES). The most recently queued one wins — they overwrite each other's pending command.
Outputs
_pcs_connect_and_set_reactive_power_kvar(cfg, pcs_id, kvar) → queue action set_reactive_kvar,
source voltage_support.