Skip to content

API reference - GET /api/v1/ems/operation-status

Operation detail-status endpoint. Reports what the EMS is doing right now for the active operation mode: charging, discharging, idling, or parked at 0 kW with the reason (SOC limit, missing reading, disabled function, outside window, ...), per plant and per PCS.

For how the status is derived and why, see operation-status.md.

Method GET
Path /api/v1/ems/operation-status
Query mode (optional) - report this mode instead of the configured one
Auth Authorization: Bearer <token> (only if the backend has a token set)
Body none
Side effects none - read-only, never writes a PCS queue, never opens Modbus
Served by ems_settings_api.py server (same process as /api/v1/ems/health)

Base URL and token (Laravel)

Laravel config Env Value on this deployment
ems.backend_url EMS_BACKEND_URL http://ems-backend:8080
ems.backend_token EMS_BACKEND_TOKEN unset in the Laravel container

The EMS backend config lives in config/ems.php as ems.backend_url / ems.backend_token. There is no services.ems_backend entry in config/services.php and no timeout key, so config('services.ems_backend.url') returns null. Existing callers (EMSOutBoundDataController) use rtrim(config('ems.backend_url'), '/') and hardcode ->timeout(10).

The EMS backend is Docker-internal. Run the curl from the Laravel container or any container on the same compose network - the URL is not meant to be exposed to browser JavaScript.

curl

