Verbrauchermodule und betriebsartabhängige Angebote ergänzen

docs/Schnittstelle.md

@@ -1,6 +1,6 @@
 # EMS-Schnittstelle
 
-Vertragsversion: `3.0`
+Vertragsversion: `4.0`
 
 Es gibt genau eine fachliche Empfangsmethode je Richtung:
 
@@ -13,7 +13,7 @@ public function VerbraucherdatenEmpfangen(array $daten): void;
 
 | Feld | Typ | Bedeutung |
 | --- | --- | --- |
-| `Version` | Text | Vertragsversion `3.0` |
+| `Version` | Text | Vertragsversion `4.0` |
 | `AbsenderID` | Ganzzahl | Sendende Symcon-Instanz |
 | `EmpfaengerID` | Ganzzahl | Empfangende Symcon-Instanz |
 | `Zeitpunkt` | Ganzzahl | Unixzeit in UTC |
@@ -23,118 +23,119 @@ public function VerbraucherdatenEmpfangen(array $daten): void;
 ```json
 {
   "Kopf": {
-    "Version": "3.0",
+    "Version": "4.0",
     "AbsenderID": 10001,
     "EmpfaengerID": 20001,
     "Zeitpunkt": 1788825600
   },
+  "Betriebsart": "PV",
   "Sollleistung_W": 1501
 }
 ```
 
-`Sollleistung_W` ist immer eine Ganzzahl und muss im aktuell gemeldeten Leistungsangebot liegen.
+`Betriebsart` ist `PV` oder `Peak`. `Sollleistung_W` ist eine Ganzzahl
+aus dem fuer diese Betriebsart gemeldeten Leistungsangebot oder `null`.
+
+`null` kuendigt nur die Betriebsart an. Der Verbraucher uebernimmt sie,
+berechnet sein Leistungsangebot neu und meldet es zurueck. Eine vorhandene
+Sollleistung wird dabei nur verworfen, wenn sie im neuen Angebot nicht mehr
+zulaessig ist.
 
 ## Verbraucher an Manager
 
 ```json
 {
   "Kopf": {
-    "Version": "3.0",
+    "Version": "4.0",
     "AbsenderID": 20001,
     "EmpfaengerID": 10001,
     "Zeitpunkt": 1788825602
   },
+  "Betriebsart": "Peak",
   "PrioritaetPV": 0,
   "PrioritaetPeak": 0,
-  "Leistungswerte_W": [
-    -3000,
-    -2000,
-    {"Von_W": -1000, "Bis_W": -500},
-    0,
-    100,
-    {"Von_W": 1000, "Bis_W": 2000},
-    3000
-  ],
-  "AenderungMoeglich": true,
+  "Leistungswerte_W": [0],
+  "AenderungMoeglich": false,
   "Verfuegbar": true,
-  "Istleistung_W": 1498.5,
-  "Leistungsquelle": 2,
+  "Istleistung_W": 0,
+  "Leistungsquelle": 1,
   "Zustand": [
     {
       "Kennung": "Sollleistung_W",
       "Art": "Sollwert",
-      "Wert": 1501,
+      "Wert": 0,
       "Einheit": "W"
     }
   ]
 }
 ```
 
-### Feste Regeln
+## Betriebsart-Synchronisation
 
-- Prioritaeten beginnen bei 0; eine kleinere Zahl bedeutet eine hoehere Prioritaet.
+1. Der Manager bestimmt `PV` oder `Peak`.
+2. Meldungen einer anderen Betriebsart werden nicht zur Verteilung verwendet.
+3. Der Manager sendet diesen Verbrauchern eine Betriebsart-Ankuendigung mit
+   `Sollleistung_W=null`.
+4. Jeder Verbraucher berechnet und meldet seine PowerSteps fuer diese
+   Betriebsart.
+5. Erst wenn alle aktiven Verbraucher synchronisiert sind, verteilt der Manager
+   Sollleistungen.
+
+Damit kann jeder Verbrauchertyp unterschiedliche Angebote fuer PV und Peak
+melden, ohne dass der Manager seine interne Geraetelogik kennen muss.
+
+## Feste Regeln
+
+- Prioritaeten beginnen bei 0; eine kleinere Zahl bedeutet hoehere Prioritaet.
 - `Leistungsquelle`: 0 nicht vorhanden, 1 berechnet, 2 gemessen.
 - Bei Leistungsquelle 0 ist `Istleistung_W` zwingend `null`.
