Skip to content

How to Add a New Alarm

Add a new alarm to a device so the EMS raises it, records it, and can act on it.

Every statement below is taken from the running code: ems_alarm_maps.py (validation and file handling), EnergySyc_EMS_ES100Cx12S/emsConfig/ (the configuration), and resources/views/alarmDefinitionEditor.blade.php (the editor). Where a thing does not exist, it is called out as an implementation gap rather than described as if it worked.


Purpose

Register a new alarm condition for an existing device, in the device model's alarm map, so that:

  • the EMS evaluates the condition on each poll,
  • the alarm appears in the active-alarm system and is recorded in TimescaleDB,
  • command sequences can be attached to it (see Add an Alarm Action).

An alarm is a map entry, not code. Adding one does not require a backend release.


Prerequisites

  • The EMS backend running, with its settings API reachable (the editor reads it over /api/v1/ems/alarms/maps).
  • An admin or super-admin login for the EMS frontend. The editor's routes sit behind web, App\Http\Middleware\Authenticate and App\Http\Middleware\AdminOrSuperAdmin.
  • The device already exists in emsConfig/ and is polled. A map for it must be readable.
  • php artisan route:clear after any deploy that adds routes — this stack runs with a cached route table (bootstrap/cache/routes-v7.php), and a new route is invisible until the cache is cleared.

Relevant Files

Path Role
emsConfig/<device_category>/<device_id>/<prefix>_alarm_code.json The alarm map (base)
emsConfig/<device_category>/<device_id>/<prefix>_alarm_code___<model>.json Per-model override
emsConfig/<device_category>/<device_id>/<prefix>_register_full.json The register map the fields come from
EnergySyc_EMS_ES100Cx12S/ems_alarm_maps.py Schema, validation, save, backups
resources/views/alarmDefinitionEditor.blade.php The alarm map editor (Blade)
app/Http/Controllers/Ems/AlarmDefinitionsController.php Read/save for that editor
app/Services/EmsAlarmDefinitionsService.php HTTP client to the settings API

Real examples from the live tree:

emsConfig/pcs/pcs1/pcs_alarm_code.json
emsConfig/pcs/pcs1/pcs_alarm_code___epcs105.json
emsConfig/pcs/pcs1/pcs_alarm_code___sinexcel_pws1_250k.json
emsConfig/pcs/pcs1/pcs_alarm_code___sungrow_sc250ud.json
emsConfig/air_condition_unit/ac1/ac_alarm_code.json
emsConfig/solar_energy_meter/solar_meter9/solarMeter_alarm_code.json

The directory and the device id are not always the same string. On the live system the device air_condition_unit / AC-UNIT-001 reads air_condition_unit/ac1/ac_alarm_code.json. Do not construct the path from the device id; read map_path from the API or use the editor, which does it for you.


Frontend Instructions

Open the alarm map editor, which handles all of the path and model resolution:

  1. Sign in as an admin or super-admin.
  2. Go to /alarm-definition-editor (route name alarmDefinitionEditor), or /emsAlarmDefinitions for the catalogue of every device that has a map.
  3. In the Device dropdown, pick the device. The list is built from the backend's own device discovery, so a newly configured device appears without a frontend change.
  4. The page loads that device's model-specific alarm configuration automatically and shows: the model, the map file, the editable-entry count, and a short hash of the file.
  5. Scroll to Add an alarm and fill in the new code, field, comparison, value, severity and display name.
  6. Submit. The engine validates; the page reports either the save or the exact refusal.
  7. The header carries a link to alarm actions → for the same device, where the alarm's command sequences are configured.

Backend Configuration

The alarm entry, key by key

These are the keys the engine understands, enforced in ems_alarm_maps.py:

Key Required Meaning
field yes The reading to evaluate, as named in the register map (alias: register)
op yes* Comparison: truthy, falsy, bit, >, >=, <, <=, ==, !=
value with op The threshold for a comparison operator
condition alternative The op and value as one string, e.g. ">= 55"
severity yes One of the engine's severities, most severe first (critical, major, …)
alarm_display_name recommended The human name shown in the UI
message optional The operator-facing message
enabled optional Boolean. Absent means enabled
ignore_zero optional Real key present in the live maps
trigger_delay optional Seconds the condition must hold before the alarm activates
recovery_delay optional Seconds the condition must be clear before it clears
recovery_value optional The threshold it must pass to clear (the hysteresis)
register_address optional Cross-checked against the register map
data_type optional Cross-checked against the register map
actions optional Command sequences to fire — see Add an Alarm Action
self_test system Marks a synthetic self-test alarm. Do not set this by hand

