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

package/boolean-logic-ultimate/HysteresisUltimate.js

@@ -0,0 +1,197 @@
+'use strict';
+
+module.exports = function (RED) {
+  const helpers = require('./lib/node-helpers.js');
+
+  function HysteresisUltimate(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+    const REDUtil = RED.util;
+
+    const setNodeStatus = helpers.createStatus(node);
+
+    const controlTopic = config.controlTopic || 'hysteresis';
+    const payloadPropName = config.payloadPropName || 'payload';
+    const mode = (config.mode || 'high').toLowerCase(); // high | low
+    const emitOnlyOnChange = config.emitOnlyOnChange !== false;
+
+    let onThreshold = Number(config.onThreshold);
+    let offThreshold = Number(config.offThreshold);
+    let state = Boolean(config.initialState);
+
+    if (!Number.isFinite(onThreshold)) onThreshold = 70;
+    if (!Number.isFinite(offThreshold)) offThreshold = 65;
+
+    function toNumber(value) {
+      if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+      }
+      if (typeof value === 'boolean') {
+        return value ? 1 : 0;
+      }
+      if (typeof value === 'string') {
+        const v = Number(value.trim());
+        return Number.isFinite(v) ? v : undefined;
+      }
+      return undefined;
+    }
+
+    function evaluateTyped(typedValue, typedType, baseMsg, fallback) {
+      try {
+        return REDUtil.evaluateNodeProperty(typedValue, typedType || 'bool', node, baseMsg);
+      } catch (error) {
+        return fallback;
+      }
+    }
+
+    function updateStatus(lastValue) {
+      const direction = mode === 'low' ? 'LOW' : 'HIGH';
+      const valueText = lastValue === undefined ? '-' : Number(lastValue).toFixed(2);
+      setNodeStatus({
+        fill: state ? 'green' : 'grey',
+        shape: state ? 'dot' : 'ring',
+        text: `${direction} ${valueText} on:${onThreshold} off:${offThreshold}`,
+      });
+    }
+
+    function evaluateState(value) {
+      let nextState = state;
+      if (mode === 'low') {
+        if (value <= onThreshold) {
+          nextState = true;
+        } else if (value >= offThreshold) {
+          nextState = false;
+        }
+      } else {
+        if (value >= onThreshold) {
+          nextState = true;
+        } else if (value <= offThreshold) {
+          nextState = false;
+        }
+      }
+      return nextState;
+    }
+
+    function emitDiagnostics(baseMsg, payload) {
+      const msg = baseMsg ? REDUtil.cloneMessage(baseMsg) : {};
+      msg.topic = `${controlTopic}/event`;
+      msg.payload = payload;
+      node.send([null, msg]);
+    }
+
+    function emitState(baseMsg, changed, inputValue) {
+      if (!changed && emitOnlyOnChange) {
+        updateStatus(inputValue);
+        return;
+      }
+      const msg = baseMsg ? REDUtil.cloneMessage(baseMsg) : {};
+      msg.payload = state
+        ? evaluateTyped(config.onPayload, config.onPayloadType, baseMsg, true)
+        : evaluateTyped(config.offPayload, config.offPayloadType, baseMsg, false);
+      msg.hysteresis = {
+        state,
+        changed,
+        mode,
+        value: inputValue,
+        onThreshold,
+        offThreshold,
+      };
+      msg.event = changed ? 'state_changed' : 'state_confirmed';
+      node.send([msg, null]);
+      updateStatus(inputValue);
+    }
+
+    function handleControl(msg) {
+      let consumed = false;
+
+      if (msg.reset === true) {
+        state = Boolean(config.initialState);
+        emitDiagnostics(msg, {
+          event: 'reset',
+          state,
+          onThreshold,
+          offThreshold,
+          mode,
+        });
+        consumed = true;
+      }
+
+      if (Object.prototype.hasOwnProperty.call(msg, 'onThreshold')) {
+        const next = Number(msg.onThreshold);
+        if (Number.isFinite(next)) {
+          onThreshold = next;
+          consumed = true;
+        }
+      }
+
+      if (Object.prototype.hasOwnProperty.call(msg, 'offThreshold')) {
+        const next = Number(msg.offThreshold);
+        if (Number.isFinite(next)) {
+          offThreshold = next;
+          consumed = true;
+        }
+      }
+
+      if (Object.prototype.hasOwnProperty.call(msg, 'state')) {
+        state = Boolean(msg.state);
+        emitState(msg, true, undefined);
+        consumed = true;
+      }
+
+      if (msg.status === true) {
+        emitDiagnostics(msg, {
+          event: 'status',
+          state,
+          mode,
+          onThreshold,
+          offThreshold,
+        });
+        consumed = true;
+      }
+
+      if (consumed) {
+        updateStatus();
+      }
+
+      return consumed;
+    }
+
+    node.on('input', (msg) => {
+      if (msg.topic === controlTopic && handleControl(msg)) {
+        return;
+      }
+
+      const resolved = helpers.resolveInput(msg, payloadPropName, config.translatorConfig, RED);
+      const inputValue = toNumber(resolved.value);
+
+      if (inputValue === undefined) {
+        emitDiagnostics(msg, {
+          event: 'invalid_input',
+          value: resolved.value,
+          property: payloadPropName,
+        });
+        return;
+      }
+
+      const nextState = evaluateState(inputValue);
+      const changed = nextState !== state;
+      state = nextState;
+      emitState(msg, changed, inputValue);
+
+      if (changed) {
+        emitDiagnostics(msg, {
+          event: 'state_changed',
+          state,
+          value: inputValue,
+          mode,
+          onThreshold,
+          offThreshold,
+        });
+      }
+    });
+
+    updateStatus();
+  }
+
+  RED.nodes.registerType('HysteresisUltimate', HysteresisUltimate);
+};

