Skip to content

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:

  1. A verified reactive-power setpoint register in emsConfig/pcs/power_sequences/<model>.json.
  2. reactive_power_actuation.enabled: true with that register number filled in.

Safety

  • Returns when is_external_control_active(), when enabled is 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); null limits ⇒ 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.