smart-nodes 0.3.36 → 0.4.0

package/shutter/locales/en-US/shutter.html

@@ -0,0 +1,133 @@
+<script type="text/html" data-help-name="smart_shutter-control">
+    <p>
+        <b>Note:</b> Smart Nodes use topics in the format <code>name#number</code>, so that different Smart Nodes can be controlled with the same topic.<br />
+        This node only uses the part <code>name</code>. <code>#</code> and <code>number</code> are optional.
+    </p>
+    <p>
+        This node controls roller shutters or blinds. There are 3 outputs that can be controlled:
+    <ol>
+        <li><b>Up/Down:</b> <code>msg.payload = false</code> moves the roller shutter up and <code>msg.payload = true</code> moves the roller shutter down.</li>
+        <li><b>Stop:</b> <code>msg.payload = true</code> stops the roller shutter.</li>
+        <li><b>Position:</b> <code>msg.payload = 42</code> Moves the roller shutter to 42%.</li>
+    </ol>
+    The outputs are assigned to the respective KNX group addresses.
+    </p>
+    <p>
+        This node expects the following topics as input:<br />
+        <table>
+            <thead>
+                <tr>
+                    <th>Topic</th>
+                    <th>Description</th>
+                    <th>msg.payload == false is ignored</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td><code>status</code> or <code>status_position</code></td>
+                    <td>
+                        The node reports the current position.
+                        This allows the node to determine in which direction a roller shutter last moved.
+                        This is required for the topic <b>toggle</b> to determine the next direction of travel for a 1-button
+                        operation.
+                    </td>
+                </tr>
+                <tr>
+                    <td><code>up_down</code></td>
+                    <td>
+                        Receives a command from Home Assistant to be informed whether the roller shutter is running and in which
+                        direction.<br />
+                        <strong>Important:</strong> This topic <u>does not</u> start the roller shutter, as the group address
+                        must be directly connected to the blind module.
+                    </td>
+                    <td>No</td>
+                </tr>
+                <tr>
+                    <td><code>short_up_down</code></td>
+                    <td>
+                        Sends a short up command if <code>msg.payload = false</code> and a short down command if
+                        <code>msg.payload = true</code>.<br />
+                        The time stored in the module is used. However, this can be overwritten once by setting
+                        <code>msg.time_on = 1500</code> or <code>msg.time_on = "1.5s"</code>.
+                    </td>
+                    <td>No</td>
+                </tr>
+                <tr>
+                    <td><code>up</code></td>
+                    <td>Sends a command to raise the roller shutter if it is not already moving up. If necessary, a stop command
+                        is sent beforehand.</td>
+                    <td>Yes</td>
+                </tr>
+                <tr>
+                    <td><code>up_stop</code></td>
+                    <td>Sends a stop and an up command alternately.</td>
+                    <td>Yes</td>
+                </tr>
+                <tr>
+                    <td><code>down</code></td>
+                    <td>Sends a down command if the roller shutter is not already moving down. If necessary, a stop command is
+                        sent beforehand.</td>
+                    <td>Yes</td>
+                </tr>
+                <tr>
+                    <td><code>down_stop</code></td>
+                    <td>Sends a stop and a down command alternately.</td>
+                    <td>Yes</td>
+                </tr>
+                <tr>
+                    <td><code>stop</code></td>
+                    <td>Sends a stop command.</td>
+                    <td>Yes</td>
+                </tr>
+                <tr>
+                    <td><code>position</code></td>
+                    <td>Sends a position command. <code>msg.payload</code> should have a value between 0 (open) and 100
+                        (closed).</td>
+                    <td>No</td>
+                </tr>
+                <tr>
+                    <td><code>toggle</code> (default)</td>
+                    <td>Switches the roller shutter alternately to up, stop, down, stop.</td>
+                    <td>Yes</td>
+                </tr>
+            </tbody>
+        </table>
+    </p>
+    <p>
+        This node does not manage a running time for the roller shutter itself. This must be configured for the output via ETS.
+        However, it is possible to switch the roller shutter off automatically after a defined time.
+        However, it is possible to switch the roller shutter off automatically after a defined time.
+        Example: <code>msg = { "topic": "up", "time_on": 5000 }</code> or <code>msg = { "topic": "up", "time_on": "5s" }</code><br />
+        This message causes the roller shutter to move up for 5000 milliseconds / 5 seconds. If it is a Venetian blind, the slats are rotated accordingly.
+        The following values can be used as a unit for time:
+        <table>
+            <thead>
+                <tr>
+                    <th>Unit</th>
+                    <th>Description</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td><code>ms</code> (default)</td>
+                    <td>Milliseconds</td>
+                </tr>
+                <tr>
+                    <td><code>s</code> or <code>sec</code></td>
+                    <td>Seconds</td>
+                </tr>
+                <tr>
+                    <td><code>m</code> or <code>min</code></td>
+                    <td>Mintun.</td>
+                </tr>
+                <tr>
+                    <td><code>h</code></td>
+                    <td>Hours</td>
+                </tr>
+            </tbody>
+        </table>
+    </p>
+    <p>
+        Specifying a time does not work with the topic <b>position</b>.
+    </p>
+</script>

