Debounce, hysteresis and dampening

A monitoring system that cries wolf is worse than none. Alarm rules have three settings against noise. Debounce makes a condition prove itself before the alarm opens or clears. Hysteresis puts a margin on the clear side. Dampening holds an alarm that keeps flipping.

Debounce

Field (JSON)	Form label	Range	Default
debounce.mode	Count in: Readings in a row (count) or Seconds (device time) (duration)		count
debounce.raise	Raise after this many readings in a row / Raise when true for (seconds)	1 to 86,400	1
debounce.clear	Clear after this many readings in a row / Clear when false for (seconds)	1 to 86,400	1

By readings

The alarm opens on the raise-th reading in a row whose condition is true, and clears on the clear-th reading in a row whose condition is false. One reading the other way resets the count. With the default 1 and 1, the alarm follows every reading.

Only readings that carry one of the rule’s keys count. A message with other keys is no reading for this rule.

By device time

The alarm opens when the condition has been true continuously for raise seconds, measured on the time stamps of the readings, not on the server’s clock. It clears symmetrically.

Example: “door open for 120 s” is door_open == true with Seconds (device time), raise 120.

Severity changes

Inside an open alarm, a change of severity waits for the same debounce: a rise waits for the raise count or time, a fall waits for the clear count or time.

Hysteresis

hysteresis (form: Hysteresis (clear margin)) is an absolute number, 0 or more. It widens the threshold on the clear side of ordering comparisons (>, >=, <, <=):

Condition	Hysteresis	Opens	Clears
temperature > 80	3	above 80	at 77 or below
battery < 20	5	below 20	at 25 or above
pressure >= 6	0.2	at 6 or above	below 5.8

Hysteresis does not apply to == and !=, and it is ignored when the rule has an explicit clear condition (that condition decides). A value hovering at the threshold therefore does not open and close the alarm on every reading.

Dampening

Dampening applies to every threshold rule. Without a dampening block, the defaults are used:

Field	Meaning	Range	Default
maxTransitions	Opens and clears allowed within the window	2 to 100	4
windowSec	The window	10 to 86,400 s	600
holdSec	How long the condition must stay clear before a held alarm clears	1 to 86,400 s	300

When a clear would make more than maxTransitions opens and clears within windowSec, the clear is held: the alarm stays open and is marked Flapping (timeline: Flapping: clears held back). It clears only after its condition has been clear for holdSec seconds of device time.

With the defaults: an alarm that opened and cleared twice in 10 minutes and opens a third time is held open on its next clear until the condition has been clear for 5 minutes.

Set your own values in JSON mode:

"dampening": { "maxTransitions": 6, "windowSec": 1800, "holdSec": 600 }

Worked examples

A noisy temperature probe. Readings every 10 s jump ±1 °C around 80.

"severities": [ { "severity": "MAJOR", "condition": { "key": "temperature", "op": ">", "value": 80 } } ],
"debounce": { "mode": "count", "raise": 3, "clear": 3 },
"hysteresis": 2

Opens on the third reading above 80 in a row, clears on the third reading at 78 or below in a row.

A door that may stand open briefly.

"severities": [ { "severity": "WARNING", "condition": { "key": "door_open", "op": "==", "value": true } } ],
"debounce": { "mode": "duration", "raise": 300, "clear": 1 }

Opens when the door has been open for 5 minutes by the device’s clock (the device must report while the door is open). In time mode a single reading never decides: the alarm clears with the second closed reading, at least 1 second after the first.

A pump that cycles on purpose. A rule on a pressure that drops every pump cycle would flap. Raise maxTransitions or holdSec so the expected cycling does not page, and keep the debounce short so a real fault is still seen quickly.

Choosing values

Device reports	Suggested debounce
Every few seconds	count 3 to 5, or duration 30 to 60
Every minute	count 2 to 3
Every 10 to 60 minutes	count 1 to 2. A duration rule takes at least one reporting interval.
Only on change	count 1; use the device’s own delay, or a Rules-card “stays so for” trigger