Standard call (token from the Laravel container's own environment):

curl -sS \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${EMS_SETTINGS_API_TOKEN}" \
  "${EMS_BACKEND_URL:-http://ems-backend:8080}/api/v1/ems/operation-status"

Without a token

While the backend runs with no token configured, the Authorization header is not required at all: an empty --bearer-token makes _authorized() return True for every request, so the call succeeds with no header (see Auth is currently off on this deployment - set EMS_SETTINGS_API_TOKEN on ems-backend to close this).

From the ems-frontend container, hitting the backend directly:

docker exec ems-frontend sh -lc \
  'curl -sS -H "Accept: application/json" "$EMS_BACKEND_URL/api/v1/ems/operation-status"'

That returns 200 and the full JSON body - identical to the token form. The same holds from any container on the compose network:

docker exec ems-backend sh -lc \
  'curl -sS http://127.0.0.1:8080/api/v1/ems/operation-status'

This applies to the EMS backend endpoint only. The Laravel proxy route has its own gate (verify.emsHardware_bearer) and still demands a token, so a token-less call to it fails:

docker exec ems-frontend sh -lc \
  'curl -sS http://ems-nginx/api/v1/ems/operation-status'
# {"error":"Token missing"}
# HTTP 401

From the Laravel container (ems-frontend)

The service is ems-frontend - the container the Laravel/SCADA app runs in. Two calls can be made from it: the direct call to the EMS backend (below), and the proxied call through the Laravel route (see The Laravel proxy route, from the container).

The token in that container is exported as EMS_SETTINGS_API_TOKEN, not EMS_BACKEND_TOKEN (that one is empty there). Confirm the environment before copying a command:

docker exec ems-frontend sh -lc 'echo "URL=[$EMS_BACKEND_URL]"; echo "EMS_SETTINGS_API_TOKEN=${#EMS_SETTINGS_API_TOKEN}"; echo "EMS_BACKEND_TOKEN=${#EMS_BACKEND_TOKEN}"'
# URL=[http://ems-backend:8080]
# EMS_SETTINGS_API_TOKEN=42
# EMS_BACKEND_TOKEN=0

The simplest form needs no compose file at all — target the container by name:

docker exec ems-frontend sh -lc \
  'curl -sS -H "Accept: application/json" -H "Authorization: Bearer $EMS_SETTINGS_API_TOKEN" "$EMS_BACKEND_URL/api/v1/ems/operation-status"'

docker compose exec also works, but only if you pass the same -f list the stack uses (gess-stack_build.sh:480). A bare docker compose exec fails: there is no docker-compose.yml in /opt/gess-stack, because the stack is composed from docker-compose.maria.yml plus docker-compose.resources.yml.

cd /opt/gess-stack
docker compose -f docker-compose.maria.yml -f docker-compose.resources.yml \
  exec -T ems-frontend sh -lc \
  'curl -sS -H "Accept: application/json" -H "Authorization: Bearer $EMS_SETTINGS_API_TOKEN" "$EMS_BACKEND_URL/api/v1/ems/operation-status"'

The literal form, with the token spelled out. Keep the real value in EMS_SETTINGS_API_TOKEN - it is a shared secret and should not be committed:

curl -sS \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <ems-settings-api-token>" \
  http://ems-backend:8080/api/v1/ems/operation-status

Verdict only (what a control form needs to render):

curl -sS \
  -H "Authorization: Bearer ${EMS_SETTINGS_API_TOKEN}" \
  "http://ems-backend:8080/api/v1/ems/operation-status" \
| jq '{mode: .operation_mode, action, reason, summary, blocked: [.detail.blocked_pcs[]?]}'

Ask a different mode:

curl -sS -H "Authorization: Bearer ${EMS_SETTINGS_API_TOKEN}" \
  "http://ems-backend:8080/api/v1/ems/operation-status?mode=SCHEDULED_CHARGE_DISCHARGE"

The Laravel proxy route, from the container

The frontend exposes its own GET /api/v1/ems/operation-status (EMSOutBoundDataController@operationStatus), which forwards to the EMS backend. Run it from inside ems-frontend, and point it at the nginx container (ems-nginx) - ems-frontend runs php-fpm only and answers nothing on localhost:80.

The route is guarded by verify.emsHardware_bearer, so it needs a bearer token. That token is already in the container's own .env (Laravel reads EMS_SETTINGS_API_TOKEN from /var/www/html/.env, 42 chars), so pull it from there instead of pasting a literal - the command is self-contained:

docker exec ems-frontend sh -lc '
  TOKEN=$(sed -n "s/^EMS_SETTINGS_API_TOKEN=//p" .env | head -1 | tr -d "\r\"")
  curl -sS -H "Accept: application/json" -H "Authorization: Bearer $TOKEN" \
    http://ems-nginx/api/v1/ems/operation-status'

EMS_BACKEND_TOKEN from the same .env is also accepted (len=42 as well). Either value must match a server_bearer_tokens row with status_01 = 'EMS', which is what the middleware looks up; read the stored value back with:

docker exec -u www-data ems-frontend php artisan tinker --execute='echo DB::table("server_bearer_tokens")->where("status_01","EMS")->value("bearer_token");'

sed is used rather than source .env so a value with spaces or quotes cannot break the shell. Without the header the middleware answers 401 {"error":"Token missing"}; with a valid token it returns the live EMS status (200), the same body the direct call produces. See Proxy config keys for the keys the controller forwards with.

Auth is currently off on this deployment

ems-backend is started with --bearer-token set to an empty string, so ems_settings_api.py treats an empty bearer token as "authorize everything". The variable is present in the container (42 chars, loaded from emsConfig/ems/ems_api_config.json by load_ems_api_token()); the launcher blanks it for this one process on purpose, because the settings API is reachable only on the Docker network and the shared token is still exported for the outbound push to the frontend (start_ems_client_in_docker.sh:234):

EMS_SETTINGS_API_TOKEN="" start_py "ems_http_api" ems_settings_api.py server ...

...and the check that makes an empty token permissive:

def _authorized(self) -> bool:
    if not self.bearer_token:
        return True
    return self.headers.get("Authorization", "") == f"Bearer {self.bearer_token}"

So a missing header, a wrong header and a raw token all return 200. The 401 row in the Errors table below does not apply here. Set EMS_SETTINGS_API_TOKEN on the ems-backend service to enforce it.

Laravel / PHP

The frontend already proxies this endpoint. routes/api.php:133 maps it inside the v1/ems group (the api prefix is added by RouteServiceProvider):

Route::group([
    'prefix' => 'v1/ems',
    'middleware' => ['verify.emsHardware_bearer'],
], function () {
    Route::get('/operation-status', 'Api\V1\EMS\EMSOutBoundDataController@operationStatus');
});

So the full path is GET /api/v1/ems/operation-status, guarded by verify.emsHardware_bearer (App\Http\Middleware\EmsSettingBearerToken). That middleware requires an Authorization: Bearer <token> value present in server_bearer_tokens with status_01 = 'EMS' - a missing header yields 401 {"error":"Token missing"}, an unknown one 401 {"error":"Invalid token"}. There is also a bearer-free web alias, GET /ems-operation-status (routes/web.php:2693), but it sits in the web group, so anonymous requests get 401 {"message":"Unauthenticated."}.

Proxy config keys

The controller forwards to the backend with the keys config/ems.php defines:

$url   = rtrim((string) config('ems.backend_url'), '/') . '/api/v1/ems/operation-status';
$token = config('ems.settings_api_token') ?: config('ems.backend_token');

An earlier build read config('services.ems_backend.url') / config('services.ems_backend.token') instead (fixed in commit bc26b9e3). Those keys do not exist - config/services.php has no ems_backend entry, so both were null, the URL collapsed to the relative path /api/v1/ems/operation-status, cURL had no host to connect to, and every authenticated caller got 502:

{"system":"EMS","status":"unreachable","error":"URL rejected: No host part in the URL","timestamp":"..."}

In the container ems.backend_url is http://ems-backend:8080, and both ems.settings_api_token and ems.backend_token are populated (42 chars). The sibling outbound calls in this controller and DiagnosticTestDebugController read the same keys.

Rewritten with the HTTP client, the working call is:

Http::baseUrl(rtrim((string) config('ems.backend_url'), '/'))
    ->withToken((string) (config('ems.settings_api_token') ?: config('ems.backend_token')))
    ->acceptJson()
    ->timeout(10)
    ->get('/api/v1/ems/operation-status')
    ->json();

No UI consumer calls the route yet: the dashboards read ems_operation_status from the stored settings JSON (EmsHardwareDashboardController), not from this API.

The controller's request, from inside the container

To see exactly what operationStatus() puts on the wire, resolve the same config keys it reads and curl them directly from inside ems-frontend. Pulling the values out of Laravel (not the shell environment) means the command cannot drift from the controller:

docker exec ems-frontend sh -lc '
  BASE=$(php artisan tinker --execute="echo rtrim((string) config(\"ems.backend_url\"), \"/\");" 2>/dev/null | tr -d "\r\n")
  TOKEN=$(php artisan tinker --execute="echo config(\"ems.settings_api_token\") ?: config(\"ems.backend_token\");" 2>/dev/null | tr -d "\r\n")
  echo "BASE=[$BASE] token_len=${#TOKEN}"
  curl -sS -H "Accept: application/json" -H "Authorization: Bearer $TOKEN" \
    "$BASE/api/v1/ems/operation-status"'

On this deployment it prints BASE=[http://ems-backend:8080] token_len=42 and returns the status body with 200 - the same JSON the proxy route relays. Drop the -H "Authorization: ..." header and it still returns 200, because the backend's own bearer check is a no-op here (see Auth is currently off on this deployment).

Response 200

{
  "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
      }
    ]
  }
}

