iobroker.utility-monitor 1.4.6 → 1.5.1

package/lib/utils/billingHelper.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const calculator = require('../calculator');
+
+/**
+ * Shared billing and cost calculation logic
+ */
+
+/**
+ * Calculates accumulated basic charges over a period
+ *
+ * @param {number} monthlyFee - Monthly basic charge
+ * @param {number} annualFee - Fixed annual fee
+ * @param {number} months - Number of months since contract start
+ * @returns {object} { basicCharge, annualFee, total }
+ */
+function calculateAccumulatedCharges(monthlyFee, annualFee, months) {
+    const basicCharge = (monthlyFee || 0) * months;
+    const annual = annualFee || 0;
+    return {
+        basicCharge: calculator.roundToDecimals(basicCharge, 2),
+        annualFee: calculator.roundToDecimals(annual, 2),
+        total: calculator.roundToDecimals(basicCharge + annual, 2),
+    };
+}
+
+/**
+ * Calculates total paid and balance
+ *
+ * @param {number} monthlyAbschlag - Monthly installment
+ * @param {number} months - Months since start
+ * @param {number} totalCosts - Total costs calculated
+ * @returns {object} { paid, balance }
+ */
+function calculateBalance(monthlyAbschlag, months, totalCosts) {
+    const paid = (monthlyAbschlag || 0) * months;
+    const balance = totalCosts > 0.01 || paid > 0.01 ? paid - totalCosts : 0;
+
+    return {
+        paid: calculator.roundToDecimals(paid, 2),
+        balance: calculator.roundToDecimals(balance, 2),
+    };
+}
+
+/**
+ * Calculates costs for HT/NT split
+ *
+ * @param {number} htQty - High tariff quantity
+ * @param {number} htPrice - High tariff price
+ * @param {number} ntQty - Low tariff quantity
+ * @param {number} ntPrice - Low tariff price
+ * @returns {object} { htCosts, ntCosts, total }
+ */
+function calculateHTNTCosts(htQty, htPrice, ntQty, ntPrice) {
+    const ht = (htQty || 0) * (htPrice || 0);
+    const nt = (ntQty || 0) * (ntPrice || 0);
+
+    return {
+        htCosts: calculator.roundToDecimals(ht, 2),
+        ntCosts: calculator.roundToDecimals(nt, 2),
+        total: calculator.roundToDecimals(ht + nt, 2),
+    };
+}
+
+module.exports = {
+    calculateAccumulatedCharges,
+    calculateBalance,
+    calculateHTNTCosts,
+};

package/lib/utils/consumptionHelper.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const calculator = require('../calculator');
+
+/**
+ * Shared consumption logic for different managers
+ */
+
+/**
+ * Calculates gas energy (kWh) and volume (m³)
+ *
+ * @param {number} value - Raw sensor value (m³)
+ * @param {number} brennwert - Calorific value
+ * @param {number} zZahl - Z-number
+ * @returns {object} { energy, volume }
+ */
+function calculateGas(value, brennwert, zZahl) {
+    const energy = calculator.convertGasM3ToKWh(value, brennwert, zZahl);
+    return {
+        energy: calculator.roundToDecimals(energy, 2),
+        volume: calculator.roundToDecimals(value, 2),
+    };
+}
+
+/**
+ * Returns the suffix (HT/NT) based on current time
+ *
+ * @param {object} config - Adapter config
+ * @param {string} type - Utility type (config name)
+ * @returns {string} 'HT', 'NT' or empty if disabled
+ */
+function getHTNTSuffix(config, type) {
+    if (!config || !type) {
+        return '';
+    }
+    const enabled = config[`${type}HtNtEnabled`];
+    if (!enabled) {
+        return '';
+    }
+
+    return calculator.isHTTime(config, type) ? 'HT' : 'NT';
+}
+
+module.exports = {
+    calculateGas,
+    getHTNTSuffix,
+};

package/lib/utils/helpers.js

