iobroker.poolcontrol 0.8.0 → 0.8.2

package/README.md

@@ -93,6 +93,17 @@ Er ermöglicht die Automatisierung von Pumpen-, Temperatur- und Solarsteuerung s
     - Separate Schalter unter `ai.weather.switches.*` zum Aktivieren/Deaktivieren einzelner Prognosefunktionen
     - Ergebnisse werden unter `ai.weather.outputs.forecast_text` gespeichert
 
+      - **Chemie-Hilfe (aiChemistryHelpHelper, ab v0.8.x)**
+    - Interaktive, rein informative KI-Hilfe zur Wasserchemie
+    - Auswahl typischer Poolprobleme über ein Auswahlfeld (z. B. pH zu hoch/niedrig, Chlor wirkt nicht, Wasser grün/trüb)
+    - Ausgabe verständlicher Ursachen- und Lösungsbeschreibungen als Text
+    - Keine automatische Dosierung
+    - Keine Produktempfehlungen
+    - Keine Steuerung von Geräten
+    - Keine Sprachausgabe (rein visuelle Information)
+    - Ziel: Ursachen verstehen und strukturiert vorgehen (messen → korrigieren → filtern → erneut messen)
+    - Datenpunkte unter `ai.chemistry_help.*`
+
   
 - **Info-System (seit v0.7.x)**
   - Informationssystem des Adapters
@@ -165,6 +176,18 @@ Neue Funktionen werden regelmäßig ergänzt – bitte den Changelog beachten.
 ## Changelog
 ### **WORK IN PROGRESS**
 
+## v0.8.2 (2025-12-25)
+- Neues KI-Modul **Chemie-Hilfe** (`aiChemistryHelpHelper`)
+- Rein informatives Hilfesystem zur Poolwasserchemie
+- Auswahl typischer Poolprobleme (z. B. pH zu hoch/niedrig, Chlor wirkt nicht, Wasser grün/trüb)
+- Verständliche Ursachen- und Lösungshinweise als Textausgabe
+- Keine automatische Dosierung
+- Keine Produktempfehlungen
+- Keine Geräte- oder Pumpensteuerung
+- Keine Sprachausgabe (rein visuelle Information)
+- Neue Datenpunkte unter `ai.chemistry_help.*`
+
+
 ## v0.8.0 (2025-12-08)
 - Module: Wetterhinweise (Open-Meteo), Pooltipps, Tageszusammenfassung, Wochenendbericht
 - Automatische Textausgaben mit optionaler Sprachausgabe

package/io-package.json

