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, thefunctions.*blocks, limits), - the merged
lastValuetelemetry (grid power/frequency, per-PCS SOC), - the last accepted setpoint per PCS, written by
ems_pcs_power_publisher.publish_pcs_power_setting()tolastValue/<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
lastValuesnapshot, not a cached cycle. applied_kwisnulluntil 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.