node-red-contrib-timer-threshold 0.1.0
A Node-RED node that triggers an output after a configured number of messages arrive within a fixed or sliding time window. Suppresses false positives from sensor noise by requiring repeated threshold breaches before acting. Sibling of timer-events, shari
timer-threshold
A threshold-counting node for Node-RED that triggers an output after a configured number of messages arrive within a fixed or sliding time window. Designed to suppress false positives from sensor noise: rather than acting on a single threshold breach, it requires the breach to repeat N times within Y time before firing.
Sibling of node-red-contrib-timer-events —
the two nodes share the same event envelope, command conventions, and
output philosophy, so downstream flows can process both with the same code.
Why this node
A humidity sensor fluctuating around its alert threshold will breach it briefly and repeatedly without anything actually being wrong. Wiring the sensor through this node — for example, "3 exceedances within 15 minutes" — means a single blip never triggers, while a genuinely persistent condition still alerts quickly: the Trigger fires the instant the count is met, never waiting for the window to close. And like its sibling, everything is observable: every counted message, blocked message, expiry, and cooldown transition is a tagged event with a consistent envelope describing the node's full state at that moment.
Outputs
| # | Output | Fires on |
|---|---|---|
| 1 | Trigger | The count reaching the limit within the window. Nothing else. |
| 2 | Query | An incoming query message, or a Heartbeat tick. |
| 3 | Events | Every event, including a copy of every Trigger and every ignored/blocked message. |
Output 1 never carries a blocked or redundant message — anything that
didn't truly happen appears only on output 3, tagged msg.ignored: true.
The Trigger message is a clone of the final counted message, so its
payload and topic carry through downstream.
Features at a glance
- Fixed or sliding window — fixed anchors one shared clock to the first message of a cycle; sliding lets each message age out individually, so the count decays naturally as messages fall out of the window
- Control commands —
stop,reset,query,disable,enable,setcountlimit,setwindow(all case-insensitive); anything else is counted - Event envelope — every output message carries
timerEvent,timerState,count,countLimit,windowMode,windowRemaining,ignored,source, and more - Cooldown — block counting for a fixed period after each Trigger to prevent rapid re-triggering from a noisy source
- Heartbeat — periodic status snapshots on the Query output for monitoring the decaying count or watchdogging long windows
- Persistence — resume a counting cycle or cooldown across deploys and Node-RED restarts, with sliding-window timestamps pruned against the wall clock
Install
From your Node-RED user directory (typically ~/.node-red):
npm install node-red-contrib-timer-threshold
Or via the Node-RED palette manager. The node appears in the function category as Timer Threshold.
Documentation
Full documentation — configuration reference, event taxonomy, command details, window-mode behavior, persistence, example flows, and troubleshooting — lives in the project wiki. The node's built-in help panel in the Node-RED editor also covers everyday usage.
Testing
The repository includes a self-contained test harness
(test-scripts/test-harness.js) covering routing, gating, both window
modes, cooldown, heartbeat, and every persistence restore path. Run it
from the repo root with npm test; it also runs automatically before
every npm publish.
License
Licensed under the Apache License 2.0.
Copyright (C) 2026 mchristegh.# node-red-contrib-timer-threshold
