node-red-contrib-ta-cmi-coe 1.0.0

package/lib/queueing.js

@@ -0,0 +1,188 @@
+/**
+ * Message Queueing and Debouncing Module
+ * 
+ * Copyright 2025 Florian Mayrhofer
+ * Licensed under the Apache License, Version 2.0
+ *
+ */ 
+
+const { createCoEPacket } = require('../lib/coe');
+
+const blockStateCache = {};
+const blockUnitsCache = {}; // Cache for units per block
+const blockQueues = {};
+const blockTimers = {};
+const DEBOUNCE_DELAY = 50; // ms (Time slot for message collection)
+
+// Returns a copy of the current block state (values) for the given block
+function getBlockState(nodeNumber, blockNumber, dataType) {
+    const key = `${nodeNumber}-${blockNumber}-${dataType}`;
+    if (!blockStateCache[key]) {
+        if (dataType === 'analog') {
+            blockStateCache[key] = [0, 0, 0, 0];
+        } else {
+            blockStateCache[key] = new Array(16).fill(0);
+        }
+    }
+    // Return a copy to avoid accidental external mutation
+    return Array.isArray(blockStateCache[key]) ? [...blockStateCache[key]] : blockStateCache[key];
+}
+
+// Sets the current block state (values) for the given block
+function setBlockState(nodeNumber, blockNumber, dataType, values) {
+    const key = `${nodeNumber}-${blockNumber}-${dataType}`;
+    blockStateCache[key] = [...values];
+}
+
+// Returns a copy of the current block units for the given block (analog only)
+function getBlockUnits(nodeNumber, blockNumber, dataType) {
+    const key = `${nodeNumber}-${blockNumber}-${dataType}`;
+    if (!blockUnitsCache[key]) {
+        // Only analog blocks have units
+        if (dataType === 'analog') {
+            blockUnitsCache[key] = [0, 0, 0, 0];
+        } else {
+            blockUnitsCache[key] = null;
+        }
+    }
+    return blockUnitsCache[key] ? [...blockUnitsCache[key]] : null;
+}
+
+// Sets the current block units for the given block (analog only)
+function setBlockUnits(nodeNumber, blockNumber, dataType, units) {
+    const key = `${nodeNumber}-${blockNumber}-${dataType}`;
+    if (dataType === 'analog') {
+        blockUnitsCache[key] = units ? [...units] : [0,0,0,0];
+    } else {
+        blockUnitsCache[key] = null;
+    }
+}
+
+// Generates a unique key for the queue based on node, block, and data type
+function getQueueKey(nodeNumber, blockNumber, dataType) {
+    return `${nodeNumber}-${blockNumber}-${dataType}`;
+}
+
+// Queues and debounces messages for a specific block
+function queueAndSend(node, translate, nodeNumber, blockNumber, values, units, dataType, version, cmiConfig, cmiAddress, origMsg) {
+    const queueKey = getQueueKey(nodeNumber, blockNumber, dataType);
+
+    // New queueing logic
+    let baseValues;
+    let baseUnits;
+
+    if (blockQueues[queueKey]) {
+        baseValues = [...blockQueues[queueKey].values];
+        baseUnits = blockQueues[queueKey].units ? [...blockQueues[queueKey].units] : null;
+    } else {
+        baseValues = getBlockState(nodeNumber, blockNumber, dataType);
+        baseUnits = (dataType === 'analog') ? getBlockUnits(nodeNumber, blockNumber, dataType) : null;
+    }
+
+    // Merge incoming values/units with existing block state
+    let mergedValues = baseValues;
+    let mergedUnits = baseUnits;
+    
+    if (dataType === 'analog') {
+        for (let i = 0; i < 4; i++) {
+            if (values[i] !== undefined && values[i] !== null) {
+                mergedValues[i] = values[i];
+            }
+            if (units && units[i] !== undefined) {
+                mergedUnits[i] = units[i];
+            }
+        }
+    } else {
+        for (let i = 0; i < 16; i++) {
+            if (values[i] !== undefined) {
+                mergedValues[i] = values[i];
+            }
+        }
+    }
+
+    if (!blockQueues[queueKey]) { // Create queue, if none
+            blockQueues[queueKey] = {
+                values: mergedValues,
+                units: mergedUnits,
+                node: node,
+                timestamp: Date.now(),
+                origMsg: origMsg || null
+            };
+        } else { // Overwrite state, if queue exists
+            const q = blockQueues[queueKey];
+            q.values = mergedValues;
+            q.units = mergedUnits;
+            q.origMsg = origMsg || q.origMsg;
+        }
+        
+    // Delete existing timer if any
+    if (blockTimers[queueKey]) {
+        clearTimeout(blockTimers[queueKey]);
+    }
+
+    // Start a new timer to send the queued message after the debounce delay
+    blockTimers[queueKey] = setTimeout(() => {
+        const queued = blockQueues[queueKey];
+        if (queued) {
+            const packet = createCoEPacket(
+                nodeNumber,
+                blockNumber,
+                queued.values,
+                queued.units,
+                dataType,
+                version
+            );
+            
+            // Persist both values and units for the block
+            setBlockState(nodeNumber, blockNumber, dataType, queued.values);
+            if (dataType === 'analog') {
+                setBlockUnits(nodeNumber, blockNumber, dataType, queued.units);
+            }
+            
+            // Send debug output on the node outputs: [original msg, debug info]
+            try {
+                const debugPayload = {
+                    debug: {
+                        hex: packet.toString('hex').toUpperCase(),
+                        node: nodeNumber,
+                        block: blockNumber,
+                        dataType: dataType,
+                        version: version,
+                        blockState: queued.values,
+                        units: queued.units
+                    }
+                };
+                // If node has outputs, send original msg on first output and debug on second
+                queued.node.send([queued.origMsg || null, { payload: debugPayload }]);
+            } catch (err) {
+                // Do not break sending on debug failure
+                queued.node.warn(`Failed to send debug msg: ${err.message}`);
+            }
+                const mergedText = translate("coe-output.status.merged");
+                const readyText = translate("coe-output.status.ready");
+
+                cmiConfig.send(cmiAddress, packet);
+                
+                queued.node.status({
+                    fill: "green",
+                    shape: "dot",
+                    text: `${mergedText} [${version}]`
+                });
+                
+                setTimeout(() => {
+                    queued.node.status({fill: "grey", shape: "ring", text: `${readyText} [v${version}]`});
+                }, 2000);
+                
+                delete blockQueues[queueKey];
+                delete blockTimers[queueKey];
+            }
+        }, DEBOUNCE_DELAY);
+}
+
+module.exports = {
+    getBlockState,
+    setBlockState,
+    getBlockUnits,
+    setBlockUnits,
+    queueAndSend
+};

