How to Edit Alarm Thresholds
Change an existing alarm's trigger, its recovery threshold, its delays, or whether it is enabled — either through the EMS frontend or by editing the alarm map directly.
Purpose
Retune an alarm that already exists. This does not create alarms; for that see How to Add a New Alarm.
Prerequisites
- Admin or super-admin login (
AdminOrSuperAdmin). - The device's map readable by the backend.
- For the JSON route: write access to the EMS backend's
emsConfig/, and a note that the backend holds this tree — read it while the service is running rather than from memory.
Relevant Files
| Path | Role |
|---|---|
emsConfig/<category>/<device_id>/<prefix>_alarm_code.json |
The alarm map |
emsConfig/<category>/<device_id>/<prefix>_alarm_code___<model>.json |
Per-model override — wins over the base for that model |
ems_alarm_maps.py |
Validation, including the hysteresis rule |
resources/views/alarmDefinitionEditor.blade.php |
The editor |
The per-model file takes precedence. If pcs_alarm_code___epcs105.json carries
PCS-OVER-TEMP, editing the base pcs_alarm_code.json will not change what an epcs105
device reports. Edit the file that applies to the model in question — the editor shows you
which one it loaded (map_path).
Method A — Using the EMS Frontend
- Open
/alarm-definition-editor(routealarmDefinitionEditor). - Select the device category via the device dropdown. The list comes from the backend's own discovery, so it always reflects what is configured.
- Select the active device. If a device is listed but has no map, the page says so instead of failing.
- The editor resolves the manufacturer and model itself and shows the model next to the device id.
- It loads the correct
*_alarm_code___<model>.jsonfor that model. - Find the alarm in the Entries table by code, field or display name.
- Edit the threshold: change
op(orcondition) and the value. - Change the comparison operator if the direction itself is wrong —
>to>=, and so on. - Set
recovery_valueto the clearing threshold. It must sit on the clearing side of the trigger, or the engine refuses the save (see the table below). - Update
trigger_delayandrecovery_delayin seconds. - Submit. Validation happens on save, not on blur.
- On success the page reports the save; reload and confirm the file hash has moved.
- Confirm the new behaviour by driving the register past the new threshold.
Changing >= 60 to >= 55
"PCS-OVER-TEMP": {
"alarm_display_name": "PCS overtemperature",
"severity": "major",
"field": "<the temperature field from pcs_register_full___epcs105.json>",
"op": ">=",
"value": 60
}
becomes
"PCS-OVER-TEMP": {
"alarm_display_name": "PCS overtemperature",
"severity": "major",
"field": "<the temperature field from pcs_register_full___epcs105.json>",
"op": ">=",
"value": 55,
"recovery_value": 50,
"trigger_delay": 10,
"recovery_delay": 60
}
The recovery threshold went from absent to 50. A recovery threshold is what stops the
alarm chattering across the trigger: with >= 55 and recovery_value: 50, the alarm
activates at 55 °C and does not clear until the device is back below 50 °C, so a fan cycling
between 54 and 56 °C no longer produces a storm of raise/clear pairs.
The
fieldis shown as a placeholder deliberately. The real temperature register name differs per PCS model and must be read from that model's register map. Writing a plausible-looking register name produces a map that validates, saves, and then never fires — the worst outcome, because it looks correct.
The hysteresis rule
recovery_value must sit on the clearing side of the trigger:
| Trigger | Recovery must be | Example |
|---|---|---|
> 60 / >= 60 |
< 60 |
recovery_value: 55 |
< 5 / <= 5 |
> 5 |
recovery_value: 8 |
== 3 |
!= 3 |
recovery_value: 0 |
!= 3 |
== 3 |
recovery_value: 3 |
Refusal text, verbatim:
The engine refused the actions: … recovery_value 60 does not recover past the trigger (> 55),
so the alarm would never clear
And on a rule with no numeric threshold:
'recovery_value' needs a numeric comparison; 'truthy' has no threshold to recover past
How a change fans out to other devices
Alarms live in per-model files, so a change affects every device sharing that model, not
just the one you have selected. On the live system pcs has three models —
epcs105, sinexcel_pws1_250k, sungrow_sc250ud — and 12 pcs devices. Editing
pcs_alarm_code___epcs105.json changes every epcs105 device at once. If you want one
unit changed, you need the change in a file only that unit reads, which for a shared model
means the base file is the wrong lever.
Check the blast radius before saving:
# which devices share the model you are about to edit?
grep -rl "<the-model-name>" emsConfig/*/*/*_alarm_code___*.json
Method B — Editing the JSON Configuration
- Resolve the file. Do not guess the folder from the device id — on the live system
air_condition_unit / AC-UNIT-001readsair_condition_unit/ac1/ac_alarm_code.json. Ask the backend:
curl -s "http://<ems-host>/api/v1/ems/alarms/maps?device_type=air_condition_unit&device_id=AC-UNIT-001" \
| python3 -c "import json,sys; print(json.load(sys.stdin)['data']['map_path'])"
- Back the file up. The engine keeps five
.bak-api-*files per save, but take your own copy so you can reverse a mistake without archaeology. - Edit the entry's
op/condition, value,recovery_value,trigger_delay,recovery_delayorenabled. - Validate the JSON parses before saving — a malformed map is worse than a stale one.
- Save, then confirm through the API that the hash moved and the new value is returned.
Editing by hand bypasses the editor's field pickers but not the engine's validation, which runs on the next save. A file edited into an invalid state will be refused the next time anyone saves through the UI, with the refusal naming the offending key.
Examples
Widening tolerance on a boolean alarm
Before — any fault raises it:
{
"AC-1001": {
"alarm_display_name": "Fault Active",
"severity": "major",
"field": "fault_active",
"op": "truthy"
}
}
After — staged off while the unit is serviced:
{
"AC-1001": {
"alarm_display_name": "Fault Active",
"severity": "major",
"field": "fault_active",
"op": "truthy",
"enabled": false
}
}
enabled: false is how you silence an alarm without deleting it, preserving its history and
its configured actions.
From a raw count to a sustained condition
Before:
{
"AC-1006": { "field": "sensor_fault_count", "op": "> 0", "severity": "major" }
}
After — tolerate a single transient, escalate on a persistent fault:
{
"AC-1006": {
"field": "sensor_fault_count",
"op": "> 0",
"severity": "major",
"trigger_delay": 60,
"recovery_delay": 300
}
}
Testing
- Change a threshold to something the device currently crosses, so it must fire.
- Wait
trigger_delayand confirm the alarm activates. - Return the value to between the two thresholds and confirm the alarm stays active —
this is the hysteresis working. If it clears here,
recovery_valueis on the wrong side. - Go past
recovery_valueand confirm it clears afterrecovery_delay. - Confirm both transitions were recorded in TimescaleDB.
Against the simulator this is quick; against real plant it is not, which is why the threshold is worth testing on the simulator first.
Troubleshooting
| Symptom | Cause |
|---|---|
Save refused, recovery_value … does not recover past the trigger |
Recovery is on the firing side |
Save refused, 'recovery_value' needs a numeric comparison |
recovery_value set on truthy/falsy/bit |
Save refused, the map changed since it was read (expected HASH, found HASH) |
Another save landed between read and write. Reload, re-apply, resubmit |
| Edited the base file, the device did not change | A ___<model> override exists and takes precedence |
| One device changed and twelve did not (or vice versa) | You edited a per-model file; all devices of that model follow it |
| The threshold changed but the alarm never fires | The field name does not exist in the register map — it validates and silently never evaluates |
| The alarm oscillates | No recovery_value, or recovery_delay too short |