@@ -0,0 +1,234 @@
+'use strict';
+
+/**
+ * Helper utilities for iobroker.utility-monitor
+ */
+
+/**
+ * Ensures a value is a number, handling German decimal commas if provided as string.
+ *
+ * @param {any} value - Value to convert
+ * @returns {number} The numeric value
+ */
+function ensureNumber(value) {
+    if (value === undefined || value === null || value === '') {
+        return 0;
+    }
+    if (typeof value === 'number') {
+        return isNaN(value) ? 0 : value;
+    }
+    if (typeof value === 'string') {
+        let normalized = value.trim();
+        // Handle common European formats: 1.234,56 -> 1234.56 or 1234,56 -> 1234.56
+        if (normalized.includes(',') && normalized.includes('.')) {
+            // Assume . is thousands and , is decimal
+            normalized = normalized.replace(/\./g, '').replace(',', '.');
+        } else if (normalized.includes(',')) {
+            // Assume , is decimal
+            normalized = normalized.replace(',', '.');
+        }
+        const parsed = parseFloat(normalized);
+        return isNaN(parsed) ? 0 : parsed;
+    }
+    const num = Number(value);
+    return isNaN(num) ? 0 : num;
+}
+
+/**
+ * Rounds a number to specified decimal places
+ *
+ * @param {number|string} value - Value to round
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @returns {number} Rounded value
+ */
+function roundToDecimals(value, decimals = 2) {
+    const numValue = ensureNumber(value);
+    const factor = Math.pow(10, decimals);
+    return Math.round(numValue * factor) / factor;
+}
+
+/**
+ * Parses a German date string (DD.MM.YYYY) into a Date object
+ *
+ * @param {string} dateStr - Date string in format DD.MM.YYYY
+ * @returns {Date|null} Date object or null if invalid
+ */
+function parseGermanDate(dateStr) {
+    if (!dateStr || typeof dateStr !== 'string') {
+        return null;
+    }
+
+    const trimmed = dateStr.trim();
+
+    // 1. Try German format (DD.MM.YYYY)
+    if (trimmed.includes('.') && !trimmed.includes('-')) {
+        const parts = trimmed.split('.');
+        if (parts.length === 3) {
+            const day = parseInt(parts[0], 10);
+            const month = parseInt(parts[1], 10) - 1;
+            let year = parseInt(parts[2], 10);
+
+            if (year < 70) {
+                year += 2000;
+            } else if (year < 100) {
+                year += 1900;
+            }
+
+            if (!isNaN(day) && !isNaN(month) && !isNaN(year)) {
+                return new Date(year, month, day, 12, 0, 0);
+            }
+        }
+    }
+
+    // 2. Try ISO or other standard formats
+    const fallback = new Date(trimmed);
+    if (!isNaN(fallback.getTime())) {
+        return fallback;
+    }
+
+    return null;
+}
+
+/**
+ * Formats a Date object to YYYY-MM-DD HH:mm:ss string
+ *
+ * @param {Date} date - Date object
+ * @returns {string|null} Formatted date string or null
+ */
+function formatDateString(date) {
+    if (!date || !(date instanceof Date)) {
+        return null;
+    }
+
+    const pad = num => num.toString().padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+/**
+ * Checks if a year is a leap year
+ *
+ * @param {number} year - Year to check
+ * @returns {boolean} True if leap year
+ */
+function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+/**
+ * Calculates the difference in months between two dates
+ *
+ * @param {Date} startDate - Start date
+ * @param {Date} endDate - End date
+ * @returns {number} Difference in months
+ */
+function getMonthsDifference(startDate, endDate) {
+    if (!startDate || !endDate) {
+        return 0;
+    }
+    return (endDate.getFullYear() - startDate.getFullYear()) * 12 + (endDate.getMonth() - startDate.getMonth());
+}
+
+/**
+ * Normalizes a meter name to a valid ioBroker ID part
+ *
+ * @param {string} name - The name to normalize
+ * @returns {string} The normalized name
+ */
+function normalizeMeterName(name) {
+    if (!name) {
+        return 'unknown';
+    }
+
+    return name
+        .toLowerCase()
+        .replace(/ä/g, 'ae')
+        .replace(/ö/g, 'oe')
+        .replace(/ü/g, 'ue')
+        .replace(/ß/g, 'ss')
+        .replace(/[^a-z0-9]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '')
+        .substring(0, 32);
+}
+
+/**
+ * Safe wrapper for setObjectNotExistsAsync with error handling
+ *
+ * @param {object} adapter - Adapter instance
+ * @param {string} id - State ID
+ * @param {object} obj - Object definition
+ */
+async function safeSetObjectNotExists(adapter, id, obj) {
+    try {
+        await adapter.setObjectNotExistsAsync(id, obj);
+    } catch (e) {
+        adapter.log.error(`Error creating object ${id}: ${e.message}`);
+    }
+}
+
+/**
+ * Safe execution wrapper for async operations with error handling.
+ * Catches errors and logs them without crashing the adapter.
+ *
+ * @param {object} adapter - Adapter instance
+ * @param {Function} fn - Async function to execute
+ * @param {string} context - Context description for error logging
+ * @param {any} fallback - Fallback value to return on error
+ * @returns {Promise<any>} Result of fn() or fallback on error
+ */
+async function safeExecute(adapter, fn, context, fallback = null) {
+    try {
+        return await fn();
+    } catch (error) {
+        if (adapter && adapter.log) {
+            adapter.log.error(`[${context}] ${error.message}`);
+        }
+        return fallback;
+    }
+}
+
+/**
+ * Debounce function to limit execution frequency
+ *
+ * @param {Function} fn - Function to debounce
+ * @param {number} delay - Delay in milliseconds
+ * @returns {Function} Debounced function
+ */
+function debounce(fn, delay) {
+    let timeoutId;
+    return function (...args) {
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => fn.apply(this, args), delay);
+    };
+}
+
+/**
+ * Validates that a value is within a specified range
+ *
+ * @param {number} value - Value to validate
+ * @param {number} min - Minimum allowed value
+ * @param {number} max - Maximum allowed value
+ * @param {number} [defaultValue] - Default value if out of range
+ * @returns {number} Validated value or default
+ */
+function validateRange(value, min, max, defaultValue = min) {
+    const num = ensureNumber(value);
+    if (num < min || num > max) {
+        return defaultValue;
+    }
+    return num;
+}
+
+module.exports = {
+    ensureNumber,
+    roundToDecimals,
+    parseGermanDate,
+    formatDateString,
+    isLeapYear,
+    getMonthsDifference,
+    normalizeMeterName,
+    safeSetObjectNotExists,
+    safeExecute,
+    debounce,
+    validateRange,
+};

