iobroker.poolcontrol 1.0.1 → 1.2.0

package/io-package.json

@@ -1,8 +1,34 @@
 {
   "common": {
     "name": "poolcontrol",
-    "version": "1.0.1",
+    "version": "1.2.0",
     "news": {
+       "1.2.0": {
+         "en": "Maintenance release. Prepares PoolControl for the Stable repository by enabling i18n in the instance configuration (jsonConfig) and adding bilingual (DE/EN) labels and texts. No functional changes to the adapter logic.",
+         "de": "Wartungs-Release. Vorbereitung für das Stable-Repository durch Aktivierung von i18n in der Instanzkonfiguration (jsonConfig) und Ergänzung zweisprachiger (DE/EN) Labels und Texte. Keine funktionalen Änderungen an der Adapterlogik.",
+         "ru": "Технический релиз. Подготовка PoolControl к репозиторию Stable: включение i18n в конфигурации экземпляра (jsonConfig) и добавление двуязычных (DE/EN) подписей и текстов. Функциональных изменений в логике адаптера нет.",
+         "pt": "Versão de manutenção. Preparação do PoolControl para o repositório Stable ao ativar o i18n na configuração da instância (jsonConfig) e adicionar rótulos e textos bilingues (DE/EN). Sem alterações funcionais na lógica do adaptador.",
+         "nl": "Onderhoudsrelease. Bereidt PoolControl voor op de Stable-repository door i18n in de instance-configuratie (jsonConfig) te activeren en tweetalige (DE/EN) labels en teksten toe te voegen. Geen functionele wijzigingen in de adapterlogica.",
+         "fr": "Version de maintenance. Prépare PoolControl pour le dépôt Stable en activant i18n dans la configuration de l’instance (jsonConfig) et en ajoutant des libellés et textes bilingues (DE/EN). Aucun changement fonctionnel dans la logique de l’adaptateur.",
+         "it": "Release di manutenzione. Preparazione di PoolControl per il repository Stable abilitando i18n nella configurazione dell’istanza (jsonConfig) e aggiungendo etichette e testi bilingui (DE/EN). Nessuna modifica funzionale alla logica dell’adattatore.",
+         "es": "Versión de mantenimiento. Prepara PoolControl para el repositorio Stable habilitando i18n en la configuración de instancia (jsonConfig) y añadiendo etiquetas y textos bilingües (DE/EN). Sin cambios funcionales en la lógica del adaptador.",
+         "pl": "Wydanie konserwacyjne. Przygotowanie PoolControl do repozytorium Stable poprzez włączenie i18n w konfiguracji instancji (jsonConfig) oraz dodanie dwujęzycznych (DE/EN) etykiet i tekstów. Brak zmian funkcjonalnych w logice adaptera.",
+         "uk": "Реліз обслуговування. Підготовка PoolControl до репозиторію Stable: увімкнення i18n у конфігурації інстансу (jsonConfig) та додавання двомовних (DE/EN) підписів і текстів. Жодних функціональних змін у логіці адаптера.",
+         "zh-cn": "维护版本。为进入 Stable 仓库做准备：在实例配置（jsonConfig）中启用 i18n，并添加双语（德语/英语）标签与文本。适配器逻辑无功能性变更。"
+       },
+       "1.1.0": {
+         "en": "Feature release. Introduces a new passive pump speed recommendation layer (pump.speed). PoolControl now derives a clear logical pump performance state (off, frost, low, normal, high, boost) from existing pump logic and provides an optional, configurable percentage recommendation (0–100%). This enables seamless integration with external speed control solutions such as Shelly 0–10 V, frequency converters or Blockly scripts, without modifying or interfering with the existing pump control logic.",
+         "de": "Feature-Release. Einführung einer neuen passiven Pumpen-Leistungsempfehlung (pump.speed). PoolControl leitet nun einen klaren logischen Leistungszustand der Pumpe (off, frost, low, normal, high, boost) aus der bestehenden Pumpenlogik ab und stellt zusätzlich eine optionale, frei konfigurierbare Prozent-Empfehlung (0–100 %) bereit. Dadurch können externe Drehzahlsteuerungen wie Shelly 0–10 V, Frequenzumrichter oder Blockly-Skripte angebunden werden, ohne die bestehende Pumpensteuerung zu verändern oder zu beeinflussen.",
+         "ru": "Релиз с новым функционалом. Добавлен новый пассивный уровень рекомендации скорости насоса (pump.speed). PoolControl теперь определяет логическое состояние производительности насоса (off, frost, low, normal, high, boost) на основе существующей логики работы насоса и предоставляет дополнительную настраиваемую рекомендацию в процентах (0–100 %). Это позволяет интегрировать внешние системы управления скоростью, такие как Shelly 0–10 V, частотные преобразователи или скрипты Blockly, без изменения существующей логики управления насосом.",
+         "pt": "Versão com novas funcionalidades. Introduz uma nova camada passiva de recomendação de velocidade da bomba (pump.speed). O PoolControl passa a derivar um estado lógico claro de desempenho da bomba (off, frost, low, normal, high, boost) a partir da lógica existente e fornece uma recomendação percentual opcional e configurável (0–100%). Isto permite a integração com soluções externas de controlo de velocidade, como Shelly 0–10 V, conversores de frequência ou scripts Blockly, sem alterar a lógica de controlo da bomba existente.",
+         "nl": "Feature-release. Introduceert een nieuwe passieve aanbevelingslaag voor pompsnelheid (pump.speed). PoolControl leidt nu een duidelijke logische pompvermogensstatus af (off, frost, low, normal, high, boost) op basis van de bestaande pomplogica en biedt daarnaast een optionele, configureerbare procentuele aanbeveling (0–100%). Dit maakt integratie mogelijk met externe snelheidsregelingen zoals Shelly 0–10 V, frequentieregelaars of Blockly-scripts, zonder de bestaande pompregeling te wijzigen.",
+         "fr": "Version fonctionnelle. Introduction d’une nouvelle couche passive de recommandation de vitesse de la pompe (pump.speed). PoolControl déduit désormais un état logique clair de performance de la pompe (off, frost, low, normal, high, boost) à partir de la logique existante et fournit en plus une recommandation de pourcentage configurable (0–100 %). Cela permet l’intégration de solutions externes de contrôle de vitesse telles que Shelly 0–10 V, variateurs de fréquence ou scripts Blockly, sans modifier la logique de commande existante.",
+         "it": "Release funzionale. Introduce un nuovo livello passivo di raccomandazione della velocità della pompa (pump.speed). PoolControl ricava ora uno stato logico chiaro delle prestazioni della pompa (off, frost, low, normal, high, boost) dalla logica esistente e fornisce una raccomandazione percentuale opzionale e configurabile (0–100%). Ciò consente l’integrazione con soluzioni esterne di controllo della velocità come Shelly 0–10 V, inverter o script Blockly, senza modificare la logica di controllo della pompa esistente.",
+         "es": "Versión con nuevas funciones. Introduce una nueva capa pasiva de recomendación de velocidad de la bomba (pump.speed). PoolControl ahora deriva un estado lógico claro del rendimiento de la bomba (off, frost, low, normal, high, boost) a partir de la lógica existente y proporciona una recomendación porcentual opcional y configurable (0–100%). Esto permite integrar soluciones externas de control de velocidad como Shelly 0–10 V, variadores de frecuencia o scripts Blockly, sin modificar la lógica de control de la bomba existente.",
+         "pl": "Wydanie z nową funkcjonalnością. Wprowadza nową pasywną warstwę rekomendacji prędkości pompy (pump.speed). PoolControl wyznacza teraz jednoznaczny logiczny stan wydajności pompy (off, frost, low, normal, high, boost) na podstawie istniejącej logiki oraz udostępnia opcjonalną, konfigurowalną rekomendację procentową (0–100%). Umożliwia to integrację z zewnętrznymi systemami sterowania prędkością, takimi jak Shelly 0–10 V, falowniki czy skrypty Blockly, bez ingerencji w istniejącą logikę sterowania pompą.",
+         "uk": "Функціональний реліз. Додано новий пасивний рівень рекомендації швидкості насоса (pump.speed). PoolControl тепер визначає чіткий логічний стан продуктивності насоса (off, frost, low, normal, high, boost) на основі наявної логіки та надає додаткову налаштовувану процентну рекомендацію (0–100 %). Це дозволяє інтегрувати зовнішні рішення керування швидкістю, такі як Shelly 0–10 V, частотні перетворювачі або скрипти Blockly, без зміни існуючої логіки керування насосом.",
+         "zh-cn": "功能版本。引入了新的被动泵速推荐层（pump.speed）。PoolControl 现在可以基于现有的泵控制逻辑派生出清晰的逻辑性能状态（off、frost、low、normal、high、boost），并提供可选的、可配置的百分比推荐（0–100%）。这使其能够与 Shelly 0–10 V、变频器或 Blockly 脚本等外部转速控制方案无缝集成，而无需修改现有的泵控制逻辑。"
+       },
        "1.0.1": {
          "en": "Bugfix release. Fixes incomplete weather code descriptions in the AI weather forecast module by fully aligning with the official Open-Meteo weather code specification. This prevents raw numeric weather codes from appearing in notifications, speech output, or AI-generated texts and ensures consistent, human-readable weather descriptions across all outputs.",
          "de": "Bugfix-Release. Behebt unvollständige Wettercode-Beschreibungen im KI-Wettervorhersagemodul durch vollständige Anpassung an die offizielle Open-Meteo-Wettercode-Spezifikation. Dadurch wird verhindert, dass rohe numerische Wettercodes in Benachrichtigungen, Sprachausgaben oder KI-generierten Texten erscheinen, und es werden durchgehend verständliche Klartext-Beschreibungen sichergestellt.",
@@ -67,32 +93,6 @@
          "pl": "Nowy moduł pomocy chemicznej oparty na AI. Interaktywny, wyłącznie informacyjny system wsparcia dla typowych problemów wody basenowej (np. zbyt wysokie/niskie pH, nieskuteczny chlor, zielona lub mętna woda). Bez automatycznego dozowania, rekomendacji produktów, sterowania urządzeniami ani komunikatów głosowych.",
          "uk": "Новий модуль допомоги з хімії басейну на основі ШІ. Інтерактивна, виключно інформаційна система підтримки для типових проблем води (наприклад, високий/низький pH, неефективний хлор, зелена або каламутна вода). Без автоматичного дозування, рекомендацій продуктів, керування пристроями чи голосового виводу.",
          "zh-cn": "新增 AI 水质化学帮助模块。为常见的泳池水问题（如 pH 过高/过低、氯无效、绿水或浑浊水）提供交互式、纯信息性的帮助说明。不包含自动投加、产品推荐、设备控制或语音输出。"
-       },
-       "0.8.1": {
-         "en": "Fix: AI messages were executed multiple times (e.g. 3x in Telegram). The timer system in aiHelper has been reworked: late executions now only run during the first 3 minutes after adapter start. All AI weather modules now trigger exactly once per day again. Stability improvements in the daily timers.",
-         "de": "Fix: KI-Meldungen wurden mehrfach ausgeführt (z.B. 3× in Telegram). Das Timer-System im aiHelper wurde überarbeitet: Nachholausführungen laufen jetzt nur noch in den ersten 3 Minuten nach Adapterstart. Alle AI-Wettermodule werden wieder exakt einmal pro Tag ausgelöst. Stabilitätsverbesserungen bei den täglichen Timern.",
-         "ru": "Исправление: сообщения ИИ выполнялись несколько раз (например, 3× в Telegram). Таймерная система в aiHelper была переработана: пропущенные задачи выполняются только в первые 3 минуты после запуска адаптера. Все модули погоды ИИ снова выполняются строго один раз в день.",
-         "pt": "Correção: mensagens de IA eram executadas várias vezes (ex.: 3× no Telegram). O sistema de temporizadores do aiHelper foi reestruturado: execuções atrasadas agora ocorrem apenas nos primeiros 3 minutos após iniciar o adaptador. Todos os módulos de clima da IA voltam a ser executados exatamente uma vez por dia.",
-         "nl": "Fix: AI-berichten werden meerdere keren uitgevoerd (bijv. 3× in Telegram). Het timersysteem in aiHelper is herwerkt: inhaaluitvoeringen draaien nu alleen in de eerste 3 minuten na adapterstart. Alle AI-weermodules worden weer precies één keer per dag uitgevoerd.",
-         "fr": "Correctif : les messages IA étaient exécutés plusieurs fois (ex. 3× dans Telegram). Le système de minuteries dans aiHelper a été revu : les exécutions différées ne s'exécutent plus que pendant les 3 premières minutes après le démarrage. Tous les modules météo IA se déclenchent à nouveau exactement une fois par jour.",
-         "it": "Fix: i messaggi dell'IA venivano eseguiti più volte (es. 3× su Telegram). Il sistema di timer dell'aiHelper è stato rivisto: le esecuzioni recuperate ora avvengono solo nei primi 3 minuti dopo l'avvio dell'adattatore. Tutti i moduli meteo IA ora si attivano nuovamente una sola volta al giorno.",
-         "es": "Corrección: los mensajes de IA se ejecutaban varias veces (p. ej., 3× en Telegram). Se ha rediseñado el sistema de temporizadores en aiHelper: las ejecuciones atrasadas ahora solo ocurren en los primeros 3 minutos tras iniciar el adaptador. Todos los módulos meteorológicos de IA vuelven a ejecutarse una sola vez al día.",
-         "pl": "Poprawka: komunikaty AI były wykonywane wielokrotnie (np. 3× w Telegramie). System timerów w aiHelper został przebudowany: zaległe wykonania działają teraz tylko w pierwszych 3 minutach po uruchomieniu adaptera. Wszystkie moduły pogodowe AI znów uruchamiają się dokładnie raz dziennie.",
-         "uk": "Виправлення: повідомлення ШІ виконувалися кілька разів (наприклад, 3× у Telegram). Систему таймерів в aiHelper перероблено: запізнілі виконання відбуваються лише в перші 3 хвилини після запуску. Усі погодні модулі ШІ знову працюють рівно один раз на добу.",
-         "zh-cn": "修复：AI 消息会被多次执行（例如在 Telegram 中出现 3 次）。已重构 aiHelper 中的计时器系统：补偿执行现在仅在适配器启动后的前 3 分钟内运行。所有 AI 天气模块现在每天只会执行一次。"
-       },
-       "0.8.0": {
-         "en": "New: Introduction of the AI Forecast System (aiForecastHelper). The adapter now creates a daily weather forecast for tomorrow, including temperature range, weather description, rain probability, wind analysis, and pool recommendations. New switches, schedules and outputs were added under ai.weather.*. First execution runs automatically at adapter start. Admin interface updated with important AI information.",
-         "de": "Neu: Einführung des KI-Vorhersagesystems (aiForecastHelper). Der Adapter erstellt nun täglich eine Wettervorhersage für morgen – inklusive Temperaturspanne, Wetterbeschreibung, Regenwahrscheinlichkeit, Windanalyse und Pool-Empfehlungen. Neue Schalter, Zeitpläne und Ausgaben unter ai.weather.* hinzugefügt. Erste Ausführung erfolgt automatisch beim Adapterstart. Admin-Oberfläche um wichtige KI-Hinweise erweitert.",
-         "ru": "Новое: Введена система ИИ-прогноза (aiForecastHelper). Адаптер теперь ежедневно создаёт прогноз погоды на завтра: диапазон температур, описание погоды, вероятность дождя, анализ ветра и рекомендации по бассейну. Добавлены новые переключатели, расписания и выходы в ai.weather.*. Первое выполнение происходит автоматически при запуске адаптера. Интерфейс администратора обновлён важной информацией об ИИ.",
-         "pt": "Novo: Introdução do sistema de previsão por IA (aiForecastHelper). O adaptador agora cria diariamente uma previsão do tempo para amanhã, incluindo faixa de temperatura, descrição do clima, probabilidade de chuva, análise de vento e recomendações para a piscina. Novos interruptores, horários e saídas adicionados em ai.weather.*. A primeira execução ocorre automaticamente ao iniciar o adaptador. Interface administrativa atualizada com informações importantes sobre IA.",
-         "nl": "Nieuw: Introductie van het AI-voorspellingssysteem (aiForecastHelper). De adapter maakt nu dagelijks een weersvoorspelling voor morgen, inclusief temperatuurbereik, weertype, regenkans, windanalyse en zwembad-aanbevelingen. Nieuwe schakelaars, schema's en outputs toegevoegd onder ai.weather.*. Eerste uitvoering gebeurt automatisch bij het starten van de adapter. Admin-interface uitgebreid met belangrijke AI-informatie.",
-         "fr": "Nouveau : Introduction du système de prévision IA (aiForecastHelper). L’adaptateur génère désormais chaque jour une prévision météo pour le lendemain, incluant plage de températures, description du temps, probabilité de pluie, analyse du vent et recommandations pour la piscine. Nouveaux commutateurs, horaires et sorties ajoutés sous ai.weather.*. Première exécution automatique au démarrage de l’adaptateur. Interface admin enrichie d’informations importantes sur l’IA.",
-         "it": "Novità: Introduzione del sistema di previsione IA (aiForecastHelper). L’adattatore ora genera quotidianamente una previsione del tempo per domani, inclusi intervallo di temperature, descrizione del meteo, probabilità di pioggia, analisi del vento e raccomandazioni per la piscina. Aggiunti nuovi switch, pianificazioni e output sotto ai.weather.*. Prima esecuzione automatica all'avvio dell’adattatore. Interfaccia admin aggiornata con importanti informazioni sull’IA.",
-         "es": "Nuevo: Introducción del sistema de previsión por IA (aiForecastHelper). El adaptador ahora genera un pronóstico diario del clima para mañana, incluyendo rango de temperatura, descripción del clima, probabilidad de lluvia, análisis del viento y recomendaciones para la piscina. Nuevos interruptores, horarios y salidas añadidos en ai.weather.*. La primera ejecución ocurre automáticamente al iniciar el adaptador. Interfaz de administración actualizada con información importante sobre IA.",
-         "pl": "Nowość: Wprowadzenie systemu prognoz opartego na AI (aiForecastHelper). Adapter tworzy teraz codzienną prognozę pogody na jutro, obejmującą zakres temperatur, opis pogody, prawdopodobieństwo opadów, analizę wiatru oraz zalecenia dla basenu. Dodano nowe przełączniki, harmonogramy i wyjścia w ai.weather.*. Pierwsze uruchomienie następuje automatycznie przy starcie adaptera. Interfejs administracyjny został uzupełniony o ważne informacje dotyczące AI.",
-         "uk": "Нове: Впроваджено систему прогнозування на основі ШІ (aiForecastHelper). Адаптер тепер щоденно створює прогноз погоди на завтра: діапазон температур, опис погоди, ймовірність опадів, аналіз вітру та рекомендації для басейну. Додано нові перемикачі, розклади та виходи в ai.weather.*. Перше виконання відбувається автоматично під час запуску адаптера. Адмін-інтерфейс оновлено важливою інформацією щодо ШІ.",
-         "zh-cn": "新增：引入 AI 预报系统（aiForecastHelper）。适配器现在每天生成明天的天气预报，包括温度范围、天气描述、降雨概率、风力分析和泳池建议。新增了 ai.weather.* 下的开关、计划和输出。首次执行在适配器启动时自动进行。管理界面已更新，包含重要的 AI 信息。"
        }
 	},
     "titleLang": {

package/lib/helpers/pumpSpeedHelper.js

@@ -0,0 +1,238 @@
+'use strict';
+
+/**
+ * pumpSpeedHelper.js
+ * ----------------------------------------------------------
+ * Leistungsempfehlung für die Hauptpumpe (rein passiv)
+ *
+ * Dieser Helper:
+ * - schaltet die Pumpe NICHT
+ * - steuert KEINE Hardware (kein 0-10V, kein Shelly, kein FU)
+ * - greift NICHT in bestehende Pumpenlogik ein
+ *
+ * Er reagiert ausschließlich auf bestehende States und leitet daraus
+ * EINEN internen Leistungszustand ab, der dann in mehreren Formen
+ * ausgegeben wird:
+ * - pump.speed.state  (interner Zustand)
+ * - pump.speed.mode   (semantische Ausgabe)
+ * - pump.speed.percent (technische Ausgabe, aus User-Mapping)
+ *
+ * Eingänge (Single Source of Truth):
+ * - pump.pump_switch
+ * - pump.mode
+ * - control.pump.backwash_active
+ * - pump.speed.config.percent.* (Mapping)
+ *
+ * Logik (schlank, wie besprochen):
+ * 1) Pumpe AUS -> off
+ * 2) Rückspülen/Wartung aktiv -> boost
+ * 3) FrostHelper aktiv -> frost
+ * 4) sonst -> normal
+ *
+ * Version: 0.1.0
+ */
+
+const pumpSpeedHelper = {
+    adapter: null,
+
+    // Cache für Mapping (damit nicht jedes Event alles neu gelesen wird)
+    mapping: {
+        frost: 0,
+        low: 0,
+        normal: 0,
+        high: 0,
+        boost: 0,
+    },
+
+    /**
+     * Initialisiert den Helper
+     *
+     * @param {ioBroker.Adapter} adapter – aktive Adapterinstanz
+     */
+    async init(adapter) {
+        this.adapter = adapter;
+
+        adapter.log.debug('[pumpSpeedHelper] Initialisierung gestartet');
+
+        // ----------------------------------------------------------
+        // Subscriptions (Grundregel: ohne subscribe -> wirkungslos)
+        // ----------------------------------------------------------
+        adapter.subscribeStates('pump.pump_switch');
+        adapter.subscribeStates('pump.mode');
+        adapter.subscribeStates('control.pump.backwash_active');
+
+        adapter.subscribeStates('pump.speed.config.percent.frost');
+        adapter.subscribeStates('pump.speed.config.percent.low');
+        adapter.subscribeStates('pump.speed.config.percent.normal');
+        adapter.subscribeStates('pump.speed.config.percent.high');
+        adapter.subscribeStates('pump.speed.config.percent.boost');
+
+        // Initiales Mapping laden
+        await this._reloadMapping();
+
+        // Initialen Output setzen
+        await this._recalculate();
+
+        adapter.log.debug('[pumpSpeedHelper] Erfolgreich initialisiert');
+    },
+
+    /**
+     * Verarbeitet relevante State-Änderungen
+     *
+     * @param {string} id - Objekt-ID
+     * @param {ioBroker.State} state - Neuer Wert
+     */
+    async handleStateChange(id, state) {
+        if (!state) {
+            return;
+        }
+
+        try {
+            // Mapping geändert? -> Cache aktualisieren + neu berechnen
+            if (
+                id.endsWith('pump.speed.config.percent.frost') ||
+                id.endsWith('pump.speed.config.percent.low') ||
+                id.endsWith('pump.speed.config.percent.normal') ||
+                id.endsWith('pump.speed.config.percent.high') ||
+                id.endsWith('pump.speed.config.percent.boost')
+            ) {
+                await this._reloadMapping();
+                await this._recalculate();
+                return;
+            }
+
+            // Relevante Eingänge? -> neu berechnen
+            if (
+                id.endsWith('pump.pump_switch') ||
+                id.endsWith('pump.mode') ||
+                id.endsWith('control.pump.backwash_active')
+            ) {
+                await this._recalculate();
+                return;
+            }
+        } catch (e) {
+            this.adapter.log.warn(`[pumpSpeedHelper] Fehler in handleStateChange: ${e.message}`);
+        }
+    },
+
+    /**
+     * Lädt das User-Mapping in den Cache
+     */
+    async _reloadMapping() {
+        this.mapping.frost = await this._getPercent('pump.speed.config.percent.frost');
+        this.mapping.low = await this._getPercent('pump.speed.config.percent.low');
+        this.mapping.normal = await this._getPercent('pump.speed.config.percent.normal');
+        this.mapping.high = await this._getPercent('pump.speed.config.percent.high');
+        this.mapping.boost = await this._getPercent('pump.speed.config.percent.boost');
+
+        this.adapter.log.debug(
+            `[pumpSpeedHelper] Mapping geladen: frost=${this.mapping.frost} low=${this.mapping.low} normal=${this.mapping.normal} high=${this.mapping.high} boost=${this.mapping.boost}`,
+        );
+    },
+
+    /**
+     * Führt die eigentliche Ableitung durch und setzt die Ausgänge
+     */
+    async _recalculate() {
+        const pumpSwitch = await this.adapter.getStateAsync('pump.pump_switch');
+        const pumpIsOn = !!pumpSwitch?.val;
+
+        // Pumpe aus -> off
+        if (!pumpIsOn) {
+            await this._setOutputs('off', 0);
+            return;
+        }
+
+        // Rückspülen/Wartung aktiv? -> boost
+        const backwash = await this.adapter.getStateAsync('control.pump.backwash_active');
+        const backwashActive = !!backwash?.val;
+        if (backwashActive) {
+            await this._setOutputs('boost', this.mapping.boost);
+            return;
+        }
+
+        // Frost? -> frost (über pump.mode = frostHelper)
+        const mode = (await this.adapter.getStateAsync('pump.mode'))?.val || '';
+        if (mode === 'frostHelper') {
+            await this._setOutputs('frost', this.mapping.frost);
+            return;
+        }
+
+        // Alles andere -> normal
+        await this._setOutputs('normal', this.mapping.normal);
+    },
+
+    /**
+     * Setzt state/mode/percent konsistent aus EINEM Zustand
+     *
+     * @param {string} stateValue - interner Zustand (off|frost|low|normal|high|boost)
+     * @param {number} percentValue - gemappter Prozentwert
+     */
+    async _setOutputs(stateValue, percentValue) {
+        const safePercent = this._clampPercent(percentValue);
+
+        // state (intern)
+        await this.adapter.setStateChangedAsync('pump.speed.state', {
+            val: stateValue,
+            ack: true,
+        });
+
+        // mode (semantisch)
+        await this.adapter.setStateChangedAsync('pump.speed.mode', {
+            val: stateValue,
+            ack: true,
+        });
+
+        // percent (technisch)
+        await this.adapter.setStateChangedAsync('pump.speed.percent', {
+            val: safePercent,
+            ack: true,
+        });
+
+        this.adapter.log.debug(`[pumpSpeedHelper] Output gesetzt: state=${stateValue}, percent=${safePercent}`);
+    },
+
+    /**
+     * Liest einen Prozentwert aus einem Konfigurations-State.
+     * Ungültige oder fehlende Werte werden als 0 interpretiert.
+     *
+     * @param {string} id - Objekt-ID des Prozent-States
+     * @returns {Promise<number>} Prozentwert im Bereich 0..100
+     */
+    async _getPercent(id) {
+        const st = await this.adapter.getStateAsync(id);
+        const val = Number(st?.val);
+        if (Number.isNaN(val)) {
+            return 0;
+        }
+        return this._clampPercent(val);
+    },
+
+    /**
+     * Begrenzt einen Zahlenwert auf den gültigen Prozentbereich (0..100).
+     *
+     * @param {number} v - Zu prüfender Prozentwert
+     * @returns {number} Gültiger Prozentwert im Bereich 0..100
+     */
+    _clampPercent(v) {
+        if (Number.isNaN(v)) {
+            return 0;
+        }
+        if (v < 0) {
+            return 0;
+        }
+        if (v > 100) {
+            return 100;
+        }
+        return Math.round(v);
+    },
+
+    /**
+     * Cleanup bei Adapter-Unload
+     */
+    cleanup() {
+        this.adapter?.log.debug('[pumpSpeedHelper] Cleanup ausgeführt.');
+    },
+};
+
+module.exports = pumpSpeedHelper;

package/lib/stateDefinitions/pumpSpeedStates.js

@@ -0,0 +1,267 @@
+/**
+ * =============================================================
+ * Pump Speed States
+ * =============================================================
+ *
+ * Dieser Bereich stellt eine **Leistungsempfehlung** für die
+ * Hauptpumpe bereit.
+ *
+ * WICHTIG:
+ * - Diese States steuern KEINE Hardware
+ * - Diese States schalten die Pumpe NICHT ein oder aus
+ * - Es findet KEINE Drehzahlregelung im Adapter statt
+ *
+ * Der Bereich `pump.speed` ist eine **reine Ableitung**
+ * aus bereits vorhandenen Pumpen-States wie z. B.:
+ * - pump.pump_switch
+ * - pump.reason
+ * - pump.mode
+ * - pump.active_helper
+ *
+ * Ziel:
+ * - Bereitstellung eines EINDEUTIGEN internen Leistungszustands
+ * - Mehrere Ausgaben (semantisch + technisch) aus DIESEM Zustand
+ * - Frei nutzbar für Blockly, Shelly, Frequenzumrichter etc.
+ *
+ * Es gibt:
+ * - genau EINEN internen Zustand
+ * - KEINE doppelte Status- oder Reason-Logik
+ * - KEIN enable/disable-Schalter (immer aktiv, rein passiv)
+ *
+ * =============================================================
+ */
+
+'use strict';
+
+/**
+ * Create pump speed recommendation states
+ *
+ * @param {object} adapter ioBroker adapter instance
+ */
+async function createPumpSpeedStates(adapter) {
+    /**
+     * -------------------------------------------------------------
+     * Channel: pump.speed
+     * -------------------------------------------------------------
+     * Übergeordneter Kanal für alle Datenpunkte zur
+     * Leistungsempfehlung der Hauptpumpe.
+     */
+    await adapter.setObjectNotExistsAsync('pump.speed', {
+        type: 'channel',
+        common: {
+            name: 'Pumpen-Leistungsempfehlung',
+        },
+        native: {},
+    });
+
+    /**
+     * -------------------------------------------------------------
+     * Interner Kernzustand
+     * -------------------------------------------------------------
+     *
+     * pump.speed.state
+     *
+     * ZENTRALER interner Zustand, aus dem alle weiteren
+     * Ausgaben abgeleitet werden.
+     *
+     * Dieser State wird:
+     * - ausschließlich vom späteren Helper gesetzt
+     * - NICHT vom User beschrieben
+     *
+     * Typische Werte:
+     * - off
+     * - frost
+     * - low
+     * - normal
+     * - high
+     * - boost
+     */
+    await adapter.setObjectNotExistsAsync('pump.speed.state', {
+        type: 'state',
+        common: {
+            name: 'Interner Leistungszustand (intern)',
+            type: 'string',
+            role: 'text',
+            read: true,
+            write: false,
+        },
+        native: {},
+    });
+
+    /**
+     * -------------------------------------------------------------
+     * Semantische Ausgabe
+     * -------------------------------------------------------------
+     *
+     * pump.speed.mode
+     *
+     * Menschlich lesbare Darstellung des aktuellen
+     * Leistungszustands.
+     *
+     * Inhaltlich identisch zu pump.speed.state,
+     * dient jedoch explizit für:
+     * - Visualisierung
+     * - Debugging
+     * - Logik in Blockly / Skripten
+     */
+    await adapter.setObjectNotExistsAsync('pump.speed.mode', {
+        type: 'state',
+        common: {
+            name: 'Empfohlener Pumpenmodus',
+            type: 'string',
+            role: 'text',
+            read: true,
+            write: false,
+        },
+        native: {},
+    });
+
+    /**
+     * -------------------------------------------------------------
+     * Technische Ausgabe (Prozentwert)
+     * -------------------------------------------------------------
+     *
+     * pump.speed.percent
+     *
+     * Prozentuale Leistungsempfehlung (0–100 %),
+     * abgeleitet aus:
+     * - pump.speed.state
+     * - User-Mapping unter pump.speed.config.percent.*
+     *
+     * WICHTIG:
+     * - Dieser State ist REIN INFORMATORISCH
+     * - Er darf KEINE Hardware direkt steuern
+     * - write = false ist ABSICHTLICH
+     */
+    await adapter.setObjectNotExistsAsync('pump.speed.percent', {
+        type: 'state',
+        common: {
+            name: 'Empfohlene Pumpenleistung',
+            type: 'number',
+            role: 'value',
+            unit: '%',
+            read: true,
+            write: false,
+        },
+        native: {},
+    });
+
+    /**
+     * -------------------------------------------------------------
+     * Konfiguration: Prozent-Mapping
+     * -------------------------------------------------------------
+     *
+     * In diesem Bereich definiert der User,
+     * wie die einzelnen Leistungszustände
+     * in Prozent interpretiert werden sollen.
+     *
+     * Diese Werte beeinflussen NUR die Ausgabe
+     * von pump.speed.percent – NICHT den Zustand
+     * der Pumpe selbst.
+     */
+
+    await adapter.setObjectNotExistsAsync('pump.speed.config', {
+        type: 'channel',
+        common: {
+            name: 'Konfiguration',
+        },
+        native: {},
+    });
+
+    await adapter.setObjectNotExistsAsync('pump.speed.config.percent', {
+        type: 'channel',
+        common: {
+            name: 'Prozent-Mapping',
+        },
+        native: {},
+    });
+
+    /**
+     * Frostschutz
+     */
+    await adapter.setObjectNotExistsAsync('pump.speed.config.percent.frost', {
+        type: 'state',
+        common: {
+            name: 'Frostschutz (%)',
+            type: 'number',
+            role: 'value',
+            unit: '%',
+            read: true,
+            write: true,
+            persist: true,
+        },
+        native: {},
+    });
+
+    /**
+     * Niedrige Leistung
+     */
+    await adapter.setObjectNotExistsAsync('pump.speed.config.percent.low', {
+        type: 'state',
+        common: {
+            name: 'Niedrige Leistung (%)',
+            type: 'number',
+            role: 'value',
+            unit: '%',
+            read: true,
+            write: true,
+            persist: true,
+        },
+        native: {},
+    });
+
+    /**
+     * Normalbetrieb
+     */
+    await adapter.setObjectNotExistsAsync('pump.speed.config.percent.normal', {
+        type: 'state',
+        common: {
+            name: 'Normalbetrieb (%)',
+            type: 'number',
+            role: 'value',
+            unit: '%',
+            read: true,
+            write: true,
+            persist: true,
+        },
+        native: {},
+    });
+
+    /**
+     * Hohe Leistung
+     */
+    await adapter.setObjectNotExistsAsync('pump.speed.config.percent.high', {
+        type: 'state',
+        common: {
+            name: 'Hohe Leistung (%)',
+            type: 'number',
+            role: 'value',
+            unit: '%',
+            read: true,
+            write: true,
+            persist: true,
+        },
+        native: {},
+    });
+
+    /**
+     * Boost / Wartung / Rückspülen
+     */
+    await adapter.setObjectNotExistsAsync('pump.speed.config.percent.boost', {
+        type: 'state',
+        common: {
+            name: 'Boost / Wartung (%)',
+            type: 'number',
+            role: 'value',
+            unit: '%',
+            read: true,
+            write: true,
+            persist: true,
+        },
+        native: {},
+    });
+}
+
+module.exports = {
+    createPumpSpeedStates,
+};

package/main.js

@@ -15,6 +15,7 @@ const pumpHelper = require('./lib/helpers/pumpHelper');
 const pumpHelper2 = require('./lib/helpers/pumpHelper2');
 const pumpHelper3 = require('./lib/helpers/pumpHelper3');
 const pumpHelper4 = require('./lib/helpers/pumpHelper4');
+const pumpSpeedHelper = require('./lib/helpers/pumpSpeedHelper'); // NEU
 const speechHelper = require('./lib/helpers/speechHelper');
 const consumptionHelper = require('./lib/helpers/consumptionHelper');
 const solarHelper = require('./lib/helpers/solarHelper');
@@ -37,6 +38,7 @@ const { createPumpStates } = require('./lib/stateDefinitions/pumpStates');
 const { createPumpStates2 } = require('./lib/stateDefinitions/pumpStates2');
 const { createPumpStates3 } = require('./lib/stateDefinitions/pumpStates3');
 const { createPumpStates4 } = require('./lib/stateDefinitions/pumpStates4');
+const { createPumpSpeedStates } = require('./lib/stateDefinitions/pumpSpeedStates'); // NEU
 const { createSolarStates } = require('./lib/stateDefinitions/solarStates');
 const { createPhotovoltaicStates } = require('./lib/stateDefinitions/photovoltaicStates');
 const { createGeneralStates } = require('./lib/stateDefinitions/generalStates');
@@ -76,6 +78,7 @@ class Poolcontrol extends utils.Adapter {
         await createPumpStates2(this);
         await createPumpStates3(this);
         await createPumpStates4(this);
+        await createPumpSpeedStates(this); // NEU: Pumpen-Leistungsempfehlung
 
         // --- Temperaturverwaltung ---
         await createTemperatureStates(this);
@@ -143,6 +146,7 @@ class Poolcontrol extends utils.Adapter {
         pumpHelper2.init(this);
         pumpHelper3.init(this);
         pumpHelper4.init(this);
+        pumpSpeedHelper.init(this); // NEU
         speechHelper.init(this);
         consumptionHelper.init(this);
         solarHelper.init(this);
@@ -187,6 +191,9 @@ class Poolcontrol extends utils.Adapter {
             if (pumpHelper4.cleanup) {
                 pumpHelper4.cleanup();
             }
+            if (pumpSpeedHelper.cleanup) {
+                pumpSpeedHelper.cleanup(); // NEU
+            }
             if (speechHelper.cleanup) {
                 speechHelper.cleanup();
             }
@@ -282,6 +289,12 @@ class Poolcontrol extends utils.Adapter {
             this.log.warn(`[pumpHelper4] Fehler in handleStateChange: ${e.message}`);
         }
 
+        try {
+            pumpSpeedHelper.handleStateChange(id, state); // NEU
+        } catch (e) {
+            this.log.warn(`[pumpSpeedHelper] Fehler in handleStateChange: ${e.message}`);
+        }
+
         try {
             speechHelper.handleStateChange(id, state);
         } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iobroker.poolcontrol",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Steuerung & Automatisierung für den Pool (Pumpe, Heizung, Ventile, Sensoren).",
   "author": "DasBo1975 <dasbo1975@outlook.de>",
   "homepage": "https://github.com/DasBo1975/ioBroker.poolcontrol",