package/boolean-logic-ultimate/RateLimiterUltimate.html

@@ -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**
@@ -161,4 +161,4 @@ The purpose of this node is to moderate the frequency of incoming messages.
 - `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>
+</script>

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/HysteresisUltimate.json

@@ -0,0 +1,109 @@
+[
+  {
+    "id": "hys-flow",
+    "type": "tab",
+    "label": "HysteresisUltimate"
+  },
+  {
+    "id": "hys-node",
+    "type": "HysteresisUltimate",
+    "z": "hys-flow",
+    "name": "Bathroom Humidity",
+    "controlTopic": "hysteresis",
+    "payloadPropName": "payload",
+    "translatorConfig": "",
+    "mode": "high",
+    "onThreshold": 70,
+    "offThreshold": 62,
+    "initialState": false,
+    "emitOnlyOnChange": true,
+    "onPayload": "on",
+    "onPayloadType": "str",
+    "offPayload": "off",
+    "offPayloadType": "str",
+    "x": 520,
+    "y": 200,
+    "wires": [["hys-out"], ["hys-diag"]]
+  },
+  {
+    "id": "hys-in-1",
+    "type": "inject",
+    "z": "hys-flow",
+    "name": "Humidity 68",
+    "props": [
+      { "p": "payload", "v": "68", "vt": "num" },
+      { "p": "topic", "v": "sensor/bathroom/humidity", "vt": "str" }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 260,
+    "y": 160,
+    "wires": [["hys-node"]]
+  },
+  {
+    "id": "hys-in-2",
+    "type": "inject",
+    "z": "hys-flow",
+    "name": "Humidity 72",
+    "props": [
+      { "p": "payload", "v": "72", "vt": "num" },
+      { "p": "topic", "v": "sensor/bathroom/humidity", "vt": "str" }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 260,
+    "y": 200,
+    "wires": [["hys-node"]]
+  },
+  {
+    "id": "hys-in-3",
+    "type": "inject",
+    "z": "hys-flow",
+    "name": "Humidity 60",
+    "props": [
+      { "p": "payload", "v": "60", "vt": "num" },
+      { "p": "topic", "v": "sensor/bathroom/humidity", "vt": "str" }
+    ],
+    "repeat": "",
+    "crontab": "",
+    "once": false,
+    "onceDelay": 0.1,
+    "x": 260,
+    "y": 240,
+    "wires": [["hys-node"]]
+  },
+  {
+    "id": "hys-out",
+    "type": "debug",
+    "z": "hys-flow",
+    "name": "HA Fan Command",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "true",
+    "targetType": "full",
+    "x": 780,
+    "y": 180,
+    "wires": []
+  },
+  {
+    "id": "hys-diag",
+    "type": "debug",
+    "z": "hys-flow",
+    "name": "Diagnostics",
+    "active": true,
+    "tosidebar": true,
+    "console": false,
+    "tostatus": false,
+    "complete": "payload",
+    "targetType": "msg",
+    "x": 760,
+    "y": 240,
+    "wires": []
+  }
+]

package/examples/README.md

@@ -8,11 +8,12 @@ How to import:
 
 ## Available example flows
 
-- `AlarmSystemUltimate.json` — Alarm System Ultimate (BETA)
 - `BlinkerUltimate.json` — BlinkerUltimate
 - `BooleanLogicUltimate.json` — BooleanLogicUltimate
 - `Comparator.json` — Comparator
+- `DebouncerUltimate.json` — DebouncerUltimate
 - `FilterUltimate.json` — FilterUltimate
+- `HysteresisUltimate.json` — HysteresisUltimate
 - `ImpulseUltimate.json` — ImpulseUltimate
 - `InjectUltimate.json` — InjectUltimate
 - `InterruptFlowUltimate.json` — InterruptFlowUltimate
@@ -27,4 +28,3 @@ How to import:
 - `SumUltimate.json` — SumUltimate
 - `toggleUltimate.json` — toggleUltimate
 - `translator-config.json` — translator-config
-

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "node-red-contrib-boolean-logic-ultimate",
-    "version": "1.2.8",
-    "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.11",
+    "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",
@@ -45,10 +46,11 @@
             "RateLimiterUltimate": "boolean-logic-ultimate/RateLimiterUltimate.js",
             "PresenceSimulatorUltimate": "boolean-logic-ultimate/PresenceSimulatorUltimate.js",
             "StaircaseLightUltimate": "boolean-logic-ultimate/StaircaseLightUltimate.js",
+            "HysteresisUltimate": "boolean-logic-ultimate/HysteresisUltimate.js",
             "translator-config": "boolean-logic-ultimate/translator-config.js"
         }
     },
     "scripts": {
         "test": "mocha test/**/*.spec.js"
     }
-}
+}