Overview
Event detectors are the foundation of Mango’s alarm and monitoring system. They watch data point values and raise events when specific conditions are met.
The architecture has two parts:
- Event detectors — watch data point values and decide when something noteworthy happens
- Event handlers — decide what to do when a detector fires (send email, set a point, run a command)
This guide covers the detector side: every detector type, when to use it, and how to configure it effectively.
Prerequisites
- Admin or data source edit permissions
- At least one data source with active data points
- Basic understanding of data point types (numeric, binary, multistate, alphanumeric)
Detector Types Reference
High Limit
What it does: Triggers when a numeric value exceeds a specified threshold.
When to use it: Over-temperature alerts, over-pressure warnings, high current draw, tank overflow prevention.
Key settings:
- Limit value — the threshold the value must exceed
- Duration — how long the value must stay above the limit before the event fires (prevents transient spikes from triggering alarms)
- Alarm level — severity of the resulting event
Example: Supply air temperature point with a high limit of 85°F and a duration of 60 seconds. If the temperature exceeds 85°F for more than one minute, the alarm fires.
TIP: A practical high-limit configuration from the field: set the high limit at 90, with the alarm clearing at 86 (a 4-degree deadband) and a 5-second duration to filter sensor noise. The deadband prevents the alarm from flapping on and off when the value hovers near the threshold, and the short duration ignores momentary electrical spikes.
Low Limit
What it does: Triggers when a numeric value drops below a specified threshold.
When to use it: Low battery voltage, low tank level, freezestat monitoring, low refrigerant pressure.
Key settings:
- Limit value — the threshold the value must drop below
- Duration — how long the value must stay below the limit
- Alarm level — severity of the resulting event
Example: Battery voltage point with a low limit of 11.5V and a duration of 30 seconds. If voltage stays below 11.5V for 30 seconds, the event fires.
Change
What it does: Triggers whenever the value changes at all, regardless of direction or magnitude.
When to use it: Binary or multistate points where any transition is significant—door open/close, equipment on/off, mode changes.
Key settings:
- Alarm level — severity of the resulting event
Note: No duration setting for this detector. Every change fires immediately.
No Change
What it does: Triggers when a value has not changed for a specified duration.
When to use it: Detecting stuck sensors, frozen readings, or equipment that should be cycling but isn’t.
Key settings:
- Duration — how long with no change before the event fires
- Alarm level — severity of the resulting event
Example: A temperature sensor that hasn’t changed value in 2 hours likely has a problem. Set duration to 7200 seconds (2 hours).
No Update
What it does: Triggers when a data point has not received any update (poll) for a specified duration.
Important distinction: No Change means the value stays the same. No Update means the point stopped receiving data entirely. No Update indicates a communication failure—the data source is not polling or the device is unreachable.
Key settings:
- Duration — how long with no update before the event fires
- Alarm level — severity of the resulting event
Example: A Modbus point that normally polls every 5 seconds hasn’t updated in 60 seconds. This likely means the device or network connection is down.
State Change Count
What it does: Triggers when a value changes more than N times within a specified time window.
When to use it: Detecting flapping or chattering equipment—a relay cycling on and off rapidly, a damper oscillating, a status that keeps toggling.
Key settings:
- Change count — number of changes that constitute a problem
- Duration — the time window to count changes within
- Alarm level — severity of the resulting event
Example: A compressor status point that changes more than 10 times in 5 minutes is short-cycling and needs attention.
Multistate
What it does: Triggers when a multistate point enters a specific state value.
When to use it: Monitoring for specific operating modes or fault states on equipment that reports status as numbered states.
Key settings:
- State value — which state(s) trigger the event
- Alarm level — severity of the resulting event
Example: An AHU reports state 4 as “Fault.” Configure the multistate detector to fire on state 4.
Alphanumeric
What it does: Triggers when a string value matches a specified pattern.
When to use it: Monitoring status messages, log outputs, or any text-based data point.
Key settings:
- Match type — contains, equals, or regex
- Pattern — the string or regex to match
- Alarm level — severity of the resulting event
Example: A device that returns a status string containing “ERROR” should trigger a warning event.
Positive CUSUM
What it does: A cumulative sum detector for detecting gradual upward drift from a target value.
Explained simply: Instead of alarming on a single spike, CUSUM tracks the cumulative deviation above a target. Small, repeated deviations add up over time. When the accumulated total exceeds a threshold, the detector fires. This catches slow, creeping increases that a simple high limit would miss.
Key settings:
- Limit — the cumulative deviation threshold
- Weight — the target value (deviations are measured from this)
- Alarm level — severity of the resulting event
Negative CUSUM
What it does: The mirror of Positive CUSUM—detects gradual downward drift from a target value.
Use case: Detecting slowly declining efficiency, gradual pressure loss, or slow temperature drop over time.
Key settings: Same as Positive CUSUM (limit, weight, alarm level).
Analog Range
What it does: Triggers when a numeric value is within OR outside a defined range (configurable).
When to use it: When you need to monitor for a value band rather than a single threshold—acceptable operating range for a process variable.
Key settings:
- Low value — bottom of the range
- High value — top of the range
- Within range / Outside range — whether to fire when inside or outside the band
- Alarm level — severity of the resulting event
Example: A humidity sensor should read between 30% and 60%. Set the range to 30–60 and trigger when outside that range.
Setting Alarm Severity Levels
Every event detector requires an alarm level. Use severity consistently across your system to ensure operators can prioritize effectively.
| Level | Typical Use |
|---|
| None | Logging only—no notification, just recorded for historical reference |
| Information | Advisory conditions—nothing is wrong, but worth noting |
| Important | Needs attention during normal business hours |
| Warning | Action needed soon—don’t ignore this |
| Urgent | Action needed now—wake someone up if after hours |
| Critical | Immediate action required—equipment damage or data loss imminent |
| Life Safety | Safety system event—human safety may be at risk |
Duration Settings (Debouncing)
Duration is one of the most important settings in event detection. It prevents transient spikes or momentary dips from triggering alarms.
How it works: When you set a duration of 60 seconds on a high limit detector, the value must stay above the limit continuously for 60 seconds before the event fires. If it dips back below the limit at any point during that 60 seconds, the timer resets.
Guidelines:
- 0 seconds (instant) — Not recommended for most use cases. Every transient spike fires an alarm.
- 30–60 seconds — Typical for process values like temperature and pressure. Filters out noise while still catching real problems quickly.
- 5–15 minutes — Appropriate for slow-moving values or situations where brief excursions are acceptable.
How to choose: Consider the normal fluctuation range of your data point. If a value routinely bounces 2–3 degrees above your limit for a few seconds during normal operation, set the duration long enough to ignore those bounces (30–60 seconds). If even a momentary excursion is dangerous (e.g., life safety), use a very short or zero duration.
Connecting Detectors to Handlers
Detectors raise events. Handlers respond to them. Without a handler, your detector will still log the event in Mango’s event history, but nobody will be notified.
Common handler types:
- Email handler — sends an email notification when the event fires (see Email Handler Setup)
- Set point handler — writes a value to another data point (e.g., shut down equipment)
- Process command handler — runs a system command or script
See the related articles on Configuring Event Handlers and Email Handler Setup for detailed instructions.
Best Practices
- Start with the essentials: High limit, low limit, and no-update detectors cover the majority of monitoring needs. Add other types as you learn your system’s behavior.
- Always set a duration to avoid nuisance alarms. Even 15–30 seconds eliminates most transient noise.
- Use severity levels consistently. Define what each level means for your organization and stick to it. If everything is “Critical,” nothing is.
- Test your detectors by manually forcing a value beyond the threshold using a virtual data source or set-point link. Verify the event fires and any handlers respond correctly.
- Document your alarm setpoints. Keep a record of what limits you set and why, so future operators understand the reasoning.
- Review alarm frequency. If a detector fires more than a few times a day, either the limit is set too tight or there is a real problem that needs fixing—not just alarming.
- Layer multiple detectors at different severities on the same point. For example, a supply temperature point might have a Warning at 85°F, an Urgent at 90°F, and a Critical at 95°F. This gives operators graduated escalation instead of a single on/off alarm.
- Use a consistent naming convention for detectors. Include the device ID, point name, limit type, and level—for example,
RTU-01_SupplyTemp_HighLimit_Warning. This makes detector lists searchable and unambiguous when reviewing alarm history.
NOTE: Mango event detectors operate in two time domains: real time and timestamp. Real-time detectors evaluate values as they arrive from the data source. Timestamp-based detectors evaluate based on the timestamp attached to the value, which matters for back-filled or imported data. For most live monitoring, real-time is correct. Use timestamp mode only when processing historical or back-filled data.
Troubleshooting
| Symptom | Possible Cause | Solution |
|---|
| Detector never fires | Limit value is set beyond the range the point actually reaches | Check recent point history and adjust the limit to a realistic threshold |
| Detector fires constantly | Limit is too close to normal operating value, or duration is 0 | Widen the limit margin and/or add a duration of 30–60 seconds |
| No email received when event fires | No email handler attached to the detector, or email settings misconfigured | Verify an email handler exists for this event and check system email settings |
| No-update fires but device is online | Data source polling interval is longer than the no-update duration | Set no-update duration to at least 2–3x the polling interval |
| Event shows in log but severity seems wrong | Alarm level set incorrectly on the detector | Edit the detector and adjust the alarm level |
| CUSUM detector fires unexpectedly | Weight (target) value does not match actual operating baseline | Adjust the weight to reflect the true normal operating value |
