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\AuthenticateandApp\Http\Middleware\AdminOrSuperAdmin. - The device already exists in
emsConfig/and is polled. A map for it must be readable. php artisan route:clearafter 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-001readsair_condition_unit/ac1/ac_alarm_code.json. Do not construct the path from the device id; readmap_pathfrom 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:
- Sign in as an admin or super-admin.
- Go to
/alarm-definition-editor(route namealarmDefinitionEditor), or/emsAlarmDefinitionsfor the catalogue of every device that has a map. - 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.
- 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.
- Scroll to Add an alarm and fill in the new code, field, comparison, value, severity and display name.
- Submit. The engine validates; the page reports either the save or the exact refusal.
- 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
- Identify the device category. The top-level folder under
emsConfig/, e.g.pcs,air_condition_unit,solar_energy_meter,bmu,ev_charger. - Identify the manufacturer and model. The editor shows the model it resolved. Model
variants use the
___<model>suffix. - Locate the alarm map. Use the editor. If you must look at the file, read
map_pathfromGET /api/v1/ems/alarms/maps?device_type=…&device_id=…rather than guessing the folder name. - Locate the register map.
<prefix>_register_full.jsonbeside the alarm map, plus the___<model>variant that applies. - Find the field. Search the register map for the reading you want to watch. The
fieldyou write into the alarm must be a name that map defines — the engine cross-checksregister_addressanddata_typewhen you supply them. - 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. - Write the entry with
field,op(orcondition), andseverity. - Set
alarm_display_nameandmessageso operators see something readable. - Add
recovery_valueif the condition can oscillate (see the hysteresis rule below). - Add
trigger_delayandrecovery_delayto suppress flapping. - Leave
enabledout to have it enabled, or set"enabled": falseto stage it. - Save. The engine validates and writes, keeping up to five
.bak-api-*backups. - Reload. Reload the editor — the hash changes and the entry is listed.
- 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
- Configure the simulated device and its model.
- Load its alarm map.
- Drive the register the alarm watches past the threshold — via the simulator's own control or the register write interface.
- Confirm the alarm appears in the active-alarm system.
- Confirm it is recorded in TimescaleDB.
- Drive the value back past
recovery_valueand confirm it clears afterrecovery_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/@checkedin 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_valueis wrong, orrecovery_delayis longer than the condition stays clear. - The alarm is not offered as an action target. It is a
SELFTESTentry, orenabledis false.