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:
- Resolves the register the rule watches.
- Computes a value that satisfies the rule.
- 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:
- The EMS polls the simulated register.
- The rule evaluates true.
- The alarm is raised with its configured code and severity.
- It appears in the EMS active alarm system.
- 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:
- Choose the device type, then search for the device (
devType,devSearch). - The page loads that device's rule rows.
- Filter the rows with the row search (
rowSearch). - Edit a limit. Validation runs as you type; the header shows
devices / rules / errors / warnings. - 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_* |