@@ -1,8 +1,34 @@
 {
   "common": {
     "name": "poolcontrol",
-    "version": "0.8.0",
+    "version": "0.8.2",
     "news": {
+       "0.8.2": {
+         "en": "New AI chemistry help module. Provides an interactive, purely informational help system for common pool water issues (e.g. pH too high/low, chlorine ineffective, green or cloudy water). Generates understandable explanations and solution directions without automatic dosing, product recommendations, device control or speech output.",
+         "de": "Neues KI-Chemie-Hilfesystem. Bietet eine interaktive, rein informative Unterstützung bei typischen Poolwasserproblemen (z. B. pH zu hoch/niedrig, Chlor wirkt nicht, grünes oder trübes Wasser). Erzeugt verständliche Ursachen- und Lösungshinweise ohne automatische Dosierung, Produktempfehlungen, Geräte­steuerung oder Sprachausgabe.",
+         "ru": "Новый модуль помощи по химии бассейна на основе ИИ. Интерактивная, исключительно информационная система поддержки для типичных проблем воды (например, высокий/низкий pH, неэффективный хлор, зелёная или мутная вода). Без автоматического дозирования, рекомендаций продуктов, управления устройствами или голосового вывода.",
+         "pt": "Novo módulo de ajuda química com IA. Sistema interativo e puramente informativo para problemas comuns da água da piscina (por exemplo, pH alto/baixo, cloro ineficaz, água verde ou turva). Sem dosagem automática, recomendações de produtos, controlo de dispositivos ou saída de voz.",
+         "nl": "Nieuw AI-chemiehulpmodule. Biedt een interactieve, puur informatieve hulp voor veelvoorkomende zwembadwaterproblemen (bijv. pH te hoog/laag, chloor werkt niet, groen of troebel water). Geen automatische dosering, productaanbevelingen, apparaatbesturing of spraakuitvoer.",
+         "fr": "Nouveau module d’aide chimique basé sur l’IA. Système interactif et purement informatif pour les problèmes courants de l’eau de piscine (pH trop élevé/bas, chlore inefficace, eau verte ou trouble). Sans dosage automatique, recommandations de produits, contrôle d’appareils ni sortie vocale.",
+         "it": "Nuovo modulo di aiuto chimico basato su IA. Sistema interattivo e puramente informativo per i problemi comuni dell’acqua della piscina (ad es. pH troppo alto/basso, cloro inefficace, acqua verde o torbida). Nessun dosaggio automatico, consigli sui prodotti, controllo dei dispositivi o output vocale.",
+         "es": "Nuevo módulo de ayuda química con IA. Sistema interactivo y puramente informativo para problemas comunes del agua de la piscina (p. ej., pH alto/bajo, cloro ineficaz, agua verde o turbia). Sin dosificación automática, recomendaciones de productos, control de dispositivos ni salida por voz.",
+         "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.",
@@ -67,32 +93,6 @@
          "pl": "Poprawka inicjalizacji czujnika ciśnienia: adapter poprawnie rozpoznaje teraz skonfigurowany identyfikator czujnika w pumpHelper4. Ulepszono również obsługę brakujących lub nieprawidłowych wartości.",
          "uk": "Виправлення ініціалізації датчика тиску: адаптер тепер правильно розпізнає налаштований ID датчика в pumpHelper4. Покращено обробку відсутніх або некоректних значень.",
          "zh-cn": "修复压力传感器初始化：适配器现在可以正确识别 pumpHelper4 中配置的传感器 ID，并改进了对缺失或无效数值的处理。"
-       },
-       "0.7.0": {
-         "en": "Added full pressure sensor integration (pump.pressure.*), including trend detection, self-learning min/max values, diagnostic output and configurable normal pressure range. No automatic control logic – purely informative.",
-         "de": "Vollständige Drucksensor-Integration (pump.pressure.*) hinzugefügt, inklusive Trenderkennung, selbstlernenden Min-/Max-Werten, Diagnoseausgabe und einstellbarem Normaldruckbereich. Keine automatische Logik – rein informativ.",
-         "ru": "Добавлена полная интеграция датчика давления (pump.pressure.*), включая определение тренда, самообучающиеся минимальные/максимальные значения, диагностический вывод и настраиваемый диапазон нормального давления. Без автоматической логики – только информация.",
-         "pt": "Adicionada integração completa do sensor de pressão (pump.pressure.*), incluindo detecção de tendência, valores mínimos/máximos autoaprendidos, saída de diagnóstico e faixa de pressão normal configurável. Sem lógica automática – apenas informativo.",
-         "nl": "Volledige druksensorintegratie (pump.pressure.*) toegevoegd, inclusief trenddetectie, zelflerende min/max-waarden, diagnostische uitvoer en instelbaar normaaldrukbereik. Geen automatische logica – puur informatief.",
-         "fr": "Intégration complète du capteur de pression (pump.pressure.*) ajoutée, comprenant la détection de tendance, des valeurs min/max auto-apprises, une sortie de diagnostic et une plage de pression normale configurable. Aucune logique automatique – uniquement informatif.",
-         "it": "Aggiunta integrazione completa del sensore di pressione (pump.pressure.*), con rilevamento delle tendenze, valori min/max autoapprendenti, output diagnostico e intervallo di pressione normale configurabile. Nessuna logica automatica – solo informativo.",
-         "es": "Se añadió la integración completa del sensor de presión (pump.pressure.*), incluyendo detección de tendencia, valores mínimos/máximos autoaprendidos, salida de diagnóstico y rango de presión normal configurable. Sin lógica automática – solo informativo.",
-         "pl": "Dodano pełną integrację czujnika ciśnienia (pump.pressure.*), w tym wykrywanie trendów, samo uczące się wartości min/max, dane diagnostyczne oraz konfigurowalny zakres ciśnienia normalnego. Bez automatycznej logiki – wyłącznie informacyjne.",
-         "uk": "Додано повну інтеграцію датчика тиску (pump.pressure.*), включаючи визначення трендів, самонавчальні мін/макс значення, діагностичний вихід та налаштовуваний діапазон нормального тиску. Без автоматичної логіки – лише інформаційно.",
-         "zh-cn": "新增完整压力传感器集成 (pump.pressure.*)，包括趋势检测、自学习最小/最大值、诊断输出以及可配置的正常压力范围。无自动控制逻辑，仅提供信息。"
-       },
-       "0.6.5": {
-         "en": "Fix for weekly, monthly and yearly reset in consumptionHelper",
-         "de": "Fix für Wochen-, Monats- und Jahres-Reset im ConsumptionHelper",
-         "ru": "Исправление еженедельного, ежемесячного и ежегодного сброса в consumptionHelper",
-         "pt": "Correção para redefinição semanal, mensal e anual no consumptionHelper",
-         "nl": "Fix voor wekelijkse, maandelijkse en jaarlijkse reset in consumptionHelper",
-         "fr": "Correctif pour la réinitialisation hebdomadaire, mensuelle et annuelle dans consumptionHelper",
-         "it": "Correzione per il reset settimanale, mensile e annuale in consumptionHelper",
-         "es": "Corrección para el reinicio semanal, mensual y anual en consumptionHelper",
-         "pl": "Poprawka cotygodniowego, comiesięcznego i corocznego resetu w consumptionHelper",
-         "uk": "Виправлення щотижневого, щомісячного та щорічного скидання в consumptionHelper",
-         "zh-cn": "修复 consumptionHelper 中每周、每月和每年重置的问题"
        }
 	},
     "titleLang": {

package/lib/helpers/aiChemistryHelpHelper.js

@@ -0,0 +1,392 @@
+'use strict';
+/* eslint-disable jsdoc/require-param-description */
+/* eslint-disable jsdoc/require-returns-description */
+
+/**
+ * aiChemistryHelpHelper
+ * --------------------------------------------------------------
+ * KI-Chemie-Hilfe für PoolControl (rein informativ).
+ *
+ * Nutzt die States aus aiChemistryHelpStates.js:
+ *   ai.chemistry_help.issue
+ *   ai.chemistry_help.help_text
+ *   ai.chemistry_help.last_issue_time
+ *
+ * Prinzip:
+ *  - User wählt ein beobachtetes Problem (issue)
+ *  - Helper schreibt einen erklärenden Text (help_text)
+ *
+ * WICHTIG:
+ *  - Keine Dosierungen
+ *  - Keine Produktempfehlungen
+ *  - Keine Steuerung / Automatik
+ *  - Keine Sprachausgabe (speech.queue bleibt unberührt)
+ *
+ * Inhalte:
+ *  - Allgemeine Ursachen
+ *  - Wichtige Zusammenhänge (pH ↔ Chlor ↔ Filterung)
+ *  - Übliche Lösungsrichtungen (schrittweise, messen, zirkulieren)
+ */
+
+const aiChemistryHelpHelper = {
+    adapter: null,
+
+    /**
+     * Initialisiert den Helper.
+     *
+     * @param {import('iobroker').Adapter} adapter
+     */
+    async init(adapter) {
+        this.adapter = adapter;
+        this.adapter.log.info('[aiChemistryHelpHelper] Initialisierung gestartet');
+
+        // NEU: auf Auswahländerungen reagieren
+        this.adapter.subscribeStates('ai.chemistry_help.issue');
+
+        // NEU: beim Start aktuellen Auswahlwert übernehmen (wenn vorhanden)
+        try {
+            const st = await this.adapter.getStateAsync('ai.chemistry_help.issue');
+            if (st && st.val !== null && st.val !== undefined) {
+                await this._processIssue(String(st.val));
+            }
+        } catch (e) {
+            this.adapter.log.debug(`[aiChemistryHelpHelper] Init: Konnte issue nicht lesen: ${e.message}`);
+        }
+
+        this.adapter.log.info('[aiChemistryHelpHelper] Initialisierung abgeschlossen');
+    },
+
+    /**
+     * Aufräumen beim Adapter-Stop.
+     */
+    cleanup() {
+        // aktuell keine Timer / Intervalle
+        this.adapter && this.adapter.log.debug('[aiChemistryHelpHelper] Cleanup abgeschlossen');
+    },
+
+    /**
+     * Reagiert auf State-Änderungen.
+     *
+     * @param {string} id
+     * @param {ioBroker.State | null} state
+     */
+    async handleStateChange(id, state) {
+        if (!this.adapter) {
+            return;
+        }
+        if (!state) {
+            return;
+        }
+
+        // Eigene Rückschreibungen ignorieren (Loop-Schutz)
+        if (
+            state.ack === true &&
+            (id.endsWith('.ai.chemistry_help.help_text') || id.endsWith('.ai.chemistry_help.last_issue_time'))
+        ) {
+            return;
+        }
+
+        // Nur unser relevanter Datenpunkt
+        if (!id.includes('.ai.chemistry_help.issue')) {
+            return;
+        }
+
+        let issue = 'none';
+
+        // Enum-Auswahl: Index → String auflösen
+        if (typeof state.val === 'number') {
+            try {
+                const obj = await this.adapter.getObjectAsync(id);
+                if (obj?.common?.states) {
+                    issue = obj.common.states[state.val] || 'none';
+                }
+            } catch (e) {
+                this.adapter.log.debug(`[aiChemistryHelpHelper] Konnte Enum-Text nicht auflösen: ${e.message}`);
+            }
+        } else {
+            issue = String(state.val || 'none');
+        }
+        this.adapter.log.debug(`[aiChemistryHelpHelper] Auswahl geändert: ${issue}`);
+
+        await this._processIssue(issue);
+    },
+
+    // ---------------------------------------------------------------------
+    // Core
+    // ---------------------------------------------------------------------
+
+    /**
+     * Schreibt Text + Timestamp für das gewählte Problem.
+     *
+     * @param {string} issue
+     */
+    async _processIssue(issue) {
+        const normalized = (issue || 'none').trim();
+
+        // "none" oder leer → Text leeren
+        if (!normalized || normalized === 'none') {
+            await this._setStateIfChanged('ai.chemistry_help.help_text', '');
+            await this._setStateIfChanged('ai.chemistry_help.last_issue_time', Date.now());
+            return;
+        }
+
+        const text = this._getHelpText(normalized);
+
+        await this.adapter.setStateAsync('ai.chemistry_help.help_text', {
+            val: text,
+            ack: true,
+        });
+        await this.adapter.setStateAsync('ai.chemistry_help.last_issue_time', {
+            val: Date.now(),
+            ack: true,
+        });
+    },
+
+    /**
+     * Liefert den finalen Hilfetext (Deutsch) für ein Problem.
+     *
+     * @param {string} issue
+     * @returns {string}
+     */
+    _getHelpText(issue) {
+        const commonFooter =
+            '\n\nWichtig:\n' +
+            '• Immer schrittweise vorgehen: erst messen → klein korrigieren → umwälzen lassen → erneut messen.\n' +
+            '• Angaben auf dem Produkt beachten (Konzentration/Beckenvolumen unterscheiden sich).\n' +
+            '• Wenn du unsicher bist: lieber langsamer korrigieren als „mit Gewalt“.\n';
+
+        const map = {
+            // ----------------------------------------------------------
+            // pH
+            // ----------------------------------------------------------
+            ph_low:
+                `Problem: pH-Wert ist zu niedrig (Wasser ist „zu sauer“).\n\n` +
+                `Was das bedeutet:\n` +
+                `Ein zu niedriger pH-Wert kann Material (Metalle/Einbauteile) stärker angreifen und Badereizungen begünstigen. Außerdem kann die Wasserbalance insgesamt instabil werden.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Viel Regen-/Frischwasser (kann das Wasser „ansäuern“)\n` +
+                `• Niedrige Alkalinität (Puffer fehlt → pH fällt schneller)\n` +
+                `• Häufige Korrekturen/Backwash/Wasserwechsel\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• pH mit einem „pH-Plus“/pH-Heber schrittweise anheben.\n` +
+                `• Wenn der pH ständig wieder fällt: Totalalkalinität/„Puffer“ mit prüfen, weil sonst jede pH-Korrektur nur kurz hält.\n${
+                    commonFooter
+                }`,
+
+            ph_high:
+                `Problem: pH-Wert ist zu hoch (Wasser ist „zu basisch“).\n\n` +
+                `Was das bedeutet:\n` +
+                `Bei zu hohem pH-Wert arbeitet Chlor/Desinfektion oft schlechter, und es kann leichter zu Trübungen/Ausfällungen kommen (z. B. Kalk). Außerdem können Augen/Haut gereizt sein.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Starkes „Ausgasen“/viel Sprudel (CO₂ entweicht → pH steigt)\n` +
+                `• Hartes Wasser / hohe Alkalinität\n` +
+                `• Manche Becken/Materialien können anfangs pH nach oben ziehen\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• pH mit „pH-Minus“/pH-Senker in kleinen Schritten senken.\n` +
+                `• Bei wiederkehrend hohem pH: Alkalinität/Wasserhärte mit betrachten, weil das die Stabilität stark beeinflusst.\n${
+                    commonFooter
+                }`,
+
+            // ----------------------------------------------------------
+            // Chlor
+            // ----------------------------------------------------------
+            chlor_low:
+                `Problem: Chlorwert ist zu niedrig.\n\n` +
+                `Was das bedeutet:\n` +
+                `Zu wenig wirksames Chlor kann dazu führen, dass sich Keime/Algen leichter vermehren. Häufig sieht man dann zuerst „müdes“ Wasser: weniger klar, mehr Geruch, schneller Belag.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Viel Sonne/UV (Chlor wird schneller abgebaut)\n` +
+                `• Hohe Badebelastung (Schweiß/Organik „verbraucht“ Chlor)\n` +
+                `• pH-Wert ungünstig (Chlor wirkt schlechter)\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Desinfektion wieder in einen normalen Bereich bringen und parallel pH kontrollieren.\n` +
+                `• Wenn Chlor dauerhaft „wegbricht“: Ursachen wie organische Belastung/Filterzustand/Umwälzung mit prüfen.\n${
+                    commonFooter
+                }`,
+
+            chlor_high:
+                `Problem: Chlorwert ist zu hoch.\n\n` +
+                `Was das bedeutet:\n` +
+                `Zu hoher Chlorwert kann Augen/Haut reizen, starken Geruch verursachen und Material/Abdeckungen stärker belasten. In diesem Zustand ist „mehr Chemie“ fast nie die richtige Richtung.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Zu viel nachdosiert / Schockbehandlung zu hoch\n` +
+                `• Zu wenig Abbau (Abdeckung drauf + wenig Sonne)\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Keine weitere Chlorzugabe.\n` +
+                `• Zeit wirken lassen (Sonne/UV baut Chlor ab) und gut umwälzen.\n` +
+                `• Erst wenn Chlor wieder im normalen Bereich ist, weitere Korrekturen (z. B. pH) sinnvoll bewerten.\n${
+                    commonFooter
+                }`,
+
+            chlor_no_effect:
+                `Problem: „Chlor steigt trotz Zugabe nicht“.\n\n` +
+                `Was das bedeutet:\n` +
+                `Das passiert häufig, wenn das Wasser eine hohe „Chlornachfrage“ hat: Das zugegebene Chlor wird sofort verbraucht, bevor ein stabiler freier Chlorwert messbar bleibt.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Hohe organische Belastung (Schmutz, Biofilm, starke Nutzung)\n` +
+                `• Beginnender/unsichtbarer Algenbefall\n` +
+                `• Stark falscher pH-Wert (Wirkung eingeschränkt)\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Erst Grundwerte prüfen (pH, Filter/Umwälzung, Sichtprüfung auf Beläge).\n` +
+                `• Wasser „sauber bekommen“ (Filter reinigen/rückspülen, Becken bürsten), damit Chlor nicht nur „verbraucht“ wird.\n` +
+                `• Wenn dauerhaft keine Wirkung messbar ist, liegt oft ein „oxidativer Bedarf“ vor (Chlor wird sofort gebunden/abgebaut) – dann hilft nur konsequent Ursachen reduzieren und danach erneut messen.\n${
+                    commonFooter
+                }`,
+
+            chlor_smell:
+                `Problem: Starker „Chlorgeruch“ trotz Messwert.\n\n` +
+                `Was das bedeutet:\n` +
+                `Der typische „Hallenbad-Geruch“ kommt oft nicht von „zu viel gutem Chlor“, sondern von gebundenen Chlorverbindungen (Chloramine). Diese entstehen, wenn Chlor sich mit Stickstoff-/Organik aus Schweiß/Urinfrachten verbindet.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Hohe Badebelastung / organische Einträge\n` +
+                `• Zu wenig Frischwasser/Abbau/Filterpflege\n` +
+                `• Schlechte Lüftung (bei Indoor-Pools) verstärkt die Wahrnehmung\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Ziel ist, gebundene Belastung zu reduzieren: gute Umwälzung/Filtration, Beckenreinigung, ggf. Frischwasseranteil.\n` +
+                `• Parallel pH prüfen, weil falscher pH die Desinfektion zusätzlich verschlechtert.\n${commonFooter}`,
+
+            // ----------------------------------------------------------
+            // Wasserbild / Optik
+            // ----------------------------------------------------------
+            water_green:
+                `Problem: Wasser ist grün.\n\n` +
+                `Was das bedeutet:\n` +
+                `Grünes Wasser ist sehr häufig ein Hinweis auf Algenwachstum (oft ausgelöst durch zu wenig wirksames Chlor und/oder schlechte Umwälzung).\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Freies Chlor zu niedrig oder „verbraucht“\n` +
+                `• pH zu hoch → Chlor wirkt deutlich schlechter\n` +
+                `• Filter/Umwälzung unzureichend oder Filter verschmutzt\n` +
+                `• Hohe Temperatur + Sonne (Algenwachstum wird begünstigt)\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Wasserwerte prüfen (insb. pH und Chlor) und Umwälzung/Filterzustand verbessern.\n` +
+                `• Becken gründlich bürsten/absaugen, damit Beläge nicht „überleben“.\n` +
+                `• Danach geduldig filtern lassen, bis das Wasser wieder klar wird.\n${commonFooter}`,
+
+            water_cloudy:
+                `Problem: Wasser ist trüb / grau / milchig.\n\n` +
+                `Was das bedeutet:\n` +
+                `Trübes Wasser entsteht oft durch feine Schwebstoffe oder chemische Ungleichgewichte (z. B. pH/Alkalinität/Kalk), die der Filter nicht gut „packt“.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Filter verschmutzt/zu kurze Filterlaufzeit\n` +
+                `• pH/Alkalinität außerhalb des stabilen Bereichs\n` +
+                `• Hohe Wasserhärte (Kalk) – besonders in Kombination mit hohem pH\n` +
+                `• Zu wenig Desinfektion → biologische Trübung möglich\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Filterzustand prüfen (Reinigung/Rückspülen) und ausreichend umwälzen.\n` +
+                `• Grundwerte pH/Chlor prüfen und stabilisieren.\n` +
+                `• Wenn die Trübung „mineralisch“ wirkt (milchig/weiß): Wasserhärte/Balance mit betrachten.\n${
+                    commonFooter
+                }`,
+
+            algae_visible:
+                `Problem: Algen an Wänden oder Boden sichtbar.\n\n` +
+                `Was das bedeutet:\n` +
+                `Sichtbare Algen sind ein klares Zeichen, dass die Desinfektion/Umwälzung nicht ausreichend war oder lokal tote Zonen entstehen (Ecken/Leitungen).\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Chlor zu niedrig oder „verbraucht“\n` +
+                `• pH zu hoch (Chlor wirkt schlechter)\n` +
+                `• Zu wenig Bürsten/Beckenpflege, schlechte Zirkulation\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Mechanik zuerst: konsequent bürsten/absaugen, Filterpflege.\n` +
+                `• Werte (pH/Chlor) danach stabilisieren und Umwälzung verbessern.\n` +
+                `• Ziel ist, Algen nicht nur „chemisch“, sondern auch mechanisch zu entfernen.\n${commonFooter}`,
+
+            foam_on_surface:
+                `Problem: Schaumbildung auf der Wasseroberfläche.\n\n` +
+                `Was das bedeutet:\n` +
+                `Schaum entsteht oft durch Tenside/Organik (Sonnencreme, Körperpflege, Reinigungsreste), manche Algenmittel/Polymere oder auch Luft im System. Es ist meist kein „Chlor-Problem“, sondern ein „Stoffe-im-Wasser“-Problem.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Viele Lotionen/Öle im Wasser, hohe organische Belastung\n` +
+                `• Bestimmte algenhemmende Mittel können Schaum begünstigen\n` +
+                `• Luft zieht ins System (kleine Undichtigkeiten) → Schaum wirkt stärker\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Oberfläche abschöpfen, Filter sauber halten, organische Einträge reduzieren.\n` +
+                `• pH/Chlor im Blick behalten (stabile Werte helfen, Organik schneller abzubauen).\n` +
+                `• Wenn Schaum dauerhaft bleibt: Quelle (Produkte/Einträge/Technik) systematisch eingrenzen.\n${
+                    commonFooter
+                }`,
+
+            // ----------------------------------------------------------
+            // Badegefühl / Stabilität
+            // ----------------------------------------------------------
+            skin_eye_irritation:
+                `Problem: Haut- oder Augenreizungen beim Baden.\n\n` +
+                `Was das bedeutet:\n` +
+                `Reizungen können verschiedene Ursachen haben: zu hoher oder sehr niedriger pH, zu hohe Desinfektionskonzentration, oder gebundene Chlorverbindungen (Chloramine) bei organischer Belastung.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• pH außerhalb des Wohlfühlbereichs\n` +
+                `• Chlor deutlich zu hoch\n` +
+                `• „Chlorgeruch“/Chloramine durch starke organische Einträge\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Zuerst messen (pH & Chlor) und Werte wieder in einen normalen Bereich bringen.\n` +
+                `• Becken/Filter sauber halten, damit organische Belastung nicht in „gebundene“ Formen kippt.\n` +
+                `• Bei starken Beschwerden: Baden pausieren, bis Wasserwerte stabil sind.\n${commonFooter}`,
+
+            values_unstable:
+                `Problem: Wasserwerte sind häufig instabil (kippen schnell).\n\n` +
+                `Was das bedeutet:\n` +
+                `Wenn pH/Chlor ständig stark schwanken, fehlt oft „Stabilität“ im Wasser: Puffer (Alkalinität) zu niedrig/zu hoch, wechselnde Belastung, oder die Umwälzung/Filtration ist nicht konstant genug.\n\n` +
+                `Häufige Ursachen:\n` +
+                `• Totalalkalinität zu niedrig → pH springt/kippt schnell\n` +
+                `• Viele kleine Korrekturen ohne ausreichende Umwälzzeit\n` +
+                `• Filterzustand schlecht / zu kurze Filterzeiten\n` +
+                `• Starke externe Einflüsse (Regen, Hitze, hohe Nutzung)\n\n` +
+                `Übliche Lösungsrichtung:\n` +
+                `• Einmal „Basis“ stabil bekommen (Puffer/Filter/Regelmäßigkeit), dann erst fein korrigieren.\n` +
+                `• Korrigieren immer in kleinen Schritten und mit Zeit zum Durchmischen.\n${commonFooter}`,
+
+            unknown_problem:
+                `Problem: Unklar, was genau los ist.\n\n` +
+                `Vorgehen (minimal & sinnvoll):\n` +
+                `1) Sichtcheck: Grün? Trüb? Beläge? Schaum?\n` +
+                `2) Zwei Messwerte reichen für den Start: pH + freies Chlor.\n` +
+                `3) Technik prüfen: Läuft die Umwälzung? Filter sauber? Rückspülen nötig?\n\n` +
+                `Typische Faustregel:\n` +
+                `• Optik-Probleme (grün/trüb) sind sehr oft eine Kombination aus Desinfektion + pH + Filterung.\n` +
+                `• „Geruch/Reizung“ ist oft nicht „zu viel Chlor“, sondern „falsch gebunden/organisch belastet“.\n${
+                    commonFooter
+                }`,
+        };
+
+        if (map[issue]) {
+            return map[issue];
+        }
+
+        // Fallback
+        return (
+            `Hinweis: Dieses Problem ist (noch) nicht bekannt.\n\n` +
+            `Bitte wähle einen der vorhandenen Punkte aus oder nutze „Problem unklar / nicht eindeutig“.\n${
+                commonFooter
+            }`
+        );
+    },
+
+    // ---------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------
+
+    /**
+     * Setzt einen State nur dann, wenn sich der Wert wirklich ändert.
+     * Verhindert unnötige State-Writes und mögliche Loop-Effekte.
+     *
+     * @param {string} id
+     * @param {string|number|boolean} value
+     */
+    async _setStateIfChanged(id, value) {
+        try {
+            const current = await this.adapter.getStateAsync(id);
+            const curVal = current ? current.val : undefined;
+
+            // String/Number/Bool robust vergleichen
+            if (String(curVal ?? '') === String(value ?? '')) {
+                return;
+            }
+
+            await this.adapter.setStateAsync(id, { val: value, ack: true });
+        } catch (e) {
+            this.adapter.log.debug(`[aiChemistryHelpHelper] _setStateIfChanged Fehler (${id}): ${e.message}`);
+        }
+    },
+};
+
+module.exports = aiChemistryHelpHelper;

package/lib/helpers/aiForecastHelper.js

@@ -38,6 +38,11 @@ const aiForecastHelper = {
 
         await this._refreshTimer();
 
+        // ----------------------------------------------------------
+        // NEU: Delay, damit ioBroker alle States laden kann
+        // ----------------------------------------------------------
+        await new Promise(res => setTimeout(res, 1500));
+
         // ----------------------------------------------------------
         // NEU: Sofortige Ausführung beim Adapterstart (wenn aktiviert)
         // ----------------------------------------------------------

package/lib/helpers/aiHelper.js

@@ -47,6 +47,8 @@ const aiHelper = {
     _lastScheduleValues: {}, // NEU: merkt sich letzte Zeitwerte
     _debugMode: false,
 
+    _adapterStartedAt: Date.now(), // FIX: Zeitpunkt des Adapterstarts
+
     // Anti-Spam-Level (merkt sich letzte Warnungen)
     _lastPoolTipCode: null,
     _lastPoolTipWindLevel: null,
@@ -120,6 +122,11 @@ const aiHelper = {
             // Timer neu aufbauen
             await this._refreshTimers();
 
+            // ----------------------------------------------------------
+            // NEU: Delay, damit ioBroker alle States laden kann
+            // ----------------------------------------------------------
+            await new Promise(res => setTimeout(res, 1500));
+
             // NEU: Wenn Uhrzeit heute noch in der Zukunft liegt → sofort ausführen
             try {
                 const now = new Date();
@@ -303,15 +310,20 @@ const aiHelper = {
         const timer = setInterval(async () => {
             const now = new Date();
 
-            // --- NEU: Nachträgliche Ausführung, falls Zeit knapp verpasst wurde ---
+            // --- FIX: Nachholen nur in den ersten 3 Minuten nach Adapterstart ---
             const diffMinutes = now.getHours() * 60 + now.getMinutes() - (hour * 60 + minute);
 
-            if (diffMinutes > 0 && diffMinutes <= 2) {
+            const adapterUptimeMs = Date.now() - this._adapterStartedAt;
+            const withinStartupWindow = adapterUptimeMs <= 3 * 60 * 1000; // 3 Minuten
+
+            if (withinStartupWindow && diffMinutes > 0 && diffMinutes <= 2) {
                 try {
                     await callback();
-                    this.adapter.log.debug('[aiHelper] Zeit knapp verpasst – nachträgliche Ausführung durchgeführt');
+                    this.adapter.log.info(
+                        '[aiHelper] Nachholung ausgeführt (innerhalb der ersten 3 Minuten nach Start)',
+                    );
                 } catch (err) {
-                    this.adapter.log.warn(`[aiHelper] Fehler bei nachträglicher Ausführung: ${err.message}`);
+                    this.adapter.log.warn(`[aiHelper] Fehler bei Nachholung: ${err.message}`);
                 }
             }
 

package/lib/stateDefinitions/aiChemistryHelpStates.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * aiChemistryHelpStates.js
+ * ----------------------------------------------------------
+ * Legt die States für die KI-Chemie-Hilfe an.
+ *
+ * Zweck:
+ *  - Manuelle Auswahl eines beobachteten Pool-Problems
+ *  - Ausgabe eines erklärenden Hilfetextes (ohne Dosierung)
+ *
+ * Struktur:
+ *   ai.chemistry_help.*
+ *
+ * Hinweis:
+ *  - Reine Informationsfunktion
+ *  - Keine Steuerung, keine Automatik, keine Sprachausgabe
+ * ----------------------------------------------------------
+ */
+
+/**
+ * Erstellt alle States für die AI-Chemie-Hilfe.
+ *
+ * @param {import('iobroker').Adapter} adapter - ioBroker Adapterinstanz
+ */
+async function createAiChemistryHelpStates(adapter) {
+    adapter.log.debug('[aiChemistryHelpStates] Initialisierung gestartet');
+
+    // ----------------------------------------------------------
+    // Channel: ai.chemistry_help
+    // ----------------------------------------------------------
+    await adapter.setObjectNotExistsAsync('ai.chemistry_help', {
+        type: 'channel',
+        common: {
+            name: 'Chemie-Hilfe (Erklärungen & Ursachen)',
+        },
+        native: {},
+    });
+
+    // ----------------------------------------------------------
+    // Auswahl des Problems (manuell)
+    // ----------------------------------------------------------
+    await adapter.setObjectNotExistsAsync('ai.chemistry_help.issue', {
+        type: 'state',
+        common: {
+            name: 'Chemie-Hilfe: Problem auswählen',
+            desc: 'Manuelle Auswahl eines beobachteten Pool-Problems zur Anzeige allgemeiner Erklärungen.',
+            type: 'string',
+            role: 'value',
+            read: true,
+            write: true,
+            def: 'none',
+            states: {
+                none: 'Kein Problem ausgewählt',
+
+                // pH-Wert
+                ph_low: 'pH-Wert ist zu niedrig',
+                ph_high: 'pH-Wert ist zu hoch',
+
+                // Chlor / Desinfektion
+                chlor_low: 'Chlorwert ist zu niedrig',
+                chlor_high: 'Chlorwert ist zu hoch',
+                chlor_no_effect: 'Chlor steigt trotz Zugabe nicht',
+                chlor_smell: 'Starker Chlorgeruch trotz Messwert',
+
+                // Wasserbild / Optik
+                water_green: 'Wasser ist grün',
+                water_cloudy: 'Wasser ist trüb / grau / milchig',
+                algae_visible: 'Algen an Wänden oder Boden sichtbar',
+                foam_on_surface: 'Schaumbildung auf der Wasseroberfläche',
+
+                // Badegefühl / Stabilität
+                skin_eye_irritation: 'Haut- oder Augenreizungen beim Baden',
+                values_unstable: 'Wasserwerte sind häufig instabil',
+
+                // Unsicherheit
+                unknown_problem: 'Problem unklar / nicht eindeutig',
+            },
+        },
+        native: {},
+    });
+
+    // ----------------------------------------------------------
+    // Erklärungstext (wird später vom Helper gefüllt)
+    // ----------------------------------------------------------
+    await adapter.setObjectNotExistsAsync('ai.chemistry_help.help_text', {
+        type: 'state',
+        common: {
+            name: 'Chemie-Hilfe: Erklärung',
+            desc: 'Erklärender Text zu Ursachen und allgemeinen Lösungsansätzen (keine Dosierung, keine Steuerung).',
+            type: 'string',
+            role: 'text',
+            read: true,
+            write: false,
+            def: '',
+        },
+        native: {},
+    });
+
+    // ----------------------------------------------------------
+    // Zeitpunkt der letzten Auswahl
+    // ----------------------------------------------------------
+    await adapter.setObjectNotExistsAsync('ai.chemistry_help.last_issue_time', {
+        type: 'state',
+        common: {
+            name: 'Chemie-Hilfe: Letzte Auswahl',
+            desc: 'Zeitpunkt der letzten Auswahl eines Chemie-Hilfe-Problems.',
+            type: 'number',
+            role: 'value.time',
+            read: true,
+            write: false,
+            def: 0,
+        },
+        native: {},
+    });
+
+    adapter.log.debug('[aiChemistryHelpStates] Initialisierung abgeschlossen');
+}
+
+module.exports = {
+    createAiChemistryHelpStates,
+};

package/main.js

@@ -23,6 +23,7 @@ const statusHelper = require('./lib/helpers/statusHelper');
 const photovoltaicHelper = require('./lib/helpers/photovoltaicHelper');
 const aiHelper = require('./lib/helpers/aiHelper');
 const aiForecastHelper = require('./lib/helpers/aiForecastHelper');
+const aiChemistryHelpHelper = require('./lib/helpers/aiChemistryHelpHelper');
 const controlHelper = require('./lib/helpers/controlHelper');
 const controlHelper2 = require('./lib/helpers/controlHelper2');
 const debugLogHelper = require('./lib/helpers/debugLogHelper');
@@ -47,6 +48,7 @@ const { createControlStates } = require('./lib/stateDefinitions/controlStates');
 const { createDebugLogStates } = require('./lib/stateDefinitions/debugLogStates');
 const { createInfoStates } = require('./lib/stateDefinitions/infoStates');
 const { createAiStates } = require('./lib/stateDefinitions/aiStates'); // NEU: KI-States
+const { createAiChemistryHelpStates } = require('./lib/stateDefinitions/aiChemistryHelpStates'); // NEU: KI-Chemie-Hilfe
 
 class Poolcontrol extends utils.Adapter {
     constructor(options) {
@@ -115,6 +117,7 @@ class Poolcontrol extends utils.Adapter {
 
         // --- AI States ---
         await createAiStates(this); // NEU: KI-States anlegen
+        await createAiChemistryHelpStates(this); // NEU: KI-Chemie-Hilfe-States
 
         // --- Migration Helper zuletzt starten ---
         await migrationHelper.init(this);
@@ -136,6 +139,7 @@ class Poolcontrol extends utils.Adapter {
         photovoltaicHelper.init(this);
         aiHelper.init(this);
         aiForecastHelper.init(this);
+        aiChemistryHelpHelper.init(this);
         frostHelper.init(this);
         statusHelper.init(this);
         infoHelper.init(this);
@@ -201,6 +205,9 @@ class Poolcontrol extends utils.Adapter {
             if (aiForecastHelper.cleanup) {
                 aiForecastHelper.cleanup();
             }
+            if (aiChemistryHelpHelper.cleanup) {
+                aiChemistryHelpHelper.cleanup();
+            }
             if (infoHelper.cleanup) {
                 infoHelper.cleanup();
             }
@@ -283,6 +290,11 @@ class Poolcontrol extends utils.Adapter {
         } catch (e) {
             this.log.warn(`[main] Fehler in aiForecastHelper.handleStateChange: ${e.message}`);
         }
+        try {
+            aiChemistryHelpHelper.handleStateChange(id, state);
+        } catch (e) {
+            this.log.warn(`[main] Fehler in aiChemistryHelpHelper.handleStateChange: ${e.message}`);
+        }
         try {
             statusHelper.handleStateChange(id, state);
         } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iobroker.poolcontrol",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Steuerung & Automatisierung für den Pool (Pumpe, Heizung, Ventile, Sensoren).",
   "author": "DasBo1975 <dasbo1975@outlook.de>",
   "homepage": "https://github.com/DasBo1975/ioBroker.poolcontrol",
@@ -15,7 +15,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/DasBo1975/ioBroker.poolcontrol.git"
+    "url": "git+https://github.com/DasBo1975/ioBroker.poolcontrol.git"
   },
   "engines": {
     "node": ">= 20"