package/lib/units.js

@@ -0,0 +1,78 @@
+/**
+ * Central Unit Definitions for TA CMI CoE
+ * 
+ * Copyright 2025 Florian Mayrhofer
+ * Licensed under the Apache License, Version 2.0
+ *
+ */  
+
+// Central Unit Definitions
+
+const UNITS = {
+0: { name_de: 'Dimensionslos', symb_de: '',name_en: 'Dimensionless', symb_en: '', decimals: 0 },
+1: { name_de: 'Temperatur °C', symb_de: '°C',name_en: 'Temperature °C', symb_en: '°C', decimals: 1 },
+2: { name_de: 'Solarstrahlung', symb_de: 'W/m²',name_en: 'Solar radiation', symb_en: 'W/m²', decimals: 0 },
+3: { name_de: 'Durchfluss l/h', symb_de: 'l/h',name_en: 'Flow rate l/h', symb_en: 'l/h', decimals: 0 },
+4: { name_de: 'Sekunden', symb_de: 'Sek',name_en: 'Seconds', symb_en: 'sec', decimals: 0 },
+5: { name_de: 'Minuten', symb_de: 'Min',name_en: 'Minutes', symb_en: 'min', decimals: 0 },
+6: { name_de: 'Durchfluss l/Imp', symb_de: 'l/Imp',name_en: 'Flow rate l/Imp', symb_en: 'l/Imp', decimals: 1 },
+7: { name_de: 'Temperatur', symb_de: 'K',name_en: 'Temperature', symb_en: 'K', decimals: 1 },
+8: { name_de: 'Prozent', symb_de: '%',name_en: 'Percent', symb_en: '%', decimals: 1 },
+10: { name_de: 'Leistung kW', symb_de: 'kW',name_en: 'Power kW', symb_en: 'kW', decimals: 1 },
+11: { name_de: 'Energie kWh', symb_de: 'kWh',name_en: 'Energy kWh', symb_en: 'kWh', decimals: 1 },
+12: { name_de: 'Energie MWh', symb_de: 'MWh',name_en: 'Energy MWh', symb_en: 'MWh', decimals: 0 },
+13: { name_de: 'Spannung', symb_de: 'V',name_en: 'Voltage', symb_en: 'V', decimals: 2 },
+14: { name_de: 'Stromstärke mA', symb_de: 'mA',name_en: 'Current mA', symb_en: 'mA', decimals: 1 },
+15: { name_de: 'Stunden', symb_de: 'Std',name_en: 'Hours', symb_en: 'hr', decimals: 0 },
+16: { name_de: 'Tage', symb_de: 'Tage',name_en: 'Days', symb_en: 'Days', decimals: 0 },
+17: { name_de: 'Anzahl Impulse', symb_de: 'Imp',name_en: 'Number of pulses', symb_en: 'Imp', decimals: 0 },
+18: { name_de: 'Widerstand', symb_de: 'kΩ',name_en: 'Resistance', symb_en: 'kΩ', decimals: 2 },
+19: { name_de: 'Liter', symb_de: 'l',name_en: 'Liters', symb_en: 'l', decimals: 0 },
+20: { name_de: 'Geschwindigkeit km/h', symb_de: 'km/h',name_en: 'Speed km/h', symb_en: 'km/h', decimals: 0 },
+21: { name_de: 'Frequenz', symb_de: 'Hz',name_en: 'Frequency', symb_en: 'Hz', decimals: 2 },
+22: { name_de: 'Durchfluss l/min', symb_de: 'l/min',name_en: 'Flow rate l/min', symb_en: 'l/min', decimals: 0 },
+23: { name_de: 'Druck bar', symb_de: 'bar',name_en: 'Pressure bar', symb_en: 'bar', decimals: 2 },
+24: { name_de: 'Arbeitszahl', symb_de: '',name_en: 'COP', symb_en: '', decimals: 2 },
+25: { name_de: 'Länge km', symb_de: 'km',name_en: 'Length km', symb_en: 'km', decimals: 0 },
+26: { name_de: 'Länge m', symb_de: 'm',name_en: 'Length m', symb_en: 'm', decimals: 1 },
+27: { name_de: 'Länge mm', symb_de: 'mm',name_en: 'Length mm', symb_en: 'mm', decimals: 1 },
+28: { name_de: 'Kubikmeter', symb_de: 'm³',name_en: 'Cubic meters', symb_en: 'm³', decimals: 0 },
+35: { name_de: 'Durchfluss l/d', symb_de: 'l/d',name_en: 'Flow rate l/d', symb_en: 'l/d', decimals: 0 },
+36: { name_de: 'Geschwindigkeit m/s', symb_de: 'm/s',name_en: 'Speed m/s', symb_en: 'm/s', decimals: 0 },
+37: { name_de: 'Durchfluss m³/min', symb_de: 'm³/min',name_en: 'Flow rate m³/min', symb_en: 'm³/min', decimals: 0 },
+38: { name_de: 'Durchfluss m³/h', symb_de: 'm³/h',name_en: 'Flow rate m³/h', symb_en: 'm³/h', decimals: 0 },
+39: { name_de: 'Durchfluss m³/d', symb_de: 'm³/d',name_en: 'Flow rate m³/d', symb_en: 'm³/d', decimals: 0 },
+40: { name_de: 'Geschwindigkeit mm/min', symb_de: 'mm/min',name_en: 'Speed mm/min', symb_en: 'mm/min', decimals: 0 },
+41: { name_de: 'Geschwindigkeit mm/h', symb_de: 'mm/h',name_en: 'Speed mm/h', symb_en: 'mm/h', decimals: 0 },
+42: { name_de: 'Geschwindigkeit mm/d', symb_de: 'mm/d',name_en: 'Speed mm/d', symb_en: 'mm/d', decimals: 0 },
+43: { name_de: 'Digital (aus/ein)', symb_de: 'Aus/Ein',name_en: 'Digital (off/on)', symb_en: 'Off/On', decimals: 0 },
+44: { name_de: 'Digital (nein/ja)', symb_de: 'Nein/Ja',name_en: 'Digital (no/yes)', symb_en: 'No/Yes', decimals: 0 },
+46: { name_de: 'RAS', symb_de: '°C',name_en: 'RAS', symb_en: '°C', decimals: 1 },
+50: { name_de: 'Euro', symb_de: '€',name_en: 'Euro', symb_en: '€', decimals: 2 },
+51: { name_de: 'Dollar', symb_de: '$',name_en: 'Dollar', symb_en: '$', decimals: 2 },
+52: { name_de: 'Absolute Feuchte', symb_de: 'g/m³',name_en: 'Absolute humidity', symb_en: 'g/m³', decimals: 1 },
+53: { name_de: 'Dimensionslos(,5)', symb_de: '',name_en: 'Dimensional (.5)', symb_en: '', decimals: 5 },
+54: { name_de: 'Grad (Winkel)', symb_de: '°',name_en: 'Degrees (Angle)', symb_en: '°', decimals: 1 },
+56: { name_de: 'Grad (1/100 .6)', symb_de: '°',name_en: 'Degrees (.6)', symb_en: '°', decimals: 6 },
+57: { name_de: 'Sekunden', symb_de: 's',name_en: 'Seconds', symb_en: 's', decimals: 1 },
+58: { name_de: 'Dimensionslos(,1)', symb_de: '',name_en: 'Dimensional (.1)', symb_en: '', decimals: 1 },
+59: { name_de: 'Prozent (,0)', symb_de: '%',name_en: 'Percent (.0)', symb_en: '%', decimals: 0 },
+60: { name_de: 'Uhrzeit', symb_de: 'h',name_en: 'Time', symb_en: 'h', decimals: 0 },
+63: { name_de: 'Stromstärke A', symb_de: 'A',name_en: 'Current A', symb_en: 'A', decimals: 1 },
+65: { name_de: 'Druck mbar', symb_de: 'mbar',name_en: 'Pressure mbar', symb_en: 'mbar', decimals: 1 },
+66: { name_de: 'Druck Pa', symb_de: 'Pa',name_en: 'Pressure Pa', symb_en: 'Pa', decimals: 0 },
+67: { name_de: 'CO2-Gehalt ppm', symb_de: 'ppm',name_en: 'CO2 content ppm', symb_en: 'ppm', decimals: 0 },
+68: { name_de: '', symb_de: '',name_en: '', symb_en: '', decimals: 0 },
+69: { name_de: 'Leistung W', symb_de: 'W',name_en: 'Power W', symb_en: 'W', decimals: 0 },
+70: { name_de: 'Gewicht t', symb_de: 't',name_en: 'Weight t', symb_en: 't', decimals: 2 },
+71: { name_de: 'Gewicht kg', symb_de: 'kg',name_en: 'Weight kg', symb_en: 'kg', decimals: 1 },
+72: { name_de: 'Gewicht g', symb_de: 'g',name_en: 'Weight g', symb_en: 'g', decimals: 1 },
+73: { name_de: 'Länge cm', symb_de: 'cm',name_en: 'Length cm', symb_en: 'cm', decimals: 1 },
+74: { name_de: 'Temperatur K', symb_de: 'K',name_en: 'Temperature K', symb_en: 'K', decimals: 0 },
+75: { name_de: 'Lichtstärke', symb_de: 'lx',name_en: 'Light intensity', symb_en: 'lx', decimals: 1 },
+76: { name_de: 'Radonkonzentration', symb_de: 'Bq/m³',name_en: 'Radon concentration', symb_en: 'Bq/m³', decimals: 0 },
+77: { name_de: 'Preis ct/kWh', symb_de: 'ct/kWh',name_en: 'Price ct/kWh', symb_en: 'ct/kWh', decimals: 3 },
+78: { name_de: 'Digital (geschl./offen)', symb_de: 'Geschlossen/Offen',name_en: 'Digital (closed/open)', symb_en: 'Closed/Open', decimals: 0 }
+};
+
+module.exports = UNITS;