package/lib/utils/stateCache.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * StateCache - Provides caching for adapter state operations.
+ * Reduces database queries by caching state values during update cycles.
+ */
+class StateCache {
+    /**
+     * Creates a new StateCache instance
+     *
+     * @param {object} adapter - ioBroker adapter instance
+     * @param {object} [options] - Configuration options
+     * @param {number} [options.maxAge] - Maximum cache age in milliseconds (default: 60s)
+     * @param {number} [options.maxSize] - Maximum number of cached entries
+     */
+    constructor(adapter, options = {}) {
+        this.adapter = adapter;
+        this.cache = new Map();
+        this.maxAge = options.maxAge || 60000;
+        this.maxSize = options.maxSize || 1000;
+        this.hits = 0;
+        this.misses = 0;
+    }
+
+    /**
+     * Gets a state value, using cache if available
+     *
+     * @param {string} id - State ID
+     * @returns {Promise<any>} State value or null
+     */
+    async get(id) {
+        const cached = this.cache.get(id);
+        const now = Date.now();
+
+        if (cached && now - cached.timestamp < this.maxAge) {
+            this.hits++;
+            return cached.value;
+        }
+
+        this.misses++;
+        const state = await this.adapter.getStateAsync(id);
+        const value = state?.val ?? null;
+
+        this._set(id, value);
+        return value;
+    }
+
+    /**
+     * Gets a state object (with val, ack, ts), using cache if available
+     *
+     * @param {string} id - State ID
+     * @returns {Promise<object|null>} State object or null
+     */
+    async getState(id) {
+        const cached = this.cache.get(`${id}_state`);
+        const now = Date.now();
+
+        if (cached && now - cached.timestamp < this.maxAge) {
+            this.hits++;
+            return cached.value;
+        }
+
+        this.misses++;
+        const state = await this.adapter.getStateAsync(id);
+
+        this._set(`${id}_state`, state);
+        if (state) {
+            this._set(id, state.val);
+        }
+        return state;
+    }
+
+    /**
+     * Sets a state value and updates cache
+     *
+     * @param {string} id - State ID
+     * @param {any} value - Value to set
+     * @param {boolean} ack - Acknowledge flag
+     * @returns {Promise<void>}
+     */
+    async set(id, value, ack = true) {
+        await this.adapter.setStateAsync(id, value, ack);
+        this._set(id, value);
+    }
+
+    /**
+     * Internal method to add to cache
+     *
+     * @param {string} id - State ID
+     * @param {any} value - Value to cache
+     */
+    _set(id, value) {
+        // Evict oldest entries if cache is full
+        if (this.cache.size >= this.maxSize) {
+            const oldestKey = this.cache.keys().next().value;
+            this.cache.delete(oldestKey);
+        }
+
+        this.cache.set(id, {
+            value,
+            timestamp: Date.now(),
+        });
+    }
+
+    /**
+     * Clears the entire cache.
+     * Should be called at the end of each update cycle.
+     */
+    clear() {
+        this.cache.clear();
+    }
+
+    /**
+     * Invalidates a specific cache entry
+     *
+     * @param {string} id - State ID to invalidate
+     */
+    invalidate(id) {
+        this.cache.delete(id);
+        this.cache.delete(`${id}_state`);
+    }
+
+    /**
+     * Gets cache statistics
+     *
+     * @returns {object} Cache statistics
+     */
+    getStats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: total > 0 ? `${((this.hits / total) * 100).toFixed(1)}%` : '0%',
+            size: this.cache.size,
+        };
+    }
+
+    /**
+     * Resets cache statistics
+     */
+    resetStats() {
+        this.hits = 0;
+        this.misses = 0;
+    }
+}
+
+module.exports = StateCache;

