iobroker.smartloadmanager 0.1.0 → 0.2.0

package/docs/de/README.md

@@ -0,0 +1,283 @@
+![Logo](../../admin/smartloadmanager.png)
+
+# ioBroker.smartloadmanager
+
+## Beispiele für Version 0.2.0
+
+Voraussetzung: Node.js ab 22.19.0. Der Adapter sendet Gerätebefehle mit
+`ack: false`; die Bestätigung (`ack: true`) übernimmt der zuständige Geräteadapter.
+Der Einspeisewert muss die Leistung am Netzanschlusspunkt in Watt darstellen.
+Bei negativem Vorzeichen für Einspeisung muss `feedinNegativ` aktiviert werden.
+Die Grundlast wird zusätzlich als Reserve abgezogen; bereits im Netzanschlusswert
+enthaltenen Hausverbrauch nicht nochmals als Grundlast eintragen.
+
+### Binärer Verbraucher und Heizung
+
+Beispiel: Steckdose mit `performance: 1000`, `switchOnPoint: 1200`,
+`switchOffPoint: 0`, `switchOnDelay: 20`, `switchOffDelay: 10`.
+Ab 1200 W Überschuss nach Grundlast startet die Einschaltverzögerung.
+Bei Netzbezug oder Unterschreiten der Abschaltgrenze startet die Abschaltung.
+`minimumOnMinutes: 10` und `minimumOffMinutes: 5` begrenzen häufiges Schalten;
+stärkerer Netzbezug als `forecastMaxGridImport` übergeht die Mindestlaufzeit.
+Mit `0` können Mindestzeiten explizit deaktiviert werden.
+
+`datapoint` schaltet boolean, `numericDatapoint` numerisch mit 0/1.
+Für Heizungen `ruletype: heating` wählen und Temperatur-, Freigabe- und
+Heartbeat-Datenpunkte konfigurieren. Das Erreichen von `maxTemperature` sowie
+fehlende Freigabe oder ein falscher Heartbeat verhindern das Einschalten.
+Ein gesetzter Heartbeat-Datenpunkt wird auf seinen Wahrheitswert geprüft;
+das ist keine Überwachung seines Alters.
+Fehlt ein konfigurierter Temperatursensor oder liefert er keinen endlichen
+Zahlenwert, wird eine Heizung nicht eingeschaltet bzw. automatisch abgeschaltet.
+„Ausschalten nur zu Ausschaltzeit“ unterdrückt absichtlich die normale
+Überschussabschaltung bis zum Zeitfensterende; Heizschutz bleibt wirksam.
+
+### Prozentregelung und Batterie
+
+Ein Prozentverbraucher mit 2000 W Maximalleistung und aktuell 50 % benötigt
+1000 W. Zeigt der Netzzähler zusätzlich 400 W Einspeisung, wird auf 70 % geregelt.
+Bei 200 W Netzbezug wird auf 40 % reduziert. Liegt die tragbare Leistung unter
+`minPercentStart`, wird auf 0 % geregelt. Deaktivierte Verbraucher werden nicht geregelt.
+Die Leistungsrechnung setzt voraus, dass der Verbraucher im Netzzähler enthalten ist.
+
+Für eine Batterie `batterySetpoint`, `performance`, optional `batterySOC` und
+`batteryTargetSOC` wählen. Bei 800 W verfügbarem Überschuss und maximal 1500 W
+Ladeleistung wird 800 W vorgegeben. Bei erreichtem Ziel-SOC wird die Ladeleistung 0.
+Der optionale globale Batterie-Modusdatenpunkt verwendet 0 (aus), 1 (Ziel erreicht)
+und 2 (laden); diese Werte müssen zum Geräteadapter passen.
+
+`controlMode` im Objektbaum: 0 = aus, 1 = manuell ein, 2 = automatisch.
+Manuell ein setzt Prozentverbraucher auf 100 % bzw. die Batterie auf ihre konfigurierte
+Leistung. Automatische Prozent- und Batterieregler überschreiben manuelle Modi nicht.
+Die Batterie berücksichtigt bereits angeforderte Ladeleistung und korrigiert sie
+um den gemessenen Netzüberschuss. `batteryDelaySeconds` und `delaySecondsProzent`
+gelten auch bei häufigen Zähleraktualisierungen; 0 bedeutet sofortige Regelung.
+Fehlt ein konfigurierter SOC-/Ziel-SOC-Wert, wird die Ladeleistung auf 0 gesetzt.
+Zeitfenster werden zusätzlich alle 15 Sekunden geprüft. Das Deaktivieren eines
+Verbrauchers beendet seine ausstehenden Schaltbefehle; es schaltet das Gerät nicht
+automatisch aus. Dafür `controlMode: 0` verwenden.
+
+### PV-Prognose mit ioBroker.pvforecast
+
+`enableForecast` aktivieren, `forecastJsonDatapoint` etwa auf
+`pvforecast.0.summary.JSONData` setzen und beim Verbraucher `useForecast` aktivieren.
+Beispiel für das erwartete Format (Zeitstempel sind Unix-Millisekunden):
+
+```js
+const now = Date.now();
+const forecast = [0, 15, 30, 45].map(minutes => ({
+    t: now + minutes * 60000,
+    y: 3.5,
+}));
+// JSON.stringify(forecast), mit forecastPowerUnit = "kW"
+```
+
+Bei 500 W Grundlast bleiben 3000 W prognostizierter Überschuss.
+Mit `forecastSafetyPercent: 80` stehen konservativ 2400 W zur Verfügung.
+Ein 2000-W-Verbraucher kann freigegeben werden, wenn das Zeitfenster mindestens
+`forecastMinMinutes: 30` lang ist, höchstens `forecastMaxStartMinutes: 30`
+Minuten entfernt liegt und bei `forecastMinCurrentPercent: 50` bereits mindestens
+1000 W realer Überschuss vorhanden sind. Prognosen ersetzen keinen gemessenen Überschuss.
+
+`forecastBridgeMinutes: 5` begrenzt das Überbrücken kurzer Einbrüche;
+`forecastMaxGridImport: 100` verhindert Überbrücken bei mehr als 100 W Netzbezug.
+Vergangene Datenpunkte werden verworfen. Bei kleinen W-Werten die Einheit explizit
+auf `W` setzen, da die automatische Erkennung Werte bis 100 als kW interpretiert.
+`forecast.*` und die Prognosestatuswerte des Verbrauchers zeigen die Entscheidung an.
+
+Zeitfenster können über Mitternacht gehen, z. B. 22:00–06:00.
+Gleiche Start- und Endzeit gelten als ganztägiges Fenster.
+
+Prüfumfang und externe Release-Abhängigkeiten: [Release-Prüfbericht](release-0.2.0-pruefung.md).
+
+## 🔧 Beschreibung
+
+Der Adapter **smartloadmanager** dient der dynamischen Steuerung von Verbrauchern anhand eines PV-Einspeisewertes. Ziel ist es, Überschuss-Strom lokal zu verbrauchen und so die Einspeisung ins öffentliche Netz zu minimieren oder vollständig zu vermeiden. Er unterstützt sowohl Ein/Aus-Verbraucher als auch prozentual regelbare Geräte und Batteriespeicher.
+
+---
+
+## 🚀 Funktionen
+
+- ✅ Überwachung eines konfigurierbaren Einspeisungs-Datenpunkts
+- ✅ Dynamische Zuschaltung von Verbrauchern bei Überschuss
+- ✅ Dynamische Abschaltung bei Defizit oder Netzbezug
+- ✅ Unterstützt **binary**, **percent**, **Heating** und **battery**-Verbraucher
+- ✅ Prozentregelung mit Verzögerung (sanftes Rückregeln), optional pro Verbraucher konfigurierbar
+- ✅ Dynamische Ladeleistung für Batteriespeicher mit Ziel-SOC
+- ✅ Zeitfenster für Ein-/Ausschaltlogik je Verbraucher (inkl. "nur zu Abschaltzeit")
+- ✅ Automatische Objekt-Erstellung mit erweiterten Informationen je Verbraucher
+- ✅ Steuerungsmodus: Off / Manual On / Auto für jeden Verbraucher separat
+- ✅ Hysterese-Steuerung durch separate Ein-/Abschaltgrenzen
+- ✅ Verbraucherspezifische Schaltverzögerung (Override der globalen)
+- ✅ Reihenfolgenlogik bei Zuschaltung (nach Leistung) und Abschaltung (umgekehrt)
+- ✅ Globale Batterie-Schaltverzögerung (`batteryDelaySeconds`)
+- ✅ Schreibprüfung für Batterie-Kontrollmodus (Debug-Ausgabe im Log)
+- ✅ **Verzögerte Schaltung über Timer** für Ein- und Ausschaltung
+- ✅ **Anzeige laufender Timer im Debug-Log** mit verbleibender Zeit
+- ✅ Optionale **Benachrichtigungen** für Ein/Aus, Prozentregelung und Batterie (Telegram / Gotify)
+- ✅ Optimierung für 0/1-Datenpunkte für Geräte mit boolean oder numerischer 0/1-Steuerung
+- ✅ Detailliertes Logging aller Timer, Überschüsse und Schaltvorgänge
+- ✅ Benachrichtigungen pro Verbrauchertyp (Binary, Percent, Battery, Heating), optional aktivierbar
+- ✅ Heizungs-/Heizstab-Steuerung mit Temperatur-, Freigabe- und Heartbeat-Prüfung
+
+---
+
+## ⚙️ Konfiguration
+
+### 🔹 Haupteinstellungen
+
+| Einstellung                     | Beschreibung                                                                           |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| **Einspeisungs-Datenpunkt**     | Objekt-ID des Einspeisewerts (z. B. PV-Überschuss)                                     |
+| **Grundlast**                   | Wird immer vom Einspeisewert abgezogen (z. B. Standby-Verbrauch)                       |
+| **Einschaltgrenze**             | Schwelle in Watt, ab der Verbraucher zugeschaltet werden                               |
+| **Abschaltgrenze**              | Schwelle in Watt, ab der Verbraucher abgeschaltet werden                               |
+| **Verzögerung (Sekunden)**      | Verzögerung für binäre Abschaltungen (Hysterese-Glättung)                              |
+| **Verzögerung Prozent (Sek.)**  | Globale Verzögerung bei Rückregelung von Prozentverbrauchern (z. B. Wallbox)           |
+| **Verzögerung Batterie (Sek.)** | Globale Verzögerung für Batterie-Steuerung                                             |
+| **Einspeisewert negativ**       | Wenn aktiv: negativer Wert = Einspeisung / positiver Wert = Netzbezug                  |
+| **Batterie Kontrollmodus-DP**   | Optionaler Steuerdatenpunkt für Batterie-Modusumschaltung (Auto/Manual/Aus)            |
+| **Benachrichtigungen**          | Aktivierung für Binary / Prozent / Batterie / Heating, inkl. Telegram/Gotify-Instanzen |
+
+---
+
+### 🔹 Verbraucher
+
+| Feld                                   | Beschreibung                                                                    |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| **Name**                               | Anzeigename                                                                     |
+| **Aktiv**                              | Aktiviert die Steuerung für diesen Verbraucher                                  |
+| **Regeltyp**                           | `"binary"`, `"percent"` oder `"battery"`                                        |
+| **Steuer-Datenpunkt**                  | ID zum Schalten oder Regeln, auch 0/1-DP unterstützt                            |
+| **Leistung [W]**                       | Realistische elektrische Leistung des Verbrauchers                              |
+| **Einschaltgrenze [W]**                | Benötigter Überschuss für Aktivierung                                           |
+| **Abschaltgrenze [W]**                 | Untergrenze für Deaktivierung                                                   |
+| **Maximalleistung [W]**                | Referenzwert zur Prozentregelung                                                |
+| **Verzögerung Prozent [s]**            | Optionale Verzögerung für Rückregelung nur dieses Verbrauchers                  |
+| **Verzögerung Override [s]**           | Verbraucherindividuelle Schaltverzögerung (z. B. sofortige Zuschaltung möglich) |
+| **Einschaltzeit (HH:MM)**              | Uhrzeit, ab wann Steuerung aktiv sein darf                                      |
+| **Ausschaltzeit (HH:MM)**              | Uhrzeit, ab wann Steuerung beendet wird                                         |
+| **Nur zu Ausschaltzeit ausschalten**   | Checkbox: Abschaltung nur zu konfigurierter Uhrzeit                             |
+| **batterySetpoint (nur battery)**      | Datenpunkt, in den die gewünschte Ladeleistung geschrieben wird                 |
+| **batterySOC / targetSOC**             | Optional: SOC & Ziel-SOC zur Ladeverhinderung bei vollem Akku                   |
+| **Timer / TimerEnd**                   | Interner Timer für verzögerte Schaltungen, Restzeit im Log sichtbar             |
+| **minTemperature / maxTemperature**    | Unter- und Obergrenze für Heating-Betrieb                                       |
+| **temperatureDatapoint (nur heating)** | Temperatur-Datenpunkt zur Prüfung min/max Grenzwerte                            |
+| **enableDatapoint (nur heating)**      | Optionaler Datenpunkt: nur bei true darf Heizstab laufen                        |
+| **heartbeatDatapoint (nur heating)**   | Optional: muss zyklisch true liefern, sonst wird abgeschaltet                   |
+
+---
+
+## 🔋 Batteriespeicher-Unterstützung
+
+- Verbraucher mit `"ruletype": "battery"` regeln den Lade-Setpoint abhängig vom aktuellen Überschuss.
+- Falls `batterySOC` und `batteryTargetSOC` gesetzt sind, wird ab Zielwert nicht mehr geladen.
+- Optional kann ein `batteryControlModeDatapoint` gesetzt werden:
+    - `0 = Aus`, `1 = Manuell`, `2 = Automatik`
+- Die Steuerung erfolgt **nur innerhalb der konfigurierten Zeitfenster**.
+- Die Steuerung wird bei jedem FeedIn-Update nach konfigurierter Verzögerung (`batteryDelaySeconds`) erneut ausgeführt.
+- Verzögerungen für alle Schaltungen (binary, percent, battery) können pro Verbraucher oder global angepasst werden.
+- Detailliertes Logging und optionale Benachrichtigungen für Batterie-Schaltungen.
+
+---
+
+## 🌡️ Heating-Unterstützung
+
+- Verbraucher mit "ruletype": "heating" sind für Heizstäbe oder vergleichbare Verbraucher vorgesehen.
+- Steuerung erfolgt nur, wenn: - Aktuelle Temperatur unter maxTemperature liegt - Optional: über minTemperature abgesichert - Optional: enableDatapoint aktiv ist - Optional: heartbeatDatapoint gültig ist
+- Bei Nichterfüllung wird Schaltung sofort abgebrochen und Timer gestoppt.
+- Unterstützt Ein-/Ausschalt-Timer (onTimerRemaining / offTimerRemaining) mit Restzeitanzeige.
+- Detailliertes Logging und optionale Benachrichtigungen für Heating-Verbraucher.
+
+---
+
+## 🧠 Steuerlogik
+
+1. **Datenpunkt-Messwert wird basierend auf Konfiguration interpretiert** (positiv = Netzbezug oder Einspeisung)
+2. **Überschuss > Grundlast + Einschaltgrenze**:  
+   → Verbraucher werden (binär) nach steigender Leistung zugeschaltet
+3. **Unterschuss < Grundlast - Abschaltgrenze**:  
+   → Verbraucher werden in umgekehrter Reihenfolge abgeschaltet
+4. **Regelung für Prozent-Verbraucher**:  
+   → % = Überschuss / Maximalleistung  
+   → Geregelt nach Verzögerung (global oder pro Verbraucher)  
+   → Optionale pro-Verbraucher Overrides möglich
+5. **Regelung für Batterie-Verbraucher**:  
+   → Ladeleistung = min(Überschuss, Maximalleistung), sofern Ziel-SOC nicht erreicht  
+   → Verzögerung über `batteryDelaySeconds` oder pro Verbraucher
+6. **Zeitfensterprüfung für alle Verbraucher**  
+   → Nur aktiv, wenn aktuelle Uhrzeit innerhalb `switchOnTime` bis `switchOffTime`
+7. **Steuerung erfolgt nur bei Steuerungsmodus „Auto (2)“**  
+   → Manuelle Eingriffe (Modus 1 oder 0) bleiben unangetastet
+8. **Verzögerte Schaltung über Timer**  
+   → Timer wird vor erneuter Schaltung abgebrochen, Restzeit kann im Log angezeigt werden
+9. **Benachrichtigungen optional für Ein/Aus, Prozent und Batterie**
+10. **Optimierung für 0/1-Datenpunkte**  
+    → Unterstützt boolean oder numerische 0/1-Steuerung automatisch
+11. **Detailliertes Logging aller Schaltvorgänge, Überschüsse und Timer**
+12. **Regelung für Heating-Verbraucher:**
+    → Schaltung nur innerhalb min/max Temperatur und bei gültigen enable-/heartbeat-States
+    → Timer werden abgebrochen, sobald Bedingungen nicht mehr erfüllt sind
+
+---
+
+## 💡 Beispiel: Wallbox
+
+| Parameter       | Wert    |
+| --------------- | ------- |
+| Einspeisung     | 1000 W  |
+| Grundlast       | 100 W   |
+| Maximalleistung | 11000 W |
+
+**Berechnung:**
+
+- Überschuss: 1000 - 100 = 900 W
+- Prozent: 900 / 11000 ≈ 8,2 % → Wallbox wird auf 8 % geregelt
+
+---
+
+## 📋 Objektstruktur
+
+Für jeden Verbraucher wird ein eigener Channel mit folgenden States erzeugt:
+
+- `.controlMode` → 0 = Aus, 1 = Manuell, 2 = Automatik
+- `.switchOnTime` / `.switchOffTime`
+- `.alwaysOffAtTime` → true/false
+- `.performance`, `.switchOnPoint`, `.switchOffPoint`
+- `.batterySetpoint` (nur für "battery")
+- `.temperatureDatapoint` (nur für "heating")
+- `.onTimerRemaining / .offTimerRemaining` → Restlaufzeit für Ein-/Ausschalt-Timer
+- `.timer` → interner Timer für verzögerte Schaltungen
+- `.timerEnd` → Zeitstempel, wann Timer abläuft (für Log)
+
+---
+
+## 🚫 Einschränkungen
+
+- Keine SOC-Historie, keine Langzeitlogik
+- Keine Mehrfachverwendung identischer Datenpunkte
+- Batterie-Steuerung basiert rein auf FeedIn, keine Rücksicht auf Entladeleistung
+- Heating ohne direkte Leistungsmessung – nur Grenzwerte und Freigabe-Checks
+
+---
+
+## 🛣️ Zukünftige Features
+
+- ~~PV-Prognosebasierte Steuerung (Beta)~~
+- Unterstützung kombinierter Verbraucher
+- ~~Priorisierungs-Profile~~
+- Überhitzungs- oder Fehler-Handling je Gerät
+- ~~Minimal- und Maximal-Prozentlimits für Regelung~~
+- Konfigurierbare Gruppen- oder Raumlogik
+
+---
+
+## PV-Prognosesteuerung
+
+SmartLoadManager kann `pvforecast.<Instanz>.summary.JSONData` verwenden. Dazu wird die Prognosesteuerung aktiviert, der JSON-Datenpunkt ausgewählt und die Funktion bei den gewünschten Verbrauchern eingeschaltet.
+
+Der Adapter bewertet ein zusammenhängendes Prognosefenster statt eines einzelnen Werts. Ein konfigurierbarer Sicherheitsfaktor reduziert optimistische Prognosen. Für prognosegestütztes Einschalten muss außerdem bereits ein Teil der benötigten Leistung als realer Überschuss vorhanden sein. Kurze Einbrüche dürfen zeitlich begrenzt überbrückt werden, jedoch nur bis zum eingestellten maximalen Netzbezug.
+
+Mindestlauf- und Mindeststillstandszeiten verhindern häufiges Schalten. Prognoseentscheidungen übersteuern niemals Zeitfenster, Temperaturgrenzen, Hardwarefreigabe, Heartbeat oder Batterie-SOC-Grenzen.
+
+Empfohlene Startwerte: 80 % Sicherheitsfaktor, 30 Minuten Prognosefenster, 30 Minuten maximale Vorlaufzeit, 50 % erforderlicher realer Überschuss, 5 Minuten Überbrückung, 100 W maximaler Netzbezug und 10/5 Minuten Mindestlauf-/Mindeststillstandszeit.

