Skip to content

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

  1. Open /alarm-definition-editor (route alarmDefinitionEditor).
  2. Select the device category via the device dropdown. The list comes from the backend's own discovery, so it always reflects what is configured.
  3. Select the active device. If a device is listed but has no map, the page says so instead of failing.
  4. The editor resolves the manufacturer and model itself and shows the model next to the device id.
  5. It loads the correct *_alarm_code___<model>.json for that model.
  6. Find the alarm in the Entries table by code, field or display name.
  7. Edit the threshold: change op (or condition) and the value.
  8. Change the comparison operator if the direction itself is wrong — > to >=, and so on.
  9. Set recovery_value to the clearing threshold. It must sit on the clearing side of the trigger, or the engine refuses the save (see the table below).
  10. Update trigger_delay and recovery_delay in seconds.
  11. Submit. Validation happens on save, not on blur.
  12. On success the page reports the save; reload and confirm the file hash has moved.
  13. 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 field is 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

  1. Resolve the file. Do not guess the folder from the device id — on the live system air_condition_unit / AC-UNIT-001 reads air_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'])"
  1. 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.
  2. Edit the entry's op/condition, value, recovery_value, trigger_delay, recovery_delay or enabled.
  3. Validate the JSON parses before saving — a malformed map is worse than a stale one.
  4. 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

  1. Change a threshold to something the device currently crosses, so it must fire.
  2. Wait trigger_delay and confirm the alarm activates.
  3. Return the value to between the two thresholds and confirm the alarm stays active — this is the hysteresis working. If it clears here, recovery_value is on the wrong side.
  4. Go past recovery_value and confirm it clears after recovery_delay.
  5. 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