* Operators accept shorthand: =, eq, ne, lt, le, gt, ge. The operators that need a value are ==, !=, <, <=, >, >= and bit.

Only four keys are policed for spelling. _rule_key_errors validates exactly enabled, recovery_value, trigger_delay and recovery_delay. Unknown keys in an entry are not rejected — unlike keys in an action, which are checked against a fixed set. A typo such as recovery_delay_ms or triggerdelay therefore saves cleanly and is then silently ignored, so check spelling against this table by eye; nothing will tell you.

A field that is not in the register map is a warning, not an error. The engine reports field 'x' is not in this model's register map, so the alarm can never fire and saves anyway. Treat that as a failure, because the map then reads as configured while the alarm never fires. The single exception is the engine's reading-age pseudo-field, which is computed from the last-value timestamp and legitimately appears in no register map.

A real entry

From emsConfig/air_condition_unit/ac1/ac_alarm_code.json:

{
  "AC-1001": {
    "alarm_display_name": "Fault Active",
    "message": "…",
    "severity": "major",
    "field": "fault_active",
    "op": "truthy"
  }
}

Note the shape: the file is a flat map of alarm code → definition. The alarm codes sit at the top level of the JSON document with no wrapper object, and there is no models wrapper in an alarm map — unlike the sequence files, which are keyed by model.

How a rule is expressed

Three spellings state a condition, and the engine accepts exactly one of them:

Form Example Notes
Boolean operator "op": "truthy" No value needed
Operator plus value "op": ">=", "value": 55 Every comparison operator needs value
Condition string "condition": ">= 55" Operator and value in one string, or a truthy/falsy word

Setting both op and condition is refused: "set either 'op' or 'condition', not both".

Both keys take an alias — operator for op, active_when for condition — and the operators accept shorthand (=, eq, ne, lt, le, gt, ge). A bare bit key with neither op nor condition is also a valid rule.

The live estate spells thresholds as condition strings and boolean alarms as op words, so both forms appear side by side in the same file.


Step-by-Step Procedure

  1. Identify the device category. The top-level folder under emsConfig/, e.g. pcs, air_condition_unit, solar_energy_meter, bmu, ev_charger.
  2. Identify the manufacturer and model. The editor shows the model it resolved. Model variants use the ___<model> suffix.
  3. Locate the alarm map. Use the editor. If you must look at the file, read map_path from GET /api/v1/ems/alarms/maps?device_type=…&device_id=… rather than guessing the folder name.
  4. Locate the register map. <prefix>_register_full.json beside the alarm map, plus the ___<model> variant that applies.
  5. Find the field. Search the register map for the reading you want to watch. The field you write into the alarm must be a name that map defines — the engine cross-checks register_address and data_type when you supply them.
  6. Choose the code. It must match ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$ — letters, digits, and . _ : - only, starting with a letter or digit. Reusing an existing code overwrites the existing alarm.
  7. Write the entry with field, op (or condition), and severity.
  8. Set alarm_display_name and message so operators see something readable.
  9. Add recovery_value if the condition can oscillate (see the hysteresis rule below).
  10. Add trigger_delay and recovery_delay to suppress flapping.
  11. Leave enabled out to have it enabled, or set "enabled": false to stage it.
  12. Save. The engine validates and writes, keeping up to five .bak-api-* backups.
  13. Reload. Reload the editor — the hash changes and the entry is listed.
  14. Confirm detection. Make the condition true and watch the alarm appear.

The hysteresis rule

recovery_value must sit on the clearing side of the trigger, or the engine refuses it (_recovery_clears_past_trigger):

Trigger Recovery must be
> 55 or >= 55 < 55
< 5 or <= 5 > 5
== 3 != 3
!= 3 == 3

The refusal reads:

recovery_value 60 does not recover past the trigger (> 55), so the alarm would never clear

recovery_value also needs a numeric comparison. On a truthy, falsy or bit rule the engine refuses it: "'recovery_value' needs a numeric comparison; 'truthy' has no threshold to recover past".


Examples

A boolean alarm (real, from the live tree)

{
  "AC-1001": {
    "alarm_display_name": "Fault Active",
    "severity": "major",
    "field": "fault_active",
    "op": "truthy"
  }
}

A threshold alarm with hysteresis and delays

Modelled on AC-ROOM-TEMP (room_temp_c, > 30, major) with the optional keys added:

{
  "AC-ROOM-TEMP": {
    "alarm_display_name": "Room temperature high",
    "message": "Server-room temperature above 30 °C",
    "severity": "major",
    "field": "room_temp_c",
    "op": ">",
    "recovery_value": 28,
    "trigger_delay": 30,
    "recovery_delay": 120
  }
}

recovery_value: 28 is below the > 30 trigger, so it passes the hysteresis check. The alarm activates only after 30 s above 30 °C, and clears only after 120 s below 28 °C.

The examples the brief asks for

Two of these can be written today; two cannot, and the honest reason matters.

Wanted Status
PCS overtemperature Writable — an alarm entry, same shape as above. The field must come from pcs_register_full___epcs105.json; it is not reproduced here because inventing a register name would produce a map that reads correctly and is wrong on the plant.
PCS overvoltage Writable — same, with recovery_value below the trigger.
EV charger communication alarm Writable — the ev_charger category exists. Use a falsy/truthy rule on the comms flag.
BMS low-SOC alarm Writable — the bmu category exists. Use a < rule on the SOC field. Whether it can also fire a corrective sequence depends on the BMU model's own sequence set; check with --device bmu --list-actions.

PCS sequences do exist, at a path of their own. PCS is the one category whose sequences are not under a sequences/ directory: the engine maps it to emsConfig/pcs/power_sequences/, where each file is named for its model (EPCS105.json, SINEXCEL_PWS1_250K.json, SUNGROW_SC250UD.json) and holds a top-level model and actions object. So a PCS alarm can fire a PCS sequence, including the load-shedding case that matters most:

Sequence EPCS105 steps
change_power write_single 0x0D57 = ${power_kw}
start write_single 0x0291 = 1, then a delay
stop write_single 0x0D57 = 0, a delay, write_single 0x0291 = 0

The engine serves 18 categories. The other seventeen keep their sequences in emsConfig/<category>/sequences/: ac, bess_energy_meter, bmu, cooling, door_sensor, ev_charger, ffr_meter, flood_sensor, frequency_meter, fss, grid_meter, heat_sensor, sensor_block, smoke_detector, solar_meter, temperature_sensor, ups.

An earlier revision of this guide claimed PCS had no sequence file. That was wrong, and the cause is worth recording: the glob emsConfig/*/sequences/* does not match emsConfig/pcs/power_sequences/*, so a file-based inventory silently omits PCS. Ask the engine instead:

python3 device_command_sequences.py --device pcs --list-actions

For every device, the field comes from the register map

grep -n "your_reading_name" emsConfig/<category>/<device_dir>/<prefix>_register_full.json

Testing

Self-test alarms

The engine maintains synthetic self-test entries prefixed SELFTEST (SELF_TEST_PREFIX = "SELFTEST"). They exercise the alarm path end to end without touching hardware, and the editor deliberately does not offer them as targets for alarm actions.

Raising a real alarm against the simulator

  1. Configure the simulated device and its model.
  2. Load its alarm map.
  3. Drive the register the alarm watches past the threshold — via the simulator's own control or the register write interface.
  4. Confirm the alarm appears in the active-alarm system.
  5. Confirm it is recorded in TimescaleDB.
  6. Drive the value back past recovery_value and confirm it clears after recovery_delay.

The read-back check

The strongest quick check is that the answer came from the backend rather than from a successful-looking response:

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; d=json.load(sys.stdin)['data']; print(d['map_path'], d['hash']); print(json.dumps(d['entries'].get('AC-1001'), indent=2))"

Verify the returned hash moved and your entry is present.


Troubleshooting

These are the engine's real refusal messages — the text after The engine refused…:

Message Cause
'action_id' must be 1-64 chars of letters, digits, . _ : - The code violates ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$
recovery_value N does not recover past the trigger (OP X), so the alarm would never clear The recovery threshold is on the firing side
'recovery_value' needs a numeric comparison; 'truthy' has no threshold to recover past recovery_value on a boolean rule
the map changed since it was read (expected HASH, found HASH) Someone saved the map between your read and your write. Reload and re-apply
'trigger' 'sometimes' must be one of active, cleared, acknowledged An enum value outside its set

Other things that bite:

  • A new page 404s after deploy. The route cache is stale. php artisan route:clear.
  • @selected / @checked in a Blade view. They do not exist in this Laravel (8.83); Blade emits them as literal text instead of failing. Use the ternary form other views use.
  • The alarm never clears. recovery_value is wrong, or recovery_delay is longer than the condition stays clear.
  • The alarm is not offered as an action target. It is a SELFTEST entry, or enabled is false.