package/lib/utils.js

@@ -0,0 +1,163 @@
+/**
+ * CoE Utilities Module (used internally by nodes)
+ * 
+ * Copyright 2025 Florian Mayrhofer
+ * Licensed under the Apache License, Version 2.0
+ *
+ */ 
+
+const UNITS = require ('./units.js');
+
+// Utilities for unit conversion
+function convertCoEToValue(rawValue, unitId, protocolVersion) {
+    const unitDecimals = getUnitDecimals(unitId, protocolVersion);
+    return rawValue / Math.pow(10, unitDecimals);
+}
+
+function convertValueToCoE(value, unitId, protocolVersion) {
+    const unitDecimals = getUnitDecimals(unitId, protocolVersion);
+    return Math.round(value * Math.pow(10, unitDecimals));
+}
+
+// Retrieves unit name, symbol from unit list
+function getUnitInfo(unitId, langCode) {
+    const useGerman = (getUnitLanguage(langCode) === "de");
+    const idKey = String(unitId);
+
+    // Use UNITS from units.js as base
+    if (UNITS && UNITS[idKey]) { 
+        const unit = UNITS[idKey];
+        return {
+            name: useGerman ? unit.name_de : unit.name_en,
+            symbol: useGerman ? unit.symb_de : unit.symb_en
+        };
+    } else {
+        return {
+            name: `Unknown (${idKey})`,
+            symbol: ''
+        };
+    }
+}
+
+// Retrieve unit decimals from unit list
+function getUnitDecimals(unitId, protocolVersion) {
+    let unitDecimals;
+    const unitKey = String(unitId); 
+    
+    if (UNITS && UNITS[unitKey]) {
+        unitDecimals = UNITS[unitKey].decimals;
+    } else {
+        unitDecimals = 0;
+    }
+    
+    // V2 specific overrides
+    if (protocolVersion === 2) {
+        const v2_Overrides = {
+            10: { decimals: 2 }  // Power kW: V1=1, V2=2 decimals
+            // Add more overrides if needed
+        };
+        
+        if (v2_Overrides[unitId]) {
+            unitDecimals = v2_Overrides[unitId].decimals;
+        }
+    }
+    return unitDecimals;
+}
+
+// Determine unit language code
+function getUnitLanguage(lang) {
+    if (lang.toLowerCase().startsWith("de")) {
+        return "de";
+    }
+    return "en";
+}
+
+// Translate output number to block position (CoE V1)
+function getBlockInfo(dataType, outputNumber) {
+    outputNumber = parseInt(outputNumber);
+    if (isNaN(outputNumber) || outputNumber < 1) {
+        // Default to block 1 position 0
+        return { block: 1, position: 0 };
+    }
+
+    if (dataType === 'analog') {
+        // Analog: Outputs 1..32 → Blocks 1..8 (4 Outputs each)
+        const block = Math.floor((outputNumber - 1) / 4) + 1; // 1..8
+        const position = (outputNumber - 1) % 4; // 0..3
+        return { block: block, position: position };
+    } else {
+        // Digital: Outputs 1..16 → Block 0, 17..32 → Block 9
+        if (outputNumber <= 16) {
+            return { block: 0, position: outputNumber - 1 }; // 0..15
+        } else {
+            return { block: 9, position: outputNumber - 17 }; // 0..15
+        }
+    }
+}
+
+// Merge incoming (V2) block data with LKGV (Last Known Good Values)
+function mergeBlockData(currentState, newBlock) {
+    const isDigital = newBlock.dataType === 'digital' || newBlock.blockNumber === 0 || newBlock.blockNumber === 9;
+    const numValues = isDigital ? 16 : 4;
+    
+    const updatedBlock = { // Initialize the updated block (copy)
+        ...currentState,
+        values: new Array(numValues).fill(undefined),
+        units: isDigital ? null : new Array(numValues).fill(undefined)
+    };
+
+    const oldValues = currentState.values || [];
+    const oldUnits = currentState.units || [];
+
+    for (let i = 0; i < numValues; i++) { // Copy the old LKGV (Last Known Good Values)
+        if (oldValues[i] !== undefined) {
+                updatedBlock.values[i] = oldValues[i];
+        }
+    }
+
+    if (!isDigital && updatedBlock.units && oldUnits) { // Copy old units
+        for (let i = 0; i < 4; i++) {
+            if (oldUnits[i] !== undefined) {
+                updatedBlock.units[i] = oldUnits[i];
+            }
+        }
+    }
+
+    for (let i = 0; i < numValues; i++) { // Merge with the new (sparse V2) values
+        if (newBlock.values && newBlock.values[i] !== undefined) {
+            updatedBlock.values[i] = newBlock.values[i];
+        }
+    }
+
+    if (!isDigital && updatedBlock.units && newBlock.units) { // Merge the new units (only analog)
+        for (let i = 0; i < 4; i++) {
+            if (newBlock.units[i] !== undefined) {
+                updatedBlock.units[i] = newBlock.units[i];
+            }
+        }
+    }
+
+    return updatedBlock;
+}
+
+// Create empty block state (incoming block)
+function createEmptyState(incomingBlock) {
+    const isDigital = incomingBlock.dataType === 'digital' || incomingBlock.blockNumber === 0 || incomingBlock.blockNumber === 9;
+    const numValues = isDigital ? 16 : 4;
+    return {
+        nodeNumber: incomingBlock.nodeNumber,
+        blockNumber: incomingBlock.blockNumber,
+        dataType: isDigital ? 'digital' : 'analog',
+        values: new Array(numValues).fill(undefined),
+        units: isDigital ? null : new Array(numValues).fill(undefined),
+    };
+}
+
+module.exports = {
+    convertCoEToValue,
+    convertValueToCoE,
+    getUnitInfo,
+    getBlockInfo,
+    mergeBlockData,
+    createEmptyState
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "node-red-contrib-ta-cmi-coe",
+  "version": "1.0.0",
+  "description": "Node-RED nodes for TA CMI CoE (CAN over Ethernet)",
+  "author": "Florian Mayrhofer",
+  "license": "Apache-2.0",
+  "keywords": [
+    "node-red",
+    "technische-alternative",
+    "ta",
+    "cmi",
+    "coe",
+    "can-over-ethernet",
+    "uvr",
+    "heating",
+    "automation"
+  ],
+  "node-red": {
+    "nodes": {
+      "coe-input": "coe/coe-input.js",
+      "coe-output": "coe/coe-output.js",
+      "coe-monitor": "coe/coe-monitor.js",
+      "cmiconfig": "coe/config.js",
+      "units-config": "coe/units-config.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mayflo/node-red-contrib-ta-cmi-coe.git"
+  },
+  "scripts": {
+    "test": "jest"
+  }
+}