Skip to content

Active alarms API

Served by ems_settings_api.py (the server sub-command), implemented in ems_alarm_status.py. Read-only and stateless: it never writes a queue, never opens Modbus, and never touches controller state. Alarms are derived from the current lastValue files, so the endpoint reports what is alarming now — there is no retained alarm history, and it is safe to poll on a ~1 Hz cadence.

Full reference: alarm-mapping-and-endpoints.md. That document covers the whole mapping chain (register map → reading → alarm map → settings gate), the alarm-map entry schema, the condition grammar and comparison semantics, message/severity formatting, the map generator, and a worked example. This file is the endpoint summary only.

Endpoints

Method / path Purpose
GET /api/v1/ems/alarms active alarms from live readings
GET /api/v1/ems/alarms/self-test the same pipeline against synthetic alarms
GET /api/v1/ems/alarms/definitions every alarm each device's map defines, active or not

Path constants DEFAULT_ALARMS_PATH, DEFAULT_ALARM_SELF_TEST_PATH and DEFAULT_ALARM_DEFINITIONS_PATH; CLI flags --alarms-path, --alarms-self-test-path and --alarms-definitions-path. The server listens on container port 8080 (--port).

Query parameters

/api/v1/ems/alarms reads no query parameters. In particular ?device_type= has no effect on that path — verified: ?device_type=pcs returns the same 18 devices and identical totals as the unfiltered call, with only the per-reading timestamps differing (the readings are live).

The filter exists on /api/v1/ems/alarms/self-test and on /api/v1/ems/alarms/definitions, not on the live path:

parameter effect
?device_type=<type> keep only that device_type
?device=<type> alias for the above

Filtering happens after each device is evaluated, so totals.devices_checked reflects it. The module docstring at ems_settings_api.py:133 states that the live endpoint also accepts the filter; the code does not implement it.

Authentication

Authorization: Bearer <token>, and open when no token is configured — the server compares against --bearer-token, whose default is $EMS_SETTINGS_API_TOKEN (empty when unset).

On the current deployment the server is started without a token, so every caller is accepted; ems-frontend and anything else on the Docker network can read the report without credentials. The API is not published to the host (only the Modbus port 1540 is), which is the effective boundary. Enforce auth with:

python3 -u ems_settings_api.py server --bearer-token "$EMS_SETTINGS_API_TOKEN"

The bearer_token in emsConfig/ems/ems_api_config.json is a client credential used by the pull/push helpers, not this server's authentication, and it already includes the Bearer prefix.

Calling it

# from the host (8080 is not published, so go through the container)
docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms

# from another container on the same network — 127.0.0.1 is refused there
docker exec ems-frontend curl -s http://ems-backend:8080/api/v1/ems/alarms

# self-test, filtered
docker exec ems-backend curl -s \
  'http://127.0.0.1:8080/api/v1/ems/alarms/self-test?device_type=pcs'

Response

Top-level keys: timestamp, source, self_test, totals, alarms, devices. self_test is false on the live path and true on the self-test path, and the self-test payload carries an extra top-level note stating that its alarms are synthetic and are reported only by that endpoint.

totals holds devices_checked, devices_skipped, devices_with_alarms and active_alarms. devices_skipped counts devices hidden by the settings gate (§1.6 of the full reference): a device type whose general_settings group has statuses and none of them active is not reported, because nobody polls a switched-off device and thresholds read from its frozen reading would be phantom alarms. The self-test endpoint ignores that gate, so it covers every configured device.

alarms[] schema (illustrative):

{
  "device_type": "pcs",
  "device_dir": "pcs1",
  "component_type": "pcs",
  "device_id": "pcs1",
  "reading_key": "pcs1",
  "model": "EPCS105",
  "alarm_code": "PCS-SOC-LOW",
  "alarm_display_name": "Battery SOC Critically Low",
  "message": "Battery state of charge below 3%, discharge must stop (measured 2%).",
  "severity": "critical",
  "field": "soc_state_of_charge_item",
  "register_address": 3005,
  "value": 2,
  "condition": "< 3.0",
  "detected_at": "2026-10-01T01:45:43.378000+00:00",
  "detected_at_ms": 1790819143378
}

devices[] row, captured live:

{
  "device_type": "grid_energy_meter",
  "device_dir": "grid_meter1",
  "component_type": "EMS",
  "device_id": "gridEnergyMeter1",
  "reading_key": "gridMeter",
  "model": "ME231",
  "status": null,
  "has_reading": true,
  "reading_timestamp_ms": 1790819138257,
  "alarm_map": "gridMeter_alarm_code___me231.json",
  "alarm_map_source": "model",
  "active_alarm_count": 0
}

Self-test alarm row, captured live:

{
  "device_type": "air_condition_unit",
  "device_dir": "ac1",
  "component_type": "airConditionor",
  "device_id": "airConditionor1",
  "reading_key": "acUnit",
  "model": "AC_STD",
  "alarm_code": "SELFTEST-001",
  "alarm_display_name": "Self-Test Alarm (Critical)",
  "severity": "critical",
  "message": "Cooling fault active: temperature control lost.",
  "field": "__self_test__",
  "register_address": null,
  "value": null,
  "condition": "self-test",
  "detected_at": "2026-10-01T01:45:43.378000+00:00",
  "detected_at_ms": 1790819143378,
  "self_test": true
}