package/lib/utils/typeMapper.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * Maps internal utility type to config/state name
+ *
+ * @param {string} type - gas, water, electricity, pv
+ * @returns {string} - gas, wasser, strom, pv
+ */
+function getConfigType(type) {
+    const mapping = {
+        electricity: 'strom',
+        water: 'wasser',
+        gas: 'gas',
+        pv: 'pv',
+    };
+    return mapping[type] || type;
+}
+
+module.exports = { getConfigType };

package/main.js

@@ -10,6 +10,8 @@ const ConsumptionManager = require('./lib/consumptionManager');
 const BillingManager = require('./lib/billingManager');
 const MessagingHandler = require('./lib/messagingHandler');
 const MultiMeterManager = require('./lib/multiMeterManager');
+const ImportManager = require('./lib/importManager');
+const calculator = require('./lib/calculator');
 
 class UtilityMonitor extends utils.Adapter {
     /**
@@ -29,6 +31,7 @@ class UtilityMonitor extends utils.Adapter {
         this.consumptionManager = new ConsumptionManager(this);
         this.billingManager = new BillingManager(this);
         this.messagingHandler = new MessagingHandler(this);
+        this.importManager = new ImportManager(this);
         this.multiMeterManager = null; // Initialized in onReady after other managers
 
         this.periodicTimers = {};
@@ -43,6 +46,9 @@ class UtilityMonitor extends utils.Adapter {
         // Initialize MultiMeterManager
         this.multiMeterManager = new MultiMeterManager(this, this.consumptionManager, this.billingManager);
 
+        // Validate configuration before starting
+        this.validateConfiguration();
+
         // Initialize each utility type based on configuration
         // Note: initializeUtility() internally calls multiMeterManager.initializeType()
         await this.initializeUtility('gas', this.config.gasAktiv);
@@ -82,16 +88,60 @@ class UtilityMonitor extends utils.Adapter {
         this.log.info('Nebenkosten-Monitor initialized successfully');
     }
 
+    /**
+     * Validates the adapter configuration and logs warnings for missing settings
+     */
+    validateConfiguration() {
+        const types = [
+            { key: 'gas', configKey: 'gas', label: 'Gas' },
+            { key: 'water', configKey: 'wasser', label: 'Wasser' },
+            { key: 'electricity', configKey: 'strom', label: 'Strom' },
+            { key: 'pv', configKey: 'pv', label: 'PV' },
+        ];
+
+        for (const type of types) {
+            const isActive = this.config[`${type.configKey}Aktiv`];
+            if (!isActive) {
+                continue;
+            }
+
+            // Check main meter contract start
+            const contractStart = this.config[`${type.configKey}ContractStart`];
+            if (!contractStart) {
+                this.log.warn(
+                    `${type.label}: Kein Vertragsbeginn konfiguriert! Für korrekte Jahresberechnungen und Abrechnungsperioden sollte ein Vertragsbeginn gesetzt werden.`,
+                );
+            }
+
+            // Check main meter sensor
+            const sensorDP = this.config[`${type.configKey}SensorDP`];
+            if (!sensorDP) {
+                this.log.warn(`${type.label}: Kein Sensor-Datenpunkt konfiguriert!`);
+            }
+
+            // Check additional meters
+            const additionalMeters = this.config[`${type.configKey}AdditionalMeters`];
+            if (Array.isArray(additionalMeters)) {
+                for (const meter of additionalMeters) {
+                    if (meter && meter.name) {
+                        if (!meter.contractStart) {
+                            this.log.warn(`${type.label} Zähler "${meter.name}": Kein Vertragsbeginn konfiguriert!`);
+                        }
+                        if (!meter.sensorDP) {
+                            this.log.warn(`${type.label} Zähler "${meter.name}": Kein Sensor-Datenpunkt konfiguriert!`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     // --- Delegation Methods (backward compatibility for internal calls) ---
 
     async initializeUtility(type, isActive) {
         return this.consumptionManager.initializeUtility(type, isActive);
     }
 
-    async handleSensorUpdate(type, sensorDP, value) {
-        return this.consumptionManager.handleSensorUpdate(type, sensorDP, value);
-    }
-
     async updateCurrentPrice(type) {
         return this.consumptionManager.updateCurrentPrice(type);
     }
@@ -253,9 +303,14 @@ class UtilityMonitor extends utils.Adapter {
         // Determine which utility this sensor belongs to
         // All meters (including main) are now handled by multiMeterManager
         if (this.multiMeterManager) {
-            const meterInfo = this.multiMeterManager.findMeterBySensor(id);
-            if (meterInfo && typeof state.val === 'number') {
-                await this.multiMeterManager.handleSensorUpdate(meterInfo.type, meterInfo.meterName, id, state.val);
+            const meters = this.multiMeterManager.findMeterBySensor(id);
+            if (meters.length > 0 && state.val != null) {
+                // Convert sensor value to number (handles strings, German commas, etc.)
+                const numValue = calculator.ensureNumber(state.val);
+                // Call handleSensorUpdate for each meter using this sensor
+                for (const meterInfo of meters) {
+                    await this.multiMeterManager.handleSensorUpdate(meterInfo.type, meterInfo.meterName, id, numValue);
+                }
                 return;
             }
         }
@@ -267,7 +322,11 @@ class UtilityMonitor extends utils.Adapter {
      * @param {Record<string, any>} obj - Message object from config
      */
     async onMessage(obj) {
-        await this.messagingHandler.handleMessage(obj);
+        if (obj.command === 'importCSV') {
+            await this.importManager.handleImportCSV(obj);
+        } else {
+            await this.messagingHandler.handleMessage(obj);
+        }
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iobroker.utility-monitor",
-  "version": "1.4.6",
+  "version": "1.5.1",
   "description": "Monitor gas, water, and electricity consumption with cost calculation",
   "author": {
     "name": "fischi87",
@@ -54,8 +54,14 @@
   },
   "main": "main.js",
   "files": [
-    "admin{,/!(src)/**}/!(tsconfig|tsconfig.*|.eslintrc).{json,json5}",
-    "admin{,/!(src)/**}/*.{html,css,png,svg,jpg,js}",
+    "admin/*.json",
+    "admin/*.json5",
+    "admin/*.png",
+    "admin/*.svg",
+    "admin/*.html",
+    "admin/*.js",
+    "admin/i18n/*.json",
+    "admin/custom/**",
     "lib/",
     "www/",
     "io-package.json",
@@ -63,7 +69,7 @@
     "main.js"
   ],
   "scripts": {
-    "test:js": "mocha --config test/mocharc.custom.json \"{!(node_modules|test)/**/*.test.js,*.test.js,test/**/*.test.js}\"",
+    "test:js": "mocha --config test/mocharc.custom.json \"{!(node_modules|test|admin)/**/*.test.js,*.test.js,test/**/*.test.js}\"",
     "test:package": "mocha test/package --exit",
     "test:integration": "mocha test/integration --exit",
     "test": "npm run test:js && npm run test:package",