Skip to content

Operation detail status

This page explains how the status is derived and why. For the API contract (request, auth, curl, response schema, error codes), see operation-status-api.md.

A single read-only endpoint that answers what the EMS is doing right now for the active operation mode: charging, discharging, idling, or parked at 0 kW because a gate refused to act (SOC limit, missing reading, disabled function, outside window, ...), with the reason and the per-PCS detail.

Endpoint GET /api/v1/ems/operation-status
Server python3 ems_settings_api.py server (same process as /health, /readings)
Evaluator ems_operation_status.build_operation_status()
Optional query ?mode=<MODE> reports a different mode than the configured one
Side effects none - never writes a PCS queue, never opens Modbus

Why it exists

The control steps only print their decisions, and the read-only ems_operation_status register carries the mode name alone. There was no way to learn why a mode was idle, or whether it stopped because a PCS hit min_soc or max_soc. This endpoint derives that from state that already exists:

  • the settings file (ems_operation_mode, the functions.* blocks, limits),
  • the merged lastValue telemetry (grid power/frequency, per-PCS SOC),
  • the last accepted setpoint per PCS, written by ems_pcs_power_publisher.publish_pcs_power_setting() to lastValue/<pcs>_power_setting_lastValue.json.

It reuses the same pure helpers the controllers use - effective_soc_band, _soc_block_reason, the peak-shaving / valley-filling window caps, scheduled_charge_discharge_step, the backup grid-mode verdict - so the explanation cannot drift from the control logic for the parts that matter most (the SOC gate and the schedule).

Action vocabulary

action Meaning
charging PCS is commanded to charge (requested_kw negative)
discharging PCS is commanded to discharge (requested_kw positive)
idle Connected, 0 kW, holding or nothing to do
stopped Deliberately parked at 0 kW (STOP_ALL, MAINTENANCE, SOC block, window block)
regulating FREQUENCY_REGULATION - the external fast controller owns the setpoints
reactive VOLTAGE_SUPPORT / POWER_FACTOR_CORRECTION kvar output
not_running External control owns the PCS, or the mode has no strategy yet

Sign convention matches the controller: requested_kw is + discharge, - charge.

Response

{
  "timestamp": 1760000000000,
  "source": "ems-backend",
  "operation_mode": "SCHEDULED_CHARGE_DISCHARGE",
  "operation_mode_requested": "SCHEDULED_CHARGE_DISCHARGE",
  "operation_status_published": "SCHEDULED_CHARGE_DISCHARGE",
  "control_mode": "local_control",
  "grid": {"active_power_total_kw": -12.4, "frequency_hz": 50.01},
  "action": "charging",
  "reason": "slot_active",
  "summary": "Charging 30.0 kW schedule slot [22:00-06:00 weekly]",
  "detail": {
    "action": "charging",
    "reason": "slot_active",
    "requested_kw": -30.0,
    "eligible_pcs": ["pcs1", "pcs2"],
    "blocked_pcs": [],
    "gates": {"slot": {"start": "22:00", "end": "06:00", "source": "weekly"}},
    "pcs": [
      {
        "id": "pcs1",
        "soc_pct": 55.0,
        "min_soc_pct": 10.0,
        "max_soc_pct": 80.0,
        "charge_allowed": true,
        "discharge_allowed": true,
        "eligible": true,
        "block_reason": null,
        "applied_kw": -30.0,
        "applied_direction": "charge",
        "applied_source": "control_logic",
        "applied_age_ms": 480,
        "applied_stale": false
      }
    ]
  }
}

Key fields

Field Meaning
operation_mode The mode actually resolved (alias-expanded, validated).
operation_status_published The value the EMS loop last wrote to ems_operation_status (the effective mode), or null.
control_mode local_control, scada_control, or external_control.
action / reason / summary The one-line verdict and its cause.
detail.requested_kw Plant setpoint the mode wants to apply (signed).
detail.eligible_pcs PCS that pass the gate for the resolved direction.
detail.blocked_pcs PCS the gate refuses, each with its reason.
detail.pcs[].soc_pct SOC reading the gate used.
detail.pcs[].min_soc_pct / max_soc_pct Band in force (per-PCS tightened by the mode band).
detail.pcs[].block_reason e.g. SOC 95.0% >= max_soc 80, SOC 8.0% <= min_soc 10, SOC missing.
detail.pcs[].applied_* Last accepted setpoint: kW, direction, source tag, age.

Common reason values

reason Action Meaning
mode_idle idle IDLE performs no control actions.
external_control_active not_running ems_control_mode=external_control - the bridge owns the PCS.
diagnostic_interlock stopped A diagnostic test suspends normal BESS operations.
functions.<X>.enabled=false idle The mode's master switch is off.
grid_reading_missing idle No gridMeter active-power reading.
grid_within_band idle Anti-backflow: grid inside the export deadband - 0 kW.
within_hysteresis_band_hold idle Peak/valley: inside the band - holding the last setpoint.
outside_charge_window / no_charge_windows_configured / no_valid_enabled_charge_window stopped Charge blocked by the window policy.
exporting_no_charge stopped Valley filling never charges while exporting.
all_pcs_soc_blocked stopped Every PCS hit its SOC bound for the direction.
arbitrage_price_dependent idle/charging/discharging Direction read from the last applied setpoint; live decision needs the price feed.

Mode coverage

Every mode in ALL_EMS_OPERATION_MODES is described: IDLE, ANTI_BACKFLOW, MANUAL, STOP_ALL, PEAK_SHAVING, SCHEDULED_CHARGE_DISCHARGE, ARBITRAGE, FREQUENCY_REGULATION, VALLEY_FILLING, POWER_FACTOR_CORRECTION, VOLTAGE_SUPPORT, PAYLOAD_DIAGNOSTIC_TEST, MAINTENANCE, ENERGY_OPTIMIZATION, POWER_NODE_ENERGY_SHARING, GRID_SYNC, BACKUP, BACKUP_PEAK_SHAVING, BACKUP_FREQUENCY_REGULATION, and DYNAMIC_LOAD_BALANCING. Mode strings are alias-expanded via DEPRECATED_MODE_ALIASES before describing.

Usage

# what the currently configured mode is doing
curl -s http://127.0.0.1:8080/api/v1/ems/operation-status | python3 -m json.tool

# ask a different mode
curl -s "http://127.0.0.1:8080/api/v1/ems/operation-status?mode=VALLEY_FILLING"

# same report from the CLI, without the server
python3 ems_operation_status.py --mode ANTI_BACKFLOW

Notes

  • The report is computed on each request from files, so it always reflects the latest lastValue snapshot, not a cached cycle.
  • applied_kw is null until a control step has written at least one setpoint (the publisher file appears on the first write).
  • Arbitrage is the one mode whose live decision depends on the electricity-price feed; the endpoint reports the applied direction and the SOC standing instead of calling the network.