iobroker.poolcontrol 1.3.9 → 1.3.10

package/README.md

@@ -188,6 +188,37 @@ New features are added regularly – please refer to the changelog.
 ---
 
 ## Changelog
+### 1.3.10 (2026-05-01)
+
+New: Photovoltaic Insights
+- Introduced a new analytics module `analytics.insights.photovoltaic`
+- Tracks PV-based pump runtime, energy usage and estimated savings
+- New helper: `photovoltaicInsightsHelper`
+- New states: inputs, calculation, results, debug
+- Includes summary outputs (text, JSON, HTML)
+- Fully integrated with i18n translations
+
+Improvement: Active Helper Handling
+- Added consistent `pump.active_helper` ownership handling for:
+  - photovoltaicHelper
+  - solarHelper
+  - solarExtendedHelper
+- Each helper now:
+  - sets its own identifier when controlling the pump
+  - releases it when stopping
+  - does not override other active helpers
+- Ensures correct priority handling and prevents conflicts
+
+Improvement: PV Runtime Evaluation
+- Photovoltaic runtime is now only counted when:
+  - PV surplus is active
+  - AND photovoltaicHelper actually owns the pump
+- Enables accurate runtime, energy and savings calculation
+
+Fix: PV Circulation Logic
+- Fixed issue where pump stopped despite `photovoltaic.ignore_on_circulation = false`
+- Circulation check is now only applied when explicitly enabled
+
 ### 1.3.9 (2026-04-24)
 
 - Fix: solarLogbookHelper no longer creates duplicate or unnecessary log entries (improved filtering & throttling logic)
@@ -219,11 +250,6 @@ frostHelper
 - Fixed critical i18n issue in solarInsightsHelper and solarLogbookHelper that could lead to instability or crashes
 - Switched translation handling to I18n.translate() for stable and consistent i18n behavior
 
