How to Add an Alarm Action
Attach command sequences to an alarm so the EMS acts on the plant when the alarm fires, and optionally acts again when it clears.
Purpose
An alarm raises visibility; an alarm action changes the plant. This guide configures the second part: which device runs which sequence, in what order, with what parameters, and what happens when it fails.
The action lives inside the alarm's own entry, in the actions list. There is no separate
store, so an action can never exist without its alarm.
Prerequisites
- Admin or super-admin login. The editor's routes sit behind the same auth group as the alarm
editor (
AdminOrSuperAdmin). - The target device must have a command-sequence file. This is the constraint that stops most configurations — see the coverage table below.
- A sequence that performs only reads if you intend to prove the wiring without moving anything.
php artisan route:clearafter deploying, if the routes were just added.
Relevant Files
| Path | Role |
|---|---|
emsConfig/<category>/<device>/<prefix>_alarm_code*.json |
Where the actions list is stored |
emsConfig/<category>/sequences/<prefix>_command_sequences.json |
Where the sequence names come from |
EnergySyc_EMS_ES100Cx12S/ems_alarm_maps.py |
Validation of the action payload |
EnergySyc_EMS_ES100Cx12S/alarm_actions.py |
The executor: gate_reason, _run_one |
resources/views/alarmActionsEditor.blade.php |
The alarm action editor |
resources/views/alarmActionsRow.blade.php |
One action row, as a partial |
app/Http/Controllers/Ems/AlarmActionsController.php |
The editor's controller |
Routes
| Method | URI | Route name |
|---|---|---|
| GET | /alarm-actions-editor |
emsAlarmActionsEdit |
| POST | /updateAlarmActions |
updateAlarmActions |
Query parameters on the GET are device_type and device_id; the alarm map editor links here
directly for the device being edited.
Frontend Instructions
- Open
/alarm-actions-editor?device_type=<category>&device_id=<device>. The alarm map editor has an alarm actions → link that fills both in. - The page reads the device's alarm map from the backend and lists the alarms that carry actions.
- For each action row:
- Alarm — the alarm code it belongs to.
- Target device — the device that will be commanded. This need not be the alarmed device.
- Sequence — populated from the target's model-specific sequence file, so you can only pick a sequence the executor can actually resolve.
- Trigger —
active,clearedoracknowledged. - Mode —
sequentialorparallel. - Order — the position within the mode.
- Submit. Validation runs on the backend; the page reports the save or the exact refusal.
- Reload to confirm the action persisted with the model the engine detected.
The editor shows the model the engine resolved for each target rather than asking you for it, because the engine detects the model and refuses a payload that names one. Naming a model in an action is the one field that is deliberately overwritten.
Backend Configuration
The action, key by key
The engine accepts exactly these keys. A key outside this set is refused:
| Key | Required | Meaning |
|---|---|---|
action_id |
yes | Unique within the alarm. ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$ |
device_category |
yes | The target device's category |
device_key |
yes | The target device's id |
sequence |
yes | The sequence name, as defined in the target's sequence file |
model |
detected | Written by the engine from the target. Do not set it |
trigger |
no | active (default), cleared, acknowledged |
mode |
no | sequential (default) or parallel |
order |
no | Position within the mode |
delay_ms |
no | Wait before running this action |
condition |
no | Further gate on this action |
parameters |
no | Dynamic inputs passed to the sequence |
timeout_ms |
no | Per-action timeout |
retries |
no | Whole number >= 0 |
failure_action |
no | abort (default), skip, retry, recovery_sequence |
recovery_sequence |
with failure_action: recovery_sequence |
The fallback sequence |
enabled |
no | Boolean. Absent means enabled |
allow_on_clear |
with trigger: cleared |
Must be true for a clearance action to run |
MAX_ACTIONS = 32 per alarm.
The closed vocabularies
These are fixed in the backend so that a payload the executor cannot honour is refused at save time rather than discovered during the incident it was configured for:
_ACTION_TRIGGERS = ("active", "cleared", "acknowledged")
_ACTION_MODES = ("sequential", "parallel")
_ACTION_FAILURES = ("abort", "skip", "retry", "recovery_sequence")
A value outside these produces:
entries[0]: 'trigger' 'sometimes' must be one of active, cleared, acknowledged
Defaults are filled in: trigger → active, mode → sequential, failure_action → abort.
Sequence coverage — check this first
An alarm can only fire a sequence that exists for the target's model. The engine serves 18
categories, each keeping its sequences in emsConfig/<category>/sequences/ — except PCS,
which uses emsConfig/pcs/power_sequences/.
The PCS case is the one most people want, and it works. An overtemperature alarm on a PCS can fire a power-reduction sequence on that same PCS:
{
"action_id": "shed-pcs1",
"device_category": "pcs",
"device_key": "PCS1",
"sequence": "change_power",
"trigger": "active",
"parameters": { "power_kw": 0 }
}
PCS defines seven sequences per model — start, stop, change_power, mode_pq, mode_vf,
read_soc, read_soh — for the models EPCS105, SINEXCEL_PWS1_250K and SUNGROW_SC250UD.
change_power is the real name; nothing in the tree is called SET ACTIVE POWER or
Reduce Active Power.
The same caution applies within a category: sequences are defined per model, and a device
whose model is absent from that category's files has no sequences and cannot be targeted.
MODEL_TEMPLATE.json under PCS is a template, not a deployable model.
Check before you configure:
curl -s "http://<ems-host>/api/v1/ems/alarms/maps?device_type=<category>&device_id=<device>" \
| python3 -c "import json,sys; d=json.load(sys.stdin)['data']; print(d['model'])"
then confirm the model appears in that category's sequence files — as a key under models in
<prefix>_command_sequences.json, or as the model field of its own file under
emsConfig/pcs/power_sequences/. The engine is the authority:
python3 device_command_sequences.py --device <engine-key> --list-models
python3 device_command_sequences.py --device <engine-key> --model <MODEL> --list-actions
Step-by-Step Procedure
- Select the alarm. It must exist and not be a
SELFTESTentry — self-test alarms are deliberately not offered as action targets. - Open the alarm actions editor for that device.
- Add an action to the alarm's
actionslist. - Name the target with
device_categoryanddevice_key. - Let the engine detect the model. It does this from the target device, and overwrites whatever you send.
- List the available sequences with
actions_for(category, model)— the editor does this for you by reading the target's*_command_sequences.json. - Pick the sequence by name. A name the model does not define is refused:
pcs2 has no sequence 'START BESS' (defined: …). - Set the order with
order, and the relationship withmode. - Choose
sequentialwhen each step depends on the last (a BESS start before a power setpoint). Chooseparallelwhen actions are independent (two chargers both reducing power). - Add a
conditionif the action should not always run. - Set
delay_msandtimeout_ms. - Pass dynamic parameters through
parameters— see below. - Set
retriesto a whole number>= 0, andfailure_actionto say what happens after they are exhausted. - Choose the trigger.
activefor the corrective action;clearedfor the restorative one, which additionally needsallow_on_clear: true. - Decide the reset behaviour — this is the safety decision, and it is not the same as the trigger. See below.
- Save. The engine validates the whole action and refuses the map if any part cannot run.
- Test against the simulator using a read-only sequence first.
Multi-Device Example
An overtemperature alarm on PCS1 that sheds load across four devices, in the shape the engine expects.
"PCS-OVER-TEMP": {
"alarm_display_name": "PCS overtemperature",
"severity": "major",
"field": "<temperature field from the PCS register map>",
"condition": ">= 60",
"recovery_value": 55,
"actions": [
{
"action_id": "shed-pcs1",
"device_category": "pcs",
"device_key": "PCS1",
"sequence": "change_power",
"trigger": "active",
"mode": "sequential",
"order": 1,
"timeout_ms": 5000,
"retries": 2,
"failure_action": "abort",
"parameters": { "power_kw": 0 },
"enabled": true
},
{
"action_id": "shed-pcs2",
"device_category": "pcs",
"device_key": "PCS2",
"sequence": "change_power",
"trigger": "active",
"mode": "sequential",
"order": 2,
"condition": "pcs1_power_kw < 10",
"parameters": { "power_kw": 20 },
"enabled": true
},
{
"action_id": "cap-ev1",
"device_category": "ev_charger",
"device_key": "EV-1",
"sequence": "set_power_limit",
"trigger": "active",
"mode": "parallel",
"order": 1,
"parameters": { "power_kw": 11 },
"enabled": true
},
{
"action_id": "cap-ev2",
"device_category": "ev_charger",
"device_key": "EV-2",
"sequence": "set_power_limit",
"trigger": "active",
"mode": "parallel",
"order": 1,
"parameters": { "power_kw": 11 },
"enabled": true
}
]
}
What each field is doing:
orderwithinmode—sequentialactions run in ascendingorder, each waiting for the previous;parallelactions run together. The two PCS actions are sequential because shedding PCS2 should follow PCS1 succeeding. The two chargers are parallel because neither depends on the other.parameterscarries the runtime value into the sequence. The names must match the placeholders the sequence declares —change_powerandset_power_limitboth read${power_kw}.failure_action: aborton the first action stops the rest, which is what you want when the first action is the safety-relevant one.condition— read the warning below before relying on it.
Implementation gap:
conditionis accepted but never enforced.conditionis in the engine's allowed action-key set (_ACTION_KEYSinems_alarm_maps.py), and the validator trims and stores it. The executor inalarm_actions.py, however, never callsaction.get("condition")— there is no condition evaluation anywhere in it. In the example above PCS2 therefore runs whether or not PCS1 came down.Put a dependency somewhere the engine actually honours: inside the sequence itself, as a step that reads PCS1's power before deciding, or by ordering the actions
sequentialand giving the first onefailure_action: abortso a failure stops the rest.Every
sequencename and everyparameterskey above is real. The brief's names map onto them:Reduce Active PowerandAdjust Active Powerare bothchange_powerwith a differentpower_kw, andEV CHARGER POWER LIMITisset_power_limit. The picker in the editor is the authority, and a name the model does not define is refused withhas no sequence '…' (defined: …).
Reset Rules — AUTO and MANUAL
This is the distinction that matters most, and it is two separate mechanisms that are easy to conflate.
AUTO
The restorative action is configured as a second action on the same alarm with
trigger: "cleared". When the alarm clears, the engine runs it — but only if all three of
gate_reason's conditions hold:
if event != _CLEARED: return None
if action.get("allow_on_clear") is not True:
return "allow_on_clear is not set on the action"
if list(still_active):
return "still active on this device: " + ", ".join(sorted(still_active))
if allowed_modes is not None and operation_mode not in allowed_modes:
return "operation mode %r does not permit a clearance action"
So a clearance action runs only when it was opted into, when nothing else is still active on that device, and when the EMS's operation mode permits acting on clearances at all. Any one condition missing leaves the equipment as it is — described in the source as "the recoverable mistake".
Note the fourth line: the operation mode is a real gate. A clearance action will not run in a mode that does not allow it, however the alarm resolves.
If you write trigger: "cleared" and omit allow_on_clear, the engine does not error — it
records allow_on_clear: false, so that the map states plainly that the clearance action does
nothing. The JSON then says what it means rather than relying on an absence.
MANUAL
There is no MANUAL reset flag in the alarm-action schema. _ACTION_KEYS contains no
latching or reset key. A manually latched protection is achieved by simply not configuring
a cleared action: the alarm clears, and the equipment stays as the active action left it
until a person intervenes.
That is the honest reading, and it is why the brief's request for an explicit AUTO/MANUAL reset key is an implementation gap rather than a feature to document. See below.
Why this matters — the emergency-stop case
Consider an emergency stop configured as an active action that trips a device. If it were
paired with a symmetric cleared action that automatically re-enabled the device, then the
moment the stop condition's measurement recovered, the EMS would restart equipment that a
person had deliberately stopped. The stop condition clearing is not the same event as a
person declaring the plant safe.
The engine's design reflects this: a clearance action is never on by default, and it is
blocked when anything else is still active on that device. The safe configuration for a
latching protection is an active action with no cleared counterpart, so recovery is a
human decision made through whatever authorisation the site uses.
Dynamic Parameters
parameters is a free-form object passed to the sequence. Its keys must match the inputs the
target sequence declares — see
How to Add a Device Command Sequence for how a
sequence declares them. Typical values: active power (kW), reactive power (kVAr), charging
current (A), voltage (V), frequency (Hz), power factor, operating mode, duration.
A parameter the sequence does not declare is not applied, so a typo produces a sequence that runs with its default instead of your value. Check the names against the sequence file.
Testing
Use a sequence that only reads, so a test cannot move the plant. On the live system
read_status is exactly that — five read_holding steps and no writes.
- Pick a device whose model is in its category's sequence file. Many are not, and the failure looks like a configuration error when it is a coverage gap.
- Attach a read-only sequence to a non-executing trigger, or to an alarm you can raise harmlessly.
- Save, and confirm the returned action carries the model the engine detected.
- Reload the editor and confirm the row renders with its target and sequence preselected.
- Raise the alarm and confirm the sequence runs and reports its result.
- Confirm that a
failure_actionofabortreally does stop subsequent actions.
Prove the write path before relying on it. A save that returns success is not proof the map changed — read it back and compare the file hash.
Troubleshooting
The engine's real refusal messages:
| Message | Cause |
|---|---|
unknown key(s) … |
A key outside _ACTION_KEYS, almost always a typo |
'trigger' 'x' must be one of active, cleared, acknowledged |
Bad trigger |
'mode' 'x' must be one of sequential, parallel |
Bad mode |
'failure_action' 'x' must be one of abort, skip, retry, recovery_sequence |
Bad failure_action |
'action_id' must be 1-64 chars of letters, digits, . _ : - |
Bad action_id |
'device_category' is required / 'device_key' is required |
Target not named |
'sequence' is required |
No sequence chosen |
pcs2 has no sequence 'X' (defined: …) |
The target's model does not define that sequence |
'failure_action' recovery_sequence requires 'recovery_sequence' |
Fallback named but not given |
'retries' N is not a whole number >= 0 |
Negative or fractional retries |
Other things that bite:
- The device has no sequences at all. Its model is not in the category's sequence file. This is a coverage gap, not a configuration error.
- The alarm is not offered as a target. It is a
SELFTESTentry. - The clearance action never runs. Any of
gate_reason's three conditions: not opted in, something else still active on the device, or the operation mode forbids it. - A parameter seems ignored. The sequence does not declare it.
Implementation Gaps
Stated plainly, because the brief asks for these and they do not exist:
- No explicit AUTO/MANUAL reset key.
_ACTION_KEYShas no latching or reset field. AUTO is expressed by aclearedaction; MANUAL is expressed by the absence of one. - No alarm-action UI before this editor. The backend has supported
actionsfor some time, but no frontend exposed them. On the live system 713 alarm-map files exist and not one carries anactionslist — the feature is implemented and has never been used in production. Treat any configuration you build as the first of its kind on this estate.