node-red-contrib-boolean-logic-ultimate 1.2.8 → 1.2.11

package/CHANGELOG.md

@@ -4,6 +4,26 @@
 
 # CHANGELOG
 
+<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/>
+
+- NEW: Hysteresis node and aligned package registration/examples docs accordingly.<br/>
+</p>
+
 <p>
 <b>Version 1.2.8</b> January 2026<br/>
 - Added youtube videos for the missing nodes and the relative links to the UI<br/>

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.
@@ -662,7 +656,7 @@ 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.                                                                                               |
@@ -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.
@@ -720,63 +745,6 @@ Each event in the sequence outputs a message configured in the JSON line. When r
 
 <br/>
 
-# ALARM SYSTEM ULTIMATE (BETA)
-
-This node implements an alarm control panel with multi-mode arming, zones, entry/exit delays, bypass, tamper/fire 24h zones, siren control, status and event log.
-
-Example flow: [`examples/AlarmSystemUltimate.json`](examples/AlarmSystemUltimate.json)
-
-### NODE CONFIGURATION
-
-| Property                    | Description                                                                                                  |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Control topic               | Topic that receives runtime commands such as arm/disarm/status/bypass.                                       |
-| With Input                  | Message property evaluated as sensor value (default `payload`).                                              |
-| Persist state               | Persists arming mode, bypass list and last log entries across restarts.                                      |
-| Require code for arm/disarm | Enables PIN checks using `msg.code` (or `msg.pin`).                                                          |
-| Exit/Entry delay (s)        | Global exit/entry delays (each zone can override entry delay).                                               |
-| Siren topic                 | Topic used on output 2 to turn the siren on/off.                                                             |
-| Siren payloads              | Values emitted on output 2 for siren on/off (typed).                                                         |
-| Siren duration (s)          | Auto stop duration (0 = latch until disarm).                                                                 |
-| Emit restore events         | Emits `zone_restore` when a zone returns to false.                                                           |
-| Event log size              | Max stored log entries in node context.                                                                      |
-| Zones                       | One JSON object per line (legacy) or a JSON array (formatted). Use **Format** in the editor to pretty-print. |
-
-Esempio JSON di una zona:
-
-```json
-{
-  "id": "front_door",
-  "name": "Front Door",
-  "topic": "house/door/front",
-  "type": "perimeter",
-  "modes": ["away", "night"],
-  "entry": true,
-  "entryDelaySeconds": 30,
-  "bypassable": true,
-  "chime": true
-}
-```
-
-### OUTPUTS
-
-- Output 1 (Events): `msg.topic = <controlTopic>/event`, with `msg.event` and `msg.payload` (state + details).
-- Output 2 (Siren): emits siren on/off commands on `sirenTopic` with the configured payloads.
-
-### CONTROL MESSAGES (`msg.topic === controlTopic`)
-
-- Arm: `msg.command = 'arm_away'|'arm_home'|'arm_night'` or `msg.arm = 'away'|'home'|'night'`
-- Disarm: `msg.command = 'disarm'` or `msg.disarm = true`
-- Status: `msg.command = 'status'` or `msg.status = true`
-- Bypass: `msg.command = 'bypass'|'unbypass'` with `msg.zone = '<zone id>'`
-- Panic: `msg.command = 'panic'` or `msg.command = 'panic_silent'`
-- Siren: `msg.command = 'siren_on'|'siren_off'`
-- Reset: `msg.command = 'reset'` or `msg.reset = true`
-
-When codes are enabled, pass `msg.code` (or `msg.pin`). If `duressCode` matches, the node raises a silent duress alarm event.
-
-<br/>
-
 # STAIRCASE LIGHT ULTIMATE
 
 The purpose of this node is to control staircase lighting with a timer, pre-off warning and optional extension on every trigger.
@@ -807,6 +775,36 @@ Output 1 delivers the ON/OFF command. Output 2 delivers the warning and includes
 
 <br/>
 
+# HYSTERESIS ULTIMATE
+
+Adds hysteresis to numeric sensor values to avoid rapid ON/OFF bouncing around thresholds.
+
+Example flow: [`examples/HysteresisUltimate.json`](examples/HysteresisUltimate.json)
+
+### 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.                                               |
+
+### CONTROL MESSAGES (`msg.topic === controlTopic`)
+
+- `msg.onThreshold`, `msg.offThreshold` &rarr; update thresholds at runtime.
+- `msg.state = true|false` &rarr; force state.
+- `msg.reset = true` &rarr; restore initial state.
+- `msg.status = true` &rarr; emit current state/thresholds on output 2.
+
+Output 1 emits the command payload (`onPayload`/`offPayload`). Output 2 emits diagnostic events.
+
+<br/>
+
 [license-image]: https://img.shields.io/badge/license-MIT-blue.svg
 [license-url]: https://github.com/Supergiovane/node-red-contrib-boolean-logic-ultimate/master/LICENSE
 [npm-url]: https://npmjs.org/package/node-red-contrib-boolean-logic-ultimate

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