-### 1.3.4 (2026-04-19)
-
-- Fixed critical i18n issue in solarInsightsHelper and solarLogbookHelper that could lead to instability or crashes
-- Switched translation handling to I18n.translate() for stable and consistent i18n behavior
-
 ## Support
 - [ioBroker Forum](https://forum.iobroker.net/)  
 - [GitHub Issues](https://github.com/DasBo1975/ioBroker.poolcontrol/issues)

package/io-package.json

@@ -1,8 +1,21 @@
 {
   "common": {
     "name": "poolcontrol",
-    "version": "1.3.9",
+    "version": "1.3.10",
     "news": {
+      "1.3.10": {
+        "en": "Added photovoltaic insights (runtime, energy, savings) with new analytics states and helper. Improved active_helper ownership handling across photovoltaic, solar and extended solar helpers. Fixed PV circulation logic when ignore_on_circulation is disabled.",
+        "de": "Photovoltaik-Einblicke (Laufzeit, Energie, Einsparungen) mit neuen Analysezuständen und Hilfsfunktionen hinzugefügt. Verbesserte Handhabung des Active_Helper-Besitzes für Photovoltaik-, Solar- und erweiterte Solar-Helfer. Die PV-Zirkulationslogik wurde korrigiert, wenn „ignore_on_circulation“ deaktiviert ist.",
+        "ru": "Добавлены данные по фотоэлектрической энергии (время работы, энергия, экономия) с новыми аналитическими состояниями и помощником. Улучшено управление владением active_helper для фотоэлектрических, солнечных и расширенных солнечных помощников. Исправлена ​​логика циркуляции PV, когда ignore_on_circulation отключен.",
+        "pt": "Adicionados insights fotovoltaicos (tempo de execução, energia, economia) com novos estados analíticos e auxiliares. Melhor gerenciamento de propriedade de active_helper em ajudantes fotovoltaicos, solares e solares estendidos. Lógica de circulação fotovoltaica corrigida quando ignore_on_circulation está desativado.",
+        "nl": "Fotovoltaïsche inzichten toegevoegd (runtime, energie, besparingen) met nieuwe analysestatussen en helper. Verbeterde afhandeling van active_helper-eigendom voor fotovoltaïsche, zonne-energie en uitgebreide zonne-helpers. Vaste PV-circulatielogica wanneer negeer_on_circulatie is uitgeschakeld.",
+        "fr": "Ajout d'informations photovoltaïques (durée de fonctionnement, énergie, économies) avec de nouveaux états d'analyse et une nouvelle aide. Amélioration de la gestion de la propriété active_helper pour les assistants photovoltaïques, solaires et solaires étendus. Correction de la logique de circulation PV lorsque ignore_on_circulation est désactivé.",
+        "it": "Aggiunti approfondimenti sul fotovoltaico (autonomia, energia, risparmio) con nuovi stati di analisi e supporto. Migliorata la gestione della proprietà di active_helper tra gli helper fotovoltaici, solari e solari estesi. Risolta la logica di circolazione FV quando ignore_on_circulation è disabilitato.",
+        "es": "Se agregaron conocimientos fotovoltaicos (tiempo de ejecución, energía, ahorros) con nuevos estados analíticos y ayuda. Se mejoró el manejo de la propiedad de active_helper en los asistentes fotovoltaicos, solares y solares extendidos. Se corrigió la lógica de circulación de PV cuando ignore_on_circulation estaba deshabilitado.",
+        "pl": "Dodano statystyki fotowoltaiczne (czas pracy, energia, oszczędności) z nowymi stanami analitycznymi i pomocą. Ulepszona obsługa własności active_helper w przypadku fotowoltaiki, energii słonecznej i rozszerzonych pomocników energii słonecznej. Naprawiono logikę cyrkulacji PV, gdy ignorowanie_cyrkulacji jest wyłączone.",
+        "uk": "Додано статистику фотоелектричної системи (час роботи, енергія, економія) з новими аналітичними станами та помічником. Покращено керування правами власності active_helper на фотоелектричні, сонячні та розширені сонячні помічники. Виправлена ​​логіка циркуляції PV, коли ignore_on_circulation вимкнено.",
+        "zh-cn": "通过新的分析状态和帮助器添加了光伏见解（运行时间、能源、节省）。改进了跨光伏、太阳能和扩展太阳能助手的 active_helper 所有权处理。修复了禁用ignore_on_circulation时的PV循环逻辑。"
+      },
       "1.3.9": {
         "en": "Fix solar logbook duplication and invalid entries, improve log stability and weather text handling; fix solar insights runtime calculation and debug timestamp update.",
         "de": "Behebung von doppelten und ungültigen Solar-Logbuch-Einträgen, Verbesserung der Log-Stabilität und Wettertext-Verarbeitung; Korrektur der Laufzeitberechnung im Solar-Insights-Bereich sowie Aktualisierung des Debug-Zeitstempels.",
@@ -120,7 +133,8 @@
       {
         "admin": ">=7.6.20"
       }
-    ]
+    ],
+    "installedFrom": "file:///opt/iobroker/ioBroker.poolcontrol"
   },
   "native": {},
   "objects": [],

package/lib/helpers/photovoltaicHelper.js

@@ -207,28 +207,29 @@ const photovoltaicHelper = {
             }
         }
 
-        // FIX: PV-Schaltlogik mit Prüfung der Umwälzung
+        // FIX: PV switching logic must only block on fulfilled circulation target if ignoreOnCirc is enabled
         if (surplusActive) {
-            try {
-                const remainingState = await this.adapter.getForeignStateAsync(
-                    'poolcontrol.0.circulation.daily_remaining',
-                );
-                const remaining = Number(remainingState?.val ?? NaN);
-
-                // RULE: Einschalten nur, wenn Umwälzung noch nicht erfüllt
-                if (Number.isFinite(remaining) && remaining <= 0) {
-                    this.adapter.log.info(
-                        `[photovoltaicHelper] Daily circulation target already reached (${remaining}) → pump stays OFF (no start despite surplus).`,
+            if (ignoreOnCirc) {
+                try {
+                    const remainingState = await this.adapter.getForeignStateAsync(
+                        'poolcontrol.0.circulation.daily_remaining',
                     );
-                    return this._maybeStopPump(true, 0, 'circulation_already_reached');
-                }
+                    const remaining = Number(remainingState?.val ?? NaN);
 
-                // RULE: Überschuss aktiv UND Umwälzung noch nicht erfüllt → einschalten
-                return this._maybeStartPump('pv_surplus');
-            } catch (err) {
-                this.adapter.log.warn(`[photovoltaicHelper] Error while checking daily_remaining: ${err.message}`);
-                return this._maybeStartPump('pv_surplus');
+                    // RULE: Start only if circulation target is not fulfilled yet
+                    if (Number.isFinite(remaining) && remaining <= 0) {
+                        this.adapter.log.info(
+                            `[photovoltaicHelper] Daily circulation target already reached (${remaining}) → pump stays OFF (no start despite surplus).`,
+                        );
+                        return this._maybeStopPump(true, 0, 'circulation_already_reached');
+                    }
+                } catch (err) {
+                    this.adapter.log.warn(`[photovoltaicHelper] Error while checking daily_remaining: ${err.message}`);
+                }
             }
+
+            // RULE: Surplus active and no circulation blocking active → switch on
+            return this._maybeStartPump('pv_surplus');
         }
 
         // RULE: Kein Überschuss → ggf. Nachlauf/Aus
@@ -249,6 +250,8 @@ const photovoltaicHelper = {
         }
         this._pvPumpHoldUntil = 0;
 
+        await this._setActiveHelperIfAllowed('photovoltaicHelper');
+
         if (this._desiredPump === true) {
             return;
         }
@@ -287,6 +290,7 @@ const photovoltaicHelper = {
             this._desiredPump = false;
             this.adapter.log.info(`[photovoltaicHelper] Pump OFF (${tag}, no afterrun)`);
             await this._setPumpSwitch(false);
+            await this._releaseActiveHelperIfOwned();
             return;
         }
 
@@ -321,6 +325,7 @@ const photovoltaicHelper = {
             this._desiredPump = false;
             this.adapter.log.info('[photovoltaicHelper] Pump OFF (afterrun finished)');
             await this._setPumpSwitch(false);
+            await this._releaseActiveHelperIfOwned();
         }, holdMs);
 
         this.adapter.log.debug(`[photovoltaicHelper] Afterrun started: ${afterrunMin} min (${tag})`);
@@ -334,6 +339,37 @@ const photovoltaicHelper = {
         }
     },
 
+    async _setActiveHelperIfAllowed(helperName) {
+        try {
+            const activeHelper = (await this.adapter.getStateAsync('pump.active_helper'))?.val || '';
+
+            if (activeHelper && activeHelper !== helperName) {
+                this.adapter.log.debug(
+                    `[photovoltaicHelper] Active helper not changed because '${activeHelper}' currently owns the pump.`,
+                );
+                return;
+            }
+
+            await this.adapter.setStateAsync('pump.active_helper', { val: helperName, ack: true });
+        } catch (err) {
+            this.adapter.log.warn(`[photovoltaicHelper] Could not set pump.active_helper: ${err.message}`);
+        }
+    },
+
+    async _releaseActiveHelperIfOwned() {
+        try {
+            const activeHelper = (await this.adapter.getStateAsync('pump.active_helper'))?.val || '';
+
+            if (activeHelper !== 'photovoltaicHelper') {
+                return;
+            }
+
+            await this.adapter.setStateAsync('pump.active_helper', { val: '', ack: true });
+        } catch (err) {
+            this.adapter.log.warn(`[photovoltaicHelper] Could not release pump.active_helper: ${err.message}`);
+        }
+    },
+
     async _updateNumberState(id, val) {
         try {
             await this.adapter.setStateAsync(id, { val: Number(val) || 0, ack: true });

package/lib/helpers/photovoltaicInsightsHelper.js

@@ -0,0 +1,306 @@
+'use strict';
+
+const { I18n } = require('@iobroker/adapter-core');
+
+const photovoltaicInsightsHelper = {
+    adapter: null,
+    checkTimer: null,
+    lastResultTimestamp: null,
+    lastPvRuntimeActive: false,
+
+    init(adapter) {
+        this.adapter = adapter;
+
+        void this._subscribeStates();
+        this._scheduleCheck(0);
+
+        this.adapter.log.debug(
+            '[photovoltaicInsightsHelper] Initialized (Block 1 inputs, Block 2 calculation, Block 3 results, Block 4 debug)',
+        );
+    },
+
+    handleStateChange(id, state) {
+        if (!state || state.ack !== true) {
+            return;
+        }
+
+        if (!this._isRelevantState(id)) {
+            return;
+        }
+
+        this._scheduleCheck(200);
+    },
+
+    _scheduleCheck(delayMs = 0) {
+        if (this.checkTimer) {
+            this.adapter.clearTimeout(this.checkTimer);
+            this.checkTimer = null;
+        }
+
+        this.checkTimer = this.adapter.setTimeout(() => {
+            this.checkTimer = null;
+            void this._updateInputs();
+        }, delayMs);
+    },
+
+    async _subscribeStates() {
+        const ids = [
+            'photovoltaic.power_surplus_w',
+            'photovoltaic.surplus_active',
+            'pump.live.current_power_w',
+            'pump.active_helper',
+        ];
+
+        for (const id of ids) {
+            await this.adapter.subscribeStatesAsync(id);
+        }
+
+        this.adapter.log.debug('[photovoltaicInsightsHelper] Subscribed to input states');
+    },
+
+    _isRelevantState(id) {
+        const ids = [
+            'photovoltaic.power_surplus_w',
+            'photovoltaic.surplus_active',
+            'pump.live.current_power_w',
+            'pump.active_helper',
+        ];
+
+        return ids.some(relevantId => id === relevantId || id.endsWith(`.${relevantId}`));
+    },
+
+    async _updateInputs() {
+        try {
+            const pvSurplusW = await this._readNumber('photovoltaic.power_surplus_w');
+            const pvSurplusActive = await this._readBoolean('photovoltaic.surplus_active');
+
+            const pumpPowerW = await this._readNumber('pump.live.current_power_w');
+
+            await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.inputs.pv_surplus_w', {
+                val: Number.isFinite(pvSurplusW) ? pvSurplusW : 0,
+                ack: true,
+            });
+
+            await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.inputs.pv_surplus_active', {
+                val: pvSurplusActive,
+                ack: true,
+            });
+
+            await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.inputs.pump_power_w', {
+                val: Number.isFinite(pumpPowerW) ? pumpPowerW : 0,
+                ack: true,
+            });
+
+            await this._updateCalculation();
+            await this._updateResults();
+
+            this.adapter.log.debug('[photovoltaicInsightsHelper] Inputs, calculation and results updated');
+        } catch (err) {
+            this.adapter.log.warn(`[photovoltaicInsightsHelper] Error updating inputs: ${err.message}`);
+        }
+    },
+
+    async _updateCalculation() {
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.calculation.mode', {
+            val: I18n.translate('photovoltaic_insights_calculation_mode_daily'),
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.calculation.price_source', {
+            val: I18n.translate('photovoltaic_insights_price_source_adapter_config'),
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.calculation.note', {
+            val: I18n.translate('photovoltaic_insights_calculation_note_block_2'),
+            ack: true,
+        });
+    },
+
+    async _updateResults() {
+        const now = Date.now();
+
+        const pvSurplusActive = await this._readBoolean('photovoltaic.surplus_active');
+        const pumpPowerW = await this._readNumber('pump.live.current_power_w');
+        const activeHelper = await this._readString('pump.active_helper');
+        const electricityPriceEurKwh = Number(this.adapter.config.energy_price_eur_kwh);
+
+        const pvControlsPump = activeHelper === 'photovoltaicHelper';
+        const pvRuntimeActive = pvSurplusActive && pvControlsPump;
+
+        let runtimeTodayMin = await this._readNumber('analytics.insights.photovoltaic.results.runtime_today_min');
+        let energyUsedTodayKwh = await this._readNumber(
+            'analytics.insights.photovoltaic.results.energy_used_today_kwh',
+        );
+        let savingsTodayEur = await this._readNumber('analytics.insights.photovoltaic.results.savings_today_eur');
+        let startsToday = await this._readNumber('analytics.insights.photovoltaic.results.starts_today');
+
+        runtimeTodayMin = Number.isFinite(runtimeTodayMin) ? runtimeTodayMin : 0;
+        energyUsedTodayKwh = Number.isFinite(energyUsedTodayKwh) ? energyUsedTodayKwh : 0;
+        savingsTodayEur = Number.isFinite(savingsTodayEur) ? savingsTodayEur : 0;
+        startsToday = Number.isFinite(startsToday) ? startsToday : 0;
+
+        if (pvRuntimeActive && !this.lastPvRuntimeActive) {
+            startsToday += 1;
+            this.lastResultTimestamp = now;
+        }
+
+        if (pvRuntimeActive && this.lastResultTimestamp && Number.isFinite(pumpPowerW) && pumpPowerW > 0) {
+            const deltaHours = (now - this.lastResultTimestamp) / 3600000;
+
+            if (deltaHours > 0 && deltaHours <= 0.5) {
+                const energyDeltaKwh = (pumpPowerW * deltaHours) / 1000;
+
+                runtimeTodayMin = Number((runtimeTodayMin + deltaHours * 60).toFixed(2));
+                energyUsedTodayKwh = Number((energyUsedTodayKwh + energyDeltaKwh).toFixed(4));
+
+                if (Number.isFinite(electricityPriceEurKwh) && electricityPriceEurKwh > 0) {
+                    savingsTodayEur = Number((savingsTodayEur + energyDeltaKwh * electricityPriceEurKwh).toFixed(2));
+                }
+            }
+        }
+
+        if (pvRuntimeActive) {
+            this.lastResultTimestamp = now;
+        } else {
+            this.lastResultTimestamp = null;
+        }
+
+        this.lastPvRuntimeActive = pvRuntimeActive;
+
+        const activeToday = runtimeTodayMin > 0 || startsToday > 0;
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.results.active_today', {
+            val: activeToday,
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.results.runtime_today_min', {
+            val: runtimeTodayMin,
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.results.energy_used_today_kwh', {
+            val: energyUsedTodayKwh,
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.results.savings_today_eur', {
+            val: savingsTodayEur,
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.results.starts_today', {
+            val: startsToday,
+            ack: true,
+        });
+
+        const summaryText = I18n.translate('photovoltaic_insights_summary_text_block_3')
+            .replace('%s', runtimeTodayMin.toFixed(0))
+            .replace('%s', energyUsedTodayKwh.toFixed(2))
+            .replace('%s', savingsTodayEur.toFixed(2));
+
+        const summaryJson = {
+            mode: 'daily_pv_surplus_analysis',
+            pv_surplus_active: pvSurplusActive,
+            pv_controls_pump: pvControlsPump,
+            pv_runtime_active: pvRuntimeActive,
+            active_today: activeToday,
+            values: {
+                pv_surplus_w: await this._readNumber('photovoltaic.power_surplus_w'),
+                pump_power_w: Number.isFinite(pumpPowerW) ? pumpPowerW : null,
+                electricity_price_eur_kwh: Number.isFinite(electricityPriceEurKwh) ? electricityPriceEurKwh : null,
+                runtime_today_min: runtimeTodayMin,
+                energy_used_today_kwh: energyUsedTodayKwh,
+                savings_today_eur: savingsTodayEur,
+                starts_today: startsToday,
+            },
+            note: I18n.translate('photovoltaic_insights_calculation_note_block_2'),
+        };
+
+        const summaryHtml = [
+            '<div>',
+            `<b>${I18n.translate('photovoltaic_insights_label_mode')}:</b> ${I18n.translate('photovoltaic_insights_calculation_mode_daily')}<br>`,
+            `<b>${I18n.translate('photovoltaic_insights_label_pv_surplus_active')}:</b> ${pvSurplusActive}<br>`,
+            `<b>${I18n.translate('photovoltaic_insights_label_pv_controls_pump')}:</b> ${pvControlsPump}<br>`,
+            `<b>${I18n.translate('photovoltaic_insights_label_runtime_today')}:</b> ${runtimeTodayMin.toFixed(2)} min<br>`,
+            `<b>${I18n.translate('photovoltaic_insights_label_energy_used_today')}:</b> ${energyUsedTodayKwh.toFixed(4)} kWh<br>`,
+            `<b>${I18n.translate('photovoltaic_insights_label_savings_today')}:</b> ${savingsTodayEur.toFixed(2)} €<br>`,
+            `<b>${I18n.translate('photovoltaic_insights_label_starts_today')}:</b> ${startsToday}<br>`,
+            `<b>${I18n.translate('photovoltaic_insights_label_summary')}:</b> ${summaryText}`,
+            '</div>',
+        ].join('');
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.results.summary_text', {
+            val: summaryText,
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.results.summary_json', {
+            val: JSON.stringify(summaryJson),
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.results.summary_html', {
+            val: summaryHtml,
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.debug.last_update', {
+            val: new Date().toISOString(),
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.debug.last_recalculation_reason', {
+            val: pvRuntimeActive
+                ? I18n.translate('photovoltaic_insights_debug_reason_pv_runtime_active')
+                : I18n.translate('photovoltaic_insights_debug_reason_no_pv_runtime'),
+            ack: true,
+        });
+
+        await this.adapter.setStateChangedAsync('analytics.insights.photovoltaic.debug.debug_text', {
+            val: pvRuntimeActive
+                ? I18n.translate('photovoltaic_insights_debug_text_pv_runtime_active')
+                : I18n.translate('photovoltaic_insights_debug_text_no_pv_runtime'),
+            ack: true,
+        });
+    },
+
+    async _readState(id) {
+        try {
+            return await this.adapter.getStateAsync(id);
+        } catch {
+            return null;
+        }
+    },
+
+    async _readBoolean(id) {
+        const state = await this._readState(id);
+        return state ? state.val === true : false;
+    },
+
+    async _readNumber(id) {
+        const state = await this._readState(id);
+
+        if (!state || state.val === null || state.val === undefined || state.val === '') {
+            return null;
+        }
+
+        const value = Number(state.val);
+        return Number.isFinite(value) ? value : null;
+    },
+
+    async _readString(id) {
+        const state = await this._readState(id);
+        return state && state.val !== undefined ? String(state.val) : '';
+    },
+
+    cleanup() {
+        if (this.checkTimer) {
+            this.adapter.clearTimeout(this.checkTimer);
+            this.checkTimer = null;
+        }
+    },
+};
+
+module.exports = photovoltaicInsightsHelper;

