Enelix-EMS/README.md

# Enelix EMS

Energiemanagement, Manager und steuerbare Verbraucher fuer IP-Symcon.

## Status

Version 0.1 Build 1 ist die erste Beta fuer kontrollierte Anlagen- und
Feldtests. Der gemeinsame Nachrichtenvertrag, die Verbraucherbasis, der Manager
und alle unten aufgefuehrten Module sind implementiert. Produktiver Einsatz
setzt eine anlagenspezifische Pruefung, Sicherung und Rueckfallplanung voraus.

## Module

- Manager (implementiert)
- Batterie (implementiert)
- Wassererwaermer (implementiert)
- Pufferspeicher (implementiert)
- Verbraucher 1-Stufig (implementiert)
- Waermepumpe (implementiert)
- Ladestation Stand-Alone (implementiert)
- Ladestation Gateway (implementiert)
- Easee Gateway (implementiert)

Die Properties, Variablen, Zustandsdaten und offenen Punkte stehen in der
[Modulübersicht](docs/module/README.md). Gemeinsame Felder werden dort nicht
abweichend neu definiert, sondern verweisen auf den zentralen Vertrag.

Die Verbraucher kommunizieren mit dem Manager ueber den gemeinsamen Vertrag
in `libs/`. Der Manager waehlt die Verbraucher aus; in einem Verbraucher gibt
es keine Manager-ID-Property.

## Betriebsartabhaengige Leistungsangebote

Der Nachrichtenvertrag `4.0` uebermittelt in beiden Richtungen verpflichtend
die aktuelle `Betriebsart`. Zulaessige Werte sind `PV` fuer Solarbetrieb und
`Peak` fuer die Lastspitzenbegrenzung. Dadurch kann jeder Verbraucher fuer
beide Betriebsarten unterschiedliche PowerSteps melden.

Ein Betriebsartwechsel wird synchronisiert:

1. Der Manager bestimmt die neue Betriebsart.
2. Er sendet sie mit `Sollleistung_W: null` an alle aktiven Verbraucher.
3. `null` ist nur eine Ankuendigung und kein Schaltbefehl.
4. Jeder Verbraucher berechnet sein zustandsabhaengiges Leistungsangebot neu
   und meldet es mit derselben Betriebsart zurueck.
5. Der Manager verteilt konkrete Sollleistungen an alle bereits
   synchronisierten Verbraucher.
6. Fehlende, veraltete oder noch nicht umgeschaltete Verbraucher bleiben von
   der Verteilung ausgeschlossen und werden als Stoerung ausgewiesen.

Der Manager verwendet damit nie ein PV-Angebot fuer Peak oder umgekehrt. Ein
nicht antwortender Verbraucher blockiert die Regelung der uebrigen Anlage
nicht; sein aktueller Einfluss ist bereits in der Netzleistungsmessung
enthalten. Eine technische Schaltsperre oder eine Mindestzeit kann das Angebot
weiterhin auf die aktuell gehaltene Leistung begrenzen.

| Verbraucher | PV-Angebot | Peak-Angebot |
| --- | --- | --- |
| Verbraucher 1-Stufig | Normal `[0, Nennleistung]`; bei faelliger Tagesmindestlaufzeit `[Nennleistung]` | Normal `[0]`; bei faelliger Tagesmindestlaufzeit konfigurierbar `[0, Nennleistung]` oder `[Nennleistung]` |
| Ladestation Stand-Alone | Mit Solarladen `[0, ...Ladestufen]`, sonst maximale Ladeleistung | Mit Solarladen `[0]`, sonst `[0, ...Ladestufen]` |
| Ladestation Gateway | Mit Solarladen `[0, ...Ladestufen]`, sonst maximale Ladeleistung | Mit Solarladen `[0]`, sonst `[0, ...Ladestufen]` |
| Warmwassererwaermer | Unter Mindesttemperatur maximale Stufe, sonst zustandsabhaengig | Unter wirksamer Mindesttemperatur `[0, ...Leistungsstufen]`, sonst `[0]` |
| Pufferspeicher | Unter Einschaltschwelle `[0, ...Leistungsstufen]`, sonst `[0]` | Unabhaengig vom Zustand `[0]` |
| Batterie | SoC-abhaengiges Lade-/Entladeraster | SoC-, Reserve- und netzabhaengiges Angebot |

Die vollstaendigen Nachrichtenfelder und JSON-Beispiele stehen in der
[Manager-Verbraucher-Schnittstelle](docs/Schnittstelle.md). Hintergrund,
Alternativen und Folgen beschreibt
[ADR 0004](docs/adr/0004-betriebsartabhaengige-leistungsangebote.md).

## Voraussetzungen

- IP-Symcon ab Version 8.0
- PHP ab Version 8.0 fuer die Entwicklungstests

## Entwicklung und Tests

```bash
composer install
composer check
```

Der Gesamttest schliesst alle Modulsuiten ein. Der einstufige Verbraucher kann
zusaetzlich unabhaengig ausgefuehrt werden:

```bash
composer check:verbraucher-einstufig
```

Neue oder geaenderte Funktionen werden zusammen mit ihren PHPUnit-Tests eingecheckt.
Jedes Modul besitzt zusätzlich einen standardisierten Laufzeittest für IP-Symcon
8.x. Einzel-, Änderungs- und Gesamtläufe sowie Cleanup und Berichte sind im
[Testleitfaden](docs/testing/README.md) beschrieben. Die CI-Pruefung muss vor
der Uebernahme in einen Freigabebranch erfolgreich sein.

| Git-Branch | IP-Symcon-Kanal |
| --- | --- |
| `main` | Stable |
| `beta` | Beta |
| `develop` | Testing |

## Dokumentation

- [Changelog](CHANGELOG.md)
- [Zentrale Liste offener Teamentscheidungen](docs/Offene-Punkte.md)
- [Manager-Verbraucher-Schnittstelle](docs/Schnittstelle.md)
- [Batterieschnittstelle](docs/Schnittstelle-Batterie.md)
- [ADR 0004: Betriebsartabhaengige Leistungsangebote](docs/adr/0004-betriebsartabhaengige-leistungsangebote.md)
- [ADR 0005: Anlagentopologie fuer Prognosen](docs/adr/0005-anlagentopologie-fuer-prognosen.md)
- [Manager-Modul inklusive Lizenzierung](docs/module/Manager/README.md)
- [Warmwassererwaermer-Modul](docs/module/Wassererwaermer/README.md)
- [Pufferspeicher-Modul](docs/module/Pufferspeicher/README.md)
- [Batteriemodul](docs/module/Batterie/README.md)
- [Verbraucher-1-Stufig-Modul](docs/module/Verbraucher-1-Stufig/README.md)
- [Ladestation-Stand-Alone-Modul](docs/module/Ladestation-Stand-Alone/README.md)
- [Ladestation-Gateway-Modul](docs/module/Ladestation-Gateway/README.md)
- [Easee-Gateway-Modul](docs/module/Easee-Gateway/README.md)
- [Easee-Gateway-Schnittstelle](docs/Schnittstelle-Easee-Gateway.md)
- [Migration Boiler x-Stufig](docs/migration/Boiler-x-Stufig.md)
- [Migration Verbraucher 1-Stufig](docs/migration/Verbraucher-1-Stufig.md)
- [Migration Batterie](docs/migration/Batterie.md)
- [Obere Anschlüsse des Managers](docs/Obere-Anschluesse.md)
- [Modulübersicht](docs/module/README.md)