node-red-contrib-ccu 4.1.0 → 4.3.0

package/nodes/ccu-mqtt.js

@@ -2,6 +2,19 @@ const path = require('path');
 const mw = require('mqtt-wildcard');
 
 const statusHelper = require(path.join(__dirname, '/lib/status.js'));
+const {castValue} = require(path.join(__dirname, '/lib/cast.js'));
+
+/** HM thermostats: CONTROL_MODE is read-only, the modes are set through actions */
+const HM_MODES = {
+    'AUTO-MODE': () => ['AUTO_MODE', true],
+    'MANU-MODE': (setpoint) => ['MANU_MODE', setpoint],
+    'BOOST-MODE': () => ['BOOST_MODE', true],
+    'COMFORT-MODE': () => ['COMFORT_MODE', true],
+    'LOWERING-MODE': () => ['LOWERING_MODE', true],
+};
+
+/** Words Home Assistant sends to LEVEL; 1.005 is the actuators' "old level" value */
+const LEVEL_WORDS = {OPEN: 1, CLOSE: 0, ON: 1.005, OFF: 0};
 
 module.exports = function (RED) {
     class CcuMqttNode {
@@ -23,7 +36,10 @@ module.exports = function (RED) {
             this.topicInputPutParam = config.topicInputPutParam;
             this.topicInputPutParamset = config.topicInputPutParamset;
 
+            this.topicInputGet = config.topicInputGet;
+
             this.topicInputRpc = config.topicInputRpc;
+            this.topicOutputRpc = config.topicOutputRpc;
 
             this.topicCounters = config.topicCounters;
             this.rxCounters = {};
@@ -98,12 +114,15 @@ module.exports = function (RED) {
         }
 
         event(message) {
-            const topic = this.ccu.topicReplace(this.topicOutputEvent, message);
+            // channels without a ReGa name used to produce hm/status//STATE-style
+            // topics — fall back to the address (B-3)
+            const topicMessage = message.channelName ? message : {...message, channelName: message.channel};
+            const topic = this.ccu.topicReplace(this.topicOutputEvent, topicMessage);
             const retain = !(message.datapoint && message.datapoint.startsWith('PRESS_'));
             this.send({topic, payload: this.output(message), retain});
 
             if (['LEVEL', 'STATE'].includes(message.datapoint) && message.working === false) {
-                const messageNotWorking = RED.util.cloneMessage(message);
+                const messageNotWorking = RED.util.cloneMessage(topicMessage);
                 messageNotWorking.datapoint += '_NOTWORKING';
                 messageNotWorking.datapointName += '_NOTWORKING';
                 this.send({
@@ -164,6 +183,7 @@ module.exports = function (RED) {
             this.debug('input ' + topic + ' ' + JSON.stringify(payload).slice(0, 40));
 
             const topicList = {
+                get: this.topicInputGet,
                 setValue: this.topicInputSetValue,
                 sysvar: this.topicInputSysvar,
                 putParam: this.topicInputPutParam,
@@ -174,7 +194,8 @@ module.exports = function (RED) {
             let command;
             let filter;
             Object.keys(topicList).forEach((key) => {
-                if (!command) {
+                // a topic left empty in the editor disables that command
+                if (!command && topicList[key]) {
                     const parts = topicList[key].split('/');
                     const patternArray = [];
                     const placeholders = [];
@@ -205,33 +226,177 @@ module.exports = function (RED) {
             }
         }
 
-        setValue(filter, payload) {
+        /**
+         * Resolve `channelNameOrAddress` to a channel address and its
+         * interface, reporting the same errors the commands used to report
+         * inline.
+         * @param {object} filter parsed from the topic; `channel` is filled in
+         * @param {boolean} [exact] pass through to findChannel
+         * @returns {string|null} the interface, or null when unresolvable
+         */
+        resolveChannel(filter, exact) {
             if (filter.channelNameOrAddress) {
                 if (this.ccu.channelNames[filter.channelNameOrAddress]) {
                     filter.channel = filter.channelNameOrAddress;
                 } else {
-                    filter.channel = this.ccu.findChannel(filter.channelNameOrAddress, true);
+                    filter.channel = this.ccu.findChannel(filter.channelNameOrAddress, exact);
                 }
 
                 if (!filter.channel) {
                     this.error('channel ' + filter.channelNameOrAddress + ' not found');
-                    return;
+                    return null;
                 }
             }
 
             if (!filter.channel) {
                 this.error('channel undefined');
-                return;
+                return null;
             }
 
             const iface = this.ccu.findIface(filter.channel);
 
             if (!iface) {
                 this.error('no interface found for channel ' + filter.channel);
+                return null;
+            }
+
+            return iface;
+        }
+
+        /**
+         * Republish the last known value of a datapoint on its status topic,
+         * so a flow can ask for a refresh over MQTT instead of waiting for the
+         * next event (#115). An empty datapoint republishes the whole channel.
+         * @param {object} filter
+         */
+        get(filter) {
+            const iface = this.resolveChannel(filter, true);
+            if (!iface) {
+                return;
+            }
+
+            const prefix = iface + '.' + filter.channel + '.';
+            const names = filter.datapoint
+                ? [prefix + filter.datapoint]
+                : Object.keys(this.ccu.values).filter((name) => name.startsWith(prefix));
+
+            if (names.length === 0) {
+                this.error('unknown datapoint ' + prefix + (filter.datapoint || '#'));
+                return;
+            }
+
+            names.forEach((name) => {
+                const value = this.ccu.values[name];
+                if (value) {
+                    this.event({...value});
+                } else {
+                    this.error('unknown datapoint ' + name);
+                }
+            });
+        }
+
+        /**
+         * Call an arbitrary RPC method on an interface and publish the result
+         * (#22). The topic supplies interface, method and a caller-chosen id
+         * that the response topic echoes; the payload is the parameter array
+         * (a single value is accepted and wrapped).
+         * @param {object} filter
+         * @param {*} payload
+         */
+        rpc(filter, payload) {
+            if (!filter.iface) {
+                this.error('interface undefined');
+                return;
+            }
+
+            if (!filter.method) {
+                this.error('method undefined');
+                return;
+            }
+
+            let parameters = payload;
+            if (parameters === undefined || parameters === null || parameters === '') {
+                parameters = [];
+            } else if (!Array.isArray(parameters)) {
+                parameters = [parameters];
+            }
+
+            const respond = (result, error) => {
+                if (!this.topicOutputRpc) {
+                    return;
+                }
+
+                this.send({
+                    topic: this.ccu.topicReplace(this.topicOutputRpc, {
+                        iface: filter.iface,
+                        method: filter.method,
+                        callid: filter.callid,
+                    }),
+                    payload: error ? {error: error.message} : {result},
+                    retain: false,
+                });
+            };
+
+            this.ccu
+                .methodCall(filter.iface, filter.method, parameters)
+                .then((result) => respond(result))
+                .catch((error) => {
+                    this.error(error.message);
+                    respond(undefined, error);
+                });
+        }
+
+        setValue(filter, payload) {
+            const iface = this.resolveChannel(filter, true);
+            if (!iface) {
                 return;
             }
 
-            this.ccu.setValue(iface, filter.channel, filter.datapoint, payload).catch(() => {});
+            const command = this.translateCommand(iface, filter.channel, filter.datapoint, payload);
+            this.ccu.setValue(iface, filter.channel, command.datapoint, command.payload).catch(() => {});
+        }
+
+        /**
+         * Words Home Assistant's single-topic conventions send (see the
+         * ccu-homeassistant node): LEVEL accepts OPEN, CLOSE, STOP, ON (restore the
+         * last level) and OFF; HM thermostats accept the CONTROL_MODE names
+         * (AUTO-MODE, MANU-MODE, BOOST-MODE, COMFORT-MODE, LOWERING-MODE), which
+         * are translated to the *_MODE actions because CONTROL_MODE itself is
+         * read-only there. Everything else passes through unchanged.
+         * @returns {{datapoint: string, payload: *}}
+         */
+        translateCommand(iface, channel, datapoint, payload) {
+            if (typeof payload !== 'string') {
+                return {datapoint, payload};
+            }
+
+            const word = payload.trim().toUpperCase();
+            const device = this.ccu.metadata.devices[iface] && this.ccu.metadata.devices[iface][channel];
+            const description = (device && this.ccu.getParamsetDescription(iface, device, 'VALUES')) || {};
+
+            if (datapoint === 'LEVEL') {
+                if (word === 'STOP' && description.STOP) {
+                    return {datapoint: 'STOP', payload: true};
+                }
+
+                if (word in LEVEL_WORDS) {
+                    return {datapoint, payload: LEVEL_WORDS[word]};
+                }
+            }
+
+            if (
+                datapoint === 'CONTROL_MODE' &&
+                HM_MODES[word] &&
+                description.CONTROL_MODE &&
+                !(description.CONTROL_MODE.OPERATIONS & 2)
+            ) {
+                const current = this.ccu.values[iface + '.' + channel + '.SET_TEMPERATURE'];
+                const setpoint = current && typeof current.value === 'number' ? current.value : 20;
+                const [dp, value] = HM_MODES[word](setpoint);
+                return {datapoint: dp, payload: value};
+            }
+
+            return {datapoint, payload};
         }
 
         sysvar(filter, payload) {
@@ -254,28 +419,8 @@ module.exports = function (RED) {
         }
 
         putParam(filter, payload) {
-            if (filter.channelNameOrAddress) {
-                if (this.ccu.channelNames[filter.channelNameOrAddress]) {
-                    filter.channel = filter.channelNameOrAddress;
-                } else {
-                    filter.channel = this.ccu.findChannel(filter.channelNameOrAddress);
-                }
-
-                if (!filter.channel) {
-                    this.error('channel ' + filter.channelNameOrAddress + ' not found');
-                    return;
-                }
-            }
-
-            if (!filter.channel) {
-                this.error('channel undefined');
-                return;
-            }
-
-            const iface = this.ccu.findIface(filter.channel);
-
+            const iface = this.resolveChannel(filter);
             if (!iface) {
-                this.error('no interface found for channel ' + filter.channel);
                 return;
             }
 
@@ -286,11 +431,14 @@ module.exports = function (RED) {
             );
             const paramsetDescription = this.ccu.paramsetDescriptions[psName];
             if (paramsetDescription && paramsetDescription[filter.param]) {
-                if (!paramsetDescription[filter.param].OPERATIONS && 2) {
+                // was `!(OPERATIONS) && 2`, which is always false - the check
+                // never fired and the write went out regardless (B-3)
+                if (!(paramsetDescription[filter.param].OPERATIONS & 2)) {
                     this.error('param ' + filter.param + ' not writeable');
+                    return;
                 }
 
-                payload = this.paramCast(payload, paramsetDescription[filter.param]);
+                payload = castValue(payload, paramsetDescription[filter.param], {clamp: true});
             } else {
                 this.warn('unknown paramset/param ' + filter.paramset + ' ' + filter.param);
             }
@@ -309,28 +457,8 @@ module.exports = function (RED) {
                 return;
             }
 
-            if (filter.channelNameOrAddress) {
-                if (this.ccu.channelNames[filter.channelNameOrAddress]) {
-                    filter.channel = filter.channelNameOrAddress;
-                } else {
-                    filter.channel = this.ccu.findChannel(filter.channelNameOrAddress);
-                }
-
-                if (!filter.channel) {
-                    this.error('channel ' + filter.channelNameOrAddress + ' not found');
-                    return;
-                }
-            }
-
-            if (!filter.channel) {
-                this.error('channel undefined');
-                return;
-            }
-
-            const iface = this.ccu.findIface(filter.channel);
-
+            const iface = this.resolveChannel(filter);
             if (!iface) {
-                this.error('no interface found for channel ' + filter.channel);
                 return;
             }
 
@@ -345,11 +473,17 @@ module.exports = function (RED) {
 
             Object.keys(payload).forEach((parameter) => {
                 if (paramsetDescription && paramsetDescription[parameter]) {
-                    if (!paramsetDescription[parameter].OPERATIONS && 2) {
+                    // was `!(OPERATIONS) && 2` (always false), and the cast
+                    // used paramsetDescription[filter.param], which is
+                    // undefined here - so every value went out uncast (B-3)
+                    if (!(paramsetDescription[parameter].OPERATIONS & 2)) {
                         this.error('param ' + parameter + ' not writeable');
+                        return;
                     }
 
-                    paramset[parameter] = this.paramCast(payload[parameter], paramsetDescription[filter.param]);
+                    paramset[parameter] = castValue(payload[parameter], paramsetDescription[parameter], {
+                        clamp: true,
+                    });
                 } else {
                     this.warn('unknown paramset/param ' + filter.paramset + ' ' + parameter);
                     paramset[parameter] = payload[parameter];
@@ -360,57 +494,6 @@ module.exports = function (RED) {
                 .methodCall(iface, 'putParamset', [filter.channel, filter.paramset, paramset])
                 .catch((error) => this.error(error.message));
         }
-
-        paramCast(value, paramset) {
-            switch (paramset && paramset.TYPE) {
-                case 'BOOL':
-                // Fallthrough by intention
-                case 'ACTION':
-                    // OMG this is so ugly...
-                    if (value === 'false') {
-                        value = false;
-                    } else if (!isNaN(value)) {
-                        // Make sure that the string "0" gets casted to boolean false
-                        value = Number(value);
-                    }
-
-                    value = Boolean(value);
-                    break;
-                case 'FLOAT':
-                    value = Number.parseFloat(value);
-                    if (value < paramset.MIN) {
-                        value = paramset.MIN;
-                    } else if (value > paramset.MAX) {
-                        value = paramset.MAX;
-                    }
-
-                    value = {explicitDouble: value};
-                    break;
-                case 'ENUM':
-                    if (typeof value === 'string') {
-                        if (paramset.ENUM && paramset.ENUM.includes(value)) {
-                            value = paramset.ENUM.indexOf(value);
-                        }
-                    }
-
-                // Fallthrough by intention
-                case 'INTEGER':
-                    value = Number.parseInt(value, 10);
-                    if (value < paramset.MIN) {
-                        value = paramset.MIN;
-                    } else if (value > paramset.MAX) {
-                        value = paramset.MAX;
-                    }
-
-                    break;
-                case 'STRING':
-                    value = String(value);
-                    break;
-                default:
-            }
-
-            return value;
-        }
     }
 
     RED.nodes.registerType('ccu-mqtt', CcuMqttNode);

package/nodes/ccu-rpc-event.html

@@ -29,6 +29,7 @@
             change: {value: false},
             working: {value: false},
             cache: {value: false},
+            certainOnly: {value: false},
             topic: {value: '${CCU}/${Interface}/${channelName}/${datapoint}'}  
         },
         inputs: 0,
@@ -596,6 +597,11 @@
                 <input type="checkbox" id="node-input-cache">
                 <span data-i18n="ccu-rpc-event.cache"></span>
             </label>
+
+            <label class="ccu-checkbox">
+                <input type="checkbox" id="node-input-certainOnly">
+                <span data-i18n="ccu-rpc-event.certainOnly"></span>
+            </label>
         </div>
     </div>
     <div class="form-row">

package/nodes/ccu-rpc-event.js

@@ -1,6 +1,20 @@
 const path = require('path');
 
 const statusHelper = require(path.join(__dirname, '/lib/status.js'));
+const {valueStatus} = require(path.join(__dirname, '/lib/valuestatus.js'));
+
+const FILTER_ATTRIBUTES = [
+    'rooms',
+    'functions',
+    'device',
+    'deviceName',
+    'deviceType',
+    'channel',
+    'channelName',
+    'channelType',
+    'channelIndex',
+    'datapoint',
+];
 
 module.exports = function (RED) {
     class CcuRpcEventNode {
@@ -21,20 +35,15 @@ module.exports = function (RED) {
                 iface: config.iface,
             };
 
+            // opt-in: only present when the option is enabled, so existing
+            // subscriptions keep receiving uncertain values (#96)
+            if (config.certainOnly) {
+                filter.uncertain = false;
+            }
+
             this.ccu.register(this);
 
-            [
-                'rooms',
-                'functions',
-                'device',
-                'deviceName',
-                'deviceType',
-                'channel',
-                'channelName',
-                'channelType',
-                'channelIndex',
-                'datapoint',
-            ].forEach((attr) => {
+            FILTER_ATTRIBUTES.forEach((attr) => {
                 if (!config[attr]) {
                     return;
                 }
@@ -45,8 +54,14 @@ module.exports = function (RED) {
                     filter[attr] = config[attr];
                 }
             });
+
+            // The node used to show nothing at all; show what came through
+            // last and how long ago (#52)
+            this.valueStatus = valueStatus(this);
+
             this.idSubscription = this.ccu.subscribe(filter, (message) => {
                 message.topic = this.ccu.topicReplace(config.topic, message);
+                this.valueStatus.set(message.topic + ' = ' + message.payload, message.ts);
                 this.send(message);
             });
             this.on('close', this._destructor);
@@ -54,6 +69,10 @@ module.exports = function (RED) {
 
         _destructor(done) {
             this.debug('ccu-rpc-event close');
+            if (this.valueStatus) {
+                this.valueStatus.stop();
+            }
+
             this.ccu.unsubscribe(this.idSubscription);
             this.ccu.deregister(this);
             done();

package/nodes/ccu-set-value.html

@@ -624,8 +624,46 @@
 
     <h3>Input</h3>
 
+
+    <h3>Dynamische Konfiguration</h3>
+    <p><code>msg.config</code> ist ein Objekt, dessen Eigenschaften die Konfiguration dieses Nodes für genau diese Nachricht überschreiben. Die gespeicherte Konfiguration bleibt unverändert.</p>
+    <ul>
+        <li><code>iface</code></li>
+        <li><code>rooms</code></li>
+        <li><code>functions</code></li>
+        <li><code>device</code></li>
+        <li><code>deviceType</code></li>
+        <li><code>deviceName</code></li>
+        <li><code>channel</code></li>
+        <li><code>channelType</code></li>
+        <li><code>channelIndex</code></li>
+        <li><code>channelName</code></li>
+        <li><code>datapoint</code></li>
+        <li><code>force</code></li>
+        <li><code>sowie die zugehörigen <code>...Rx</code>-Selektoren</code></li>
+    </ul>
+    <p>Zusätzlich füllen gleichnamige Eigenschaften der Nachricht selbst (<code>msg.rooms</code> usw.) leer gelassene Felder — so war es schon immer.</p>
 </script>
 
 <script type="text/x-red" data-help-name="ccu-set-value" lang="en-US">
     <p>Control multiple devices at once.</p>
+
+    <h3>Dynamic configuration</h3>
+    <p><code>msg.config</code> is an object whose properties override this node's configuration for that one message. The stored configuration is never modified.</p>
+    <ul>
+        <li><code>iface</code></li>
+        <li><code>rooms</code></li>
+        <li><code>functions</code></li>
+        <li><code>device</code></li>
+        <li><code>deviceType</code></li>
+        <li><code>deviceName</code></li>
+        <li><code>channel</code></li>
+        <li><code>channelType</code></li>
+        <li><code>channelIndex</code></li>
+        <li><code>channelName</code></li>
+        <li><code>datapoint</code></li>
+        <li><code>force</code></li>
+        <li><code>and the matching <code>...Rx</code> selectors</code></li>
+    </ul>
+    <p>Properties of the message itself (<code>msg.rooms</code> and so on) also fill in fields left empty in the dialog, as they always did.</p>
 </script>