Top-level fields

Field Type Meaning
timestamp int Server time in epoch milliseconds.
source string Always ems-backend.
operation_mode string Mode actually resolved (alias-expanded, validated against ALL_EMS_OPERATION_MODES).
operation_mode_requested string | null Raw ems_operation_mode from the settings file.
operation_status_published string | null Value the EMS loop last wrote to ems_operation_status (the effective mode).
control_mode string local_control, scada_control, or external_control.
grid object active_power_total_kw, frequency_hz (both may be null).
action string Decided action - see the vocabulary below.
reason string | null Machine-readable cause code.
summary string One-line human-readable verdict.
detail object Mode-specific explanation (may be empty for safety-only modes).

detail fields

Field Type Meaning
requested_kw float Plant setpoint the mode wants to apply. Sign: + discharge, - charge.
eligible_pcs string[] PCS that pass the gate for the resolved direction.
blocked_pcs object[] {id, reason} for PCS the gate refuses.
gates object Mode-specific inputs used for the decision (grid kW, thresholds, window, slot, ...).
pcs object[] Per-PCS detail (below). May be absent for IDLE/STOP_ALL/etc.
requested_kvar float Present only for reactive actions.
error string Present only when a mode's evaluation hit an internal error.

detail.pcs[] fields

Field Type Meaning
id string PCS id (e.g. pcs1).
soc_pct float | null SOC reading the gate used.
min_soc_pct / max_soc_pct float | null Band in force (per-PCS limits tightened by the mode's own band).
charge_allowed / discharge_allowed bool Whether the SOC gate permits each direction now.
eligible bool True when allowed for the resolved direction.
block_reason string | null e.g. SOC 95.0% >= max_soc 80, SOC 8.0% <= min_soc 10, SOC missing.
applied_kw float | null Last setpoint the PCS accepted (null until the first write).
applied_direction string | null charge, discharge, stop.
applied_source string | null Queue source tag, e.g. control_logic, stop_all, soc_guard.
applied_age_ms int | null Age of that setpoint in milliseconds.
applied_stale bool | null True when older than 10 s.

action vocabulary

Value Meaning
charging PCS commanded to charge (requested_kw negative).
discharging PCS 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 - 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.

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 stopped Charge blocked: outside the enabled charge window.
no_charge_windows_configured stopped Charge blocked: no charge_windows configured.
no_valid_enabled_charge_window stopped Charge blocked: charge_windows exist but none valid+enabled.
exporting_no_charge stopped Valley filling never charges while exporting.
all_pcs_soc_blocked stopped Every PCS hit its SOC bound for the direction.
manual_stop stopped Manual operation type is STOP.
stop_all stopped STOP_ALL holds every active PCS at 0 kW.
maintenance_hold_zero stopped MAINTENANCE suspends control and holds 0 kW.
arbitrage_price_dependent idle/charging/discharging Direction read from the last applied setpoint; the live decision needs the price feed.
no_control_strategy not_running Mode is registered but unimplemented (ENERGY_OPTIMIZATION, POWER_NODE_ENERGY_SHARING, GRID_SYNC, DYNAMIC_LOAD_BALANCING).
status_evaluation_error idle Internal error while describing the mode; see detail.error.

Errors

Status Body Cause
401 {"error": "unauthorized"} Authorization header missing or not exactly Bearer <token>. Only reachable once EMS_SETTINGS_API_TOKEN is set on ems-backend - see Auth is currently off on this deployment.
404 {"error": "not_found"} Path not served by the backend.
500 {"error": "operation_status_failed", "detail": "<message>"} The evaluator raised; detail carries the exception message.

Note: data problems (missing grid reading, missing SOC, unknown mode) do not produce an error status - they are reported inside a 200 body as action: "idle"/"stopped" with an explanatory reason.

CLI equivalent (no server needed)

python3 ems_operation_status.py                      # configured mode
python3 ems_operation_status.py --mode ANTI_BACKFLOW # a specific mode

Examples

Charging, all PCS eligible:

{
  "action": "charging",
  "reason": "slot_active",
  "summary": "Charging 30.0 kW schedule slot [22:00-06:00 weekly]",
  "detail": {
    "requested_kw": -30.0,
    "eligible_pcs": ["pcs1", "pcs2"],
    "blocked_pcs": []
  }
}

Stopped because a PCS hit max_soc:

{
  "action": "stopped",
  "reason": "all_pcs_soc_blocked",
  "summary": "Wanted charge 25.0 kW but every PCS is SOC-blocked",
  "detail": {
    "requested_kw": -25.0,
    "eligible_pcs": [],
    "blocked_pcs": [
      {"id": "pcs1", "reason": "SOC 95.0% >= max_soc 90.0"},
      {"id": "pcs2", "reason": "SOC 96.0% >= max_soc 90.0"}
    ]
  }
}

Idle, grid inside the anti-backflow band:

{
  "action": "idle",
  "reason": "grid_within_band",
  "summary": "Grid 0.0 kW within band -> holding 0 kW",
  "detail": {
    "requested_kw": 0.0,
    "gates": {"grid_kw": 0.0, "export_limit_kw": 0.0}
  }
}