Skip to content

How to access EMS alarms

This is the practical guide to getting alarms out of the EMS: where the API lives, how to reach it from a laptop, the exact curl commands, how to read and format the output, and how to keep an eye on it. For the alarm logic (the register → reading → alarm map → settings gate chain, the condition grammar, the map generator) see alarm-mapping-and-endpoints.md.

1. What this API is

Served by ems_settings_api.py (the server sub-command) and implemented in ems_alarm_status.py. It is:

  • Read-only and stateless — it never writes a queue, never opens Modbus, and never touches controller state.
  • Derived from the live lastValue files — it reports what is alarming right now.
  • History-free — there is no retained alarm log, no acknowledge, no clear. When a condition stops being true, the row simply disappears.
  • Cheap enough to poll — a ~1 Hz cadence is fine. Onset tracking across polls is deliberately not persisted.

Because there is no history, "monitoring" means sampling. Section 7 shows how.

2. Where it lives, and why that matters

Container ems-backend
Port 8080, inside the container only (--port, default 8080)
Bind address 0.0.0.0 inside the container (--host)
Published to the host? No — only Modbus 1540 is published

This trips people up: curl http://192.168.6.116:8080/... will not work — nothing is listening on the host's 8080. Four ways in:

From Address
The Docker host docker exec ems-backend curl -s http://127.0.0.1:8080/...
ems-frontend docker exec ems-frontend curl -s http://ems-backend:8080/...
Any sibling container http://ems-backend:8080/... (127.0.0.1 is refused there)
The Docker host, direct http://172.18.0.2:8080/... (container bridge IP)

The bridge IP is the least stable of the three — it changes if the container is recreated. Prefer docker exec or the container name.

3. Quick start

Run these on the Docker host (ssh root@192.168.6.116). jq is installed on the host, which is why it can format output that the container produced:

# 1. The number, for a badge
docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/count | jq

# 2. What is firing right now
docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/active | jq

# 3. One line per alarm
docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/active \
  | jq -r '.alarms[] | "\(.alarm_code)  \(.device_type)  \(.field)  \(.value)  \(.severity)"'

4. Endpoints

All paths sit under the base http://<host>:8080/api/v1/ems.

Path Purpose ?device_type= Typical size
/alarms Full report: active alarms and a per-device summary no ~35 KB
/alarms/active Only what is firing, with the count that matches it yes ~7 KB
/alarms/count Just the number and severity breakdown yes ~180 B
/alarms/definitions Every alarm each map defines, firing or not yes ~0.9 MB
/alarms/maps The alarm-map index (device list, operators, severities) no ~47 KB
/alarms/self-test The same pipeline against synthetic alarms yes ~30 KB

Which one to use:

  • /alarms/active is the one to monitor. It returns the rows and a count computed by the same evaluation, so the number and the rows cannot disagree.
  • /alarms/count is for a badge or a tight poll loop — it skips the rows.
  • /alarms is the richest view (it adds devices[] with per-device status, reading freshness and alarm-map filenames) when you are diagnosing.
  • /alarms/definitions answers "what can go wrong here" — the catalogue a config editor searches. It is large, so either fetch once and filter client-side or narrow it with ?device_type=.
  • /alarms/self-test proves the pipeline end to end without a faulty device. Its rows are synthetic and are reported only here.

Query parameters

Parameter Effect
?device_type=<type> Keep only that device family
?device=<type> Alias for the above

Both are accepted by /alarms/active, /alarms/count, /alarms/definitions and /alarms/self-test. Values are device families such as ems, pcs, bmu, grid_energy_meter.

Two caveats worth knowing:

  • /alarms and /alarms/maps ignore the filter entirely — they report every configured device.
  • ?device_type= has no effect on the live /alarms path. The module docstring in ems_settings_api.py says it does; the code does not implement it there. Use /alarms/active?device_type=... when you want a filtered live view.

5. Call recipes

From the Docker host (most robust — no IP or DNS dependency):

docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/active | jq

From ems-frontend — the container that owns the settings file, and the one the alarm-definition editor writes through. It ships curl:

docker exec ems-frontend curl -s http://ems-backend:8080/api/v1/ems/alarms/active | jq

This is the same address the app itself uses — EMS_BACKEND_URL=http://ems-backend:8080 in the container environment, with config/ems.php falling back to it.

From any other sibling container on the stack network:

docker exec bess-simulator-backend curl -s http://ems-backend:8080/api/v1/ems/alarms/active

From your laptop, one shot, no interactive session:

ssh root@192.168.6.116 'docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/active' | jq

Filtered, one device family:

