Setting up Event Detectors & Event Handlers
Event detectors and event handlers form the alarm and notification backbone of Mango. Detectors watch data point values for conditions that warrant attention, while handlers define what happens when those conditions are detected.
About Event Detectors
An event detector's purpose is to determine whether the value of a data point satisfies one or more conditions. When the conditions are met, the detector becomes "active" and raises an event. A data point can have an unlimited number of event detectors, and you can attach multiple detectors of the same type to a single point (for example, multiple high limit detectors at different thresholds).
Adding an Event Detector
To add a new event detector to a data point:
- Navigate to the data point's edit page (either from the data source page or the bulk data point edit page).
- Open the Event Detectors tab.
- Select the detector type from the dropdown. Only detector types applicable to the point's data type are listed.
- Give the detector a name. This name identifies the event when configuring event handlers and viewing the alarm table.
- Set the alarm level to determine the severity: None, Information, Important, Warning, Urgent, Critical, or Life Safety. A level of "None" means the detector will fire but will not appear as an alarm.
- Configure the detector-specific settings (threshold, duration, state, etc.).
- Save the data point.
Timing Mode
All detectors have a timing mode setting that affects how time-based conditions (such as durations) are measured and how event timestamps are displayed:
- Real-time -- Timers measure elapsed wall-clock time. Event timestamps (active time, return-to-normal time) reflect the actual time at which Mango observed the condition. This is the standard mode for most deployments.
- Point value time -- Durations are measured as the difference between the timestamps of point values. Events will not be raised or return to normal unless the point value is updated, since no real-time timers are used. This mode is useful when processing historical data or receiving timestamped data from remote devices where the timestamps may lag behind wall-clock time.
Active vs. Instantaneous Events
Most detector types raise events that remain "active" for a period of time before they "return to normal" (RTN). For example, a high limit detector becomes active when the value exceeds the limit and returns to normal when the value drops back below. These events have both an active timestamp and an RTN timestamp.
Two detector types -- Point Change and State Change Count (when configured as instantaneous) -- raise "instantaneous" events that have a single timestamp and do not become active or return to normal. They simply record that the event occurred at a specific moment.
Detector Types for Numeric Points
High Limit
Raises an event when the point value exceeds a configured High limit threshold. The State setting controls the comparison:
- Greater than -- The event becomes active when the value is above the limit.
- Less than or equal to -- The event becomes active when the value is at or below the limit.
Reset limit (hysteresis): An optional reset limit introduces hysteresis to prevent rapid toggling. When the state is "Greater than," the value must drop to or below the reset limit before the event returns to normal. If no reset limit is set, the event returns to normal as soon as the value is no longer above the high limit.
Duration: Optionally, the value must stay beyond the limit for a specified duration before the event is raised. This prevents brief spikes from triggering alarms.
Reset duration: Controls how long the value must remain below the limit/reset limit before the event returns to normal. Defaults to zero (immediate RTN).
Example: Monitor a boiler temperature with a high limit of 200 degrees, reset limit of 195 degrees, and duration of 30 seconds. The alarm fires only if the temperature stays above 200 for 30 seconds, and clears when the temperature drops to 195 or below.
Low Limit
The inverse of the high limit detector. Raises an event when the point value drops below a configured Low limit threshold.
- Less than -- The event becomes active when the value is below the limit.
- Greater than or equal to -- The event becomes active when the value is at or above the limit.
Reset limit, duration, and reset duration work symmetrically to the high limit detector.
Example: Monitor a tank level with a low limit of 10%. The alarm fires when the level drops below 10% and clears when it rises back above the reset limit.
Range
Raises an event when the point value enters or exits a defined range. You configure a Low range limit and a High range limit. The range is inclusive -- values exactly at either limit are considered within the range.
The detector can be configured to fire when the value is within the range or outside the range (depending on configuration). Duration and reset duration settings are supported.
Example: Detect when a pH sensor reading is outside the acceptable range of 6.5 to 8.5.
Analog Change
Detects when the point value changes by more than a specified amount within a time window. You configure:
- State -- Whether to detect increases, decreases, or either direction of change.
- Limit -- The magnitude of change that triggers the event.
- Duration -- The time window over which the change is measured.
- Update event -- Whether to consider only logged values or all updates.
The detector compares the current value against the value at the beginning of the time window. If the difference exceeds the limit, the event becomes active.
Example: Detect a temperature swing of more than 5 degrees in 10 minutes, which could indicate an HVAC malfunction.
Rate of Change
Detects when the rate of change of the point value exceeds or drops below a threshold. This detector supports two modes:
- Instantaneous mode (duration = 0) -- Computes the rate of change between the previous and current point values. Evaluated only when a new value arrives.
- Averaging mode (duration > 0) -- Computes the rate of change over a sliding time window. The rate is recalculated both when new values arrive and when old values leave the window.
The rate of change is calculated as:
RoC = (Latest value - Period start value) / Time window
Use absolute value ensures the comparison is done against the absolute value of the computed rate, triggering the event whether the value is increasing or decreasing.
Reset threshold provides a separate threshold for returning the event to normal. Without it, the event returns to normal as soon as the comparison is no longer true.
Example: Detect a temperature rising faster than 10 degrees per hour to catch runaway heating conditions.
Smoothness
Uses an algorithm to calculate a smoothness metric on a stream of values. This detector is best suited for points that update on a regular schedule (e.g., every 5 minutes). The Low limit is the smoothness value below which the event becomes active. The Boxcar size sets how many consecutive smoothness calculations are averaged to reduce variability.
Duration and reset duration are supported.
Example: Detect erratic readings from a vibration sensor that suggest mechanical wear.
Positive CUSUM
CUSUM (Cumulative Sum) is a statistical process control method for detecting small shifts in a process mean. The positive CUSUM detector becomes active when the cumulative sum exceeds the configured Positive limit. The Weight is the constant subtracted from each deviation in the CUSUM calculation.
Duration and reset duration are supported.
Negative CUSUM
The inverse of the positive CUSUM detector. Becomes active when the cumulative sum drops below the configured Negative limit.
Detector Types for Binary, Multistate, and Alphanumeric Points
State
Becomes active when the point enters a specified State value. For binary points, this is true or false. For multistate points, this is one of the defined state values. For alphanumeric points, this is a text string.
Duration is supported -- the point must remain in the specified state for the full duration before the event fires. Reset duration is also configurable.
Example: Detect when a pump status point goes to "Fault" state and stays there for more than 60 seconds.
State Change Count
Becomes active when the point value changes at least a specified Change count number of times within the given Duration. This can detect "chattering" or rapid state oscillation that indicates a control problem.
Applies to Binary, Multistate, and Alphanumeric points.
Example: Detect when a valve position changes more than 20 times in 5 minutes.
Detector Types for All Data Types
Point Change
Raises an instantaneous event whenever the point value changes to any new value. This detector has no duration or return-to-normal behavior -- each change is a discrete event.
Caveat: If the data point cache size is 0, this detector will always raise an event when the data point starts (because there is no previous value to compare against). Set the cache size to at least 1 to avoid this.
No Change
Raises an event when the point value has not changed within the given Duration. A change requires the new value to be different from the previous value. This detector is useful for detecting equipment malfunctions where a sensor stops reporting new values.
The event automatically returns to normal when a new, different value arrives.
No Update
Raises an event when the point has not been updated within the given Duration. An update only requires the timestamp to change -- the value itself can remain the same. This is a stricter check than "No Change" because it fires when the data source stops providing any values at all.
The event automatically returns to normal when a new update arrives.
Example: Detect when a remote device has stopped communicating. If a Modbus device normally polls every 10 seconds, a "No Update" detector with a 60-second duration will fire if no data arrives for a full minute.
Summary of Detector Availability by Data Type
| Detector Type | Numeric | Binary | Multistate | Alphanumeric |
|---|---|---|---|---|
| High Limit | Yes | -- | -- | -- |
| Low Limit | Yes | -- | -- | -- |
| Range | Yes | -- | -- | -- |
| Analog Change | Yes | -- | -- | -- |
| Rate of Change | Yes | -- | -- | -- |
| Smoothness | Yes | -- | -- | -- |
| Positive CUSUM | Yes | -- | -- | -- |
| Negative CUSUM | Yes | -- | -- | -- |
| State | -- | Yes | Yes | Yes |
| State Change Count | -- | Yes | Yes | Yes |
| Point Change | Yes | Yes | Yes | Yes |
| No Change | Yes | Yes | Yes | Yes |
| No Update | Yes | Yes | Yes | Yes |
About Event Handlers
For details on configuring event handlers, see Event Handlers.
Common Patterns
Alarm Escalation
Create multiple detectors on the same point at different thresholds with increasing alarm levels:
- Warning at 180 degrees (Information level) -- sends an email notification.
- High alarm at 200 degrees (Urgent level) -- sends email and triggers an audible alarm.
- Critical at 220 degrees (Critical level) -- sends email, triggers alarm, and shuts down equipment via set-point handler.
Stale Data Detection
Attach a No Update detector to critical points with a duration slightly longer than the expected poll interval. If a remote device stops communicating, the alarm will fire and notify operators.
Chattering Detection
Use the State Change Count detector to identify control loops that are oscillating rapidly. If a valve or relay changes state more than a configured number of times in a short period, raise an alarm for the control engineer to investigate.
Best Practices
Naming Conventions
Use clear, location-aware names that identify the equipment and condition at a glance:
- Good:
RTU-1 – High Discharge Temp,Site A – Power Fail,Server Room – Door Open - Avoid:
High Limit 1,Alarm,Test
A consistent naming pattern makes it much easier to manage large deployments and to configure handlers that target specific detectors.
Avoiding Alarm Fatigue
Too many alarms cause operators to start ignoring all of them. To keep alarm load manageable:
- Use duration filters — require conditions to persist for a minimum time (e.g., 5 minutes) before raising an alarm. This filters out transient spikes that don't warrant action.
- Separate severities — define organizational rules for each alarm level (Information, Warning, Critical) and apply them consistently. Life-safety alarms must be clearly distinguishable from informational events.
- Prefer fewer, meaningful alarms over many noisy ones.
Standardize Alarm Levels
Define what each alarm level means for your organization and document it. A consistent definition ensures operators know immediately how to respond:
| Level | Typical meaning |
|---|---|
| Information | Normal events that may be worth logging (no action required) |
| Warning | Conditions to monitor; action may be needed soon |
| Urgent | Requires operator attention within a defined response time |
| Critical | Immediate action required |
| Life Safety | Critical safety alarm — highest priority |
Testing Before Production
Always test detector configurations before deploying to production:
- Temporarily lower thresholds so the detector is easy to trigger (e.g., set a high limit from 80°F to 70°F).
- Manually set a test point value to cross the threshold.
- Verify in the Events/Alarms view that the event becomes Active, then Inactive when the condition clears.
- Test handlers — confirm emails arrive, set-point handlers change values, and scripts run without errors.
- Restore original thresholds once testing is complete.
Periodic Review
Review and tune your alarm configuration:
- After major system changes (new equipment, new points, new logic).
- After any incident or missed alarm.
- Periodically (e.g., quarterly) to remove obsolete or excessively noisy detectors.
Related Pages
- Event Handlers — Configure automated actions (email, set point, script, process) triggered by event detectors
- Alarms and Alarm Management — Understand alarm levels, acknowledgment, and the events page
- Email Notification Setup — Send email notifications when event detectors fire
- Advanced Alarms with Meta Data Points — Create complex multi-point alarm conditions using scripting
- Data Point Properties Reference — Configure cache size and other properties that affect event detector behavior