smart-nodes 0.3.37 → 0.4.0

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 });
             });
         };

package/shutter-complex/locales/de-DE/shutter-complex.html

@@ -0,0 +1,120 @@
+<script type="text/html" data-help-name="smart_shutter-complex-control">
+    <p>
+        <b>Hinweis:</b> Diese Node wurde entwickelt, falls die KNX Rollladensteuerung nicht verwendet werden kann um man gezwungen ist 2 separate Ausgänge für Auf und Ab zu verwenden.
+        Es ist dabei sehr zu empfehlen, dass die Ausgänge sich gegenseitig verriegeln um ein gleichzeitiges Ansteuern zu verhindern. Für etwaige Schäden am Rollladen ist jeder selbst verantwortlich.
+    </p>
+    <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:</b> <code>msg.payload = true;</code> startet den Rollladen um nach oben zu fahren und <code>msg.payload = false;</code> stoppt diesen wieder.</li>
+            <li><b>Ab:</b> <code>msg.payload = true;</code> startet den Rollladen um nach unten zu fahren und <code>msg.payload = false;</code> stoppt diesen wieder.</li>
+            <li><b>Status Position:</b> <code>msg.payload = 42;</code>Gibt den aktuellen Status der Rollladen aus. 0 = offen, 100 = geschlossen.</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>up_stop</code></td>
+                    <td>Sendet abwechselnd einen Stop- und einen Hochfahrbefehl.</td>
+                    <td>Ja</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 und die eingestellte Zeit gewartet.</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>down</code></td>
+                    <td>Sendet einen Runterfahrbefehl, falls der Rollladen nicht bereits nach unten fährt. Ggf. wird vorher noch ein Stop-Befehl gesendet und die eingestellte Zeit gewartet.</td>
+                    <td>Ja</td>
+                </tr>
+                <tr>
+                    <td><code>up_down</code></td>
+                    <td>Nimmt einen Befehl von Home Assistant entgegen und leitet die entsprechende Aktion ein.</td>
+                    <td>Nein</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>alarm</code></td>
+                    <td>Setzt den aktuellen Alarmzustand.</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 die Laufzeit für den Rollladen selbst.
+        Es ist aber auch möglich, den Rollladen nach einer definierten Zeit automatisch abschalten zu lassen.
+        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>Minuten.</td>
+                </tr>
+                <tr>
+                    <td><code>h</code></td>
+                    <td>Stunden</td>
+                </tr>
+            </tbody>
+        </table>
+    </p>
+    <p>
+        Um mögliche Positionsabweichungen zu korrigieren läuft der Rollladen immer für mindestens 5 Sekunden, wenn nichts anderes in <code>msg.on_time</code> eingestellt wurde.
+        Dadurch kann der Rollladen auch noch weiter hochgefahren werden, falls er im System als offen erkannt wird, er aber in Wirklichkeit noch nicht ganz oben sein sollte.<br>
+        Manchmal kann es aber auch erwünscht sein, dass ein Rollladen bei 0 oder 100 % nicht nochmals startet. Dafür muss dann <code>msg.exact = true</code> gesetzt werden.
+    </p>
+    <p>
+        Die Angabe einer Zeit funktioniert nicht mit dem topic <b>position</b>.
+    </p>
+</script>

package/shutter-complex/locales/de-DE/shutter-complex.json

@@ -0,0 +1,20 @@
+{
+    "shutter": {
+        "ui": {
+            "name": "Name",
+            "text": "Text",
+            "controlled_by_words": "Diese Node kann über die eingegebenen Wörter gesteuert werden. Mehrere Wörter werden durch ein Komma getrennt.",
+            "time_up": "Zeit auf",
+            "time_down": "Zeit ab",
+            "pause_change": "Pause Wechsel",
+            "alarm_on": "Alarm Ein",
+            "alarm_off": "Alarm Aus",
+            "controlled_by_central": "Dieser Baustein wird von folgenden Zentralbausteinen gesteuert:",
+
+            "no_action": "Keine Aktion",
+            "up": "Hoch / Öffnen",
+            "down": "Runter / Schließen",
+            "last_position": "Letze Position"
+        }
+    }
+}

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

@@ -0,0 +1,120 @@
+<script type="text/html" data-help-name="smart_shutter-complex-control">
+    <p>
+        <b>Note:</b> This node was developed if the KNX roller shutter control cannot be used and you are forced to use 2 separate outputs for up and down.
+        It is highly recommended that the outputs lock each other to prevent simultaneous control. Everyone is responsible for any damage to the roller shutter.
+    </p>
+    <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 <code>name</code> part. <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:</b> <code>msg.payload = true;</code> starts the roller shutter to move up and <code>msg.payload = false;</code> stops it again. </li>
+            <li><b>Down:</b> <code>msg.payload = true;</code> starts the roller shutter to move down and <code>msg.payload = false;</code> stops it again. </li>
+            <li><b>Status Position:</b> <code>msg.payload = 42;</code>Shows the current status of the roller shutter. 0 = open, 100 = closed.</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>up_stop</code></td>
+                    <td>Sends a stop and a raise command alternately.</td>
+                    <td>Yes</td>
+                </tr>
+                <tr>
+                    <td><code>up</code></td>
+                    <td>Sends a raise command if the roller shutter is not already moving up. If necessary, a stop command is sent beforehand and the set time is waited for.</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>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 and the set time is waited for.</td>
+                    <td>Yes</td>
+                </tr>
+                <tr>
+                    <td><code>up_down</code></td>
+                    <td>Receives a command from Home Assistant and initiates the corresponding action.</td>
+                    <td>No</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>alarm</code></td>
+                    <td>Sets the current alarm state.</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 manages the running time for the roller shutter itself.
+        It is also possible to have the roller shutter switch 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 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>Minutes.</td>
+                </tr>
+                <tr>
+                    <td><code>h</code></td>
+                    <td>Hours</td>
+                </tr>
+            </tbody>
+        </table>
+    </p>
+    <p>
+        To correct possible position deviations, the roller shutter always runs for at least 5 seconds if nothing else has been set in <code>msg.on_time</code>.
+        This means that the roller shutter can be raised even further if it is recognized as open in the system, but in reality it is not yet completely up.<br>
+        Sometimes it may also be desirable for a roller shutter not to start again at 0 or 100%. For this, <code>msg.exact = true</code> must be set.
+    </p>
+    <p>
+        Specifying a time does not work with the topic <b>position</b>.
+    </p>
+</script>

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

@@ -0,0 +1,20 @@
+{
+    "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_up": "Time up",
+            "time_down": "Time down",
+            "pause_change": "Pause change",
+            "alarm_on": "Alarm On",
+            "alarm_off": "Alarm Off",
+            "controlled_by_central": "This module is controlled by the following central modules:",
+
+            "no_action": "No action",
+            "up": "Up / Open",
+            "down": "Down / Close",
+            "last_position": "Last position"
+        }
+    }
+}