-- Leistungsbereiche enthalten jeden ganzen Wattwert von `Von_W` bis `Bis_W` einschliesslich.
-- Die Leistungswerte sind aufsteigend, eindeutig und ueberschneiden sich nicht.
-- `Zustand` enthaelt immer den gemeinsamen Eintrag `Sollleistung_W` und daneben nur benoetigte geraetespezifische Eintraege.
-- Eine aktive Stoerung wird mit `Art=Stoerung` und `Wert=true` gemeldet; eine behobene mit `false`.
-- Verbraucher werden ausschliesslich im Manager zugeordnet. Der Verbraucher besitzt keine Manager-ID-Property.
+- Leistungsbereiche enthalten jeden ganzen Wattwert von `Von_W` bis `Bis_W`.
+- Leistungswerte sind aufsteigend, eindeutig und ueberschneiden sich nicht.
+- `Zustand` enthaelt immer `Sollleistung_W`.
+- Verbraucher werden ausschliesslich im Manager zugeordnet.
+- Der Verbraucher besitzt keine Manager-ID-Property.
 
 ## Technische Umsetzung in IP-Symcon
 
-Der Transport erfolgt über `IPS_RequestAction` mit JSON. `MessageSink` erkennt
-registrierte Änderungen; der empfangende Action-Handler prüft das Paket und
-ruft danach genau eine fachliche Empfangsmethode auf. Empfang und Neuberechnung
-werden intern entkoppelt, damit keine gegenseitige Endlosschleife entsteht.
+Der Transport erfolgt ueber `IPS_RequestAction` mit JSON. `MessageSink`
+erkennt registrierte Aenderungen. Empfang und Neuberechnung sind intern
+entkoppelt, damit keine gegenseitige Endlosschleife entsteht.
 
-Das PHP-Interface legt nur die Methode fest. Die folgenden gemeinsamen
-Symcon-Datenpunkte werden durch `VerbraucherBasisTrait` registriert.
+Das PHP-Interface legt nur die Empfangsmethode fest. Die gemeinsamen
+Symcon-Datenpunkte registriert `VerbraucherBasisTrait`.
 
 ### Gemeinsame Properties aller Verbraucher
 
 | Ident | Typ | Standard | Beschreibung |
 | --- | --- | --- | --- |
-| `PrioritaetPV` | Integer | `0` | Priorität ab 0; kleinere Zahl bedeutet höhere Priorität. |
-| `PrioritaetPeak` | Integer | `0` | Wie PV-Priorität, ohne fachliche Obergrenze. |
-| `Meldeintervall` | Integer | `10` | Vollständige Rückmeldung in Sekunden; muss grösser als 0 sein. |
-| `VorgabeTimeout` | Integer | `120` | Sollwert wird nach dieser Zeit ohne Erneuerung ungültig. |
-| `EinstellungenInVisu` | Boolean | `false` | Blendet lokale Einstellvariablen ein und macht sie geprüft bedienbar. |
-| `LoggingEin` | Boolean | `false` | Aktiviert das laufende Diagnoseprotokoll. Module können zusätzliche Diagnosevariablen getrennt einblenden. |
+| `PrioritaetPV` | Integer | `0` | Prioritaet in der Betriebsart PV |
+| `PrioritaetPeak` | Integer | `0` | Prioritaet in der Betriebsart Peak |
+| `Meldeintervall` | Integer | `10` | Vollstaendige Rueckmeldung in Sekunden |
+| `VorgabeTimeout` | Integer | `120` | Ablaufzeit einer Sollleistung |
+| `EinstellungenInVisu` | Boolean | `false` | Lokale Einstellungen in der Visualisierung |
+| `LoggingEin` | Boolean | `false` | Laufendes Diagnoseprotokoll |
 
 ### Gemeinsame Variablen aller Verbraucher
 
 | Ident | Typ / Zugriff | Beschreibung |
 | --- | --- | --- |