package/docs/de/release-0.2.0-pruefung.md

@@ -0,0 +1,74 @@
+# Arbeits- und Prüfplan für 0.2.0
+
+Alle vorgefundenen lokalen Änderungen werden gemäß Auftrag übernommen und geprüft.
+Die vorhandene Adapterarchitektur bleibt erhalten. Fehler werden mit reproduzierbaren
+Regressionstests korrigiert; eine reale Geräteprüfung ist mangels Testanlage nicht möglich.
+
+1. GitHub-Issues #90, #93, #86 und zugehörige Wartungs-PRs prüfen; aktuelle
+   npm-Versionen von Controller, Admin und Testwerkzeugen feststellen.
+2. Steuerungsfehler in `main.js` mit simulierten ioBroker-Zuständen reproduzieren:
+   Schaltbefehle, Prozentregelung, Batterie, Betriebsmodi, Heizschutz und Timer.
+3. Fehler korrigieren und Regressionstests ausführen; Prognoseeingaben und
+   Mindestlaufzeiten prüfen.
+4. Abhängigkeiten, Node-Testmatrix, Übersetzungen und Paketinhalt prüfen.
+5. README-Changelog und deutsche/englische Nutzerdokumentation mit Beispielen ergänzen.
+6. Versionen in Paketdateien synchron auf 0.2.0 setzen. Unit-, Paket-, Typ-,
+   Lint- und Integrationstests gegen aktuellen js-controller ausführen.
+7. Änderungen prüfen, committen und nach erfolgreichen Prüfungen pushen.
+
+Issue #84 betrifft das separate ioBroker-Stable-Repository. Ein Adapter-Push
+allein aktualisiert dessen Version nicht. Es wird nicht fälschlich als lokal
+behobener Programmfehler behandelt.
+
+## Ausgangslage
+
+- Node.js lokal: 22.19.0.
+- Ausgangstests: 6 Unit-Tests (davon ein Platzhalter), 40 Paketprüfungen bestanden.
+- Typprüfung und ESLint bestanden.
+- npm latest bei Prüfung: js-controller 7.2.5, Admin 8.3.3,
+  adapter-core 3.4.3, testing 6.3.1.
+- Keine reale ioBroker-Testinstanz und keine angeschlossenen Geräte vorhanden.
+
+## Behobene Fehler und Prüfung
+
+- Echte Regressionstests ersetzen den bisherigen Platzhalter. Geprüft werden
+  boolesche/numerische Befehle, Betriebsmodi, Prozentregelung, Vorzeichen,
+  Batterie-SOC, Ladeleistungsrückführung, Heizschutz und Timerabbrüche.
+- Verzögerte Einschaltungen prüfen den aktuellen Überschuss und das Zeitfenster
+  nochmals. Deaktivierung beendet laufende Schalt- und Anzeigetimer.
+- Gleichzeitige Zählerereignisse verschieben Regelungstimer nicht dauerhaft;
+  Batterie-Verzögerungen werden nicht durch einen sofortigen Regelpfad umgangen.
+- Prognosen verwerfen vergangene Werte und respektieren 0 Minuten Vorlaufzeit.
+- Eine periodische Prüfung berücksichtigt Zeitfenster auch ohne neue Zählerwerte.
+- Alle elf Übersetzungskataloge enthalten dieselben Schlüssel. Benachrichtigungen
+  und Release-Metadaten sind in allen unterstützten Sprachen vorhanden.
+- Offizielle aktuelle JSON-Schemas: 61 Paketprüfungen erfolgreich.
+- 29 Funktionstests erfolgreich unter Node 22.19.0, 24.22.1 und 26.12.1.
+- Konfigurierter Integrationstest gegen js-controller 7.2.5 erfolgreich:
+  Verbraucherobjekte erstellt, Schaltbefehl als `ack: false` empfangen.
+- Dieser Integrationstest besteht auch unter Node.js 26.12.1 (2 Tests).
+- Abschließende Typprüfung, ESLint und Kontrolle des npm-Paketinhalts erfolgreich;
+  Laufzeitmodul, Übersetzungen und Dokumentation enthalten, Testdateien ausgeschlossen.
+- Saubere Installation mit `npm ci` erfolgreich.
+- Repository-Checker 5.23.2 im lokalen Modus: keine Fehler. Verbleibende Hinweise
+  betreffen noch nicht veröffentlichtes 0.2.0, fehlendes Release-Tag, alte nicht
+  mehr abrufbare CI-Logs sowie noch offene GitHub-Vorgänge.
+
+## Bewusste Entscheidungen und externe Abhängigkeiten
+
+- TypeScript bleibt auf 6.0.3: Version 7 kollidiert mit den Peer-Anforderungen
+  des offiziellen ioBroker-ESLint-Setups. PR #79 wird daher nicht blind übernommen.
+- `alwaysOffAtTime` behält seine dokumentierte Bedeutung: normale Abschaltung
+  erst zum Zeitfensterende. Die Heizschutzprüfung bleibt davon unabhängig.
+- `npm audit` meldet nach kompatiblen Updates sechs transitive Meldungen:
+  drei moderate über `@iobroker/testing` → `@alcalzone/esbuild-register` → `esbuild`
+  und drei hohe über `@iobroker/adapter-core` → `@iobroker/js-controller-common-db`
+  → `node-forge`. Die Zählung umfasst die jeweils betroffenen Elternpakete.
+  Es gibt im verwendeten aktuellen Abhängigkeitsbaum kein kompatibles Update.
+  Der Adapter startet keinen esbuild-Entwicklungsserver und verarbeitet selbst
+  keine RSA-Signaturen. Es wird keine Sicherheitsfreiheit behauptet und kein
+  erzwungenes Downgrade der vom Repository-Checker geforderten Werkzeuge vorgenommen.
+- Issue #84 benötigt eine gesonderte Änderung im ioBroker-Stable-Repository
+  nach einer erfolgreichen Veröffentlichung und wird durch einen Git-Push allein
+  nicht erledigt.
+- Automatisierte Prüfungen ersetzen keine Inbetriebnahme mit realen Geräten.

package/docs/en/README.md

@@ -0,0 +1,268 @@
+![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.
+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.