package/shutter/locales/en-US/shutter.json

@@ -0,0 +1,11 @@
+{
+    "shutter": {
+        "ui": {
+            "name": "Name",
+            "text": "Text",
+            "controlled_by_words": "This node can be controlled using the words entered. Multiple words are separated by a comma.",
+            "time_short": "Time short",
+            "controlled_by_central": "This module is controlled by the following central modules:"
+        }
+    }
+}

package/{shutter-control/shutter-control.html → shutter/shutter.html}

@@ -153,6 +153,7 @@
             oneditprepare: function ()
             {
                 let node = this;
+
                 onEditPrepare(this, ["smart_central-control"]);
                 initTreeList(node, ["smart_central-control"]);
 
@@ -180,145 +181,18 @@
 
 <script type="text/html" data-template-name="smart_shutter-control">
     <div class="form-row">
-        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
-        <input type="text" id="node-input-name" placeholder="Name" />
+        <label for="node-input-name"><i class="fa fa-tag"></i> <span data-i18n="shutter.ui.name"></span></label>
+        <input type="text" id="node-input-name" data-i18n="[placeholder]shutter.ui.name" />
     </div>
     <div class="form-row">
-        <label for="node-input-exec_text_names"><i class="fa fa-comments-o"></i> Text</label>
+        <label for="node-input-exec_text_names"><i class="fa fa-comments-o"></i> <span data-i18n="shutter.ui.text"></span></label>
         <input id="node-input-exec_text_names" type="text" />
-        <div style="max-width: 450px;">Diese Node kann über die eingegebenen Wörter gesteuert werden. Mehrere Wörter werden durch ein Komma getrennt.</div>
+        <div style="max-width: 450px;" data-i18n="shutter.ui.controlled_by_words"></div>
     </div>
     <div class="form-row">
-        <label for="node-input-short_time_on_ms"><i class="fa fa-clock-o"></i> Zeit kurz</label>
+        <label for="node-input-short_time_on_ms"><i class="fa fa-clock-o"></i> <span data-i18n="shutter.ui.time_short"></span></label>
         <input id="node-input-short_time_on_ms" placeholder="200" /> ms
     </div>
-    <span><i class="fa fa-link"></i>Dieser Baustein wird von folgenden Zentralbausteinen gesteuert:</span>
+    <span><i class="fa fa-link"></i> <span data-i18n="shutter.ui.controlled_by_central"></span></span>
     <div class="form-row node-input-link-row node-input-link-rows"></div>
-</script>
-
-<script type="text/html" data-help-name="smart_shutter-control">
-    <p>
-        <b>Hinweis:</b> Smart Nodes verwenden Topics im Format <code>name#nummer</code>, damit können verschiedene Smart Nodes mit dem gleichen Topic angesteuert werden.<br/>
-        Diese Node verwendet nur den Teil <code>name</code>. <code>#</code> und <code>nummer</code> sind dabei optional.
-    </p>
-    <p>
-        Diese Node steuert Rollladen oder Jalousien.
-        Es gibt 3 Ausgänge die angesteuert werden können:
-        <ol>
-            <li><b>Auf/Ab:</b> <code>msg.payload = false</code> lässt den Rollladen nach oben fahren und <code>msg.payload = true</code> lässt den Rollladen nach unten fahren.</li>
-            <li><b>Stop:</b> <code>msg.payload = true</code> lässt den Rollladen stoppen.</li>
-            <li><b>Position:</b> <code>msg.payload = 42</code> Lässt den Rollladen auf 42% fahren.</li>
-        </ol>
-        Die Ausgänge sind den jeweiligen KNX Gruppenadressen zuzuordnen.
-    </p>
-    <p>
-        Diese Node erwartet folgende Topics als Eingang:<br/>
-        <table>
-            <thead>
-                <tr>
-                    <th>Topic</th>
-                    <th>Beschreibung</th>
-                    <th>msg.payload == false wird ignoriert</th>
-                </tr>
-            </thead>
-            <tbody>
-                <tr>
-                    <td><code>status</code> oder <code>status_position</code></td>
-                    <td>
-                        Meldet der Node die aktuelle Position.
-                        Dadurch kann die Node feststellen in welche Richtung ein Rollladen als letztes gefahren ist.
-                        Dies wird für das topic <b>toggle</b> benötigt um die nächste Laufrichtung bei einer 1-Tasten Bedienung zu ermitteln.
-                    </td>
-                </tr>
-                <tr>
-                    <td><code>up_down</code></td>
-                    <td>
-                        Nimmt einen Befehl von Home Assistant entgegen um informiert zu werden ob der Rollladen läuft und in welche Richtung.<br/>
-                        <strong>Wichtig:</strong> Dieses Topic startet den Rollladen <u>nicht</u>, da die Gruppenadresse direkt mit dem Jalousiemodul verbunden sein muss.
-                    </td>
-                    <td>Nein</td>
-                </tr>
-                <tr>
-                    <td><code>short_up_down</code></td>
-                    <td>
-                        Sendet bei <code>msg.payload = false</code> einen kurzen Hochfahrbefehl und bei <code>msg.payload = true</code> einen kurzen Runterfahrbefehl.<br/>
-                        Es wird dabei die im Baustein hinterlegte Zeit verwendet. Diese kann aber durch setzen von <code>msg.time_on = 1500</code> oder <code>msg.time_on = "1.5s"</code> einmalig überschrieben werden.
-                    </td>
-                    <td>Nein</td>
-                </tr>
-                <tr>
-                    <td><code>up</code></td>
-                    <td>Sendet einen Hochfahrbefehl, falls der Rollladen nicht bereits nach oben fährt. Ggf. wird vorher noch ein Stop-Befehl gesendet.</td>
-                    <td>Ja</td>
-                </tr>
-                <tr>
-                    <td><code>up_stop</code></td>
-                    <td>Sendet abwechselnd einen Stop- und einen Hochfahrbefehl.</td>
-                    <td>Ja</td>
-                </tr>
-                <tr>
-                    <td><code>down</code></td>
-                    <td>Sendet einen Runterfahrbefehl, falls der Rollladen nicht bereits nach unten fährt. Ggf. wird vorher noch ein Stop-Befehl gesendet.</td>
-                    <td>Ja</td>
-                </tr>
-                <tr>
-                    <td><code>down_stop</code></td>
-                    <td>Sendet abwechselnd einen Stop- und einen Runterfahrbefehl.</td>
-                    <td>Ja</td>
-                </tr>
-                <tr>
-                    <td><code>stop</code></td>
-                    <td>Sendet einen Stopbefehl.</td>
-                    <td>Ja</td>
-                </tr>
-                <tr>
-                    <td><code>position</code></td>
-                    <td>Sendet einen Positionsbefehl. <code>msg.payload</code> sollte ein Wert zwischen 0 (offen) und 100 (geschlossen) haben.</td>
-                    <td>Nein</td>
-                </tr>
-                <tr>
-                    <td><code>toggle</code> (default)</td>
-                    <td>Schaltet den Rollladen abwechselnd auf hoch, stop, runter, stop.</td>
-                    <td>Ja</td>
-                </tr>
-            </tbody>
-        </table>
-    </p>
-    <p>
-        Diese Node verwaltet keine Laufzeit für den Rollladen selbst. Diese muss über ETS für den Ausgang konfiguriert werden.
-        Es ist jedoch möglich, den Rollladen nach einer definierten Zeit automatisch abzuschalten.
-        Es ist jedoch möglich, den Rollladen nach einer definierten Zeit automatisch abzuschalten.
-        Beispiel: <code>msg = { "topic": "up", "time_on": 5000 }</code> oder <code>msg = { "topic": "up", "time_on": "5s" }</code><br/>
-        Diese Nachricht lässt den Rollladen für 5000 Millisekunden / 5 Sekunden nach oben fahren. Sollte es sich um eine Jalousie halten, werden die Lamellen entsprechend gedreht.
-        Als Einheit für die Zeit können folgende Werte verwendet werden:
-        <table>
-            <thead>
-                <tr>
-                    <th>Einheit</th>
-                    <th>Beschreibung</th>
-                </tr>
-            </thead>
-            <tbody>
-                <tr>
-                    <td><code>ms</code> (default)</td>
-                    <td>Millisekunden</td>
-                </tr>
-                <tr>
-                    <td><code>s</code> oder <code>sec</code></td>
-                    <td>Sekunden</td>
-                </tr>
-                <tr>
-                    <td><code>m</code> oder <code>min</code></td>
-                    <td>Mintun.</td>
-                </tr>
-                <tr>
-                    <td><code>h</code></td>
-                    <td>Stunden</td>
-                </tr>
-            </tbody>
-        </table>
-    </p>
-    <p>
-        Die Angabe einer Zeit funktioniert nicht mit dem topic <b>position</b>.
-    </p>
 </script>

package/{shutter-control/shutter-control.js → shutter/shutter.js}

@@ -7,29 +7,57 @@ module.exports = function (RED)
         const node = this;
         RED.nodes.createNode(node, config);
 
+        // ###################
+        // # Class constants #
+        // ###################
+
+
+        // #######################
+        // # Global help objects #
+        // #######################
         const smart_context = require("../persistence.js")(RED);
         const helper = require("../smart_helper.js");
 
-        // used from text-exec node
+
+        // ############################
+        // # Used from text-exec node #
+        // ############################
         if (typeof config.exec_text_names == "string")
             node.exec_text_names = config.exec_text_names.split(",").map(n => n.trim().toLowerCase());
         else
             node.exec_text_names = [];
 
-        // persistent values
-        var node_settings = Object.assign({}, {
+
+        // #####################
+        // # persistent values #
+        // #####################
+        var node_settings = helper.cloneObject({
             last_position: 0,        // 0 = opened, 100 = closed
             last_direction_up: true, // remember last direction for toggle action
         }, smart_context.get(node.id));
 
-        // dynamic config
-        let short_time_on_ms = config.short_time_on_ms || 200;
 
-        // runtime values
-        let is_running = false;         // remember if shutter is running, this is only recognized when starting within this control or position 0% or 100% is reached.
-        let max_time_on_timeout = null; // save timeout value to cancel auto timeout if needed
+        // ##################
+        // # Dynamic config #
+        // ##################
+        let short_time_on_ms = parseInt(config.short_time_on_ms || 200, 10);
+
+
+        // ##################
+        // # Runtime values #
+        // ##################
+
+        // Here the setTimeout return value is stored to stop the shutter.
+        // That means if it is null, the shutter is stopped.
+        let timeout = null;
+
+        // This is set to true if a command to start the shutter is recognized.
+        let is_running = false;
+
 
-        // central handling
+        // #########################
+        // # Central node handling #
+        // #########################
         var event = "node:" + config.id;
         var handler = function (msg)
         {
@@ -37,43 +65,58 @@ module.exports = function (RED)
         }
         RED.events.on(event, handler);
 
-        node.status({ fill: "red", shape: "dot", text: helper.getCurrentTimeForStatus() + ": Stopped at " + Math.round(node_settings.last_position) + "%" });
 
+        // ###############
+        // # Node events #
+        // ###############
         node.on("input", function (msg)
         {
             handleTopic(msg);
 
+            setStatus();
             smart_context.set(node.id, node_settings);
         });
 
         node.on("close", function ()
         {
-            stopAutoOff();
+            startAction(ACTION_STOP);
             RED.events.off(event, handler);
         });
 
+
+        // #####################
+        // # Private functions #
+        // #####################
+
+        // This is the main function which handles all topics that was received.
         let handleTopic = msg =>
         {
+            helper.log("handle topic:");
+            helper.log(msg);
+
             var resultUpDown = null;
             var resultStop = null;
             var resultPosition = null;
 
-            var real_topic = helper.getTopicName(msg.topic);
-
-            // set default topic
-            if (!["status", "status_position", "up_down", "up", "up_stop", "down", "down_stop", "stop", "toggle", "position", "short_up_down"].includes(real_topic))
-                real_topic = "toggle";
+            let real_topic = helper.getRealTopic(msg.topic, "toggle", ["status", "status_position", "up_down", "up", "up_stop", "down", "down_stop", "stop", "toggle", "position", "short_up_down"]);
 
             // skip if button is released
             if (msg.payload === false && ["up", "up_stop", "down", "down_stop", "stop", "toggle"].includes(real_topic))
                 return;
 
             // Correct next topic to avoid handling up_stop, down_stop or toggle separately.
-            if ((max_time_on_timeout != null || is_running) && (real_topic == "up_stop" || real_topic == "down_stop" || real_topic == "toggle"))
+            if (real_topic == "short_up_down")
+            {
+                real_topic = msg.payload ? "down" : "up";
+                if (msg.time_on == null)
+                    msg.time_on = short_time_on_ms;
+            }
+
+            if ((timeout != null || is_running) && (real_topic == "up_stop" || real_topic == "down_stop" || real_topic == "toggle"))
             {
                 real_topic = "stop";
             }
-            else if (max_time_on_timeout == null && !is_running)
+            else if (timeout == null && !is_running)
             {
                 // shutter is not running, set next command depending on topic
                 if (real_topic == "up_stop")
@@ -86,7 +129,7 @@ module.exports = function (RED)
                     real_topic = "up";
             }
 
-
+            helper.log("handle real topic: " + real_topic);
             switch (real_topic)
             {
                 case "status":
@@ -96,30 +139,18 @@ module.exports = function (RED)
 
                     if (is_running && (msg.payload == 0 || msg.payload == 100))
                         is_running = false;
-
-                    node.status({ fill: "yellow", shape: "ring", text: helper.getCurrentTimeForStatus() + ": Position status received: " + msg.payload + "%" });
                     return;
 
-                // This is only used to track starting of the shutter
                 case "up_down":
+                    // This is only used to track starting of the shutter
                     node_settings.last_direction_up = !msg.payload;
                     is_running = true;
-
-                    if (node_settings.last_direction_up)
-                        node.status({ fill: "green", shape: "dot", text: helper.getCurrentTimeForStatus() + ": Up" });
-                    else
-                        node.status({ fill: "green", shape: "dot", text: helper.getCurrentTimeForStatus() + ": Down" });
-                    return;
-
-                case "short_up_down":
-                    handleTopic({ topic: msg.payload ? "down" : "up", time_on: msg.time_on ?? short_time_on_ms });
                     return;
 
                 case "up":
                     node_settings.last_direction_up = true;
                     is_running = true;
                     resultUpDown = false;
-                    node.status({ fill: "green", shape: "dot", text: helper.getCurrentTimeForStatus() + ": Up" });
                     startAutoOffIfNeeded(msg);
                     break;
 
@@ -127,14 +158,12 @@ module.exports = function (RED)
                     is_running = false;
                     resultStop = true;
                     stopAutoOff();
-                    node.status({ fill: "red", shape: "dot", text: helper.getCurrentTimeForStatus() + ": Stopped" });
                     break;
 
                 case "down":
                     node_settings.last_direction_up = false;
                     is_running = true;
                     resultUpDown = true;
-                    node.status({ fill: "green", shape: "dot", text: helper.getCurrentTimeForStatus() + ": Down" });
                     startAutoOffIfNeeded(msg);
                     break;
 
@@ -145,67 +174,98 @@ module.exports = function (RED)
                     if (value > 100) value = 100;
                     // is_running = true; // Not guaranteed that the shutter starts running.
                     resultPosition = value;
-                    node.status({ fill: "green", shape: "dot", text: helper.getCurrentTimeForStatus() + ": Set position to " + value + "%" });
                     break;
             }
 
             if (resultUpDown != null)
             {
-                node.send([{ payload: resultUpDown, topic: "up_down" }, null, null]);
+                node.send([{ payload: resultUpDown }, null, null]);
                 notifyCentral(true);
             }
             else if (resultStop != null)
             {
-                node.send([null, { payload: resultStop, topic: "stop" }, null]);
+                node.send([null, { payload: resultStop }, null]);
                 notifyCentral(false);
             }
             else if (resultPosition != null)
             {
-                node.send([null, null, { payload: resultPosition, topic: "position" }]);
+                node.send([null, null, { payload: resultPosition }]);
             }
         };
 
+        /**
+         * This function sets a timeout to stop the shutter after the defined time is over.
+         * @param {*} msg The original message object
+         */
         let startAutoOffIfNeeded = msg =>
         {
-            if (!msg.time_on)
+            if (msg.time_on == null || msg.time_on == 0)
                 return;
 
+            // calculate needed time
             let timeMs = helper.getTimeInMsFromString(msg.time_on);
-            if (isNaN(timeMs))
+            if (isNaN(timeMs) || timeMs <= 0)
             {
-                node.status({ fill: "red", shape: "dot", text: helper.getCurrentTimeForStatus() + ": Invalid time_on value send: '" + msg.time_on + "'" });
-                return;
-            }
-
-            if (timeMs <= 0)
-            {
-                node.status({ fill: "red", shape: "dot", text: helper.getCurrentTimeForStatus() + ": time_on value has to be greater than 0" });
+                console.warn("Invalid msg.time_on value was sent.", msg);
                 return;
             }
 
             // Stop if any timeout is set
             stopAutoOff();
 
-            node.status({ fill: "yellow", shape: "ring", text: helper.getCurrentTimeForStatus() + ": Wait " + (timeMs / 1000).toFixed(1) + " sec for auto off" });
-            max_time_on_timeout = setTimeout(() =>
+            timeout = setTimeout(() =>
             {
-                node.status({ fill: "red", shape: "dot", text: helper.getCurrentTimeForStatus() + ": Stopped" });
                 is_running = false;
+                timeout = null;
+
                 node.send([null, { payload: true }, null]);
                 notifyCentral(false);
+
+                smart_context.set(node.id, node_settings);
+
+                setStatus();
             }, timeMs);
         };
 
+        /**
+         * Stops the current running timeout
+         */
         let stopAutoOff = () =>
         {
-            if (max_time_on_timeout != null)
+            if (timeout != null)
             {
-                node.status({});
-                clearTimeout(max_time_on_timeout);
-                max_time_on_timeout = null;
+                clearTimeout(timeout);
+                timeout = null;
             }
         };
 
+        /**
+         * Set the current node status
+         */
+        let setStatus = () =>
+        {
+            let fill = "green";
+            let shape = (timeout != null || is_running) ? "ring" : "dot";
+
+            // collect all texts and join later with a comma
+            let texts = [];
+
+            if (timeout == null && !is_running)
+                texts.push("Stopped");
+            else if (node_settings.last_direction_up)
+                texts.push("Up");
+            else
+                texts.push("Down");
+
+            texts.push("Position: " + node_settings.last_position?.toFixed(0) + "%");
+
+            node.status({ fill, shape, text: helper.getCurrentTimeForStatus() + ": " + texts.join(", ") });
+        }
+
+        /**
+         * Notify all connected central nodes
+         * @param {boolean} state The state if the shutter is running
+         */
         let notifyCentral = state =>
         {
             if (!config.links)
@@ -213,8 +273,8 @@ module.exports = function (RED)
 
             config.links.forEach(link =>
             {
-                // console.log(node.id + " -> " + link);
-                // console.log({ source: node.id, state: state });
+                helper.log(node.id + " -> " + link);
+                helper.log({ source: node.id, state: state });
                 RED.events.emit("node:" + link, { source: node.id, state: state });
             });
         };