package/lib/helpers/solarExtendedHelper.js

@@ -235,10 +235,18 @@ const solarExtendedHelper = {
             // wenn Solar Extended überhaupt der zuständige Solarmodus ist
             // und keine höhere Fremdpriorität aktiv ist.
             if (isExtendedMode && !isControlPriority && !isTimePriority) {
+                if (speechSolarActive) {
+                    await this._setActiveHelperIfAllowed('solarExtendedHelper');
+                } else {
+                    await this._releaseActiveHelperIfOwned();
+                }
+
                 await this.adapter.setStateChangedAsync('pump.pump_switch', {
                     val: speechSolarActive,
                     ack: false,
                 });
+            } else {
+                await this._releaseActiveHelperIfOwned();
             }
 
             await this.adapter.setStateChangedAsync('solar.extended.enabled_by_master', {
@@ -309,6 +317,37 @@ const solarExtendedHelper = {
         }
     },
 
+    async _setActiveHelperIfAllowed(helperName) {
+        try {
+            const activeHelper = (await this.adapter.getStateAsync('pump.active_helper'))?.val || '';
+
+            if (activeHelper && activeHelper !== helperName) {
+                this.adapter.log.debug(
+                    `[solarExtendedHelper] Active helper not changed because '${activeHelper}' currently owns the pump.`,
+                );
+                return;
+            }
+
+            await this.adapter.setStateAsync('pump.active_helper', { val: helperName, ack: true });
+        } catch (err) {
+            this.adapter.log.warn(`[solarExtendedHelper] Could not set pump.active_helper: ${err.message}`);
+        }
+    },
+
+    async _releaseActiveHelperIfOwned() {
+        try {
+            const activeHelper = (await this.adapter.getStateAsync('pump.active_helper'))?.val || '';
+
+            if (activeHelper !== 'solarExtendedHelper') {
+                return;
+            }
+
+            await this.adapter.setStateAsync('pump.active_helper', { val: '', ack: true });
+        } catch (err) {
+            this.adapter.log.warn(`[solarExtendedHelper] Could not release pump.active_helper: ${err.message}`);
+        }
+    },
+
     cleanup() {
         if (this.checkTimer) {
             this.adapter.clearInterval(this.checkTimer);

package/lib/helpers/solarHelper.js

@@ -131,6 +131,12 @@ const solarHelper = {
                 });
 
                 // ZENTRAL: Pumpe über Bool-Schalter setzen
+                if (shouldRun) {
+                    await this._setActiveHelperIfAllowed('solarHelper');
+                } else {
+                    await this._releaseActiveHelperIfOwned();
+                }
+
                 await this.adapter.setStateChangedAsync('pump.pump_switch', {
                     val: shouldRun,
                     ack: false,
@@ -145,6 +151,8 @@ const solarHelper = {
                     ack: true,
                 });
 
+                await this._releaseActiveHelperIfOwned();
+
                 // Keine Schaltung – Grund protokollieren
                 const reason = !season
                     ? 'Saison inaktiv'
@@ -209,6 +217,37 @@ const solarHelper = {
         }
     },
 
+    async _setActiveHelperIfAllowed(helperName) {
+        try {
+            const activeHelper = (await this.adapter.getStateAsync('pump.active_helper'))?.val || '';
+
+            if (activeHelper && activeHelper !== helperName) {
+                this.adapter.log.debug(
+                    `[solarHelper] Active helper not changed because '${activeHelper}' currently owns the pump.`,
+                );
+                return;
+            }
+
+            await this.adapter.setStateAsync('pump.active_helper', { val: helperName, ack: true });
+        } catch (err) {
+            this.adapter.log.warn(`[solarHelper] Could not set pump.active_helper: ${err.message}`);
+        }
+    },
+
+    async _releaseActiveHelperIfOwned() {
+        try {
+            const activeHelper = (await this.adapter.getStateAsync('pump.active_helper'))?.val || '';
+
+            if (activeHelper !== 'solarHelper') {
+                return;
+            }
+
+            await this.adapter.setStateAsync('pump.active_helper', { val: '', ack: true });
+        } catch (err) {
+            this.adapter.log.warn(`[solarHelper] Could not release pump.active_helper: ${err.message}`);
+        }
+    },
+
     cleanup() {
         if (this.checkTimer) {
             this.adapter.clearInterval(this.checkTimer);

package/lib/i18n/de.json

@@ -167,5 +167,22 @@
   "solar_log_text_weather_supported_with_text": "Wetterbasierte Plausibilisierung ist aktiv. Aktuelle Wetterzusammenfassung: %s",
   "solar_log_text_weather_supported": "Für diese Bewertung ist eine wetterbasierte Plausibilisierung aktiv.",
   "solar_log_text_small_gain_detail": "Der aktuell geschätzte Tagesertrag liegt bei etwa %s Wh, das entspricht etwa %s kWh.",
-  "solar_log_text_quality_level": "Die aktuelle Qualitätsstufe der Bewertung ist %s."
+  "solar_log_text_quality_level": "Die aktuelle Qualitätsstufe der Bewertung ist %s.",
+
+  "photovoltaic_insights_calculation_mode_daily": "Tägliche PV-Überschussanalyse",
+  "photovoltaic_insights_price_source_adapter_config": "Adapter-Konfiguration",
+  "photovoltaic_insights_calculation_note_block_2": "Der Berechnungsblock bereitet die Quelleninformationen für die Photovoltaik-Insights-Analyse vor.",
+  "photovoltaic_insights_summary_text_block_3": "PV-Überschuss hat die Pumpe heute %s Minuten betrieben, dabei etwa %s kWh genutzt und ungefähr %s € eingespart.",
+  "photovoltaic_insights_label_mode": "Modus",
+  "photovoltaic_insights_label_pv_surplus_active": "PV-Überschuss aktiv",
+  "photovoltaic_insights_label_pv_controls_pump": "PV steuert Pumpe",
+  "photovoltaic_insights_label_runtime_today": "Laufzeit heute",
+  "photovoltaic_insights_label_energy_used_today": "Genutzte Energie heute",
+  "photovoltaic_insights_label_savings_today": "Einsparung heute",
+  "photovoltaic_insights_label_starts_today": "Starts heute",
+  "photovoltaic_insights_label_summary": "Zusammenfassung",
+  "photovoltaic_insights_debug_reason_pv_runtime_active": "PV-Überschussbetrieb aktiv",
+  "photovoltaic_insights_debug_reason_no_pv_runtime": "Kein aktiver PV-Überschussbetrieb",
+  "photovoltaic_insights_debug_text_pv_runtime_active": "PV-Überschuss ist aktiv und der Photovoltaik-Helper besitzt aktuell die Pumpe.",
+  "photovoltaic_insights_debug_text_no_pv_runtime": "Aktuell wird keine PV-Laufzeit gezählt, weil entweder kein PV-Überschuss aktiv ist oder der Photovoltaik-Helper die Pumpe nicht besitzt."
 }

package/lib/i18n/en.json

@@ -239,5 +239,22 @@
   "solar_log_text_weather_supported_with_text": "Weather-based plausibility is active. Current weather summary: %s",
   "solar_log_text_weather_supported": "Weather-based plausibility is active for this assessment.",
   "solar_log_text_small_gain_detail": "The currently estimated daily gain is about %s Wh, which corresponds to about %s kWh.",
-  "solar_log_text_quality_level": "The current quality level of the assessment is %s."
+  "solar_log_text_quality_level": "The current quality level of the assessment is %s.",
+
+  "photovoltaic_insights_calculation_mode_daily": "Daily PV surplus analysis",
+  "photovoltaic_insights_price_source_adapter_config": "Adapter configuration",
+  "photovoltaic_insights_calculation_note_block_2": "The calculation block prepares the source information for the photovoltaic insights analysis.",
+  "photovoltaic_insights_summary_text_block_3": "PV ran today for %s minutes, used %s kWh and saved approximately %s €.",
+  "photovoltaic_insights_label_mode": "Mode",
+  "photovoltaic_insights_label_pv_surplus_active": "PV surplus active",
+  "photovoltaic_insights_label_pv_controls_pump": "PV controls pump",
+  "photovoltaic_insights_label_runtime_today": "Runtime today",
+  "photovoltaic_insights_label_energy_used_today": "Energy used today",
+  "photovoltaic_insights_label_savings_today": "Savings today",
+  "photovoltaic_insights_label_starts_today": "Starts today",
+  "photovoltaic_insights_label_summary": "Summary",
+  "photovoltaic_insights_debug_reason_pv_runtime_active": "PV surplus operation active",
+  "photovoltaic_insights_debug_reason_no_pv_runtime": "No active PV surplus operation",
+  "photovoltaic_insights_debug_text_pv_runtime_active": "PV surplus is active and the photovoltaic helper currently owns the pump.",
+  "photovoltaic_insights_debug_text_no_pv_runtime": "No PV runtime is currently counted because either no PV surplus is active or the photovoltaic helper does not own the pump."
 }