-| `Aktiv` | Boolean / bedienbar | Lokale EMS-Freigabe; Start `false`. |
-| `Istleistung` | Float / Anzeige | Aktuelle Leistung in W; nur zusammen mit `Leistungsquelle` gültig. |
-| `Leistungsquelle` | Integer / Anzeige | `0` nicht vorhanden, `1` berechnet, `2` gemessen. |
-| `Sollleistung` | Integer / Anzeige | Tatsächlich angenommene Vorgabe in W. |
-| `SollwertGueltig` | Boolean / Anzeige | Kennzeichnet eine aktuell gültige Vorgabe. |
-| `Verfuegbar` | Boolean / Anzeige | Verbraucher grundsätzlich für EMS-Steuerung verfügbar. |
-| `AenderungMoeglich` | Boolean / Anzeige | Neue Vorgabe darf momentan übernommen werden. |
-| `Stoerung` | Boolean / Anzeige | Mindestens ein Zustandseintrag der Art `Stoerung` ist aktiv. |
-| `Stoertext` | String / Anzeige | Zusammengefasste lesbare Störbeschreibung. |
+| `Aktiv` | Boolean / bedienbar | Lokale EMS-Freigabe; Start `false` |
+| `Istleistung` | Float / Anzeige | Aktuelle Leistung in W |
+| `Leistungsquelle` | Integer / Anzeige | 0 nicht vorhanden, 1 berechnet, 2 gemessen |
+| `Sollleistung` | Integer / Anzeige | Angenommene oder lokal erzwungene Vorgabe |
+| `SollwertGueltig` | Boolean / Anzeige | Aktuelle, nicht abgelaufene Vorgabe |
+| `Verfuegbar` | Boolean / Anzeige | Verbraucher grundsaetzlich verfuegbar |
+| `AenderungMoeglich` | Boolean / Anzeige | Neue Vorgabe darf uebernommen werden |
+| `Stoerung` | Boolean / Anzeige | Mindestens eine Stoerung aktiv |
+| `Stoertext` | String / Anzeige | Zusammengefasste Stoerbeschreibung |
 
-`Leistungswerte_W` und `Zustand` werden intern gehalten und direkt in die
-Nachricht geschrieben. Dafür werden keine zusätzlichen Symcon-Variablen
-angelegt. Der gemeinsame Zustandseintrag `Sollleistung_W` wird durch die Basis
-ergänzt. Während einer Lastwechselsperre meldet ein Verbraucher
-`AenderungMoeglich` als `false` und beschränkt `Leistungswerte_W` auf die aktuell
-gehaltene Leistung. Separate Felder wie `Idle` oder `IdleCounter` sind nicht
-Bestandteil des Vertrags.
+`Leistungswerte_W`, `Betriebsart` und `Zustand` werden intern gehalten
+und direkt in die Nachricht geschrieben.
 
 ## Zeitverhalten
 
-- Rückmeldung nach dem Start, bei relevanten Änderungen und zusätzlich alle
-  `Meldeintervall` Sekunden.
-- Laufende Vorgaben werden vom Manager standardmässig alle 60 Sekunden erneuert.
-- Nach `VorgabeTimeout` Sekunden ist eine nicht erneuerte Vorgabe ungültig.
-- Nach einem Neustart wird zuerst der Gerätezustand erfasst; eine alte Vorgabe
-  wird nicht ungeprüft wieder aufgenommen.
-
-## Obere Anschlüsse des Managers
-
-SDL/VGT, Prognose, Lizenzierung und Störüberwachung verändern den
-Manager-Verbraucher-Vertrag nicht. Ihr aktueller Diskussionsstand ist in
-[Obere-Anschluesse.md](Obere-Anschluesse.md) beschrieben.
+- Rueckmeldung nach Start, relevanten Aenderungen und alle `Meldeintervall`
+  Sekunden.
+- Laufende Vorgaben werden vom Manager standardmaessig erneuert.
+- Nach `VorgabeTimeout` ist eine nicht erneuerte Vorgabe ungueltig.
+- Nach einem Neustart wird keine alte Vorgabe ungeprueft aufgenommen.