Skip to content

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:

  • state error with "error": "diagnostic_run_failed" when a run fails outside any single test. The exception is kept under error_detail.
  • reports[].upload.error "diagnostic_report_upload_failed" when a report could not be posted to the configured results API, with the exception under upload.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, currently diagnostic_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"