node-red-contrib-stoptimer-varidelay-plus 0.5.4

package/stoptimer-varidelay/stoptimer-varidelay.html

@@ -0,0 +1,230 @@
+<!--
+  Modifications copyright (C) 2020 hamsando
+  Copyright jbardi
+
+  Modifications copyright (C) 2025 mchristegh
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+<script type="text/javascript">
+    RED.nodes.registerType('stoptimer-varidelay',{
+        category: 'function',
+        color:"#869869",
+        defaults: {
+            duration: {value:"5",required:true,validate:RED.validators.typedInput("durationType")},
+            durationType: {value:'num'},
+            units: {value:"Second"},
+            payloadtype: {value:'num'},
+            payloadval: {value:"0"},
+            name: {value:""},
+            reporting: {value:"none"},
+            reportingformat: {value:"human"},
+            persist: {value:false},
+            ignoretimerpass: {value:false},
+            donotresettimer: {value:false}
+        },
+        inputs:1,
+        outputs:4,
+        icon: "stoptimer.png",
+        label: function() {
+            return this.name || this.duration + " " + this.units + " Timer";
+        },
+        labelStyle: function() {
+            return this.name?"node_label_italic":"";
+        },
+        outputLabels: ["Original Payload","Additional Payload","Time Remaining","Ignored Message"],
+        oneditprepare: function() {
+            $("#node-input-payloadval").typedInput({
+                default: 'num',
+                typeField: $("#node-input-payloadtype"),
+                types:['str','num','bool']
+            });
+
+            if (this.durationType == null) {
+                this.durationType = "num";
+            }
+
+            $("#node-input-durationType").val(this.durationType);
+
+            $("#node-input-duration").typedInput({
+                default: 'num',
+                typeField: $("#node-input-durationType"),
+                types:['num','env']
+            });
+
+            $("#node-input-duration").typedInput('type', this.durationType);
+
+            $("#node-input-reporting").val(this.reporting);
+            $("#node-input-reportingformat").val(this.reportingformat);
+        }
+    });
+</script>
+
+<script type="text/x-red" data-template-name="stoptimer-varidelay">
+    <div class="form-row">
+        <i class="fa fa-clock-o"></i>
+        <label for="node-input-duration"> Timer</label>
+        <input type="hidden" id="node-input-durationType">
+        <input type="text" id="node-input-duration" style="text-align:end; width:270px !important">
+    </div>
+    <div class="form-row">
+        <i class="fa fa-bars"></i>
+        <label for="node-input-units"> Units</label>
+        <select id="node-input-units">
+            <option value="Millisecond">Milliseconds</option>
+            <option value="Second">Seconds</option>
+            <option value="Minute">Minutes</option>
+            <option value="Hour">Hours</option>
+        </select>
+    </div>
+    <div class="form-row">
+        <i class="fa fa-heartbeat"></i>
+        <label for="node-input-reporting"> Reporting</label>
+        <select id="node-input-reporting">
+            <option value="none">Never</option>
+            <option value="every_second">Every Second</option>
+            <option value="last_minute_seconds">Every Minute, Last minute by seconds</option>
+        </select>
+    </div>
+    <div class="form-row">
+        <label for="node-input-reportingformat"> Reporting format</label>
+        <select id="node-input-reportingformat">
+            <option value="human">HH:MM:SS</option>
+            <option value="seconds">Seconds</option>
+            <option value="minutes">Minutes</option>
+            <option value="hours">Hours</option>
+        </select>
+    </div>
+    <div class="form-row">
+        <i class="fa fa-floppy-o"></i>
+        <label style="width:auto" for="node-input-persist"> Resume timer on deploy/restart</label>
+        <input type="checkbox" id="node-input-persist" style="display:inline-block; width:auto; vertical-align:top;">
+    </div>
+    <div class="form-row">
+        <i class="fa fa-recycle"></i>
+        <label style="width:auto" for="node-input-ignoretimerpass"> Ignore incoming _timerpass</label>
+        <input type="checkbox" id="node-input-ignoretimerpass" style="display:inline-block; width:auto; vertical-align:top;">
+    </div>
+    <div class="form-row">
+        <i class="fa fa-lock"></i>
+        <label style="width:auto" for="node-input-donotresettimer"> Do Not Reset Timer on Subsequent Incoming Message</label>
+        <input type="checkbox" id="node-input-donotresettimer" style="display:inline-block; width:auto; vertical-align:top;">
+    </div>
+    <div class="form-row">
+        <i class="fa fa-envelope"></i>
+        <label for="node-input-payloadtype"> 2nd Payload</label>
+        <input type="hidden" id="node-input-payloadtype">
+        <input style="width: 70%" type="text" id="node-input-payloadval">
+    </div>
+    <div class="form-row">
+        <i class="fa fa-tag"></i>
+        <label for="node-input-name"> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name"></input>
+    </div>
+</script>
+
+<script type="text/x-red" data-help-name="stoptimer-varidelay">
+    <p><B>General usage</B><br>
+       Sends the <code>msg</code> through the first output after the set timer duration. If a new <code>msg</code> is received before the timer has ended, it will replace the existing <code>msg</code> and the timer will be restarted, unless the new <code>msg</code> has a <code>payload</code> of <code>stop</code>, <code>STOP</code>, <code>pause</code>, <code>PAUSE</code>, <code>resume</code>, or <code>RESUME</code>. The second output allows you to send an additional payload of a number, string or boolean. If the timer is stopped, the second and third outputs will automatically send a payload of <code>stopped</code>. The third output will send the time remaining as time ticks away.
+    <br><br>The status below the node as well as the third output can be configured via the <I>Reporting</I> field in the node to update at a frequency of:
+        <ul>
+          <li>Never (default)</li>
+          <li>Every Second</li>
+          <li>Every Minute, Last minute by seconds</li>
+        </ul>
+        The last option works as follows:
+        <ul>
+          <li>While there is more than 1 minute remaining, the timer will decrement every minute. At the 1 minute point, it will switch to reporting every second.</li>
+          <li>The exception to this rule is if your duration is not a minute increment. In that case, the first update will be for the partial minute, after which it will operate as noted above. (for example: 2.5 minutes will decrement to 2 minutes, then 1 minute, then every second down to zero)</li>
+        </ul>
+    </p>
+    <p>
+      The format of the reporting (and status) are defined by the "Reporting Format" option. The default is hh:mm:ss (string), but it can be configured to present that as the total number of seconds, minutes or hours (number) instead.
+    </p>
+    <p><B>Message properties on all outputs</B><br>
+      All output messages include the following additional properties:
+      <ul>
+        <li><code>msg.timerState</code> — the current state of the timer: <code>running</code>, <code>paused</code>, <code>stopped</code>, or <code>expired</code></li>
+        <li><code>msg.timerDuration</code> — the original timer duration in milliseconds</li>
+        <li><code>msg.elapsedTime</code> — the elapsed time in milliseconds (outputs 1, 2, and 3)</li>
+        <li><code>msg.remainingTime</code> — the remaining time in milliseconds (outputs 3 and 4)</li>
+      </ul>
+    </p>
+    <p><B>Overriding the node via incoming messages</B><br>
+      If the input contains <code>msg.delay</code>, then the delay will be <code>msg.delay</code> units of time, where the units are whatever the units are defaulted to in the node itself. In the absence of a <code>msg.delay</code>, or a value in <code>msg.delay</code> that cannot be converted to an int, the value configured within the node will be used. If the value of <code>msg.delay</code> is less than 0, then 0 is used.
+    </p>
+    <p>
+      If the input contains <code>msg.units</code>, with a value of "Milliseconds", "Seconds", "Minutes" or "Hours" then that will override what is defaulted in the node. In the absence of a <code>msg.units</code>, or an unknown string in <code>msg.units</code>, the units configured within the node will be used. In the case of an unknown string, a warning message will appear in the Debug logs.
+    </p>
+    <p><b>Pausing and Resuming</b><br>
+      The timer can be paused by sending a message with <code>msg.payload</code> of <code>pause</code> or <code>PAUSE</code>. While paused:
+      <ul>
+        <li>The countdown is frozen at the remaining time</li>
+        <li>The node status shows <code>Paused: HH:MM:SS</code> with a yellow indicator</li>
+        <li>Outputs 2 and 3 will send a payload of <code>paused</code></li>
+        <li>Any incoming message other than <code>resume</code>, <code>RESUME</code>, <code>stop</code>, or <code>STOP</code> will be routed to output 4</li>
+        <li>Sending another <code>pause</code> message while already paused will also be routed to output 4</li>
+      </ul>
+      The timer can be resumed by sending a message with <code>msg.payload</code> of <code>resume</code> or <code>RESUME</code>. On resume:
+      <ul>
+        <li>The countdown restarts from where it was frozen</li>
+        <li>Outputs 2 and 3 will send a payload of <code>resumed</code></li>
+      </ul>
+      If the <i>Resume timer on deploy/restart</i> option is enabled and the timer is paused when Node-RED restarts or the flow is redeployed, the timer will restore as paused at the same remaining time.
+    </p>
+    <p><b>Special Note on Milliseconds</b><br>
+      While you can set Milliseconds, I would not rely on the accuracy for anything critical. For the purposes of the node status and output 3, except in the case where Reporting is set to None, the milliseconds are not displayed or provided on the 3rd output as it wouldn't make sense based on the available reporting rates.
+    </p>
+    <p><b>Resume timer on deploy/restart</b><br>
+      This option is <b>DISABLED</b> by default. If you <i>ENABLE</i> it (check the checkbox) then if the stoptimer is running and you re-Deploy the flow, or restart Node-RED, then the timer will automatically restart itself where it should be. What does that mean? A couple of examples will help here.
+      <ul>
+        <li>If you had a 10 minute stoptimer running, with 6 minutes elapsed (ie: 4 minutes left) and you hit Deploy, normally the stoptimer would no longer be running, but if you have this feature enabled, the timer will continue running from the 6 minute mark (ie: counting down 4 more minutes and then trigger).</li>
+        <li>If you had a 10 minute stoptimer running, with 6 minutes elapsed (ie: 4 minutes left) and you <i>stopped</i> Node-RED for 2 minutes and then restarted it, normally the stoptimer would no longer be running, but if you have this feature enabled, the timer will continue running from the 8 minute mark (6 minutes from the original run + 2 minutes of Node-RED downtime) -- counting down 2 more minutes and then trigger.</li>
+        <li><b>Special Case</b> If on restart or re-Deploy, there is less than 3 seconds remaining on the stoptimer (or if the stoptimer should have elapsed already) then the stoptimer is set to a random amount between 3 and 8 seconds. This helps to ensure that anything else that needs to initialize before the stoptimer triggers has a chance to do so. It also helps so that if you happen to have a lot of timers, they don't all trigger at once and flood unsuspecting nodes/devices.</li>
+      </ul>
+      <br>
+      This persistence is <b>not</b> related to "Persistent Context" (the contextStorage option in <code>settings.js</code>). When the "Resume timer" option is enabled in the node, the node will store timer related information in a <code>stvd-timers</code> subdirectory of <i>userDir</i> (where <i>userDir</i> is defined in <code>settings.js</code>). If <i>userDir</i> is not explicitly defined, it defaults to a directory called <code>.node-red</code> in your home user directory. The files in this directory will be created/destroyed as needed by the node.
+    </p>
+    <p><b>What is <code>_timerpass</code></b><br>
+      <code>_timerpass</code> is a property added to messages exiting the 1st/top and 2nd/middle outputs of stoptimer.
+      <code>_timerpass</code> is set to <code>true</code> when the timer expires.
+      <br><br>
+      <b>What does <code>_timerpass</code> do?</b><br>
+      If stoptimer has at any point been stopped using message.payload=stop (or STOP) AND <br>
+      If stoptimer has not received a message with _timerpass not set since that time THEN <br>
+      any incoming message that has the _timerpass=true property will die within stoptimer with no output.
+      <br><br>
+      This can be problematic if you want to chain multiple stoptimers together. It is not insurmountable, but it can be irritating.
+      <br><br>
+      <b>Why does this behavior exist?</b><br>
+      It is a legacy thing, it was part of the original stoptimer whose code I forked. Not sure what exactly the original intent was, but I'm sure there is some rationale.
+      <br><br>
+      <b>How does Stoptimer-Varidelay handle this?</b><br>
+      <i>Ignore Timerpass</i> in the node config dialog. If enabled in a given stoptimer-varidelay node, it will ignore the presence of the <code>_timerpass</code> property on an incoming message and will process the incoming message as it does every other message.
+      By default, this option is not enabled in order to preserve compatibility with any existing flows. Note that you may need to refresh the web UI after updating the node in order to see the new "ignore timerpass" option.
+    </p>
+    <p><b>Do Not Reset Timer on Subsequent Incoming Message</b><br>
+      This option is <b>DISABLED</b> by default. If you <i>ENABLE</i> it (check the checkbox) then while the timer is running, any subsequent incoming messages (other than <code>stop</code>, <code>STOP</code>, <code>pause</code>, <code>PAUSE</code>, <code>resume</code>, or <code>RESUME</code>) will be ignored and the timer will continue running undisturbed. The first message always starts the timer normally.
+      <br><br>
+      When a message is ignored, it will be sent to the 4th output with the original message content intact plus:
+      <ul>
+        <li><code>msg.remainingTime</code> — remaining time in milliseconds</li>
+        <li><code>msg.timerState</code> — current timer state</li>
+      </ul>
+      When this option is enabled, the node status will show:<br>
+      <code>Remaining: 00:04:32 | Ignored: 3, Last: Jun 27 14:22:05</code>
+      <br><br>
+      The ignored count and last ignored datetime will reset each time a new message starts the timer. They will remain visible on the status after the timer expires or is stopped, so you can see how many messages were ignored during that timer run.
+    </p>
+</script>