EMS Operation Modes
Documentation for every EMS operation mode in EnergySyc_EMS_ES100Cx12S.
Each mode has its own page under docs/modes/ (also listed in the Operation Modes section of this site).
Mode index
| Mode | Dispatcher in ems_main.py |
Config block | Implemented |
|---|---|---|---|
| ANTI_BACKFLOW | control_step |
functions.Anti_Backflow |
Yes |
| MANUAL | control_step_manual |
functions.Manual_Operation |
Yes |
| PEAK_SHAVING | control_step_peak_shaving |
functions.Peak_Shaving |
Yes |
| VALLEY_FILLING | control_step_valley_filling |
functions.Valley_Filling |
Yes |
| SCHEDULED_CHARGE_DISCHARGE | control_step_scheduled_charge_discharge |
functions.Scheduled_Charge_Discharge |
Yes |
| ARBITRAGE | control_step_arbitrage |
functions.Arbitrage |
Yes |
| FREQUENCY_REGULATION | external process ems_frequency_regulation_direct_modbus_v4.py |
functions.Frequency_Regulation |
Yes (separate process) |
| VOLTAGE_SUPPORT | control_step_voltage_support |
functions.Voltage_Support |
Yes (actuation gated) |
| POWER_FACTOR_CORRECTION | control_step_power_factor_correction |
functions.Power_Factor_Correction |
Yes (actuation gated) |
| BACKUP | control_step_backup (pre-dispatch) |
functions.Backup |
Grid-mode governor + power dispatch |
| BACKUP_PEAK_SHAVING | control_step_backup |
functions.Backup_Peak_Shaving |
Composition stub |
| BACKUP_FREQUENCY_REGULATION | control_step_backup |
functions.Backup_Frequency_Regulation |
Composition stub |
| IDLE | inline | none | Yes (no-op) |
| STOP_ALL | control_step_stop_all |
none, by design | Yes |
| FFR | external process (alias of FREQUENCY_REGULATION) | functions.Frequency_Regulation |
Yes (alias) |
| PAYLOAD_DIAGNOSTIC_TEST | diagnostic interlock (pre-dispatch) | diagnostic_test_mode (top level) |
Yes |
| SELF_TEST | inline (no control actions) | functions.Self_Test |
Yes |
| MAINTENANCE | control_step_maintenance |
functions.Maintenance |
Yes |
| ENERGY_OPTIMIZATION | dispatch stub | functions.Energy_Optimization |
No — awaiting spec |
| POWER_NODE_ENERGY_SHARING | dispatch stub | functions.Power_Node_Energy_Sharing |
No — awaiting spec |
| GRID_SYNC | dispatch stub | functions.Grid_Sync |
No — awaiting spec |
The canonical mode strings live in ems_operation_modes.py (EMS_OP_* and ALL_EMS_OPERATION_MODES).
The selected mode is read from ems_operation_mode in emsConfig/ems/ems_control_setting.json.
Runtime detail status
The read-only GET /api/v1/ems/operation-status endpoint reports what the active
mode is doing right now (charging / discharging / idle / stopped) with the reason
and the per-PCS SOC standing.
operation-status-api.md- API reference: request, auth, curl (from Laravel), response schema, error codes.operation-status.md- how the status is derived and why.
Common architecture
The control loop runs at control_settings.ems_refresh_rate_hz (currently 2 Hz). Each cycle it
loads the merged lastValue telemetry into a values dict and calls exactly one control_step_*
function. Control steps are stateless per call: no while True, no sleep, one call = one decision.
lastValue telemetry ──► values dict ──► control_step_<mode>(values)
│
▼
emsConfig/pcs/<pcs_id>/pcs_write_queue.json
│
▼
pcs_client_save_data_v21_ES100CX12S.py (drains the queue)
│
▼
pcs_power_sequence.py ──► Modbus ──► PCS
Control logic never opens Modbus. It only writes commands into the per-PCS write queue under an
fcntl lock with an atomic temp-file + fsync + os.replace. The PCS client drains that queue and
executes the model-specific sequence (emsConfig/pcs/power_sequences/<model>.json).
Sign convention
| Value | Meaning |
|---|---|
+kW |
discharge (battery to grid/load) |
-kW |
charge (grid to battery) |
0 |
stop power |
For reactive power (+kvar = inject / capacitive, -kvar = absorb / inductive).
Priority and safety rules enforced everywhere
is_external_control_active()— ifems_control_modenormalises toexternal_control, every control step returns immediately; the external bridge owns the PCS.functions.<Mode>.enabled— every mode is off by default.- SOC gating is direction-aware via
_soc_block_reason(soc, min_soc, max_soc, action): discharge→ blocked bymin_soc_pctonly (the ceiling is ignored),charge→ blocked bymax_soc_pctonly (the floor is ignored),- unknown/
Noneaction → both bounds apply, - SOC telemetry missing → blocked (fail-safe).
- Per-PCS allocation uses
_equal_allocate_with_caps(total_kw, eligible, caps_kw)— iterative equal share that redistributes from PCS which have hit their own cap. - Final hard clamp happens inside
_pcs_connect_and_set_power_kwagainst each PCS'spower_limits.max_charge_kw/power_limits.max_discharge_kw, so no mode can exceed a PCS rating.
Telemetry keys
| Quantity | Key |
|---|---|
| Grid power | gridMeter_lastValue__gridMeter_active_power_total_kw |
| Grid reactive power | gridMeter_lastValue__gridMeter_reactive_power_total_kvar |
| Grid per-phase L-N voltage | gridMeter_lastValue__gridMeter_voltage_l1_n_v, ..._l2_n_v, ..._l3_n_v |
| Grid frequency | gridMeter_lastValue__gridMeter_frequency_hz |
| Grid power factor | gridMeter_lastValue__gridMeter_pf_total |
| Per-PCS SOC | <pcs_id>_lastValue__pcs_soc_state_of_charge_item (several fallbacks) |
PCS capacity, SOC limits, grid mode and device addressing live under
general_settings.pcs.<pcs_id> in emsConfig/ems/ems_control_setting.json. Each mode page listed
above documents that mode's own config block and every key it actually reads.