Skip to content

How to Trigger a Simulator Alarm

Purpose

Raise and clear a specific, model-defined alarm on a simulated device, then watch the EMS detect it and act on it. This is the fastest way to test an alarm rule, an alarm action or a protection latch without waiting for real conditions.

Prerequisites

  • The simulator stack is up and the target device is being served (How to configure simulated devices).
  • The alarm rule exists in the site's alarm map. The simulator does not invent alarms — it reads the map the EMS uses.
  • To verify the EMS side: the EMS backend is up and polling the device.

How the simulator sources alarms

The Alarms page builds its table from the EMS alarm catalogue:

GET /api/v1/ems/alarms/definitions

One row per alarm, resolved the same way as the live alarm report. Each definition carries the alarm map it came from, in two fields:

Field Meaning
alarm_map The alarm map (device directory) the rule belongs to
alarm_map_source The file those definitions were read from

The page also reads GET /api/v1/ems/alarms for live state. A rule with no readable condition cannot be triggered, so it is shown but not offered.

In this stack the file is not called alarms.json. It is a per-device, per-model file named:

<prefix>_alarm_code.json                                  # default model
<prefix>_alarm_code___<MODEL>.json                        # a specific model

For example, pcs_alarm_code.json and pcs_alarm_code___EPCS105.json. The <device_dir> the alarm lives in is the same directory the settings register file uses, which is how the simulator keeps the rule and its register together. See alarm-mapping-and-endpoints and alarm-code-to-register-relationship.

What "trigger" actually does

This is the single most important thing to understand before using the page.

A trigger does not toggle an alarm flag. It writes the register the rule watches.

Each rule is a condition over one register (or one bit of a register). Triggering a rule:

  1. Resolves the register the rule watches.
  2. Computes a value that satisfies the rule.
  3. Writes that value to the simulated register over Modbus.

Clearing works the same way in reverse: the simulator writes a value that does not satisfy the rule. For a bit-mask rule the bits that belong to one alarm are known, so clearing it rewrites those bits and leaves the other alarms in the same register alone.

That design is why a triggered alarm behaves exactly like a real one: the EMS is not told anything out of band, it simply reads a register that violates a rule.

Step-by-step procedure

Step 1 — Open the Alarms page

Go to Alarms (/alarms). Four summary tiles sit at the top:

Tile Meaning
Devices Devices known to the EMS, and how many are active
Triggerable Active devices that the simulator actually serves
Alarm rules Rules across every device map
Firing now Alarms the EMS currently reports — "as the EMS sees it"

Below them the page is organised one collapsible section per device. Each section holds that device's rules in a table:

Column Meaning
Code The alarm code
Severity From the alarm definition
Alarm The alarm name
Watched register The register the rule reads
Rule The condition that makes it fire
Writes What the trigger writes to force it

Step 2 — Find the alarm

There is no search box on this page. Browsing is by device: find the device's section and read its rules.

The brief this guide was written against asks for a table searchable by code, name, description and register address. That search does not exist in alarms/index.blade.php today — the only text input on the page is the per-row custom value box described in Step 4. This is an implementation gap.

The separate live panel — Active alarms — lists what is firing and refreshes on its own. Refresh now forces an immediate poll.

Step 3 — Select one or more alarms

  • Tick individual rows.
  • Tick Select every triggerable device to select all devices at once.
  • Use All / None to set every row in one go.
  • Trigger all N inside a device section selects that device's whole rule set.
  • The count next to the buttons updates as you tick ("N selected").

Step 4 — Trigger

Press Trigger selected. This submits the selection to alarms.trigger (POST /alarms/trigger). The simulator writes the satisfying value to each selected rule's register.

To force a specific value instead of the rule's own satisfying value, type it into the small text box on the rule's row and press that row's Trigger. The Writes column shows what the simulator would otherwise send.

Step 5 — Watch the simulator side

The live list should show the alarm as firing within one poll interval. The register now holds a rule-violating value; you can confirm it read-only on the EMS Modbus or Config Editor pages.

Step 6 — Verify the EMS detected it

On the EMS side, check the active alarm list. Expected sequence:

  1. The EMS polls the simulated register.
  2. The rule evaluates true.
  3. The alarm is raised with its configured code and severity.
  4. It appears in the EMS active alarm system.
  5. It is written to TimescaleDB.

The EMS endpoints involved are documented in accessing-alarms and alarms-api.

Step 7 — Verify alarm actions ran

If the alarm has actions configured, they execute now. Watch the simulator's Write Monitor for the commands that arrive as a result — see HOW_TO_MONITOR_EMS_COMMANDS and HOW_TO_TEST_EMS_ALARM_ACTIONS.

Step 8 — Clear

Press Reset selected (alarms.reset). For alarms currently firing that should all be silenced at once, press Reset all firing in the Active alarms panel — it posts to alarms.reset_active and writes the non-firing value for every rule the EMS reports as firing, so you do not have to find and tick each one. The simulator writes a value that no longer satisfies the rule.

Step 9 — Verify clearance and protection reset

After clearing, confirm:

Check Expected when the action is AUTO Expected when the action is MANUAL
Alarm state Clears once the rule is satisfied again Clears
Protection latch Released after validation Still latched — needs an authorised reset

The two are deliberately independent. See EMS_PROTECTION_FRAMEWORK and HOW_TO_TEST_EMS_ALARM_ACTIONS.

Editing the thresholds behind the rules

The Alarm Thresholds page (/alarms/thresholds) edits the numeric limits in the alarm map, per device:

  1. Choose the device type, then search for the device (devType, devSearch).
  2. The page loads that device's rule rows.
  3. Filter the rows with the row search (rowSearch).
  4. Edit a limit. Validation runs as you type; the header shows devices / rules / errors / warnings.
  5. Save device posts to alarms.thresholds.save. Revert discards edits.

A rule whose warnings are non-zero still saves — warnings flag a limit that looks unusual or a field absent from the register map, not a hard error. The full procedure is in HOW_TO_EDIT_ALARM_THRESHOLDS.

Verification

Check How
Rule discovered The alarm appears in the Alarms table
Trigger applied Register holds the satisfying value
EMS raised it It shows in the EMS active alarm list
Persisted Present in TimescaleDB
Actions ran Commands appear in the Write Monitor
Cleared Alarm leaves the firing list; register no longer violates the rule

Troubleshooting

Symptom Cause Fix
Alarms table empty The EMS alarm catalogue could not be read Check GET /api/v1/ems/alarms/definitions; see the errors panel at the top of the page
Device missing from the page The device is known to the EMS but not served by the simulator Check the Triggerable tile and the device's active flag
Search box not found The page has no search — this is the known gap in Step 2 Browse by device section
Trigger returns OK but nothing fires The rule watches a register the EMS does not poll Confirm addresses in the register map
Alarm never clears Recovery threshold/hysteresis not satisfied by the written clear value Inspect the rule's recovery condition
Other alarms in the same register disappeared Expected for a bit-mask register — clearing rewrites that alarm's bits only Re-trigger the ones you still need
Fired in simulator, never seen by EMS EMS not polling the simulated port Check MODBUS_MODE/MODBUS_SIM_*