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:
alarmssort by severity (critical,major,minor,warning, unknown last), then device id, then alarm code.detected_atis 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.conditionis the normalised rule. Anoprule echoes its stored operand unchanged, so{"op": "<", "value": 3}reports"< 3"; aconditionshorthand is parsed through_literal, whose numeric result is a float, so"< 3"reports"< 3.0". Atruthy/falsyrule reports the operator alone, which is what most rows say — that is the form the generated maps use.alarm_map_sourceismodelwhen a model-specific map was used anddefaultotherwise. A device for which no map file resolves carries"note": "no_alarm_map"; no device does so at present.component_typeneed not matchdevice_type:grid_energy_meterdevices reportEMSandair_condition_unitdevices reportairConditionor.device_diris the emsConfig directory the device lives in, anddevice_typeis 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_idcannot serve that purpose - it is the register map's own id, which need not match anything in the settings (gridEnergyMeter1for a unit the settings callgrid_meter1).reading_keymay differ fromdevice_id(gridEnergyMeter1→gridMeter,ups_unit→ups), and isnullwhen no reading file was found — currentlyCl1_P1(bmu) andfireSuppression1, both of which also reporthas_reading: false.statusis the settings entry'sstatusfor that device key, andnullwhen the settings index has no matching entry or that entry carries nostatus.
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
}
messageis the map's own wording exactly as stored — what/api/v1/ems/alarmsemits, 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.conditionis the normalised rule (truthy,< 3.0,bit 3), the form the live rows carry;fieldis the reading/register name it reads.activeuses the same evaluation the live report uses — an unreadable field, or a zero reading on a map that setsignore_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_checkedtherefore matches the self-test report (23) and there is nodevices_skipped; every device row carriesstatusso a caller can still tell which are off. This is also whyactive_alarmshere 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-testreports 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.
Related
alarm-mapping-and-endpoints.md— mapping chain, alarm-map schema, condition grammar, generator, worked example.operation-status-api.md— the read-onlyems_operation_statusregister endpoint (/api/v1/ems/operation-status).