iobroker.smartloadmanager 0.1.2 → 0.4.1

package/docs/en/README.md

@@ -0,0 +1,275 @@
+![Logo](../../admin/smartloadmanager.png)
+
+# ioBroker.smartloadmanager
+
+## Version 0.2.0 examples
+
+Requires Node.js >=22.19.0. Device commands use `ack: false`; the device adapter
+provides the acknowledgement. Feed-in must represent grid connection power in watts.
+Enable `feedinNegativ` when export is negative. Baseload is an additional reserve;
+do not subtract household consumption twice if it is already included in the meter reading.
+
+### Binary loads and heating
+
+Example: `performance: 1000`, `switchOnPoint: 1200`, `switchOffPoint: 0`,
+`switchOnDelay: 20`, `switchOffDelay: 10`. A 1200 W surplus after baseload starts
+the on timer. Import or surplus below the off threshold starts the off timer.
+`minimumOnMinutes: 10` and `minimumOffMinutes: 5` reduce cycling; import above
+`forecastMaxGridImport` overrides minimum runtime. Set minimum times to 0 to disable them.
+
+Use `datapoint` for boolean switching and `numericDatapoint` for numeric 0/1.
+Heating consumers additionally support temperature, enable and heartbeat inputs.
+Maximum temperature and missing enable/heartbeat prevent activation.
+Heartbeat checks the input's truth value, not the age of its last update.
+A missing or nonfinite configured temperature sensor prevents activation and
+stops automatic heating. “Switch off only at switch-off time” intentionally
+disables normal surplus shutdown until the time window ends; heating protection remains active.
+
+### Percentage and battery control
+
+A 2000 W percent consumer at 50% consumes 1000 W. With 400 W additional export,
+the target becomes 70%. With 200 W import it becomes 40%. Below `minPercentStart`,
+the target becomes 0%. Disabled consumers are not regulated. This calculation
+assumes the load is included in the grid meter reading.
+
+Configure a battery's `batterySetpoint`, `performance`, and optional `batterySOC`
+and `batteryTargetSOC`. With 800 W surplus and a 1500 W rating, the charging command
+is 800 W. Reaching target SOC sets charging power to 0. The optional global battery
+mode datapoint uses 0 (off), 1 (target reached), and 2 (charging); verify that these
+values match the device adapter.
+
+`controlMode`: 0 = off, 1 = manual on, 2 = automatic. Manual on sets a percent load
+to 100% or battery charging power to its configured rating. Automatic regulators
+respect manual modes.
+Battery control includes already requested charging power and corrects it by the
+measured grid surplus. `batteryDelaySeconds` and `delaySecondsProzent` remain
+effective during frequent meter updates; 0 means immediate regulation.
+Missing configured SOC/target SOC values stop charging. Time windows are also
+checked every 15 seconds. Disabling a consumer cancels pending switches but leaves
+its existing device state unchanged; use `controlMode: 0` to switch it off.
+
+### PV forecast example
+
+Enable `enableForecast`, select e.g. `pvforecast.0.summary.JSONData` as
+`forecastJsonDatapoint`, and enable `useForecast` for the consumer.
+Alternatively select `pvforecast.0.plants.<plant name>.JSONData` to use one plant.
+Both global forecast control and the individual consumer's forecast option must be
+enabled. Decision notifications do not enable forecast control and are emitted only
+when a forecast actually affects control. Version 0.2.0 logs imports at debug level.
+Version 0.4.1 logs configuration, imports and enabled decision
+notifications only at debug level, suppressing identical decisions for five minutes.
+External delivery additionally requires Notification Manager or a messenger service.
+The expected JSON array uses Unix timestamps in milliseconds:
+
+```js
+const now = Date.now();
+const forecast = [0, 15, 30, 45].map(minutes => ({
+    t: now + minutes * 60000,
+    y: 3.5,
+}));
+// JSON.stringify(forecast), with forecastPowerUnit = "kW"
+```
+
+With 500 W baseload this gives 3000 W forecast surplus, reduced to 2400 W at
+`forecastSafetyPercent: 80`. A 2000 W consumer requires a sustained
+`forecastMinMinutes: 30` window starting within `forecastMaxStartMinutes: 30`.
+At `forecastMinCurrentPercent: 50`, at least 1000 W must already be available.
+
+`forecastBridgeMinutes: 5` limits dip bridging; `forecastMaxGridImport: 100`
+prevents bridging above 100 W import. Past forecast points are ignored.
+Select `W` explicitly for small watt readings: automatic detection treats values
+up to 100 as kW. Inspect `forecast.*` and each consumer's forecast status states.
+
+Time windows may cross midnight (22:00–06:00). Equal start/end times mean all day.
+Automated tests use simulated devices; no physical device installation was available.
+
+## 🔧 Description
+
+The **smartloadmanager** adapter dynamically controls consumers based on a PV feed-in value.  
+The goal is to consume surplus power locally and minimize or completely avoid feeding into the public grid.  
+It supports binary consumers, percentage-controllable devices, and battery storage systems.
+
+---
+
+## 🚀 Features
+
+- ✅ Monitoring of a configurable feed-in datapoint
+- ✅ Dynamic switching on of consumers in case of surplus
+- ✅ Dynamic switching off in case of deficit or grid consumption
+- ✅ Supports **binary**, **percent**, **heating** and **battery** consumers
+- ✅ Percentage control with delay (smooth down-regulation), optionally configurable per consumer
+- ✅ Dynamic charging power for battery storage with target SOC
+- ✅ Time windows for on/off logic per consumer (incl. "only at off-time")
+- ✅ Automatic object creation with extended information per consumer
+- ✅ Control mode: Off / Manual On / Auto per consumer
+- ✅ Hysteresis control via separate on/off thresholds
+- ✅ Consumer-specific switching delay (override of global setting)
+- ✅ Global battery switching delay (`batteryDelaySeconds`)
+- ✅ Write check for battery control mode (debug output in log)
+- ✅ **Delayed switching via timers** for on and off
+- ✅ **Display of active timers in debug log** with remaining time
+- ✅ Optional **notifications** for binary, percent, battery and heating (Telegram / Gotify)
+- ✅ Optimization for 0/1 datapoints (boolean or numeric 0/1 control)
+- ✅ Detailed logging of all timers, surpluses and switching operations
+- ✅ Notifications per consumer type (Binary, Percent, Battery, Heating), optionally enabled
+- ✅ Heating/immersion heater control with temperature, enable and heartbeat checks
+
+---
+
+## ⚙️ Configuration
+
+### 🔹 Main settings
+
+| Setting                            | Description                                                                     |
+| ---------------------------------- | ------------------------------------------------------------------------------- |
+| **Feed-in datapoint**              | Object ID of the feed-in value (e.g. PV surplus)                                |
+| **Base load**                      | Always subtracted from feed-in value (e.g. standby consumption)                 |
+| **Switch-on threshold**            | Threshold in watts at which consumers are switched on                           |
+| **Switch-off threshold**           | Threshold in watts at which consumers are switched off                          |
+| **Delay (seconds)**                | Delay for binary switching (hysteresis smoothing)                               |
+| **Delay percent (s)**              | Global delay for down-regulation of percent consumers (e.g. wallbox)            |
+| **Delay battery (s)**              | Global delay for battery control                                                |
+| **Feed-in negative**               | If active: negative = feed-in / positive = grid consumption                     |
+| **Battery control mode datapoint** | Optional datapoint for battery mode switching (Auto/Manual/Off)                 |
+| **Notifications**                  | Enable notifications for Binary / Percent / Battery / Heating (Telegram/Gotify) |
+
+---
+
+### 🔹 Consumers
+
+| Field                               | Description                                                           |
+| ----------------------------------- | --------------------------------------------------------------------- |
+| **Name**                            | Display name                                                          |
+| **Active**                          | Enables control for this consumer                                     |
+| **Rule type**                       | `"binary"`, `"percent"`, `"battery"`, `"heating"`                     |
+| **Control datapoint**               | ID to switch or regulate, supports 0/1 datapoints                     |
+| **Power [W]**                       | Realistic electrical power of the consumer                            |
+| **Switch-on threshold [W]**         | Required surplus for activation                                       |
+| **Switch-off threshold [W]**        | Lower limit for deactivation                                          |
+| **Max power [W]**                   | Reference value for percentage control                                |
+| **Delay percent [s]**               | Optional delay for down-regulation for this consumer only             |
+| **Delay override [s]**              | Consumer-specific switching delay (e.g. immediate switching possible) |
+| **Switch-on time (HH:MM)**          | Time when control may start                                           |
+| **Switch-off time (HH:MM)**         | Time when control must end                                            |
+| **Only off at time**                | Checkbox: switch off only at configured time                          |
+| **batterySetpoint (battery only)**  | Datapoint where desired charging power is written                     |
+| **batterySOC / targetSOC**          | Optional: SOC & target SOC to stop charging at target                 |
+| **Timer / TimerEnd**                | Internal timer for delayed switching, remaining time visible in log   |
+| **minTemperature / maxTemperature** | Lower/upper threshold for heating operation                           |
+| **temperatureDatapoint (heating)**  | Temperature datapoint for min/max checks                              |
+| **enableDatapoint (heating)**       | Optional datapoint: heating only allowed if true                      |
+| **heartbeatDatapoint (heating)**    | Optional: must cyclically deliver true, otherwise switched off        |
+
+---
+
+## 🔋 Battery storage support
+
+- Consumers with `"ruletype": "battery"` control the charging setpoint based on current surplus.
+- If `batterySOC` and `batteryTargetSOC` are set, charging stops at target SOC.
+- Optional `batteryControlModeDatapoint`:
+    - `0 = Off`, `1 = Manual`, `2 = Auto`
+- Control is only active within configured time windows.
+- Control runs on every feed-in update, after configured delay (`batteryDelaySeconds`).
+- Delays for all consumer types (binary, percent, battery) can be set globally or per consumer.
+- Detailed logging and optional notifications for battery switching.
+
+---
+
+## 🌡️ Heating support
+
+- Consumers with `"ruletype": "heating"` are intended for immersion heaters or similar devices.
+- Control only occurs when:
+    - Current temperature is below `maxTemperature`
+    - Optional: above `minTemperature`
+    - Optional: `enableDatapoint` is active
+    - Optional: `heartbeatDatapoint` is valid
+- If conditions are not met, switching is stopped immediately and timers are canceled.
+- Supports on/off timers (`onTimerRemaining` / `offTimerRemaining`) with remaining time display.
+- Detailed logging and optional notifications for heating consumers.
+
+---
+
+## 🧠 Control logic
+
+1. **Feed-in datapoint value is interpreted** (positive = grid consumption or feed-in, depending on config)
+2. **Surplus > base load + switch-on threshold**:  
+   → Consumers are switched on (binary) in ascending order of power
+3. **Deficit < base load - switch-off threshold**:  
+   → Consumers are switched off in reverse order
+4. **Percent consumers**:  
+   → % = surplus / max power  
+   → Adjusted after delay (global or per consumer)  
+   → Optional overrides possible
+5. **Battery consumers**:  
+   → Charging power = min(surplus, max power), if target SOC not reached  
+   → Delay via `batteryDelaySeconds` or per consumer
+6. **Time window check for all consumers**
+7. **Control only in mode Auto (2)**
+8. **Delayed switching via timers** (cancel/restart on updates, remaining time visible in log)
+9. **Optional notifications for all switching/regulation types**
+10. **0/1 datapoint optimization** (boolean or numeric 0/1 supported)
+11. **Detailed logging of all switching and surplus values**
+12. **Heating logic**: switch only within temp ranges and with valid enable/heartbeat datapoints
+
+---
+
+## 💡 Example: Wallbox
+
+| Parameter | Value   |
+| --------- | ------- |
+| Feed-in   | 1000 W  |
+| Base load | 100 W   |
+| Max power | 11000 W |
+
+**Calculation:**
+
+- Surplus: 1000 – 100 = 900 W
+- Percent: 900 / 11000 ≈ 8.2 % → Wallbox set to 8 %
+
+---
+
+## 📋 Object structure
+
+Each consumer gets its own channel with the following states:
+
+- `.controlMode` → 0 = Off, 1 = Manual, 2 = Auto
+- `.switchOnTime` / `.switchOffTime`
+- `.alwaysOffAtTime` → true/false
+- `.performance`, `.switchOnPoint`, `.switchOffPoint`
+- `.batterySetpoint` (battery only)
+- `.temperatureDatapoint` (heating only)
+- `.onTimerRemaining / .offTimerRemaining` → Remaining time for timers
+- `.timer` → internal timer for delayed switching
+- `.timerEnd` → timestamp when timer expires (for log)
+
+---
+
+## 🚫 Limitations
+
+- No SOC history, no long-term logic
+- No multiple use of identical datapoints
+- Battery control based only on feed-in, not discharge power
+- Heating without direct power measurement – only thresholds and enable checks
+
+---
+
+## 🛣️ Future features
+
+- ~~PV forecast-based control (beta)~~
+- Combined consumer support
+- ~~Prioritization profiles~~
+- Overheating or fault handling per device
+- ~~Min/max percentage limits~~
+- Configurable group or room logic
+
+---
+
+## PV forecast control
+
+SmartLoadManager can use `pvforecast.<instance>.summary.JSONData`. Enable forecast control, select the JSON data point and enable it for the desired consumers.
+
+The adapter evaluates a continuous forecast window instead of a single value. A configurable safety factor reduces optimistic forecasts. Forecast-assisted switch-on additionally requires part of the required power to be present as real surplus. Short drops can be bridged for a limited time, but only up to the configured maximum grid import.
+
+Minimum run and off times prevent rapid cycling. Forecast decisions never override time windows, heating temperature limits, hardware enable/heartbeat signals or battery SOC limits.
+
+Recommended starting values: 80% safety factor, 30-minute forecast window, 30-minute maximum lead time, 50% current-surplus requirement, 5-minute dip bridging, 100 W maximum grid import and 10/5-minute minimum run/off times.

