node-red-contrib-boolean-logic-ultimate 1.2.9 → 1.2.13

package/CHANGELOG.md

@@ -4,11 +4,38 @@
 
 # CHANGELOG
 
+<p>
+<b>Version 1.2.13</b> May 2026<br/>
+
+- BooleanLogicUltimate: renamed the editor field label from "Evaluate" to "Input".<br/>
+- Updated BooleanLogic help and README terminology to match the new label.<br/>
+</p>
+
+<p>
+<b>Version 1.2.12</b> May 2026<br/>
+
+- Renamed editor label from "With Input" to "Input" for clearer wording across affected nodes.<br/>
+- Updated the related node help sections and README terminology accordingly.<br/>
+</p>
+
+<p>
+<b>Version 1.2.11</b> April 2026<br/>
+
+- DebouncerUltimate: simplified the node to a single output, with clearer editor labels for non-technical users.<br/>
+- Updated Debouncer help and README, adding a dedicated explanatory image.<br/>
+</p>
+
+<p>
+<b>Version 1.2.10</b> April 2026<br/>
+
+- NEW: DebouncerUltimate node for dedicated debounce flows with trailing/leading/both emission modes.<br/>
+- Updated README, examples and tests accordingly.<br/>
+</p>
+
 <p>
 <b>Version 1.2.9</b> April 2026<br/>
-- Removed the following newly introduced HA nodes because considered too complex: ForDurationUltimate, WatchdogUltimate, PriorityMuxUltimate, GroupStateUltimate.<br/>
-- Removed related examples, tests and documentation sections.<br/>
-- Kept HysteresisUltimate and aligned package registration/examples docs accordingly.<br/>
+
+- NEW: Hysteresis node and aligned package registration/examples docs accordingly.<br/>
 </p>
 
 <p>

package/README.md

@@ -1,17 +1,11 @@
 ![Logo](img/logo.png)
 
 [![NPM version][npm-version-image]][npm-url]
-
 [![NPM downloads per month][npm-downloads-month-image]][npm-url]
-
 [![NPM downloads total][npm-downloads-total-image]][npm-url]
-
 [![MIT License][license-image]][license-url]