docker exec ems-backend curl -s 'http://127.0.0.1:8080/api/v1/ems/alarms/active?device_type=ems' | jq

Direct container IP (works on this host, verified):

curl -s http://172.18.0.2:8080/api/v1/ems/alarms/active | jq

Reaching it from your laptop without ssh-ing each time

Tunnel through the host, since the host can reach the bridge IP:

ssh -N -L 8080:172.18.0.2:8080 root@192.168.6.116
# in a second terminal:
curl -s http://127.0.0.1:8080/api/v1/ems/alarms/active | jq

The durable alternative is to publish the port in the compose file ("8080:8080"), after which http://192.168.6.116:8080 works directly. Note that this exposes the alarm API to anyone who can reach the host, so pair it with a bearer token (section 9) if the network is not trusted.

6. Response shape

Top-level keys per endpoint

Endpoint Top-level keys
/alarms timestamp, source, self_test, totals, alarms, devices
/alarms/active timestamp, source, self_test, active_alarm_count, by_severity, devices_checked, devices_with_alarms, devices_not_live, alarms
/alarms/count timestamp, source, self_test, active_alarm_count, by_severity, devices_with_alarms
/alarms/definitions timestamp, source, totals, devices, note
/alarms/maps timestamp, source, device_count, operators, operators_with_value, severities, devices
/alarms/self-test timestamp, source, self_test, totals, alarms, devices, note

self_test is false on every live path and true on /alarms/self-test; the self-test payload carries an extra note stating its rows are synthetic.

Alarm row

Each entry of alarms[] looks like this:

{
  "device_type": "ems",
  "device_dir": "ems",
  "component_type": "ffrEnergyMeter",
  "device_id": "ems",
  "reading_key": "ems",
  "model": "ME231",
  "alarm_code": "EMS-0072",
  "alarm_display_name": "PCS poller Data Stale",
  "severity": "major",
  "message": "PCS poller has not refreshed its readings for more than 30 s; the values it reports are frozen (measured 329374).",
  "field": "ems_pcs_client_age_s",
  "register_address": 3164,
  "value": 329374,
  "condition": "> 30.0",
  "detected_at": "2026-10-10T08:06:31.477000+00:00",
  "detected_at_ms": 1791619591477
}

That row is verbatim from ems-backend on 2026-10-10 08:06 UTC.

The _age_s fields count only units that are switched on. A unit set to inactive in ems_control_setting.json is skipped, and a family with no live unit at all reports 0 ("no reading expected") rather than its frozen age. So a poller stale alarm always means "a poller whose devices are switched on has stopped refreshing" — never "a device you switched off has gone quiet".

Notes on the fields:

  • device_dir + device_type identify a device. Together they match the pair the control settings use for a unit (door_sensor/door_sensor1/…).
  • device_id is the register map's own id and may not match anything in the settings (gridEnergyMeter1 for a unit the settings call grid_meter1). Do not key on it alone.
  • reading_key may also differ from device_id (gridEnergyMeter1 → gridMeter), and is null when no reading file was found.
  • detected_at is the timestamp of the device reading that carried the alarm, not the moment you asked. On a self-test row it is the moment the report was built.
  • condition is the normalised rule, so the same rule can render as > 50 or > 50.0 depending on how the map authored it.

Severity

Rows sort by severity rank, then device id, then alarm code. The rank order is critical, major, minor, warning, with anything unrecognised last.

The counting keys

These four are the ones people misread:

Key Meaning
devices_checked Devices the report looked at (after the settings gate)
devices_with_alarms How many of those contributed at least one row
devices_not_live Devices whose reading is not being refreshed, so their value rules were not evaluated
active_alarm_count Number of rows in alarms[] — counts alarms, not devices

devices_not_live is the important one. A reading is treated as stale once it is older than poll_interval_ms × 10 (LIVE_READING_MULTIPLIER in ems_alarm_status.py), so a slow device is given proportionally longer to go quiet. Such devices are counted and listed rather than silently dropped — their rules are skipped, and the EMS health alarms are what reports the stalled poller behind them. If devices_not_live is high, look at the ems self-health alarms before trusting a low alarm count.

A zero reading on a map that sets ignore_zero, or an unreadable field, counts as not active — that is by design, so an empty register never fabricates an alarm.

7. Monitoring

watch gives a live-refreshing panel:

watch -n 5 'docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/active \
  | jq -r "\"active: \(.active_alarm_count)  not-live: \(.devices_not_live)\",
           (.alarms[] | \"  \(.alarm_code)  \(.field)  \(.value)\")"'

A log-friendly loop with timestamps:

while :; do
  printf '%s  ' "$(date +%H:%M:%S)"
  docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/count \
    | jq -c '{count: .active_alarm_count, sev: .by_severity}'
  sleep 10
done

Just the count, for a script or a status bar:

docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/count \
  | jq -r '.active_alarm_count'

Only the critical rows:

docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/active \
  | jq -r '.alarms[] | select(.severity == "critical") | "\(.alarm_code)  \(.device_type)  \(.message)"'

Group by device family:

docker exec ems-backend curl -s http://127.0.0.1:8080/api/v1/ems/alarms/active \
  | jq -r '.alarms | group_by(.device_type)[] | "\(.[0].device_type): \(length)"'

Look up what an alarm code means

docker exec ems-backend curl -s 'http://127.0.0.1:8080/api/v1/ems/alarms/definitions?device_type=ems' \
  | jq -r '.devices[].definitions[] | select(.alarm_code == "EMS-0072") | "\(.alarm_code)  \(.alarm_display_name)  rule=\(.condition)  field=\(.field)"'

8. Web UI

Two different frontends expose alarm configuration. They are separate apps on separate ports.

UI URL Auth
Simulator threshold editor http://192.168.6.116:9698/alarms/thresholds none (HTTP 200)
EMS alarm definition editor http://192.168.6.116:9595/alarm-definition-editor login required (redirects 302 when unauthenticated)
EMS alarm-map API, public hostname https://ems.gess-sweden.com/alarm-map-edit?device_type=pcs&device_id=pcs1 bearer token; JSON 401 without one. A session may read, never write

Per-device view in the simulator editor:

http://192.168.6.116:9698/alarms/thresholds/device?device_type=ems&device_id=ems

The API endpoints above are the read path; the editors are the write path (they PUT a device's alarm map, guarded by the hash returned on read).

Two things to know about reaching alarms through the frontend:

  • ems-nginx does not proxy the alarm API. Its config carries only location / and location ~ \.php$ — there is no proxy_pass to ems-backend:8080. So http://192.168.6.116:9595/api/v1/ems/alarms/active does not exist. The Laravel app calls the engine server-side over EMS_BACKEND_URL.
  • The frontend's own alarm routes (/ems-alarms-self-test, /alarm-definition-editor) sit behind the login middleware and answer 302 to an unauthenticated curl. They need a session, not just a URL.
  • Exception: /alarm-map-edit republishes GET/PUT /api/v1/ems/alarms/maps on the public hostname. An API client — Accept: application/json, or a bearer token — gets JSON and never a redirect; a browser signed in as Admin gets the alarm-map editor from the same URL:
# read one device's map (bearer token, no session needed)
curl -s -H "Authorization: Bearer $EMS_SETTINGS_API_TOKEN" \
  "https://ems.gess-sweden.com/alarm-map-edit?device_type=pcs&device_id=pcs1"

# replace it — quote back the hash the read returned
curl -s -X PUT -H "Authorization: Bearer $EMS_SETTINGS_API_TOKEN" \
  -H 'Content-Type: application/json' \
  "https://ems.gess-sweden.com/alarm-map-edit" \
  -d '{"device_type":"pcs","device_id":"pcs1","expected_hash":"<hash>","entries":{...}}'

A bearer token matching EMS_SETTINGS_API_TOKEN or EMS_BACKEND_TOKEN may read and write through the JSON API. A signed-in Admin may not PUT that way, and that asymmetry is deliberate: the route is CSRF-exempt so scripts can write, which means a bare browser session must not be able to. An Admin writes instead through the editor page, whose form posts to the CSRF-protected save route — two different doors, each with the guard that fits it. ?token= works for a quick manual check but lands in access logs — prefer the header.

A PUT that changes nothing answers 200 with "changed": false and "backup": null — the engine validates, sees the map already matches, and writes nothing at all. That is the safe way to prove write access without touching a map; a PUT that does change one is backed up into the device's own folder first, and a stale expected_hash is refused with 409 alarm_map_conflict.

Omit device_type/device_id on a GET and the engine answers with its listing instead of one map — every device with its model, map file and entry counts, plus the operators a map may use. That is the index the editor selects from, and the same discovery the alarm reports walk, so a device or model the engine can see is one you can edit with no frontend change. An unknown device answers 404 alarm_map_not_found.

Opening /alarm-map-edit in a browser as Admin gives the same table editor: search and sort the entries, edit thresholds, comparison operators, conditions, severities, register fields, names and messages, enable or disable entries by deleting them, and add new ones. Opening a row is guarded by the hash read with it, so a map edited by someone else meanwhile is refused rather than overwritten. Before saving, the page names the file and every other device that reads it — the blast radius is that file, which is not always the same thing as the model. The engine re-reads maps each cycle, so a save applies on the next one and needs no restart. The previous file is kept beside the map and its name is reported back.

An entry carries more than a threshold. Alongside field, op, value, condition, bit, severity, message, alarm_display_name, description and ignore_zero, these keys are honoured by the evaluator and editable in the table:

Key Meaning
enabled false keeps the entry in the file and the catalogue but it can never raise. Absent means enabled, so it is stored only when off
recovery_value hysteresis: once latched, the alarm holds until the value passes back beyond this threshold, not merely below the trigger. With >= 60 and 55, it clears below 55
trigger_delay seconds the condition must hold before the alarm activates
recovery_delay seconds the condition must stay clear before it clears
data_type how the value is read. Must agree with the type the device's register map declares
register_address the register address. Must agree with the field's address, and can name the field when field is omitted

A recovery threshold recorded on the firing side (a >= 60 rule recovering at 65), a negative delay, a non-boolean enabled, or an address or type contradicting the register map are all refused before the save, because the evaluator could not act on them. Delays and hysteresis need to know the previous cycle, so they are remembered in <stem>_alarmState.json beside the readings — written only for entries that use those keys, so a map without them writes no state and behaves exactly as it did before they existed.

For automation, use /alarm-map-edit above, or go straight to the engine from inside ems-frontend (section 5). The other /alarms/* read endpoints (active, count, self-test, definitions) still have no public route.

9. Authentication

What the code supports

Authorization: Bearer <token>, compared by the server against --bearer-token, whose argparse default is $EMS_SETTINGS_API_TOKEN. An empty token makes _authorized() accept every request.

What this deployment does

Auth is deliberately off. The start script blanks the variable for the server process and passes the flag explicitly empty:

EMS_SETTINGS_API_TOKEN="" start_py "ems_http_api" ems_settings_api.py server \
  --host 0.0.0.0 \
  ... \
  --bearer-token ""

The reasoning is written next to it in start_ems_client_in_docker.sh: the API is reachable only on the Docker network, nothing is published to the host, and ems_control_setting.json is written only by ems-frontend, so a token adds nothing between those two containers.

A token does exist, which is what confuses people: docker inspect ems-backend shows EMS_SETTINGS_API_TOKEN=5|…, and ems-frontend likewise carries EMS_BACKEND_TOKEN=5|…. That shared token belongs to the outbound push path. The server process is started with it blanked.

Verified on this host — all three return 200:

Request Result
no Authorization header 200
Authorization: Bearer nonsense 200
Authorization: Bearer <the real token> 200

So sending a token changes nothing here: it is neither required nor checked.

Turning it on

Give --bearer-token a value and export the identical value to ems-frontend as EMS_BACKEND_TOKEN. Both sides must agree:

docker exec ems-backend curl -s -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/ems/alarms/active

Do not confuse this with bearer_token in emsConfig/ems/ems_api_config.json — that is the client credential for the push to the frontend, and it already includes the Bearer prefix. The host carries a longer write-up at /opt/gess-stack/help/ems_backend_token.md.

10. Status codes

Condition Status
Authorised (or no token configured) 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": "…"}

11. Troubleshooting

Connection refused on 192.168.6.116:8080. Expected. 8080 is not published to the host. Use one of the three routes in section 2.

Connection refused on 127.0.0.1:8080 from inside another container. Inside a container, 127.0.0.1 is that container. Use http://ems-backend:8080.

Empty alarms[] with a high devices_not_live. Not a healthy "all clear" — it usually means pollers have stalled, so rules were skipped rather than evaluated. Check the ems self-health alarms (?device_type=ems), which name the stalled client.

The count and the rows disagree. They should not. /alarms/active and /alarms/count run the same evaluation. If they differ, report it — that is a bug, not a configuration.

A device you expected is missing entirely. The settings gate: a device family whose general_settings group has statuses and none of them active is not reported, because a switched-off device is not being polled. Use /alarms/definitions (which ignores the gate) to confirm the device is configured.

A 500 on /alarms/definitions. It is the largest payload (~0.9 MB) and does real work. Narrow it with ?device_type=.

  • alarm-mapping-and-endpoints.md — the full mapping chain, alarm-map entry schema, condition grammar and semantics, message and severity formatting, the map generator, and a worked example.
  • alarm-code-to-register-relationship.md — how an alarm code ties back to the register that fires it.
  • alarms-api.md — earlier endpoint summary. It predates /alarms/active, /alarms/count and /alarms/maps, so this file is the current reference for the endpoint list.
  • operation-status-api.md — the read-only /api/v1/ems/operation-status endpoint (what the EMS is doing right now).