package/io-package.json

@@ -1,22 +1,35 @@
 {
   "common": {
     "name": "smartloadmanager",
-    "version": "0.1.2",
+    "version": "0.4.1",
     "news": {
-      "0.1.2": {
-        "en": "Update dependencies",
-        "de": "Abhängigkeiten aktualisieren",
-        "ru": "Обновление зависимостей",
-        "pt": "Atualizar dependências",
-        "nl": "Afhankelijkheden bijwerken",
-        "fr": "Mise à jour des dépendances",
-        "it": "Dipendenze di aggiornamento",
-        "es": "Actualizar las dependencias",
-        "pl": "Aktualizuj zależności",
-        "uk": "Оновлення залежності",
-        "zh-cn": "更新依赖关系"
+      "0.4.1": {
+        "en": "Fix forecast notifications for percentage and battery consumers, limit duplicate notifications, clear invalid forecast data and log all forecast diagnostics only at debug level.",
+        "de": "Prognosemeldungen für Prozent- und Batterieverbraucher korrigiert, doppelte Meldungen begrenzt, ungültige Prognosedaten verworfen und sämtliche Prognosediagnosen ausschließlich auf Debug-Stufe protokolliert.",
+        "ru": "Исправлены уведомления прогноза для процентных потребителей и батарей, ограничены повторы, очищены недействительные данные; диагностика прогноза выводится только на уровне debug.",
+        "pt": "Corrigidas notificações de previsão para consumidores percentuais e baterias, limitadas repetições, eliminados dados inválidos e diagnóstico apenas no nível debug.",
+        "nl": "Prognosemeldingen voor procentuele verbruikers en batterijen hersteld, herhalingen beperkt, ongeldige gegevens gewist en prognosediagnose uitsluitend op debugniveau gelogd.",
+        "fr": "Correction des notifications de prévision pour consommateurs en pourcentage et batteries, limitation des doublons, suppression des données invalides et diagnostic uniquement au niveau debug.",
+        "it": "Corrette le notifiche di previsione per utenze percentuali e batterie, limitati i duplicati, eliminati i dati non validi e diagnostica solo a livello debug.",
+        "es": "Corregidas las notificaciones de previsión para consumidores porcentuales y baterías, limitados los duplicados, borrados los datos inválidos y diagnóstico solo en nivel debug.",
+        "pl": "Poprawiono powiadomienia prognozy dla odbiorników procentowych i akumulatorów, ograniczono duplikaty, usunięto nieprawidłowe dane; diagnostyka wyłącznie na poziomie debug.",
+        "uk": "Виправлено повідомлення прогнозу для відсоткових споживачів і батарей, обмежено повтори, очищено недійсні дані; діагностика прогнозу лише на рівні debug.",
+        "zh-cn": "修复百分比用电设备和电池的预测通知，限制重复通知，清除无效预测数据，所有预测诊断仅在 debug 级别记录。"
+      },
+      "0.2.0": {
+        "en": "Added sustained PV forecast control and minimum run/off times; fixed consumer commands, percent regulation, battery control, time windows and timers; updated translations, tests and workflows.",
+        "de": "PV-Prognosesteuerung und Mindestlaufzeiten ergänzt; Verbrauchersteuerung, Zeitfenster und Timer korrigiert; Übersetzungen, Tests und Workflows aktualisiert.",
+        "ru": "Добавлены управление по прогнозу ФЭ и минимальные времена работы; исправлены управление потребителями, временные окна и таймеры; обновлены переводы, тесты и рабочие процессы.",
+        "pt": "Adicionado controlo por previsão solar e tempos mínimos de funcionamento; corrigidos consumidores, horários e temporizadores; atualizados traduções, testes e fluxos de trabalho.",
+        "nl": "PV-prognosesturing en minimale aan/uit-tijden toegevoegd; schakelopdrachten, procentregeling, batterij, tijdvensters en timers hersteld; vertalingen, tests en workflows bijgewerkt.",
+        "fr": "Ajout des prévisions solaires et durées minimales ; correction des commandes, plages horaires et minuteries ; mise à jour des traductions, tests et workflows.",
+        "it": "Aggiunti controllo tramite previsioni FV e tempi minimi di accensione/spegnimento; corretti comandi, regolazione percentuale, batteria, fasce orarie e timer; aggiornati traduzioni, test e workflow.",
+        "es": "Añadidos control por previsión FV y tiempos mínimos; corregidos consumidores, horarios y temporizadores; actualizados traducciones, pruebas y flujos de trabajo.",
+        "pl": "Dodano prognozę PV i minimalne czasy pracy; poprawiono sterowanie odbiornikami, okna czasowe i zegary; zaktualizowano tłumaczenia, testy i przepływy pracy.",
+        "uk": "Додано керування за прогнозом ФЕ та мінімальні часи роботи; виправлено керування споживачами, часові вікна та таймери; оновлено переклади, тести та робочі процеси.",
+        "zh-cn": "新增光伏预测控制和最短运行时间；修复用电设备控制、时间窗口和定时器；更新翻译、测试和工作流。"
       },
-      "0.1.1": {
+      "0.1.2": {
         "en": "Update dependencies",
         "de": "Abhängigkeiten aktualisieren",
         "ru": "Обновление зависимостей",
@@ -83,7 +96,7 @@
       },
       "0.0.1": {
         "en": "Release",
-        "de": "Release",
+        "de": "Veröffentlichung",
         "ru": "Выпуск",
         "pt": "Lançar",
         "nl": "Loslaten",
@@ -163,7 +176,7 @@
     ],
     "globalDependencies": [
       {
-        "admin": ">=7.6.17"
+        "admin": ">=7.6.20"
       }
     ]
   },
@@ -185,19 +198,46 @@
       },
       "description": {
         "en": "Notifications from SmartLoadManager",
-        "de": "Benachrichtigungen vom SmartLoadManager"
+        "de": "Benachrichtigungen vom SmartLoadManager",
+        "ru": "Уведомления от SmartLoadManager",
+        "pt": "Notificações do SmartLoadManager",
+        "nl": "Meldingen van SmartLoadManager",
+        "fr": "Notifications de SmartLoadManager",
+        "it": "Notifiche da SmartLoadManager",
+        "es": "Notificaciones de SmartLoadManager",
+        "pl": "Powiadomienia z SmartLoadManager",
+        "uk": "Сповіщення від SmartLoadManager",
+        "zh-cn": "来自 SmartLoadManager 的通知"
       },
       "categories": [
         {
           "category": "info",
           "name": {
             "en": "Info",
-            "de": "Info"
+            "de": "Information",
+            "ru": "Информация",
+            "pt": "Informação",
+            "nl": "Informatie",
+            "fr": "Information",
+            "it": "Informazioni",
+            "es": "Información",
+            "pl": "Informacja",
+            "uk": "Інформація",
+            "zh-cn": "信息"
           },
           "severity": "notify",
           "description": {
             "en": "Information about consumer switching or battery adjustments",
-            "de": "Informationen zu Verbraucherschaltungen oder Batterieanpassungen"
+            "de": "Informationen zu Verbraucherschaltungen oder Batterieanpassungen",
+            "ru": "Информация о переключении потребителей или настройке батареи",
+            "pt": "Informações sobre comutação de consumidores ou ajustes da bateria",
+            "nl": "Informatie over het schakelen van verbruikers of batterijaanpassingen",
+            "fr": "Informations sur la commutation des consommateurs ou les réglages de batterie",
+            "it": "Informazioni sulla commutazione delle utenze o sulle regolazioni della batteria",
+            "es": "Información sobre la conmutación de consumidores o los ajustes de batería",
+            "pl": "Informacje o przełączaniu odbiorników lub regulacji baterii",
+            "uk": "Інформація про перемикання споживачів або налаштування батареї",
+            "zh-cn": "有关用电设备切换或电池调整的信息"
           },
           "regex": [],
           "limit": 1
@@ -206,12 +246,30 @@
           "category": "notify",
           "name": {
             "en": "Notify",
-            "de": "Benachrichtigen"
+            "de": "Benachrichtigung",
+            "ru": "Уведомление",
+            "pt": "Notificação",
+            "nl": "Melding",
+            "fr": "Notification",
+            "it": "Notifica",
+            "es": "Notificación",
+            "pl": "Powiadomienie",
+            "uk": "Сповіщення",
+            "zh-cn": "通知"
           },
           "severity": "notify",
           "description": {
             "en": "Notify about events",
-            "de": "Benachrichtigen über Ereignisse"
+            "de": "Über Ereignisse benachrichtigen",
+            "ru": "Уведомлять о событиях",
+            "pt": "Notificar sobre eventos",
+            "nl": "Melden over gebeurtenissen",
+            "fr": "Notifier les événements",
+            "it": "Notifica gli eventi",
+            "es": "Notificar sobre eventos",
+            "pl": "Powiadamiaj o zdarzeniach",
+            "uk": "Сповіщати про події",
+            "zh-cn": "事件通知"
           },
           "regex": [],
           "limit": 1
@@ -220,12 +278,30 @@
           "category": "alert",
           "name": {
             "en": "Alert",
-            "de": "Alarm"
+            "de": "Alarm",
+            "ru": "Тревога",
+            "pt": "Alerta",
+            "nl": "Alarm",
+            "fr": "Alerte",
+            "it": "Allarme",
+            "es": "Alerta",
+            "pl": "Alarm",
+            "uk": "Тривога",
+            "zh-cn": "警报"
           },
           "severity": "alert",
           "description": {
             "en": "Alarm or failures in the adapter",
-            "de": "Alarm oder Ausfälle im Adapter"
+            "de": "Alarm oder Ausfälle im Adapter",
+            "ru": "Тревоги или сбои адаптера",
+            "pt": "Alarmes ou falhas no adaptador",
+            "nl": "Alarmen of storingen in de adapter",
+            "fr": "Alarmes ou défaillances de l’adaptateur",
+            "it": "Allarmi o guasti nell'adattatore",
+            "es": "Alarmas o fallos en el adaptador",
+            "pl": "Alarmy lub awarie adaptera",
+            "uk": "Тривоги або збої адаптера",
+            "zh-cn": "适配器中的警报或故障"
           },
           "regex": [],
           "limit": 1
@@ -263,13 +339,19 @@
     "pushoverRecipients": "",
     "enableNotificationManager": false,
     "enableForecast": false,
-    "forecastDefaultMinMinutes": 0,
+    "forecastDefaultMinMinutes": 30,
+    "forecastPowerUnit": "auto",
+    "forecastSafetyPercent": 80,
+    "forecastMaxStartMinutes": 30,
+    "forecastMinCurrentPercent": 50,
+    "forecastBridgeMinutes": 5,
+    "forecastMaxGridImport": 100,
     "enableNotifications": false,
     "notifyForecastBinary": false,
     "notifyForecastPercent": false,
     "notifyForecastBattery": false,
     "forecastJsonDatapoint": "",
-    "notifyForecast": ""
+    "notifyForecast": false
   },
   "objects": [],
   "instanceObjects": []

package/lib/forecast.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Determine the conversion factor for forecast power values.
+ *
+ * @param {'W'|'kW'|null|undefined} unit Configured or detected power unit.
+ * @param {number[]} values Raw forecast values used for automatic detection.
+ * @returns {number} Multiplier to convert forecast values to watts.
+ */
+function powerFactor(unit, values = []) {
+    if (unit === 'W') {
+        return 1;
+    }
+    if (unit === 'kW') {
+        return 1000;
+    }
+    const finite = values.filter(Number.isFinite).map(Math.abs);
+    return finite.length && Math.max(...finite) <= 100 ? 1000 : 1;
+}
+
+/**
+ * Parse pvforecast JSONData into normalized future data points.
+ *
+ * @param {string|Array<{t: number, y: number}>} value JSON string or decoded pvforecast array.
+ * @param {{now?: number, unit?: 'W'|'kW'|null, baseload?: number}} options Parser options.
+ * @returns {Array<{timestamp: number, power: number, surplus: number}>} Normalized forecast points.
+ */
+function parseForecast(value, options = {}) {
+    const now = options.now || Date.now();
+    let data = value;
+    if (typeof data === 'string') {
+        data = JSON.parse(data);
+    }
+    if (!Array.isArray(data)) {
+        throw new Error('Forecast must be an array');
+    }
+
+    const raw = data
+        .map(entry => ({ timestamp: Number(entry?.t), value: Number(entry?.y) }))
+        .filter(entry => Number.isFinite(entry.timestamp) && Number.isFinite(entry.value) && entry.timestamp >= now)
+        .sort((a, b) => a.timestamp - b.timestamp);
+    const factor = powerFactor(
+        options.unit,
+        raw.map(entry => entry.value),
+    );
+    const baseload = Math.max(0, Number(options.baseload) || 0);
+    return raw.map(entry => ({
+        timestamp: entry.timestamp,
+        power: Math.max(0, Math.round(entry.value * factor)),
+        surplus: Math.max(0, Math.round(entry.value * factor - baseload)),
+    }));
+}
+
+/**
+ * Find a sustained forecast window with enough conservative surplus.
+ *
+ * @param {Array<{timestamp: number, surplus: number}>} points Normalized forecast points.
+ * @param {{now?: number, requiredPower?: number, safetyFactor?: number, minDurationMinutes?: number, maxStartMinutes?: number}} options Evaluation limits.
+ * @returns {{available: boolean, startMinutes: number|null, durationMinutes: number, minimumSurplus: number, averageSurplus: number}} Forecast decision.
+ */
+function evaluateForecast(points, options = {}) {
+    const now = options.now || Date.now();
+    points = points
+        .filter(point => Number.isFinite(point.timestamp) && Number.isFinite(point.surplus) && point.timestamp >= now)
+        .sort((a, b) => a.timestamp - b.timestamp);
+    const requiredPower = Math.max(0, Number(options.requiredPower) || 0);
+    const safetyFactor = Math.min(1, Math.max(0.1, Number(options.safetyFactor) || 0.8));
+    const minDurationMinutes = Math.max(1, Number(options.minDurationMinutes) || 30);
+    const maxStartMinutes = Math.max(
+        0,
+        options.maxStartMinutes === undefined ? 30 : Number(options.maxStartMinutes) || 0,
+    );
+    const threshold = requiredPower / safetyFactor;
+    const maxStart = now + maxStartMinutes * 60000;
+    const fallbackStep = 15 * 60000;
+
+    for (let start = 0; start < points.length; start++) {
+        if (points[start].timestamp > maxStart || points[start].surplus < threshold) {
+            continue;
+        }
+        let end = start;
+        let minimum = points[start].surplus;
+        let sum = 0;
+        while (end < points.length && points[end].surplus >= threshold) {
+            if (end > start) {
+                const gap = points[end].timestamp - points[end - 1].timestamp;
+                if (gap > 90 * 60000) {
+                    break;
+                }
+            }
+            minimum = Math.min(minimum, points[end].surplus);
+            sum += points[end].surplus;
+            end++;
+        }
+        const step = end - start > 1 ? points[start + 1].timestamp - points[start].timestamp : fallbackStep;
+        const durationMinutes = Math.round((points[end - 1].timestamp - points[start].timestamp + step) / 60000);
+        if (durationMinutes >= minDurationMinutes) {
+            return {
+                available: true,
+                startMinutes: Math.max(0, Math.round((points[start].timestamp - now) / 60000)),
+                durationMinutes,
+                minimumSurplus: minimum,
+                averageSurplus: Math.round(sum / (end - start)),
+            };
+        }
+    }
+    return { available: false, startMinutes: null, durationMinutes: 0, minimumSurplus: 0, averageSurplus: 0 };
+}
+
+/**
+ * Check whether a minimum on/off period has elapsed.
+ *
+ * @param {number} lastChange Timestamp of the last state change.
+ * @param {number} minimumMinutes Required state duration in minutes.
+ * @param {number} now Current timestamp.
+ * @returns {boolean} Whether a new state change is allowed.
+ */
+function minimumStateTimeSatisfied(lastChange, minimumMinutes, now = Date.now()) {
+    const minimumMs = Math.max(0, Number(minimumMinutes) || 0) * 60000;
+    return !lastChange || now - lastChange >= minimumMs;
+}
+
+module.exports = { evaluateForecast, minimumStateTimeSatisfied, parseForecast, powerFactor };