@@ -0,0 +1,137 @@
+<script type="text/javascript">
+  RED.nodes.registerType('HysteresisUltimate', {
+    category: 'Boolean Logic Ultimate',
+    color: '#ff8080',
+    defaults: {
+      name: { value: '' },
+      controlTopic: { value: 'hysteresis' },
+      payloadPropName: { value: 'payload', required: false },
+      translatorConfig: { type: 'translator-config', required: false },
+      mode: { value: 'high' },
+      onThreshold: { value: 70, validate: RED.validators.number() },
+      offThreshold: { value: 65, validate: RED.validators.number() },
+      initialState: { value: false },
+      emitOnlyOnChange: { value: true },
+      onPayload: { value: true },
+      onPayloadType: { value: 'bool' },
+      offPayload: { value: false },
+      offPayloadType: { value: 'bool' }
+    },
+    inputs: 1,
+    outputs: 2,
+    outputLabels: ['State output', 'Diagnostics'],
+    icon: 'font-awesome/fa-sliders',
+    label: function () {
+      return this.name || 'Hysteresis';
+    },
+    paletteLabel: function () {
+      return 'Hysteresis';
+    },
+    oneditprepare: function () {
+      const payloadField = $('#node-input-payloadPropName');
+      if (payloadField.val() === '') payloadField.val('payload');
+      payloadField.typedInput({ default: 'msg', types: ['msg'] });
+
+      $('#node-input-onPayload').typedInput({
+        default: this.onPayloadType || 'bool',
+        types: ['str', 'num', 'bool', 'json']
+      });
+      $('#node-input-onPayload').typedInput('type', this.onPayloadType || 'bool');
+
+      $('#node-input-offPayload').typedInput({
+        default: this.offPayloadType || 'bool',
+        types: ['str', 'num', 'bool', 'json']
+      });
+      $('#node-input-offPayload').typedInput('type', this.offPayloadType || 'bool');
+    },
+    oneditsave: function () {
+      this.onPayloadType = $('#node-input-onPayload').typedInput('type');
+      this.offPayloadType = $('#node-input-offPayload').typedInput('type');
+    }
+  });
+</script>
+
+<script type="text/html" data-template-name="HysteresisUltimate">
+  <div class="form-row">
+    <b>Hysteresis Ultimate</b>
+    &nbsp;&nbsp;<span style="color:red"><i class="fa fa-question-circle"></i>&nbsp;<a target="_blank" href="https://github.com/Supergiovane/node-red-contrib-boolean-logic-ultimate"><u>Help online</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-controlTopic"><i class="fa fa-tag"></i> Control topic</label>
+    <input type="text" id="node-input-controlTopic">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-mode"><i class="fa fa-arrows-v"></i> Mode</label>
+    <select id="node-input-mode">
+      <option value="high">High threshold (ON above)</option>
+      <option value="low">Low threshold (ON below)</option>
+    </select>
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-onThreshold"><i class="fa fa-long-arrow-up"></i> ON threshold</label>
+    <input type="number" id="node-input-onThreshold" step="any">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-offThreshold"><i class="fa fa-long-arrow-down"></i> OFF threshold</label>
+    <input type="number" id="node-input-offThreshold" step="any">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-initialState"><i class="fa fa-power-off"></i> Initial state ON</label>
+    <input type="checkbox" id="node-input-initialState" style="width:auto; margin-top:7px;">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-emitOnlyOnChange"><i class="fa fa-filter"></i> Emit only on change</label>
+    <input type="checkbox" id="node-input-emitOnlyOnChange" style="width:auto; margin-top:7px;">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-payloadPropName"><i class="fa fa-ellipsis-h"></i> With Input</label>
+    <input type="text" id="node-input-payloadPropName">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-translatorConfig"><i class="fa fa-language"></i> Translator</label>
+    <input type="text" id="node-input-translatorConfig">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-onPayload"><i class="fa fa-sign-in"></i> On payload</label>
+    <input type="text" id="node-input-onPayload">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-offPayload"><i class="fa fa-sign-out"></i> Off payload</label>
+    <input type="text" id="node-input-offPayload">
+  </div>
+</script>
+
+<script type="text/markdown" data-help-name="HysteresisUltimate">
+<p>Adds hysteresis to numeric values to avoid rapid ON/OFF bouncing around a threshold.</p>
+
+|Property|Description|
+|--|--|
+| 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`). |
+| Translator | Optional translator-config. |
+| On/Off payload | Values sent on output 1. |
+
+Control topic messages:
+
+- `msg.onThreshold`, `msg.offThreshold` to update thresholds at runtime.
+- `msg.state = true|false` to force state.
+- `msg.reset = true` to restore initial state.
+- `msg.status = true` to emit current status on output 2.
+</script>