Skip to content

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.

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() — if ems_control_mode normalises to external_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 by min_soc_pct only (the ceiling is ignored),
  • charge → blocked by max_soc_pct only (the floor is ignored),
  • unknown/None action → 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_kw against each PCS's power_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.