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_pctisnullandnominal_hzis absent. Withdroop_pctnull the controller computes a 0 kW setpoint regardless of frequency, so this mode is inert as shipped. Supplydroop_pct,deadband_hzandparticipation_pctbefore enabling.
Safety
- Only runs while
ems_operation_mode == FREQUENCY_REGULATION; otherwiseems_main.pystops 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: allowmeans 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.