Skip to content

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:clear after 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

  1. Open /alarm-actions-editor?device_type=<category>&device_id=<device>. The alarm map editor has an alarm actions → link that fills both in.
  2. The page reads the device's alarm map from the backend and lists the alarms that carry actions.
  3. For each action row:
  4. Alarm — the alarm code it belongs to.
  5. Target device — the device that will be commanded. This need not be the alarmed device.
  6. Sequence — populated from the target's model-specific sequence file, so you can only pick a sequence the executor can actually resolve.
  7. Trigger — active, cleared or acknowledged.
  8. Mode — sequential or parallel.
  9. Order — the position within the mode.
  10. Submit. Validation runs on the backend; the page reports the save or the exact refusal.
  11. 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

  1. Select the alarm. It must exist and not be a SELFTEST entry — self-test alarms are deliberately not offered as action targets.
  2. Open the alarm actions editor for that device.
  3. Add an action to the alarm's actions list.
  4. Name the target with device_category and device_key.
  5. Let the engine detect the model. It does this from the target device, and overwrites whatever you send.
  6. List the available sequences with actions_for(category, model) — the editor does this for you by reading the target's *_command_sequences.json.
  7. Pick the sequence by name. A name the model does not define is refused: pcs2 has no sequence 'START BESS' (defined: …).
  8. Set the order with order, and the relationship with mode.
  9. Choose sequential when each step depends on the last (a BESS start before a power setpoint). Choose parallel when actions are independent (two chargers both reducing power).
  10. Add a condition if the action should not always run.
  11. Set delay_ms and timeout_ms.
  12. Pass dynamic parameters through parameters — see below.
  13. Set retries to a whole number >= 0, and failure_action to say what happens after they are exhausted.
  14. Choose the trigger. active for the corrective action; cleared for the restorative one, which additionally needs allow_on_clear: true.
  15. Decide the reset behaviour — this is the safety decision, and it is not the same as the trigger. See below.
  16. Save. The engine validates the whole action and refuses the map if any part cannot run.
  17. 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:

  • order within mode — sequential actions run in ascending order, each waiting for the previous; parallel actions 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.
  • parameters carries the runtime value into the sequence. The names must match the placeholders the sequence declares — change_power and set_power_limit both read ${power_kw}.
  • failure_action: abort on 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: condition is accepted but never enforced. condition is in the engine's allowed action-key set (_ACTION_KEYS in ems_alarm_maps.py), and the validator trims and stores it. The executor in alarm_actions.py, however, never calls action.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 sequential and giving the first one failure_action: abort so a failure stops the rest.

Every sequence name and every parameters key above is real. The brief's names map onto them: Reduce Active Power and Adjust Active Power are both change_power with a different power_kw, and EV CHARGER POWER LIMIT is set_power_limit. The picker in the editor is the authority, and a name the model does not define is refused with has 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.

  1. 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.
  2. Attach a read-only sequence to a non-executing trigger, or to an alarm you can raise harmlessly.
  3. Save, and confirm the returned action carries the model the engine detected.
  4. Reload the editor and confirm the row renders with its target and sequence preselected.
  5. Raise the alarm and confirm the sequence runs and reports its result.
  6. Confirm that a failure_action of abort really 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 SELFTEST entry.
  • 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:

  1. No explicit AUTO/MANUAL reset key. _ACTION_KEYS has no latching or reset field. AUTO is expressed by a cleared action; MANUAL is expressed by the absence of one.
  2. No alarm-action UI before this editor. The backend has supported actions for some time, but no frontend exposed them. On the live system 713 alarm-map files exist and not one carries an actions list — 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.