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}
}
}