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
lastValuefiles — 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/activeis 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/countis for a badge or a tight poll loop — it skips the rows./alarmsis the richest view (it addsdevices[]with per-device status, reading freshness and alarm-map filenames) when you are diagnosing./alarms/definitionsanswers "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-testproves 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:
/alarmsand/alarms/mapsignore the filter entirely — they report every configured device.?device_type=has no effect on the live/alarmspath. The module docstring inems_settings_api.pysays 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_typeidentify a device. Together they match the pair the control settings use for a unit (door_sensor/door_sensor1/…).device_idis the register map's own id and may not match anything in the settings (gridEnergyMeter1for a unit the settings callgrid_meter1). Do not key on it alone.reading_keymay also differ fromdevice_id(gridEnergyMeter1→gridMeter), and isnullwhen no reading file was found.detected_atis 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.conditionis the normalised rule, so the same rule can render as> 50or> 50.0depending 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-nginxdoes not proxy the alarm API. Its config carries onlylocation /andlocation ~ \.php$— there is noproxy_passtoems-backend:8080. Sohttp://192.168.6.116:9595/api/v1/ems/alarms/activedoes not exist. The Laravel app calls the engine server-side overEMS_BACKEND_URL.- The frontend's own alarm routes (
/ems-alarms-self-test,/alarm-definition-editor) sit behind the login middleware and answer302to an unauthenticatedcurl. They need a session, not just a URL. - Exception:
/alarm-map-editrepublishesGET/PUT /api/v1/ems/alarms/mapson 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=.
12. Related documents
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/countand/alarms/maps, so this file is the current reference for the endpoint list.operation-status-api.md— the read-only/api/v1/ems/operation-statusendpoint (what the EMS is doing right now).