Notes:

  • alarms sort by severity (critical, major, minor, warning, unknown last), then device id, then alarm code.
  • detected_at is the timestamp of the device reading that carried the alarm (UTC ISO-8601, microseconds); onset tracking across polls is intentionally not persisted. On a self-test row it is the moment the report was built.
  • condition is the normalised rule. An op rule echoes its stored operand unchanged, so {"op": "<", "value": 3} reports "< 3"; a condition shorthand is parsed through _literal, whose numeric result is a float, so "< 3" reports "< 3.0". A truthy/falsy rule reports the operator alone, which is what most rows say — that is the form the generated maps use.
  • alarm_map_source is model when a model-specific map was used and default otherwise. A device for which no map file resolves carries "note": "no_alarm_map"; no device does so at present.
  • component_type need not match device_type: grid_energy_meter devices report EMS and air_condition_unit devices report airConditionor.
  • device_dir is the emsConfig directory the device lives in, and device_type is its parent. Together they identify the device: the control settings name the same pair in the register file they declare for a unit (door_sensor/door_sensor1/door_sensor_register_full.json), so a consumer can pair a settings unit with the alarms that belong to it without inferring which map applies. device_id cannot serve that purpose - it is the register map's own id, which need not match anything in the settings (gridEnergyMeter1 for a unit the settings call grid_meter1).
  • reading_key may differ from device_id (gridEnergyMeter1 → gridMeter, ups_unit → ups), and is null when no reading file was found — currently Cl1_P1 (bmu) and fireSuppression1, both of which also report has_reading: false.
  • status is the settings entry's status for that device key, and null when the settings index has no matching entry or that entry carries no status.

Definitions response

/api/v1/ems/alarms/definitions answers what can go wrong here: every alarm each device's map defines, one row per definition, whether or not it is firing. It is the catalogue behind the alarm_map filename the other endpoints report, and it is what a config editor can search to find the register an alarm belongs to.

Top-level keys: timestamp, source, totals, devices, note. A devices row is the same summary the live report returns (device_type, device_dir, component_type, device_id, reading_key, model, status, alarm_map, alarm_map_source) plus definition_count and a definitions array:

{
  "alarm_code": "PCS-1004",
  "alarm_display_name": "A Phase Overvoltage Fault Flag",
  "message": "A-phase overvoltage fault: voltage has exceeded the safe operating limit.",
  "severity": "critical",
  "field": "a_phase_overvoltage_fault_flag",
  "condition": "truthy",
  "active": false
}
  • message is the map's own wording exactly as stored — what /api/v1/ems/alarms emits, minus the measured clause the engine appends at report time. For an alarm that is not firing there is no reading to quote, and the catalogue is meant to show the authored text a map editor would change.
  • condition is the normalised rule (truthy, < 3.0, bit 3), the form the live rows carry; field is the reading/register name it reads.
  • active uses the same evaluation the live report uses — an unreadable field, or a zero reading on a map that sets ignore_zero, counts as not active — so an inactive row here is exactly one the live report leaves out.
  • Unlike the live report the settings gate is not applied: a switched-off device type is still configured and its alarms are still worth documenting. totals.devices_checked therefore matches the self-test report (23) and there is no devices_skipped; every device row carries status so a caller can still tell which are off. This is also why active_alarms here can be higher than the live report's: a rule that is firing on a hidden device type still counts here.
  • Rows sort by severity rank (unknown severities last), then alarm_code.
  • Synthetic SELFTEST-* entries are excluded; only /alarms/self-test reports them.
  • ?device_type= / ?device= filter as on the self-test path.

The full catalogue is 2,345 rows and serves ~845 KB, so fetch it once and filter client-side, or narrow it with ?device_type=.

Status codes

condition status
authorised 200
token configured, header missing or wrong 401 {"error": "unauthorized"}
path outside the known set 404 {"error": "not_found"}
engine raised 500 {"error": "alarm_report_failed"\|"alarm_self_test_failed"\|"alarm_definitions_failed", "detail": "…"}

Counts at the time of writing

Captured from ems-backend on 2026-10-01 01:45 UTC (container clock). Counts move with the device configuration, so re-run the endpoints rather than trusting this table.

Request devices_checked devices_skipped active_alarms
/api/v1/ems/alarms 18 5 0
/api/v1/ems/alarms/self-test 23 0 69
/api/v1/ems/alarms/self-test?device_type=pcs 12 0 36
/api/v1/ems/alarms/self-test?device=ups 1 0 3
/api/v1/ems/alarms/self-test?device_type=bmu 1 0 3
/api/v1/ems/alarms/definitions 23 — 2

The definitions call additionally reports alarm_definitions: 2345 and has no devices_skipped (the settings gate does not apply to it).

The 5 skipped types are those whose devices are all inactive in ems_control_setting.json: air_condition_unit, fire_safety_system, frequency_meter, liquid_cooling_unit, sensor_block. They remain fully visible through the self-test endpoint.