iobroker.utility-monitor 1.5.0 → 1.6.1

package/lib/calculator.js

@@ -1,23 +1,34 @@
 const helpers = require('./utils/helpers');
 
 /**
- * Converts gas volume from m³ to kWh
- * Formula: kWh = m³ × Brennwert × Z-Zahl
+ * @file Calculator module for utility consumption and cost calculations.
+ * Contains functions for gas conversion, cost calculation, and tariff handling.
+ * @module calculator
+ */
+
+/**
+ * Converts gas volume from cubic meters (m³) to kilowatt-hours (kWh).
+ * The conversion uses the standard German gas billing formula:
+ * kWh = m³ × Brennwert (calorific value) × Z-Zahl (state number)
+ * Brennwert: Energy content per cubic meter, typically 9.5-11.5 kWh/m³.
+ * Z-Zahl: Correction factor for temperature and pressure differences.
  *
- * @param {number} m3 - Volume in cubic meters
- * @param {number} brennwert - Calorific value (typically ~11.5 kWh/m³)
- * @param {number} zZahl - Z-number/state number (typically ~0.95)
- * @returns {number} Energy in kWh
+ * @param {number} m3 - Gas volume in cubic meters (must be >= 0)
+ * @param {number} brennwert - Calorific value in kWh/m³ (must be > 0)
+ * @param {number} zZahl - State number (must be > 0 and <= 1)
+ * @returns {number} Energy consumption in kWh
+ * @throws {RangeError} If parameters are outside valid ranges
  */
 function convertGasM3ToKWh(m3, brennwert = 11.5, zZahl = 0.95) {
-    // Hier number zu string
     const cleanM3 = helpers.ensureNumber(m3);
     const cleanBrennwert = helpers.ensureNumber(brennwert);
     const cleanZZahl = helpers.ensureNumber(zZahl);
 
-    // Validierung der Logik (jetzt mit den konvertierten Zahlen)
+    // Validate parameters
     if (cleanM3 < 0 || cleanBrennwert <= 0 || cleanZZahl <= 0 || cleanZZahl > 1) {
-        throw new RangeError('Ungültige Parameterwerte für die Gas-Umrechnung');
+        throw new RangeError(
+            'Invalid parameters for gas conversion: m3 must be >= 0, brennwert must be > 0, zZahl must be > 0 and <= 1',
+        );
     }
 
     return cleanM3 * cleanBrennwert * cleanZZahl;
@@ -53,11 +64,14 @@ function calculateCost(consumption, price) {
 }
 
 /**
- * Checks if the current time is within the High Tariff (HT) period
+ * Checks if the current time falls within the High Tariff (HT) period.
+ * German electricity providers often offer dual-tariff rates:
+ * HT (Haupttarif): Higher rate during peak hours (typically 6:00-22:00)
+ * NT (Nebentarif): Lower rate during off-peak hours (typically 22:00-6:00)
  *
- * @param {object} config - Adapter configuration
- * @param {string} type - Utility type: 'gas' or 'strom'
- * @returns {boolean} True if current time is HT, false if NT
+ * @param {object} config - Adapter configuration object with HT/NT settings
+ * @param {string} type - Utility type identifier: 'gas', 'strom', 'wasser', or 'pv'
+ * @returns {boolean} True if current time is within HT period, false for NT
  */
 function isHTTime(config, type) {
     if (!config || !type) {

package/lib/multiMeterManager.js

@@ -227,7 +227,7 @@ class MultiMeterManager {
         const timestampRoles = ['lastDayStart', 'lastWeekStart', 'lastMonthStart', 'lastYearStart'];
 
         for (const role of timestampRoles) {
-            const statePath = `${basePath}.statistics.${role}`;
+            const statePath = `${basePath}.statistics.timestamps.${role}`;
             const state = await this.adapter.getStateAsync(statePath);
 
             if (role === 'lastYearStart') {
@@ -307,9 +307,148 @@ class MultiMeterManager {
         // Initial cost calculation
         await this.updateCosts(type, meterName, config);
 
+        // Reconstruct weekly consumption from daily values if needed
+        await this.reconstructPeriodConsumption(type, meterName, basePath);
+
         this.adapter.log.debug(`Meter initialization completed for ${type}.${meterName}`);
     }
 
+    /**
+     * Reconstructs weekly and monthly consumption values after adapter restart
+     * This fixes data loss when adapter was offline and missed delta accumulation
+     *
+     * @param {string} type - Utility type
+     * @param {string} meterName - Meter name
+     * @param {string} basePath - State base path
+     */
+    async reconstructPeriodConsumption(type, meterName, basePath) {
+        const now = Date.now();
+
+        // Get period start timestamps
+        const lastWeekStartState = await this.adapter.getStateAsync(`${basePath}.statistics.timestamps.lastWeekStart`);
+        const lastDayStartState = await this.adapter.getStateAsync(`${basePath}.statistics.timestamps.lastDayStart`);
+
+        if (!lastWeekStartState?.val || !lastDayStartState?.val) {
+            this.adapter.log.debug(`[${basePath}] No period timestamps found, skipping reconstruction`);
+            return;
+        }
+
+        const lastWeekStart = lastWeekStartState.val;
+        const lastDayStart = lastDayStartState.val;
+
+        // Calculate days since week start
+        const daysSinceWeekStart = (now - lastWeekStart) / (24 * 60 * 60 * 1000);
+
+        // Only reconstruct if we're within a valid week (0-7 days)
+        if (daysSinceWeekStart < 0 || daysSinceWeekStart > 7) {
+            this.adapter.log.debug(
+                `[${basePath}] Week period out of range (${daysSinceWeekStart.toFixed(1)} days), skipping reconstruction`,
+            );
+            return;
+        }
+
+        // Get current consumption values
+        const weeklyState = await this.adapter.getStateAsync(`${basePath}.consumption.weekly`);
+        const dailyState = await this.adapter.getStateAsync(`${basePath}.consumption.daily`);
+        const lastDayState = await this.adapter.getStateAsync(`${basePath}.statistics.consumption.lastDay`);
+
+        const currentWeekly = weeklyState?.val || 0;
+        const currentDaily = dailyState?.val || 0;
+        const lastDay = lastDayState?.val || 0;
+
+        // Calculate expected weekly based on lastDay values accumulated since lastWeekStart
+        // Simple approach: If daily counter was reset today and we have lastDay,
+        // weekly should be at least lastDay + currentDaily
+        const daysSinceDayReset = (now - lastDayStart) / (24 * 60 * 60 * 1000);
+
+        // If daily was reset (daysSinceDayReset < 1) and weekly seems too low
+        if (daysSinceDayReset < 1 && currentWeekly < lastDay + currentDaily) {
+            // Weekly might have missed the lastDay value
+            // This can happen if adapter restarted after daily reset
+            const reconstructedWeekly = calculator.roundToDecimals(currentWeekly + lastDay, 2);
+
+            if (reconstructedWeekly > currentWeekly) {
+                this.adapter.log.info(
+                    `[${basePath}] Reconstructing weekly: ${currentWeekly} -> ${reconstructedWeekly} (added lastDay: ${lastDay})`,
+                );
+                await this.adapter.setStateAsync(`${basePath}.consumption.weekly`, reconstructedWeekly, true);
+
+                // Also reconstruct gas volume if applicable
+                if (type === 'gas') {
+                    const weeklyVolumeState = await this.adapter.getStateAsync(`${basePath}.consumption.weeklyVolume`);
+                    const lastDayVolumeState = await this.adapter.getStateAsync(
+                        `${basePath}.statistics.consumption.lastDayVolume`,
+                    );
+                    const currentWeeklyVolume = weeklyVolumeState?.val || 0;
+                    const lastDayVolume = lastDayVolumeState?.val || 0;
+
+                    if (lastDayVolume > 0) {
+                        const reconstructedWeeklyVolume = calculator.roundToDecimals(
+                            currentWeeklyVolume + lastDayVolume,
+                            4,
+                        );
+                        await this.adapter.setStateAsync(
+                            `${basePath}.consumption.weeklyVolume`,
+                            reconstructedWeeklyVolume,
+                            true,
+                        );
+                    }
+                }
+            }
+        }
+
+        // Similar logic for monthly reconstruction
+        const lastMonthStartState = await this.adapter.getStateAsync(
+            `${basePath}.statistics.timestamps.lastMonthStart`,
+        );
+        if (lastMonthStartState?.val) {
+            const lastMonthStart = lastMonthStartState.val;
+            const daysSinceMonthStart = (now - lastMonthStart) / (24 * 60 * 60 * 1000);
+
+            // Only if within valid month range (0-31 days)
+            if (daysSinceMonthStart >= 0 && daysSinceMonthStart <= 31) {
+                const monthlyState = await this.adapter.getStateAsync(`${basePath}.consumption.monthly`);
+                const currentMonthly = monthlyState?.val || 0;
+
+                // If daily was reset and monthly seems to be missing the lastDay
+                if (daysSinceDayReset < 1 && currentMonthly < lastDay + currentDaily) {
+                    const reconstructedMonthly = calculator.roundToDecimals(currentMonthly + lastDay, 2);
+
+                    if (reconstructedMonthly > currentMonthly) {
+                        this.adapter.log.info(
+                            `[${basePath}] Reconstructing monthly: ${currentMonthly} -> ${reconstructedMonthly} (added lastDay: ${lastDay})`,
+                        );
+                        await this.adapter.setStateAsync(`${basePath}.consumption.monthly`, reconstructedMonthly, true);
+
+                        // Also reconstruct gas volume if applicable
+                        if (type === 'gas') {
+                            const monthlyVolumeState = await this.adapter.getStateAsync(
+                                `${basePath}.consumption.monthlyVolume`,
+                            );
+                            const lastDayVolumeState = await this.adapter.getStateAsync(
+                                `${basePath}.statistics.consumption.lastDayVolume`,
+                            );
+                            const currentMonthlyVolume = monthlyVolumeState?.val || 0;
+                            const lastDayVolume = lastDayVolumeState?.val || 0;
+
+                            if (lastDayVolume > 0) {
+                                const reconstructedMonthlyVolume = calculator.roundToDecimals(
+                                    currentMonthlyVolume + lastDayVolume,
+                                    4,
+                                );
+                                await this.adapter.setStateAsync(
+                                    `${basePath}.consumption.monthlyVolume`,
+                                    reconstructedMonthlyVolume,
+                                    true,
+                                );
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     /**
      * Handles sensor value updates
      *
@@ -463,6 +602,10 @@ class MultiMeterManager {
         if (recoveredValue > 0 && Math.abs(consumption - recoveredValue) < 100) {
             this.adapter.log.info(`[${basePath}] Recovered persistent baseline: ${recoveredValue}`);
             this.lastSensorValues[sensorDP] = recoveredValue;
+
+            // Validate period consumption values against spike threshold
+            // This catches cases where old consumption values are unrealistically high
+            await this._validatePeriodConsumption(type, basePath, now);
         } else {
             if (recoveredValue > 0) {
                 this.adapter.log.warn(
@@ -479,6 +622,9 @@ class MultiMeterManager {
                 await this.adapter.setStateAsync(`${basePath}.info.meterReadingVolume`, consumptionM3 || 0, true);
             }
 
+            // On baseline reset, validate and potentially reset period consumption values
+            await this._validatePeriodConsumption(type, basePath, now);
+
             if (config.initialReading > 0) {
                 await this.calculateAbsoluteYearly(type, meterName, config, consumption, consumptionM3 || 0, now);
                 await this.updateCosts(type, meterName, config);
@@ -489,6 +635,50 @@ class MultiMeterManager {
         await this.adapter.setStateAsync(`${basePath}.consumption.lastUpdate`, now, true);
     }
 
+    /**
+     * Validates period consumption values and resets them if they exceed the spike threshold.
+     * This prevents unrealistic values after adapter restart or database inconsistencies.
+     *
+     * @param {string} type - Utility type
+     * @param {string} basePath - State base path
+     * @param {number} now - Current timestamp
+     */
+    async _validatePeriodConsumption(type, basePath, now) {
+        const spikeThreshold = this.adapter.config.sensorSpikeThreshold || DEFAULT_SPIKE_THRESHOLD;
+
+        // Check and reset period consumption values that exceed the spike threshold
+        const periods = ['daily', 'weekly', 'monthly'];
+        for (const period of periods) {
+            const state = await this.adapter.getStateAsync(`${basePath}.consumption.${period}`);
+            const value = state?.val || 0;
+
+            // Get period start timestamp to calculate expected max consumption
+            const periodKey =
+                period === 'daily' ? 'Day' : period === 'weekly' ? 'Week' : period === 'monthly' ? 'Month' : 'Year';
+            const periodStartState = await this.adapter.getStateAsync(
+                `${basePath}.statistics.timestamps.last${periodKey}Start`,
+            );
+            const periodStart = periodStartState?.val || now;
+            const daysSincePeriodStart = (now - periodStart) / (24 * 60 * 60 * 1000);
+
+            // Calculate reasonable max: spike threshold per day * days in period
+            // Add buffer of 2x for safety
+            const maxReasonableConsumption = spikeThreshold * Math.max(1, daysSincePeriodStart) * 2;
+
+            if (value > maxReasonableConsumption) {
+                this.adapter.log.warn(
+                    `[${basePath}] Resetting ${period} consumption: ${value} exceeds reasonable max of ${maxReasonableConsumption.toFixed(0)} (${daysSincePeriodStart.toFixed(1)} days * ${spikeThreshold} threshold * 2)`,
+                );
+                await this.adapter.setStateAsync(`${basePath}.consumption.${period}`, 0, true);
+
+                // Also reset volume states for gas
+                if (type === 'gas') {
+                    await this.adapter.setStateAsync(`${basePath}.consumption.${period}Volume`, 0, true);
+                }
+            }
+        }
+    }
+
     /**
      * Handles meter reset or replacement condition
      *
@@ -798,7 +988,7 @@ class MultiMeterManager {
      * @returns {Promise<number>} Months since start (at least 1)
      */
     async _calculateMonthsSinceYearStart(basePath) {
-        const yearStartState = await this.adapter.getStateAsync(`${basePath}.statistics.lastYearStart`);
+        const yearStartState = await this.adapter.getStateAsync(`${basePath}.statistics.timestamps.lastYearStart`);
         let monthsSinceYearStart = 1;
 
         if (yearStartState && yearStartState.val) {

package/lib/state/history.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const STATE_ROLES = require('./roles');
+
+/**
+ * Creates history structure for a specific year
+ *
+ * @param {object} adapter - The adapter instance
+ * @param {string} type - 'gas', 'water', 'electricity', 'pv'
+ * @param {string} meterName - Meter name
+ * @param {number|string} year - Year (YYYY)
+ * @returns {Promise<void>}
+ */
+async function createHistoryStructure(adapter, type, meterName, year) {
+    const basePath = `${type}.${meterName}.history.${year}`;
+
+    await adapter.setObjectNotExistsAsync(`${type}.${meterName}.history`, {
+        type: 'channel',
+        common: { name: 'Historie' },
+        native: {},
+    });
+
+    await adapter.setObjectNotExistsAsync(basePath, {
+        type: 'channel',
+        common: { name: `Jahr ${year}` },
+        native: { year },
+    });
+
+    let consumptionUnit = 'kWh';
+    if (type === 'water') {
+        consumptionUnit = 'm³';
+    } else if (type === 'gas') {
+        consumptionUnit = 'kWh';
+    }
+
+    await adapter.setObjectNotExistsAsync(`${basePath}.consumption`, {
+        type: 'state',
+        common: {
+            name: `Jahresverbrauch ${year} (${consumptionUnit})`,
+            type: 'number',
+            role: STATE_ROLES.consumption,
+            read: true,
+            write: false,
+            unit: consumptionUnit,
+            def: 0,
+        },
+        native: {},
+    });
+
+    if (type === 'gas') {
+        await adapter.setObjectNotExistsAsync(`${basePath}.volume`, {
+            type: 'state',
+            common: {
+                name: `Jahresverbrauch ${year} (m³)`,
+                type: 'number',
+                role: STATE_ROLES.consumption,
+                read: true,
+                write: false,
+                unit: 'm³',
+                def: 0,
+            },
+            native: {},
+        });
+    }
+
+    await adapter.setObjectNotExistsAsync(`${basePath}.costs`, {
+        type: 'state',
+        common: {
+            name: `Jahreskosten ${year} (€)`,
+            type: 'number',
+            role: STATE_ROLES.cost,
+            read: true,
+            write: false,
+            unit: '€',
+            def: 0,
+        },
+        native: {},
+    });
+
+    await adapter.setObjectNotExistsAsync(`${basePath}.balance`, {
+        type: 'state',
+        common: {
+            name: `Bilanz ${year} (€)`,
+            type: 'number',
+            role: STATE_ROLES.cost,
+            read: true,
+            write: false,
+            unit: '€',
+            def: 0,
+        },
+        native: {},
+    });
+}
+
+module.exports = createHistoryStructure;