HTTP API
Served by ems_settings_api.py server inside the ems-backend container on port 8080.
Laravel calls it server-side at http://ems-backend:8080. Browsers call Laravel, not this service.
Authentication
When EMS_SETTINGS_API_TOKEN is set, every request needs:
Authorization: Bearer <token>
A missing or wrong token returns 401. When the variable is empty, authentication is disabled, which is only acceptable on a closed network.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/ems/health |
Liveness check |
| GET | /api/v1/ems/settings |
Read the active settings |
| PUT | /api/v1/ems/settings |
Replace the settings |
| POST | /api/v1/ems/settings |
Replace the settings |
| GET | /api/v1/ems/readings |
All current device values |
| GET | /api/v1/ems/readings/{device} |
One device snapshot |
| GET | /api/v1/ems/operation-status |
Current dispatch action, control mode, and per-PCS eligibility |
| GET | /api/v1/ems/register-maps |
Every register map, gzipped |
| POST | /api/v1/ems/diagnostic-tests |
Trigger or schedule diagnostic tests |
| GET | /api/v1/ems/diagnostic-tests |
Diagnostic state, schedules, and catalog |
| GET | /api/v1/ems/diagnostic-tests/report/latest |
Latest XML diagnostic report |
| GET | /api/v1/ems/device-models |
Device types and their available models (see device-models-api.md) |
| GET | /api/v1/ems/register-map |
The merged ems_register_full.json the Modbus server loads, as raw bytes |
| GET | /api/v1/ems/alarms |
Active alarms across every configured device |
| GET | /api/v1/ems/alarms/self-test |
The same pipeline against synthetic self-test alarms |
| GET | /api/v1/ems/alarms/definitions |
The alarm definitions |
| GET | /api/v1/ems/alarms/maps |
One device's alarm map (requires device_type and device_id) |
| PUT | /api/v1/ems/alarms/maps |
Replace one device's alarm map |
Both alarms/maps rows above are also reachable through the EMS frontend at
/alarm-map-edit — the one engine endpoint the frontend republishes on the public
hostname, because ems-nginx proxies only / to Laravel and alarm maps must be
editable from outside the Docker network. GET/PUT with a bearer token is the
API; the same URL renders an editable page to a signed-in Admin, whose form posts
to the CSRF-protected save route. A GET with no device parameters returns the
editor's device index. See accessing-alarms.md §8.
Health
{ "status": "ok", "service": "ems-backend" }
Settings
GET returns the contents of emsConfig/ems/ems_control_setting.json.
PUT and POST require the complete settings object. The body replaces the file; it is not merged. The EMS picks it up on the next control cycle.
Every consumer reads the settings through this endpoint. There is no shared-folder copy any more: the --mirror-path option that wrote ems-hardware/1/ems_hardware_GTW-ems100CX.json went with that file, and the simulator frontend reads GET /api/v1/ems/settings when it renders.
Readings
GET /api/v1/ems/readings:
{
"timestamp": 1769374275562,
"source": "ems-backend",
"devices": {
"pcs1_lastValue": { "pcs_soc_state_of_charge_item": 55.2 },
"gridMeter_lastValue": { "gridMeter_active_power_total_kw": 1.02 }
}
}
Keys under devices are the filename stems in lastValue/.
GET /api/v1/ems/readings/gridMeter_lastValue:
{
"timestamp": 1769374275562,
"source": "ems-backend",
"device": "gridMeter_lastValue",
"readings": { "gridMeter_active_power_total_kw": 1.02 }
}
An unknown device returns 404 with {"error": "device_not_found"}.
These endpoints read whatever the collectors last wrote. They do not provide history.
Alarm maps
GET /api/v1/ems/alarms/maps requires both device_type and device_id. A map
belongs to exactly one device, so the route cannot answer without them.
GET /api/v1/ems/alarms/maps?device_type=pcs&device_id=pcs1
{
"timestamp": 1791298952639,
"source": "ems-backend",
"changed": false,
"device_type": "pcs",
"component_type": "pcs",
"device_id": "pcs1",
"reading_key": "pcs1_lastValue",
"model": "ES100CX12S",
"status": "ok",
"map_file": "emsConfig/pcs/pcs1/..."
}
Missing either parameter returns 400 with
{"error": "alarm_map_rejected", "detail": "device_type and device_id are required"}.
Both parameters present but naming a device that does not exist returns 404 with
{"error": "alarm_map_not_found", "detail": "no <device_type> device with id '<device_id>'"}.
Parameter order does not matter.
PUT /api/v1/ems/alarms/maps replaces one device's map. The device identity and
the entries go in the body (device_type, device_id, entries). An optional
expected_hash makes a write that would clobber someone else's edit fail instead
of overwriting it.
Diagnostic tests
Served by the same process as the settings API. The test engine lives in
ems_diagnostic_tests.py; site-specific procedures live in
ems_diagnostic_handlers.py.
GET /api/v1/ems/diagnostic-tests returns the current state, pending schedules,
and the full test catalog:
{
"state": "idle",
"active": false,
"queued": 0,
"scheduled": [],
"catalog": [
{
"mode_number": 1,
"name": "State of Health (SOH) Estimation",
"description": "",
"implemented": true
}
]
}
implemented is true only when a handler has been registered for that mode
number. A non-implemented test still runs and reports
"outcome": "not_implemented".
POST /api/v1/ems/diagnostic-tests triggers tests immediately, or schedules them
for a later time. It accepts a single test:
{ "mode_number": 1 }
or several at once:
{ "multi_select": { "modes": [1, 2, 9] } }
To schedule instead of running immediately, add an ISO-8601 UTC timestamp:
{ "mode_number": 1, "date-time": "2026-01-30T08:00:00Z" }
The same can be expressed as
"multi_select": { "modes": [...], "scheduled_time": "..." }.
The response is 202:
{
"accepted": true,
"diagnostic": {
"run_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
"mode_numbers": [1],
"selected_name": "State of Health (SOH) Estimation",
"requested_at": "2026-01-30T08:00:00.000+00:00",
"scheduled_for": null,
"source": "api",
"state": "queued"
}
}
state is queued for immediate runs and scheduled when a future time is
given.
The request is checked before the job is queued: mode_number,
multi_select.modes, and the timestamp. A value the endpoint cannot use is
answered 400 naming the field at fault, never with a Python parser message.
{ "error": "date-time must be an ISO-8601 timestamp, for example 2026-01-30T08:00:00Z" }
GET /api/v1/ems/diagnostic-tests returns the engine's state. Faults inside the
engine, rather than in the request, surface as stable codes instead of exception
text:
stateerrorwith"error": "diagnostic_run_failed"when a run fails outside any single test. The exception is kept undererror_detail.reports[].upload.error"diagnostic_report_upload_failed"when a report could not be posted to the configured results API, with the exception underupload.detail.
A fault while producing the state itself answers 500
{"error": "diagnostic_status_failed", "detail": "..."}.
GET /api/v1/ems/diagnostic-tests/report/latest returns the most recent report
as application/xml. Each selected test writes its own XML file under
diagnostic_reports/; this endpoint returns the last one written. It responds
404 when no report exists yet, and 500
{"error": "diagnostic_report_unreadable"} when the file cannot be read.
A test that could not run is reported inside the XML rather than as an HTTP
status, because the request itself was valid. Its TestResult then carries:
ErrorCode— a stable code, currentlydiagnostic_handler_failed.Summary— a sentence naming the test that could not run.ErrorDetail— the exception as raised, for whoever diagnoses the test.
A test that ran and simply failed its own criteria is unaffected: it reports
Outcome and Passed with no error code.
A convenience runner exists at the project root:
./run_diagnostic_test.sh 1
./run_diagnostic_test.sh 1 2 9
./run_diagnostic_test.sh --schedule "2026-01-30T08:00:00Z" 1 2
./run_diagnostic_test.sh --status
./run_diagnostic_test.sh --list
./run_diagnostic_test.sh --report soh.xml
Status codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 202 | Diagnostic tests accepted (queued or scheduled) |
| 400 | The request body is missing, malformed, or not what the endpoint needs |
| 401 | Missing or wrong bearer token |
| 404 | Unknown route, device, or report not found |
| 500 | Unexpected failure inside the service |
| 503 | Diagnostic service unavailable |
Server options
python3 ems_settings_api.py server \
--host 0.0.0.0 \
--port 8080 \
--path emsConfig/ems/ems_control_setting.json \
--lastvalue-dir lastValue \
--bearer-token "$EMS_SETTINGS_API_TOKEN"