-
 [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
-
 [![Donate via PayPal](https://img.shields.io/badge/Donate-PayPal-blue.svg?style=flat-square)](https://www.paypal.me/techtoday)
-
 [![youtube][youtube-image]][youtube-url]
 
 A set of Node-RED enhanced boolean logic and utility nodes, with persistent values after reboot. Compatible also with Homeassistant values.
@@ -105,7 +99,7 @@ The node can convert arbitrary input values to true/false. It supports Homeassis
 | Property                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Inputs count                                 | Set the number of different topics to be evaluated. The node will output a message to the flow, after this number of _different_ topics arrives. _Remember: each input topic must be different. For example, if you set this field to 3, the node expects 3 different topics._                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Evaluate                                     | It's the msg property to be evaluated. _By default, it is "payload", but you can also specify other properties, for example "payload.value"_                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Input                                        | It's the msg property to be evaluated. _By default, it is "payload", but you can also specify other properties, for example "payload.value"_                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Filter output                                | **Output both 'true' and 'false'** results: Standard behaviour, the node will output <b>true</b> and <b>false</b> whenever it receives an input and calculate the boolean logics as output. **Output only 'true'** results: whenever the node receives an input, it outputs a payload <b>true</b> only if the result of the logic is true. <b>False</b> results are filtered out.                                                                                                                                                                                                                                                                                                                            |
 | Trigger mode                                 | **All topics**: standard behaviour, the node will evaluate each input topic and ouputs the values. At each input change, it will output a msg on the flow. **Single topic + eval other inputs**: the node evaluates all the input topics, but only whenever it receives a msg input with the **specified topic**, it outputs a msg to the flow.                                                                                                                                                                                                                                                                                                                                                              |
 | If input states are undefined                | Every time you create a node or modify the node, all inputs are set to undefined. This means that the node will wait the arrive of all topics (for example 3 topics, if you've selected 3 topics in the option), before it can output a payload. This can be a problem if your logic must be operative as soon as you deploy the flow. To overcome this problem, you can "initialize" all the undefined inputs with True or False. **Leave undefined**: Standard behaviour, the node will wait all the "undefined" topics to arrive, then starts a flow with the result. **True or False**: The node is immediately operative, by force the initialization of the "undefined" inputs with "true" or "false". |
@@ -137,7 +131,7 @@ The interrupt flows is able to stop the input messages to exiting the node.
 | Property         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Trigger by topic | Whenever the node receives a payload = false from this topic,it stops output messages to the flow. As soon it receives payload = true from this topic, the output messages start to flow out again. The node will output the current stored message plus an added property "isReplay = true", as soon as it receives a **_msg.play = true_** from this topic. The node will clear the current stored message, as soon as it receives a **_msg.reset = true_** from this topic.                                                                              |
-| With Input       | It's the msg property to be evaluated. _By default, it is "payload", but you can also specify other properties, for example "payload.value"_                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Input       | It's the msg property to be evaluated. _By default, it is "payload", but you can also specify other properties, for example "payload.value"_                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Then             | This property, allow you to auto toggle the selected start state (pass or block) after a timer has elapsed. You can choose from some pre-defined delays. If you have, for example, an Homekit-Bridged nodeset with a thermostat node or security system node in your flow, once node-red restarts, these homekit nodes output a default message to the flow. Just put an InterruptFlow node with a "block at start" behaviour and a toggle delay enabled behind homekit nodes, to temporary stop the chained nodes to receive the unwanted startup message. |
 
 <br/>
@@ -477,7 +471,7 @@ The railway switcher, redirect the incoming messages to one ot the avaiable outp
 | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | Switcher topic | Whenever the node receives a payload from this **topic**, it redirects the input messages to a choosen output PIN.                           |
 | Output pins    | Number of output pins (outputs) to show. Default is 5, range is 1..10.                                                                       |
-| With Input     | It's the msg property to be evaluated. _By default, it is "payload", but you can also specify other properties, for example "payload.value"_ |
+| Input     | It's the msg property to be evaluated. _By default, it is "payload", but you can also specify other properties, for example "payload.value"_ |
 | Translator     | Translates the incoming <code>payload</code> value. This allows the compatibility with, for example, **HomeAssistant** nodes.                |
 
 ### Inputs
@@ -496,7 +490,7 @@ Take the example where you choosen such properties:
 
 **Switcher topic**: "switcher"
 
-**With Input**: "payload"
+**Input**: "payload"
 
 this JSON input message redirects all input messages to the first PIN
 
@@ -662,14 +656,14 @@ Gateway per sensori e dispositivi troppo “chiacchieroni”: limita burst e rim
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Mode             | Seleziona la logica: _Debounce_ (attende quiete), _Throttle_ (impone un intervallo minimo), _Window_ (massimo N messaggi per finestra temporale). |
 | Wait (ms)        | Ritardo di quiete per la modalità debounce.                                                                                                       |
-| Emit             | Per debounce: scegli tra _Leading_ (subito), _Trailing_ (ultimo), _Both_.                                                                         |
+| Emit             | Per debounce: scegli se inviare subito il primo messaggio, solo l’ultimo dopo la pausa, oppure entrambi.                                          |
 | Interval (ms)    | Intervallo minimo tra messaggi in modalità throttle.                                                                                              |
 | Emit trailing    | In throttle, inoltra l’ultimo messaggio ricevuto allo scadere dell’intervallo.                                                                    |
 | Window size (ms) | Larghezza della finestra mobile in modalità window.                                                                                               |
 | Max messages     | Numero di messaggi ammessi nella finestra.                                                                                                        |
 | On limit         | _Drop_ scarta i messaggi extra, _Queue last_ accoda l’ultimo e lo riproduce appena possibile.                                                     |
 | Control topic    | Topic dei messaggi di controllo (default `rate`).                                                                                                 |
-| With Input       | Proprietà del messaggio da monitorare (default `msg.payload`).                                                                                    |
+| Input       | Proprietà del messaggio da monitorare (default `msg.payload`).                                                                                    |
 | Stats every (s)  | Ogni quanti secondi emettere un riepilogo statistico (0 = disattivato).                                                                           |
 | Translator       | Nodo translator-config opzionale per adattare le stringhe d’ingresso a true/false.                                                                |
 
@@ -691,6 +685,37 @@ Gateway per sensori e dispositivi troppo “chiacchieroni”: limita burst e rim
 
 <br/>
 
+# DEBOUNCER ULTIMATE
+
+Nodo dedicato al solo debounce: utile quando vuoi filtrare rimbalzi o burst rapidi senza portarti dietro le altre modalità del `RateLimiterUltimate`. Può inoltrare il **primo** messaggio, l’**ultimo** oppure **entrambi**, dopo un intervallo di quiete configurabile.
+
+<img src='img/debouncer.png' width='80%'>
+
+Nell'immagine si vede il comportamento tipico: a sinistra arrivano molti messaggi ravvicinati, il nodo aspetta una breve pausa, e a destra lascia passare solo il messaggio utile.
+
+Example flow: [`examples/DebouncerUltimate.json`](examples/DebouncerUltimate.json)
+
+### NODE CONFIGURATION
+
+| Property      | Description                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| Wait (ms)     | Tempo di quiete richiesto prima di chiudere la finestra di debounce.                          |
+| Emit          | Scegli se inviare subito il primo messaggio, solo l’ultimo dopo la pausa, oppure entrambi.    |
+| Control topic | Topic dei messaggi di controllo (default `debouncer`).                                        |
+
+### OUTPUT
+
+- **Output 1**: messaggi inoltrati dopo il debounce.
+
+### CONTROL MESSAGES (`msg.topic === controlTopic`)
+
+- `msg.reset = true` &rarr; cancella timer e messaggio pendente.
+- `msg.flush = true` &rarr; inoltra subito l’ultimo messaggio in attesa.
+- `msg.wait` &rarr; aggiorna il ritardo di debounce a runtime.
+- `msg.emitOn = 'leading'|'trailing'|'both'` &rarr; cambia la modalità di emissione.
+
+<br/>
+
 # PRESENCE SIMULATOR ULTIMATE
 
 The purpose of this node is to replay a programmable sequence of messages in order to simulate occupancy when you are away.
@@ -704,7 +729,7 @@ The purpose of this node is to replay a programmable sequence of messages in ord
 | Loop sequence | Repeats the sequence when it reaches the end.                                                  |
 | Random delays | Enables a random variation of the programmed delays.                                           |
 | Jitter (%)    | Maximum percentage of variation applied when random delays are enabled.                        |
-| With Input    | Message property to inspect for inline events (default `payload`).                             |
+| Input    | Message property to inspect for inline events (default `payload`).                             |
 | Translator    | Optional translator-config to convert incoming values.                                         |
 | Sequence      | One JSON object per line, each containing at least `delay` (ms) plus the properties to output. |
 
@@ -734,7 +759,7 @@ The purpose of this node is to control staircase lighting with a timer, pre-off
 | Warning offset (s) | Seconds before switch-off when the warning is sent.                |
 | Restart on trigger | Restarts the timer when a new trigger arrives while active.        |
 | Allow off input    | Allows a `false` from the main input to switch off immediately.    |
-| With Input         | Message property evaluated as trigger (default `payload`).         |
+| Input         | Message property evaluated as trigger (default `payload`).         |
 | Translator         | Optional translator-config for true/false conversion.              |
 | On/Off payload     | Values emitted on output 1 to turn the light on/off.               |
 | Warning payload    | Value emitted on output 2 when the warning fires.                  |
@@ -758,16 +783,16 @@ Example flow: [`examples/HysteresisUltimate.json`](examples/HysteresisUltimate.j
 
 ### NODE CONFIGURATION
 
-| Property            | Description                                                                                                  |
-| ------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Control topic       | Topic that receives runtime commands such as threshold updates and reset.                                   |
-| Mode                | `high` = ON above threshold, OFF below. `low` = ON below threshold, OFF above.                             |
-| ON/OFF threshold    | Hysteresis limits.                                                                                           |
-| Initial state       | Startup output state.                                                                                        |
-| Emit only on change | If enabled, output 1 emits only on state transitions.                                                       |
-| With Input          | Message property evaluated as numeric value (default `payload`).                                            |
-| Translator          | Optional translator-config.                                                                                  |
-| On/Off payload      | Typed payloads sent on output 1.                                                                            |
+| Property            | Description                                                                    |
+| ------------------- | ------------------------------------------------------------------------------ |
+| Control topic       | Topic that receives runtime commands such as threshold updates and reset.      |
+| Mode                | `high` = ON above threshold, OFF below. `low` = ON below threshold, OFF above. |
+| ON/OFF threshold    | Hysteresis limits.                                                             |
+| Initial state       | Startup output state.                                                          |
+| Emit only on change | If enabled, output 1 emits only on state transitions.                          |
+| Input          | Message property evaluated as numeric value (default `payload`).               |
+| Translator          | Optional translator-config.                                                    |
+| On/Off payload      | Typed payloads sent on output 1.                                               |
 
 ### CONTROL MESSAGES (`msg.topic === controlTopic`)
 

package/boolean-logic-ultimate/BooleanLogicUltimate.html

@@ -142,7 +142,7 @@
 				<input style="width:100px" type="text" id="node-input-inputCount" placeholder="Inputs count, for example: 2">
 			</div>
 			<div class="form-row">
-				<label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> Evaluate</label>
+				<label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> Input</label>
 				<input type="text" id="node-input-payloadPropName">
 			</div>
 			<div class="form-row">
@@ -228,7 +228,7 @@
 |Property|Description|
 |--|--|
 | Inputs count | Set the number of different topics to be evaluated. The node will output a message to the flow, after this number of *different* topics arrives. *Remember: each input topic must be different. For example, if you set this field to 3, the node expects 3 different topics.* |
-| Evaluate | It's the msg property to be evaluated. *By default, it is "payload", but you can also specify other properties, for example "payload.value"* |
+| Input | It's the msg property to be evaluated. *By default, it is "payload", but you can also specify other properties, for example "payload.value"* |
 
 <br/>
 
@@ -259,4 +259,4 @@
 [Find it useful?](https://www.paypal.me/techtoday)
 <br/>
 
-</script>
+</script>

package/boolean-logic-ultimate/DebouncerUltimate.html

@@ -0,0 +1,76 @@
+<script type="text/javascript">
+  RED.nodes.registerType('DebouncerUltimate', {
+    category: 'Boolean Logic Ultimate',
+    color: '#ff8080',
+    defaults: {
+      name: { value: '' },
+      wait: { value: 500, validate: RED.validators.number() },
+      emitOn: { value: 'trailing' },
+      controlTopic: { value: 'debouncer' }
+    },
+    inputs: 1,
+    outputs: 1,
+    outputLabels: ['Forward'],
+    icon: 'file-in.png',
+    label: function () {
+      return this.name || 'Debouncer';
+    },
+    paletteLabel: function () {
+      return 'Debouncer';
+    }
+  });
+</script>
+
+<script type="text/html" data-template-name="DebouncerUltimate">
+  <div class="form-row">
+    <b>Debouncer Ultimate</b>
+    &nbsp;&nbsp;<span style="color:red"><i class="fa fa-youtube-play"></i>&nbsp;<a target="_blank" href="https://youtu.be/t45kaMQzm5Q"><u>Youtube Video</u></a></span>
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-name"><i class="icon-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="Name">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-wait"><i class="fa fa-hourglass-o"></i> Wait (ms)</label>
+    <input type="number" id="node-input-wait" min="0">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-emitOn"><i class="fa fa-exchange"></i> Emit</label>
+    <select id="node-input-emitOn">
+      <option value="leading">Send first message immediately</option>
+      <option value="trailing">Send only the last message after the pause</option>
+      <option value="both">Send first immediately and last after the pause</option>
+    </select>
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-controlTopic"><i class="fa fa-tag"></i> Control topic</label>
+    <input type="text" id="node-input-controlTopic">
+  </div>
+</script>
+
+<script type="text/markdown" data-help-name="DebouncerUltimate">
+<p>Dedicated debounce node to suppress rapid bursts and forward only the first, last or both messages of a quiet-time window.</p>
+
+<p><img src="/resources/node-red-contrib-boolean-logic-ultimate/img/debouncer.png" alt="Debouncer example" style="max-width:100%; border-radius:6px;" /></p>
+
+|Property|Description|
+|--|--|
+| Wait (ms) | Quiet time before the debounce window closes. |
+| Emit | Choose whether to send the first message immediately, only the last one after the pause, or both. |
+| Control topic | Topic used for runtime commands (default `debouncer`). |
+
+Output:
+
+- Output 1 forwards the debounced message.
+
+Control topic messages:
+
+- `msg.reset = true` clears the timer and pending message.
+- `msg.flush = true` emits the pending message immediately.
+- `msg.wait` updates the debounce time.
+- `msg.emitOn = 'leading'|'trailing'|'both'` changes the emission mode.
+</script>

package/boolean-logic-ultimate/DebouncerUltimate.js

@@ -0,0 +1,190 @@
+'use strict';
+
+module.exports = function (RED) {
+  function DebouncerUltimate(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    const REDUtil = RED.util;
+    const helpers = require('./lib/node-helpers.js');
+
+    const setNodeStatus = helpers.createStatus(node);
+    const timerBag = helpers.createTimerBag(node);
+
+    const controlTopic = config.controlTopic || 'debouncer';
+
+    let wait = Number(config.wait);
+    if (!Number.isFinite(wait) || wait < 0) {
+      wait = 500;
+    }
+
+    let emitOn = normalizeEmitOn(config.emitOn);
+    let passedCount = 0;
+    let droppedCount = 0;
+    let currentState = 'idle';
+    let debounceTimer = null;
+    let leadingSent = false;
+    let pendingMessage = null;
+
+    function normalizeEmitOn(value) {
+      const normalized = String(value || 'trailing').toLowerCase();
+      return ['leading', 'trailing', 'both'].includes(normalized)
+        ? normalized
+        : 'trailing';
+    }
+
+    function clone(msg) {
+      return REDUtil.cloneMessage ? REDUtil.cloneMessage(msg) : JSON.parse(JSON.stringify(msg));
+    }
+
+    function sendStatus() {
+      const colour = currentState === 'idle' ? 'green' : 'yellow';
+      const modeLabel = {
+        leading: 'L',
+        trailing: 'T',
+        both: 'B',
+      }[emitOn] || 'T';
+
+      setNodeStatus({
+        fill: colour,
+        shape: 'dot',
+        text: `DB|${modeLabel}|${currentState} pass:${passedCount} drop:${droppedCount}`,
+      });
+    }
+
+    function emitForward(msg, nextState = 'idle') {
+      passedCount += 1;
+      currentState = nextState;
+      node.send(msg);
+      sendStatus();
+    }
+
+    function emitDrop() {
+      droppedCount += 1;
+      currentState = 'waiting';
+      sendStatus();
+    }
+
+    function clearDebounce() {
+      if (debounceTimer) {
+        timerBag.clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      pendingMessage = null;
+      leadingSent = false;
+    }
+
+    function resetDebounce() {
+      clearDebounce();
+      currentState = 'idle';
+      sendStatus();
+    }
+
+    function flushPending() {
+      if (!pendingMessage) {
+        currentState = 'idle';
+        sendStatus();
+        return false;
+      }
+
+      const toSend = pendingMessage;
+      if (debounceTimer) {
+        timerBag.clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      pendingMessage = null;
+      leadingSent = false;
+      emitForward(toSend, 'idle');
+      return true;
+    }
+
+    function handleControlMessage(msg) {
+      let consumed = false;
+
+      if (Object.prototype.hasOwnProperty.call(msg, 'wait')) {
+        const nextWait = Number(msg.wait);
+        if (Number.isFinite(nextWait) && nextWait >= 0) {
+          wait = nextWait;
+          consumed = true;
+        }
+      }
+
+      if (typeof msg.emitOn === 'string') {
+        emitOn = normalizeEmitOn(msg.emitOn);
+        consumed = true;
+      }
+
+      if (msg.reset === true) {
+        resetDebounce();
+        consumed = true;
+      }
+
+      if (msg.flush === true) {
+        flushPending();
+        consumed = true;
+      }
+
+      if (msg.status === true) {
+        consumed = true;
+        sendStatus();
+      }
+
+      if (consumed) {
+        sendStatus();
+      }
+
+      return consumed;
+    }
+
+    function handleDebounce(msg) {
+      const cloned = clone(msg);
+
+      if (debounceTimer) {
+        timerBag.clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+
+      pendingMessage = cloned;
+      currentState = 'waiting';
+
+      const shouldEmitLeading =
+        (emitOn === 'leading' || emitOn === 'both') && !leadingSent;
+
+      if (shouldEmitLeading) {
+        emitForward(cloned, 'waiting');
+        leadingSent = true;
+      }
+
+      if (emitOn === 'leading' && !shouldEmitLeading) {
+        emitDrop();
+      }
+
+      debounceTimer = timerBag.setTimeout(() => {
+        debounceTimer = null;
+        leadingSent = false;
+        const shouldEmitTrailing = emitOn === 'trailing' || emitOn === 'both';
+
+        if (shouldEmitTrailing && pendingMessage) {
+          const toSend = pendingMessage;
+          pendingMessage = null;
+          emitForward(toSend, 'idle');
+        } else {
+          pendingMessage = null;
+          currentState = 'idle';
+          sendStatus();
+        }
+      }, wait);
+    }
+
+    node.on('input', function (msg) {
+      if (msg.topic === controlTopic && handleControlMessage(msg)) {
+        return;
+      }
+
+      handleDebounce(msg);
+    });
+
+    sendStatus();
+  }
+
+  RED.nodes.registerType('DebouncerUltimate', DebouncerUltimate);
+};

package/boolean-logic-ultimate/HysteresisUltimate.html

@@ -96,7 +96,7 @@
   </div>
 
   <div class="form-row">
-    <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> With Input</label>
+    <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> Input</label>
     <input type="text" id="node-input-payloadPropName">
   </div>
 
@@ -124,7 +124,7 @@
 | Mode | `high`: ON above threshold, OFF below. `low`: ON below threshold, OFF above. |
 | ON/OFF threshold | The two hysteresis limits. |
 | Emit only on change | Emits output only when state changes. |
-| With Input | Message property to evaluate (default `payload`). |
+| Input | Message property to evaluate (default `payload`). |
 | Translator | Optional translator-config. |
 | On/Off payload | Values sent on output 1. |
 

package/boolean-logic-ultimate/InterruptFlowUltimate.html

@@ -56,7 +56,7 @@
 		<input type="text" id="node-input-triggertopic" placeholder="Name">
     </div>
 	<div class="form-row">
-        <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> With Input</label>
+        <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> Input</label>
 		<input type="text" id="node-input-payloadPropName">
     </div>
 	<div><i>Whenever the node receives a msg with false from this topic,<br/> it stops output messages to the flow.<br/>As soon it receives a message with true from this topic,<br/>the output messages start to flow out again.
@@ -105,7 +105,7 @@
 |Property|Description|
 |--|--|
 | Trigger by topic | Whenever the node receives a payload = false from this topic,it stops output messages to the flow. As soon it receives payload = true from this topic, the output messages start to flow out again. The node will output the current stored message plus an added property "isReplay = true", as soon as it receives a ***msg.play = true*** from this topic. The node will clear the current stored message, as soon as it receives a ***msg.reset = true*** from this topic. |
-| With Input | It's the msg property to be evaluated. *By default, it is "payload", but you can also specify other properties, for example "payload.value"* |
+| Input | It's the msg property to be evaluated. *By default, it is "payload", but you can also specify other properties, for example "payload.value"* |
 | Then | This property, allow you to auto toggle the selected start state (pass or block) after a timer has elapsed. You can choose from some pre-defined delays. If you have, for example, an Homekit-Bridged nodeset with a thermostat node or security system node in your flow, once node-red restarts, these homekit nodes output a default message to the flow. Just put an InterruptFlow node with a "block at start" behaviour and a toggle delay enabled behind homekit nodes, to temporary stop the chained nodes to receive the unwanted startup message.|
 | Translator Input | Translates the incoming <code>payload</code> value, to true/false. This allows the compatibility with, for example, **HomeAssistant** nodes. |
 

package/boolean-logic-ultimate/PresenceSimulatorUltimate.html

@@ -68,7 +68,7 @@
   </div>
 
   <div class="form-row">
-    <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> With Input</label>
+    <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> Input</label>
     <input type="text" id="node-input-payloadPropName">
   </div>
 
@@ -93,7 +93,7 @@
 | Loop sequence | Repeats the sequence when the end is reached. |
 | Random delays | Enables a random variation of the programmed delays. |
 | Jitter (%) | Maximum percentage of variation applied when random delays are enabled. |
-| With Input | Message property to inspect for inline events (default `payload`). |
+| Input | Message property to inspect for inline events (default `payload`). |
 | Translator | Optional translator-config to convert incoming values. |
 | Sequence | One JSON object per line, each composed at least of `delay` (in ms) and the properties to output. |
 

package/boolean-logic-ultimate/RailwaySwitchUltimate.html

@@ -141,7 +141,7 @@
 		</select>
 	</div>
 	<div class="form-row">
-        <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> With Input</label>
+        <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> Input</label>
 		<input type="text" id="node-input-payloadPropName">
     </div>
 	<div class="form-row">
@@ -163,7 +163,7 @@
 |--|--|
 | Switcher topic | Whenever the node receives a payload from this **topic**, it redirects the input messages to a choosen output PIN. |
 | Output pins | Number of output pins to display (1..10). |
-| With Input | It's the msg property to be evaluated. *By default, it is "payload", but you can also specify other properties, for example "payload.value"* |
+| Input | It's the msg property to be evaluated. *By default, it is "payload", but you can also specify other properties, for example "payload.value"* |
 | Translator | Translates the incoming <code>payload</code> value. This allows the compatibility with, for example, **HomeAssistant** nodes. |
 
 ### Inputs
@@ -178,7 +178,7 @@ Once an output PIN has been choosen, all messages passing through the node will
 
 Take the example where you choosen such properties:  
 **Switcher topic**: "switcher"  
-**With Input**: "payload"  
+**Input**: "payload"  
 this JSON input message redirects all input messages to the first PIN  
 
 ```json

package/boolean-logic-ultimate/RateLimiterUltimate.html

@@ -87,7 +87,7 @@
   </div>
 
   <div class="form-row rate-config-common">
-    <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> With Input</label>
+    <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> Input</label>
     <input type="text" id="node-input-payloadPropName">
   </div>
 
@@ -104,9 +104,9 @@
   <div class="form-row rate-config-section rate-config-debounce">
     <label for="node-input-emitOn"><i class="fa fa-exchange"></i> Emit</label>
     <select id="node-input-emitOn">
-      <option value="leading">Leading edge</option>
-      <option value="trailing">Trailing edge</option>
-      <option value="both">Both</option>
+      <option value="leading">Send first message immediately</option>
+      <option value="trailing">Send only the last message after the pause</option>
+      <option value="both">Send first immediately and last after the pause</option>
     </select>
   </div>
 
@@ -116,7 +116,7 @@
   </div>
 
   <div class="form-row rate-config-section rate-config-throttle">
-    <label for="node-input-trailing"><i class="fa fa-arrow-circle-right"></i> Emit trailing</label>
+    <label for="node-input-trailing"><i class="fa fa-arrow-circle-right"></i> Also send the last queued message</label>
     <input type="checkbox" id="node-input-trailing" style="width:auto; margin-top:7px;">
   </div>
 
@@ -144,8 +144,8 @@ The purpose of this node is to moderate the frequency of incoming messages.
 
 **Modes**
 
-- **Debounce** – waits for the line to be quiet before forwarding the final message. With *Leading* it emits the first message immediately and blocks the following ones until the delay ends; *Trailing* sends only the last message; *Both* combines both behaviours.
-- **Throttle** – enforces a minimum interval between consecutive messages. When *Emit trailing* is enabled the most recent message is forwarded once the interval has elapsed.
+- **Debounce** – waits for the line to be quiet before forwarding a message. You can choose to send the first message immediately, only the last message after the pause, or both.
+- **Throttle** – enforces a minimum interval between consecutive messages. When *Also send the last queued message* is enabled the most recent message is forwarded once the interval has elapsed.
 - **Window** – limits the number of messages in a moving time window. Extra messages can be dropped or queued to play once a slot becomes available.
 
 **Outputs**
@@ -160,5 +160,5 @@ The purpose of this node is to moderate the frequency of incoming messages.
 - `msg.mode = 'debounce'|'throttle'|'window'` – changes mode at runtime.
 - `msg.interval`, `msg.wait`, `msg.windowSize`, `msg.maxInWindow` – adjust the related thresholds.
 
-The **With Input** field selects which message property to evaluate (default `msg.payload`). When configured, it can be translated through the **translator-config** node for Home Assistant compatibility.
-</script>
+The **Input** field selects which message property to evaluate (default `msg.payload`). When configured, it can be translated through the **translator-config** node for Home Assistant compatibility.
+</script>

package/boolean-logic-ultimate/StaircaseLightUltimate.html

@@ -103,7 +103,7 @@
   </div>
 
   <div class="form-row">
-    <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> With Input</label>
+    <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> Input</label>
     <input type="text" id="node-input-payloadPropName">
   </div>
 
@@ -139,7 +139,7 @@
 | Warning offset (s) | Seconds before switch-off when the warning is sent. |
 | Restart on trigger | Restarts the timer every time a new trigger arrives while active. |
 | Allow off input | Allows a `false` from the main input to switch off immediately. |
-| With Input | Message property to evaluate as trigger (default `payload`). |
+| Input | Message property to evaluate as trigger (default `payload`). |
 | Translator | Optional translator-config for true/false conversion. |
 | On/Off payload | Values emitted on output 1 to switch the light. |
 | Warning payload | Value emitted on output 2 when the warning fires. |

package/examples/DebouncerUltimate.json

@@ -0,0 +1,168 @@
+[
+  {
+    "id": "db_tab_1",
+    "type": "tab",
+    "label": "DebouncerUltimate - burst filter",
+    "disabled": false,
+    "info": "Esempio: filtra burst ravvicinati con il nodo DebouncerUltimate."
+  },
+  {
+    "id": "db_cmt_1",
+    "type": "comment",
+    "z": "db_tab_1",
+    "name": "Burst → Debouncer → Forward",
+    "info": "Clicca BURST per generare messaggi ravvicinati. Cambia la modalità con LEADING/TRAILING/BOTH oppure usa FLUSH/RESET via topic \"debouncer\".",
+    "x": 300,
+    "y": 60,
+    "wires": []
+  },
+  {
+    "id": "db_inj_burst",
+    "type": "inject",
+    "z": "db_tab_1",
+    "name": "BURST (10 msgs)",
+    "props": [
+      { "p": "count", "v": "10", "vt": "num" },
+      { "p": "interval", "v": "50", "vt": "num" }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 150,
+    "y": 140,
+    "wires": [["db_fn_burst"]]
+  },
+  {
+    "id": "db_fn_burst",
+    "type": "function",
+    "z": "db_tab_1",
+    "name": "Burst generator",
+    "func": "const count = Number(msg.count || 10);\nconst interval = Number(msg.interval || 50);\nlet i = 0;\n\nconst sendOne = () => {\n  node.send({ topic: 'data', payload: i, index: i, ts: Date.now() });\n  i += 1;\n  if (i < count) {\n    setTimeout(sendOne, interval);\n  }\n};\n\nsendOne();\nreturn null;",
+    "outputs": 1,
+    "noerr": 0,
+    "initialize": "",
+    "finalize": "",
+    "libs": [],
+    "x": 360,
+    "y": 140,
+    "wires": [["db_node_1"]]
+  },
+  {
+    "id": "db_inj_leading",
+    "type": "inject",
+    "z": "db_tab_1",
+    "name": "LEADING (400ms)",
+    "props": [
+      { "p": "topic", "v": "debouncer", "vt": "str" },
+      { "p": "emitOn", "v": "leading", "vt": "str" },
+      { "p": "wait", "v": "400", "vt": "num" }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 160,
+    "y": 220,
+    "wires": [["db_node_1"]]
+  },
+  {
+    "id": "db_inj_trailing",
+    "type": "inject",
+    "z": "db_tab_1",
+    "name": "TRAILING (400ms)",
+    "props": [
+      { "p": "topic", "v": "debouncer", "vt": "str" },
+      { "p": "emitOn", "v": "trailing", "vt": "str" },
+      { "p": "wait", "v": "400", "vt": "num" }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 170,
+    "y": 260,
+    "wires": [["db_node_1"]]
+  },
+  {
+    "id": "db_inj_both",
+    "type": "inject",
+    "z": "db_tab_1",
+    "name": "BOTH (400ms)",
+    "props": [
+      { "p": "topic", "v": "debouncer", "vt": "str" },
+      { "p": "emitOn", "v": "both", "vt": "str" },
+      { "p": "wait", "v": "400", "vt": "num" }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 150,
+    "y": 300,
+    "wires": [["db_node_1"]]
+  },
+  {
+    "id": "db_inj_flush",
+    "type": "inject",
+    "z": "db_tab_1",
+    "name": "FLUSH",
+    "props": [
+      { "p": "topic", "v": "debouncer", "vt": "str" },
+      { "p": "flush", "v": "true", "vt": "bool" }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 120,
+    "y": 340,
+    "wires": [["db_node_1"]]
+  },
+  {
+    "id": "db_inj_reset",
+    "type": "inject",
+    "z": "db_tab_1",
+    "name": "RESET",
+    "props": [
+      { "p": "topic", "v": "debouncer", "vt": "str" },
+      { "p": "reset", "v": "true", "vt": "bool" }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 120,
+    "y": 380,
+    "wires": [["db_node_1"]]
+  },
+  {
+    "id": "db_node_1",
+    "type": "DebouncerUltimate",
+    "z": "db_tab_1",
+    "name": "Debouncer",
+    "wait": 400,
+    "emitOn": "trailing",
+    "controlTopic": "debouncer",
+    "x": 590,
+    "y": 240,
+    "wires": [["db_dbg_fwd"]]
+  },
+  {
+    "id": "db_dbg_fwd",
+    "type": "debug",
+    "z": "db_tab_1",
+    "name": "Forward",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "true",
+    "targetType": "full",
+    "statusVal": "",
+    "statusType": "auto",
+    "x": 780,
+    "y": 220,
+    "wires": []
+  }
+]

package/examples/README.md

@@ -11,6 +11,7 @@ How to import:
 - `BlinkerUltimate.json` — BlinkerUltimate
 - `BooleanLogicUltimate.json` — BooleanLogicUltimate
 - `Comparator.json` — Comparator
+- `DebouncerUltimate.json` — DebouncerUltimate
 - `FilterUltimate.json` — FilterUltimate
 - `HysteresisUltimate.json` — HysteresisUltimate
 - `ImpulseUltimate.json` — ImpulseUltimate

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "node-red-contrib-boolean-logic-ultimate",
-    "version": "1.2.9",
-    "description": "A set of Node-RED enhanced boolean logic and utility nodes, flow interruption, blinker, invert, filter, toggle etc.., with persistent values after reboot. Compatible also with Homeassistant values.",
+    "version": "1.2.13",
+    "description": "A set of Node-RED enhanced boolean logic and utility nodes, flow interruption, blinker, debouncer, invert, filter, toggle etc.., with persistent values after reboot. Compatible also with Homeassistant values.",
     "author": "Supergiovane (https://github.com/Supergiovane)",
     "dependencies": {
         "fs": "0.0.1-security",
@@ -28,6 +28,7 @@
     },
     "node-red": {
         "nodes": {
+            "DebouncerUltimate": "boolean-logic-ultimate/DebouncerUltimate.js",
             "BooleanLogicUltimate": "boolean-logic-ultimate/BooleanLogicUltimate.js",
             "InvertUltimate": "boolean-logic-ultimate/InvertUltimate.js",
             "FilterUltimate": "boolean-logic-ultimate/FilterUltimate.js",

package/test/debouncer.spec.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const { expect } = require('chai');
+const { helper, loadDebouncer } = require('./helpers');
+
+describe('DebouncerUltimate node', function () {
+  this.timeout(5000);
+
+  before(function (done) {
+    helper.startServer(done);
+  });
+
+  after(function (done) {
+    helper.stopServer(done);
+  });
+
+  afterEach(function () {
+    return helper.unload();
+  });
+
+  it('trailing debounce emits only the last message after quiet time', function (done) {
+    const flowId = 'flow1';
+    const flow = [
+      { id: flowId, type: 'tab', label: 'flow1' },
+      {
+        id: 'debouncer',
+        type: 'DebouncerUltimate',
+        z: flowId,
+        wait: 40,
+        emitOn: 'trailing',
+        controlTopic: 'debouncer',
+        wires: [['out']],
+      },
+      { id: 'in', type: 'helper', z: flowId, wires: [['debouncer']] },
+      { id: 'out', type: 'helper', z: flowId },
+    ];
+
+    loadDebouncer(flow).then(() => {
+      const debouncer = helper.getNode('debouncer');
+      const out = helper.getNode('out');
+      const seen = [];
+
+      out.on('input', (msg) => {
+        seen.push(msg.payload);
+      });
+
+      debouncer.receive({ topic: 'sensor', payload: 'first' });
+      setTimeout(() => {
+        debouncer.receive({ topic: 'sensor', payload: 'second' });
+      }, 15);
+
+      setTimeout(() => {
+        try {
+          expect(seen).to.deep.equal(['second']);
+          done();
+        } catch (error) {
+          done(error);
+        }
+      }, 120);
+    }).catch(done);
+  });
+
+  it('both mode emits first immediately and last after quiet time', function (done) {
+    const flowId = 'flow2';
+    const flow = [
+      { id: flowId, type: 'tab', label: 'flow2' },
+      {
+        id: 'debouncer',
+        type: 'DebouncerUltimate',
+        z: flowId,
+        wait: 50,
+        emitOn: 'both',
+        controlTopic: 'debouncer',
+        wires: [['out']],
+      },
+      { id: 'in', type: 'helper', z: flowId, wires: [['debouncer']] },
+      { id: 'out', type: 'helper', z: flowId },
+    ];
+
+    loadDebouncer(flow).then(() => {
+      const debouncer = helper.getNode('debouncer');
+      const out = helper.getNode('out');
+      const seen = [];
+
+      out.on('input', (msg) => {
+        seen.push(msg.payload);
+      });
+
+      debouncer.receive({ topic: 'sensor', payload: 'first' });
+      setTimeout(() => {
+        debouncer.receive({ topic: 'sensor', payload: 'second' });
+      }, 15);
+
+      setTimeout(() => {
+        try {
+          expect(seen).to.deep.equal(['first', 'second']);
+          done();
+        } catch (error) {
+          done(error);
+        }
+      }, 140);
+    }).catch(done);
+  });
+
+  it('leading mode emits only the first message during the debounce window', function (done) {
+    const flowId = 'flow3';
+    const flow = [
+      { id: flowId, type: 'tab', label: 'flow3' },
+      {
+        id: 'debouncer',
+        type: 'DebouncerUltimate',
+        z: flowId,
+        wait: 60,
+        emitOn: 'leading',
+        controlTopic: 'debouncer',
+        wires: [['out']],
+      },
+      { id: 'in', type: 'helper', z: flowId, wires: [['debouncer']] },
+      { id: 'out', type: 'helper', z: flowId },
+    ];
+
+    loadDebouncer(flow).then(() => {
+      const debouncer = helper.getNode('debouncer');
+      const out = helper.getNode('out');
+      const seen = [];
+
+      out.on('input', (msg) => {
+        seen.push(msg.payload);
+      });
+
+      debouncer.receive({ topic: 'sensor', payload: 'first' });
+      setTimeout(() => {
+        debouncer.receive({ topic: 'sensor', payload: 'second' });
+      }, 15);
+
+      setTimeout(() => {
+        try {
+          expect(seen).to.deep.equal(['first']);
+          done();
+        } catch (error) {
+          done(error);
+        }
+      }, 140);
+    }).catch(done);
+  });
+});

package/test/helpers.js

@@ -6,6 +6,7 @@ const helper = require('node-red-node-test-helper');
 helper.init(require.resolve('node-red')); // initialise with Node-RED runtime
 
 const nodes = {
+  DebouncerUltimate: require(path.join('..', 'boolean-logic-ultimate', 'DebouncerUltimate.js')),
   RateLimiterUltimate: require(path.join('..', 'boolean-logic-ultimate', 'RateLimiterUltimate.js')),
   PresenceSimulatorUltimate: require(path.join('..', 'boolean-logic-ultimate', 'PresenceSimulatorUltimate.js')),
   RailwaySwitchUltimate: require(path.join('..', 'boolean-logic-ultimate', 'RailwaySwitchUltimate.js')),
@@ -33,6 +34,10 @@ function loadRateLimiter(flow, credentials = {}) {
   return loadNode(nodes.RateLimiterUltimate, flow, credentials);
 }
 
+function loadDebouncer(flow, credentials = {}) {
+  return loadNode(nodes.DebouncerUltimate, flow, credentials);
+}
+
 function loadPresence(flow, credentials = {}) {
   return loadNode(nodes.PresenceSimulatorUltimate, flow, credentials);
 }
@@ -43,6 +48,7 @@ function loadRailwaySwitch(flow, credentials = {}) {
 
 module.exports = {
   helper,
+  loadDebouncer,
   loadRateLimiter,
   loadPresence,
   loadRailwaySwitch,