Skip to content

FREQUENCY_REGULATION

Primary frequency response: discharges on under-frequency, charges on over-frequency, following a droop curve.

Mode string FREQUENCY_REGULATION (EMS_OP_FREQUENCY_REGULATION)
Dispatcher Separate process, started/stopped by ems_main.py
Controller ems_frequency_regulation_direct_modbus_v4.py
Config block functions.Frequency_Regulation
Status Implemented (external fast controller)

Purpose

The only mode that does not run inside the normal 2 Hz dispatch. Because frequency response needs a much tighter loop, ems_main.py starts it as a child process and then skips its own dispatch:

if mode == EMS_OP_FREQUENCY_REGULATION:
    freq_reg.start()

ems_main.py launches it as python3 ems_frequency_regulation_direct_modbus_v4.py. When the mode changes away, freq_reg.stop() is called.

Why it is a separate process

It talks to the PCS directly over Modbus, bypassing the write-queue architecture used by every other mode. It also reads the grid frequency directly rather than through the merged lastValue telemetry path.

The controller accepts these mode strings: FREQUENCY_REGULATION, FREQUENCY_REG, FFR.

The droop curve

compute_reg_setpoint_kw(freq_hz, cfg, plant_discharge_cap_kw, plant_charge_cap_kw):

nominal   = cfg.nominal_hz  (default 50.0)   # not present in the shipped config
deadband  = cfg.deadband_hz
droop     = cfg.droop_pct
df        = freq_hz - nominal

if |df| <= deadband or droop <= 0:
    return 0.0

if df < 0:                                   # under-frequency -> discharge
    kw_per_hz = (droop / 100) * plant_discharge_cap_kw
    req = +kw_per_hz * (|df| - deadband)     # clamped to plant_discharge_cap_kw
else:                                        # over-frequency -> charge
    kw_per_hz = (droop / 100) * plant_charge_cap_kw
    req = -kw_per_hz * (|df| - deadband)     # clamped to plant_charge_cap_kw

return req * (participation_pct / 100)

Sign convention matches the rest of the EMS: +kW discharge, −kW charge. A separate apply_ramp_limit stage limits how fast the setpoint may move.

Configuration

functions.Frequency_Regulation

Key Live value Meaning
enabled false Master switch.
grid_mode on-grid-only Frequency response only while grid-tied.
droop_pct null Droop percentage. null/0 ⇒ the controller returns 0 kW.
deadband_hz null Deadband around nominal frequency.
participation_pct null Scaling factor applied to the setpoint (100 = full).
response_time_ms null Recorded; not used in the droop formula.
ramp_rate_limit_kw_s null Ramp limit applied to the output setpoint.
soc_limits {null, null} SOC bounds for the fast loop.
soc_recovery_target_pct null Recharge target.
power_caps_kw {null, null} Plant caps.
frequency_measurement_interval_ms null Frequency sampling interval.
priority_rule frequency_over_arbitrage_valley Documented precedence.
telemetry_api object External reporting (endpoint_url, api_key, send_frequency_ms, failover_behavior: last-setpoint).
recharge_windows[] 5 entries start, end, enabled, charge_cap_kw — windows for SOC recovery.
logging object JSONL logging (flush_interval_ms, rotation, batch size).
soc_source object type: lastValue_json, missing_soc_behavior: allow.

Blocking item: droop_pct is null and nominal_hz is absent. With droop_pct null the controller computes a 0 kW setpoint regardless of frequency, so this mode is inert as shipped. Supply droop_pct, deadband_hz and participation_pct before enabling.

Safety

  • Only runs while ems_operation_mode == FREQUENCY_REGULATION; otherwise ems_main.py stops it.
  • grid_mode: on-grid-only — the intent is to not perform frequency response in island/backup operation.
  • SOC handling per soc_limits; soc_source.missing_soc_behavior: allow means a missing SOC reading does not block, which is a deliberate choice for a fast primary-response loop — review it against your protection philosophy.
  • telemetry_api.failover_behavior: last-setpoint — keeps the last setpoint if reporting fails.

Relationship to FFR

FFR is accepted by this controller as an alias but is not dispatched by ems_main.py — selecting FFR does not start this process.