HEMS: circuit update, breaking change (#1011)

Author: naltatis

AGENTS.md

@@ -119,6 +119,7 @@ Everything else is manually maintained:
 #### UI Elements & Technical Terms
 
 - **Bold** for UI elements and modes: **PV-Modus**, **Min+PV**
+- **Bold with `→` separator** for UI navigation paths: **Konfiguration → Externe Steuerung**, **Configuration → EEBus**
 - `Code formatting` for configuration keys: `residualPower`, `evcc.yaml`
 - _Italics_ for technical terms when introducing concepts
 

blog/2023-10-05/feature-highlights-10-2023.mdx

@@ -48,7 +48,7 @@ Die Mindestladung-Funktion existiert bei evcc schon seit Ewigkeiten.
 Sie ist hilfreich, wenn du mal mit wenigen Prozenten nach Hause kommst und sichergehen willst, dass du immer genug Reichweite für bspw. ein unerwartetes Ereignis hast.
 
 Bislang konnte sie aber nur über die Konfigurationsdatei oder per API eingestellt werden.
-Inzwischen geht das auch über die UI unter **Plan** > **Ankunft** > **Min. Ladung %**.
+Inzwischen geht das auch über die UI unter **Plan** → **Ankunft** → **Min. Ladung %**.
 
 Die Einstellungen werden pro Fahrzeug gespeichert und bleiben auch nach einem Neustart oder Update erhalten.
 

docs/features/external-control.mdx

@@ -38,27 +38,11 @@ Dies betrifft hauptsächlich größere PV-Anlagen, kann aber auch im privaten Be
 
 Die Anbindung erfolgt über **Relais** (über einen Schaltkontakt) oder **EEBus** (über das EEBus-Protokoll).
 
-## Vorbereitung
+## Einrichtung
 
-Die externe Steuerung nutzt das [Lastmanagement](./loadmanagement).
-Lastmanagement muss konfiguriert sein (mindestens minimale Konfiguration).
-
-**1. Lastmanagement konfigurieren**
-
-In der Benutzeroberfläche unter **Konfiguration > Lastmanagement** muss folgender Eintrag angelegt werden:
-
-```yaml title="Lastmanagement (Minimale Konfiguration)"
-- name: lpc
-```
-
-Hinweis: Falls bereits Lastmanagement mit bestehenden Stromkreisen genutzt wird, wird `lpc` automatisch als oberste Ebene darüber gesetzt.
-
-**2. Ladepunkte zuordnen**
-
-Alle Ladepunkte und Wärmepumpen, die durch die externe Steuerung geregelt werden sollen, müssen im jeweiligen Konfigurationsdialog diesem Stromkreis zugeordnet werden.
-
-Jetzt kann die Einrichtung der externen Steuerung erfolgen.
-Extern gesetzte Limits sind in der Lastmanagement-Statusübersicht dargestellt (`lpc` Stromkreis).
+Die Einrichtung erfolgt über **Konfiguration → Externe Steuerung**.
+Das Umsetzen der Begrenzung erfolgt über das [Lastmanagement](./loadmanagement).
+Dabei wird automatisch ein "Externe Begrenzung" Stromkreis (`gridcontrol`) erstellt, der als oberste Ebene über eventuell bestehende Stromkreise gesetzt wird.
 
 ## Konfiguration via Relais
 
@@ -144,7 +128,7 @@ Die Steuerbox kommuniziert über das EEBus-Protokoll direkt mit evcc und übermi
 - Netzwerkverbindung zwischen evcc und Steuerbox
 
 EEBus ist vorkonfiguriert.
-SHIP-ID und SKI der evcc Instanz können unter **Konfiguration > EEBus** eingesehen werden.
+SHIP-ID und SKI der evcc Instanz können unter **Konfiguration → EEBus** eingesehen werden.
 
 ### Steuerbox verbinden
 
@@ -164,7 +148,7 @@ Bei EEBus wird das Leistungslimit automatisch von der Steuerbox übermittelt.
 
 #### SKI von evcc ermitteln
 
-Die SKI kann unter **Konfiguration > EEBus** eingesehen werden.
+Die SKI kann unter **Konfiguration → EEBus** eingesehen werden.
 
 #### Pairing durchführen
 
@@ -191,7 +175,7 @@ Wenn der Netzbetreiber ein Reduzierungssignal sendet:
 1. **Relais**: Der Kontakt wird geschlossen, evcc aktiviert das konfigurierte `maxPower` Limit
 2. **EEBus**: Die Steuerbox übermittelt das berechnete Gesamtlimit digital
 
-evcc regelt alle dem `lpc` Stromkreis zugeordneten Ladepunkte entsprechend dem Limit herunter.
+Alle dem "Externe Begrenzung" Stromkreis (`gridcontrol`) zugeordneten Ladepunkte werden entsprechend dem Limit heruntergeregelt.
 Bei zu hohem Gesamtverbrauch können Ladevorgänge auch gestoppt werden.
 Die Regelung betrifft alle Modi (PV, Min+PV, Schnell).
 
@@ -206,7 +190,7 @@ Wenn ein Regellimit aktiv ist, wird ein **Banner mit Regelhinweis** auf der Haup
 ## Protokollierung
 
 Alle Limitierungsanfragen durch den Netzbetreiber werden automatisch dokumentiert.
-Die Protokolldaten können unter **Konfiguration > Externe Steuerung** als CSV-Datei heruntergeladen werden.
+Die Protokolldaten können unter **Konfiguration → Externe Steuerung** als CSV-Datei heruntergeladen werden.
 
 Jeder Eintrag enthält:
 
@@ -227,7 +211,7 @@ Der Anlagenbetreiber ist für den ordnungsgemäßen Betrieb verantwortlich und m
 Neben Ladepunkten können auch weitere steuerbare Verbraucher in das §14a Lastmanagement einbezogen werden.
 Dies betrifft z. B. Wärmepumpen oder Batteriespeicher, die über EEBus angebunden oder als Zähler mit zusätzlichem Relaisausgang konfiguriert sind.
 
-Die Steuerung berücksichtigt dabei die aktuelle Leistungsaufnahme aller dem internen `lpc` Stromkreis zugeordneten Verbraucher.
+Die Steuerung berücksichtigt dabei die aktuelle Leistungsaufnahme aller dem "Externe Begrenzung" Stromkreis (`gridcontrol`) zugeordneten Verbraucher.
 Dazu zählen automatisch alle Ladepunkte und alle Zähler mit entsprechenden Schaltausgängen oder EEBus-Schnittstelle mit LPC Use Case als sonstige Verbraucher.
 
 Zunächst werden alle sonstigen Verbraucher gedimmt.

docs/features/loadmanagement.mdx

@@ -82,8 +82,12 @@ Die Ladepunkte _Carport A_ und _Carport B_ sind dem Stromkreis `carport` zugeord
 Die Stromkreise `garage`, `carport` und die Wärmepumpe sind direkt am Hauptstromkreis (`main`) angeschlossen.
 Die Regelung stellt sicher, dass zu keinem Zeitpunkt die Grenzen der jeweiligen Stromkreise überschritten werden.
 
-**Wichtig:** Es muss immer einen Hauptstromkreis geben.
-Dieser hat keine `parent` Eigenschaft.
+**Wichtig:** Es muss immer genau einen Hauptstromkreis geben (einen Stromkreis ohne `parent` Eigenschaft).
+
+:::info Externe Steuerung (§14a, §9)
+Wenn [externe Steuerung](./external-control) konfiguriert ist, wird automatisch ein "Externe Begrenzung" Stromkreis (`gridcontrol`) über dem bestehenden Hauptstromkreis erstellt.
+Dieser wird dann zum neuen obersten Stromkreis.
+:::
 
 ## Messwerte
 

docs/reference/configuration/hems.md

@@ -4,127 +4,108 @@ sidebar_position: 7
 
 # `hems`
 
-evcc kann in bestehende Home Energy Management Systeme (HEMS) integriert werden. Momentan wird der SMA Sunny Home Manager 2.0 (SHM) unterstützt!
+Unter `hems` wird die externe Steuerung von Verbrauchsleistung und Einspeisung konfiguriert.
+Dies wird z. B. für die Umsetzung von §14a EnWG oder §9 EEG benötigt.
+Details zu Hintergrund und Einrichtung findest du unter [Externe Steuerung](../../features/external-control).
 
-**Beispiel**:
-
-```yaml
-hems:
-  type: sma
-  ...
-```
+:::info Hinweis
+Wenn `hems` konfiguriert ist, wird automatisch ein "Externe Begrenzung" Stromkreis (`gridcontrol`) erstellt.
+Eine manuelle Konfiguration von Stromkreisen ist dafür nicht erforderlich.
+:::
 
-Im folgenden werden nun alle möglichen Parameter erklärt.
+:::info SMA Sunny Home Manager & SEMP-Protokoll
+Die Integration mit dem SMA Sunny Home Manager (SHM) ist standardmäßig aktiv und muss nicht mehr unter `hems:` konfiguriert werden.
+Details und Konfigurationsmöglichkeiten findest du unter **Konfiguration > Sunny Home Manager**.
+:::
 
 ---
 
 ## Erforderliche Parameter
 
 ### `type`
 
-Definiert das HEMS System.
+Definiert den Typ der externen Steuerung.
 
 **Mögliche Werte**:
 
-- `sma`: Für den SMA Sunny Home Manager 2.0. Siehe [`sma`](#sma) Definition
-
-**Beispiel**:
-
-```yaml
-type: sma
-```
+- `relay`: Anbindung über Schaltkontakt
+- `eebus`: Anbindung über das EEBus-Protokoll
 
 ---
 
-## Optionale SMA Parameter
-
-evcc meldet jeden Ladepunkt an den SHM als eigenständiges Device. Die Device ID wird dabei von evcc generiert.
+## `type: relay`
 
-Die Device ID ist ein HEX-String und setzt sich wie folgt zusammen
+Anbindung über einen Schaltkontakt (z. B. Steuerbox).
+Der Kontakt signalisiert, ob eine Leistungsbegrenzung aktiv ist.
 
-```text
-F-AAAAAAAA-BBBBBBBBBBBB-00
+```yaml
+hems:
+  type: relay
+  maxPower: 8400 # Gesamtleistungslimit bei aktivem Signal (in Watt)
+  limit:
+    source: gpio
+    function: read
+    pin: 17
 ```
 
-- F: Vendor ID Type, fest definiert
-- AAAAAAAA: Siehe `vendorid`
-- BBBBBBBBBBBB: Siehe `deviceid`
-- 00: Sub Device ID, fest definiert
+### Parameter
 
----
+#### `maxPower`
 
-### `vendorid`
+Gesamtleistungslimit in Watt, das bei aktivem Signal gesetzt wird.
 
-Definiert die VendorID die für die Erstellung der Device ID verwendet wird. Wenn in der Konfiguration keine Vendor ID angegeben wird, wird eine fest definierte ID verwendet.
-Normalerweise wird diese nicht manuell konfiguriert.
+#### `limit`
 
-HEX-String, Länge 8 Zeichen
+[Plugin](../../devices/plugins)-Konfiguration zum Auslesen des Schaltkontakts.
+Erwarteter Rückgabewert: `true`/`1` = begrenzt, `false`/`0` = normal.
 
-**Beispiel**:
+#### `passthrough`
 
-```yaml
-hems:
-  type: sma
-  vendorid: "AAAAAAAA"
-  ...
-```
+Optionale [Plugin](../../devices/plugins)-Konfiguration zum Durchreichen des Begrenzungssignals an ein externes System.
 
----
+#### `interval`
 
-### `deviceid`
+Abfrageintervall für den Schaltkontakt.
+Standard: `10s`.
 
-Definiert die Geräte ID, die für die Erstellung der Device ID des ersten Ladepunkts verwendet wird. Wenn keine Geräte ID angegeben wird, generiert evcc eine zufällige Geräte ID in Abhängigkeit auf den aktuellen Computer.
+Weitere Beispiele für verschiedene Anbindungen (GPIO, MQTT, HTTP) findest du unter [Externe Steuerung](../../features/external-control#konfiguration-via-relais).
 
-HEX-String, Länge: 12 Zeichen
+---
+
+## `type: eebus`
 
-**Beispiel**:
+Anbindung über das EEBus-Protokoll.
+Die Steuerbox übermittelt das Leistungslimit automatisch.
 
 ```yaml
 hems:
-  type: sma
-  deviceid: "BBBBBBBBBBBB"
-  ...
+  type: eebus
+  ski: "1234-5678-90AB-CDEF" # SKI der Steuerbox
 ```
 
-:::info Docker Container
-Wenn evcc als Docker Container ausgeführt wird, muss zu diesem Zweck die `machine-id` gemounted werden. Siehe auch [Docker Konfiguration](../../installation/docker)
-:::
-
-#### Bisherige DeviceID herausfinden
-
-Wenn evcc auf einen anderen Computer umgezogen wird, ändert sich dadurch auch die zufällig erzeugte Geräte ID. Der SHM wird evcc in diesem Fall als neues Gerät erkannt und die bisherigen Geräte werden im SMA Portal nicht erkannt.
+### Parameter
 
-Um dies zu verhindern, sollte die Geräte ID vom bisherigen System übernommen werden:
+#### `ski`
 
-- Öffne in einem Browser die Adresse `http://IP-ADRESSE-BISHERIGER-EVCC-HOST:7070/semp`
-- Es wird ein Text im XML Format angezeigt. Der Text beginnt in dieser Form:
+SKI (Subject Key Identifier) der Steuerbox.
+Wird für das Pairing benötigt.
 
-  ```xml
-  <Device2EM xmlns="http://www.sma.de/communication/schema/SEMP/v1">
-    <DeviceInfo>
-      <Identification>
-        <DeviceId>F-AAAAAAAA-BBBBBBBBBBBB-00</DeviceId>
-  ```
+#### Erweiterte Limits
 
-- Die Zeichenkette an der Stelle von `AAAAAAAA` ist die VendorID
-- Die Zeichenkette an der Stelle von `BBBBBBBBBBBB` entspricht der DeviceID des ersten Ladepunkts
-- Diese Zeichenkette muss nun in der Konfiguration für `deviceid` im neuen System übernommen werden
-- Wurde die `vendorid` zuvor ebenfalls manuell konfiguriert muss auch diese auf das neue System übertragen werden
-
----
+Folgende optionale Parameter können für die EEBus-Kommunikation gesetzt werden:
 
-## Unterstützte HEMS
+- `contractualConsumptionNominalMax`: Vertragliche maximale Verbrauchsleistung (in Watt)
+- `failsafeConsumptionActivePowerLimit`: Failsafe-Limit für Verbrauchsleistung (in Watt)
+- `failsafeProductionActivePowerLimit`: Failsafe-Limit für Einspeiseleistung (in Watt)
+- `failsafeDurationMinimum`: Minimale Failsafe-Dauer (z. B. `2h`)
 
-### `sma`
+#### `passthrough`
 
-Bietet Unterstützung für den SMA Sunny Home Manager 2.0 (SHM).
+Optionale [Plugin](../../devices/plugins)-Konfiguration zum Durchreichen des Begrenzungssignals an ein externes System.
 
-Durch die Integration können die [Ladepunkte](loadpoints) dem SHM hinzugefügt werden und erscheinen im Sunny Portal.
-Die Ladesteuerung erfolgt ausschließlich durch evcc.
+#### `interval`
 
-**Beispiel**:
+Abfrageintervall.
+Standard: `10s`.
 
-```yaml
-hems:
-  type: sma
-```
+Details zur Einrichtung und zum Pairing findest du unter [Externe Steuerung](../../features/external-control#konfiguration-via-eebus).

i18n/en/docusaurus-plugin-content-blog/2023-10-05/feature-highlights-10-2023.mdx

@@ -48,7 +48,7 @@ The minimum charge function has been around at evcc for ages.
 It is helpful if you come home with only a few percent and want to make sure you always have enough range for an unexpected event.
 
 Until now, it could only be set via the configuration file or via API.
-Now you can also do this via the UI under **Plan** > **Arrival** > **Min. charge %**.
+Now you can also do this via the UI under **Plan** → **Arrival** → **Min. charge %**.
 
 The settings are stored per vehicle and are retained even after a restart or update.
 

i18n/en/docusaurus-plugin-content-docs/current/features/external-control.mdx

@@ -38,27 +38,11 @@ This mainly affects larger solar installations, but can also become relevant in
 
 Connection is established via **Relay** (via a switch contact) or **EEBus** (via the EEBus protocol).
 
-## Preparation
+## Setup
 
-External control uses [Load Management](./loadmanagement).
-Load management must be configured (at least minimal configuration).
-
-**1. Configure load management**
-
-In the user interface under **Configuration > Load Management**, the following entry must be created:
-
-```yaml title="Load Management (Minimal Configuration)"
-- name: lpc
-```
-
-Note: If load management with existing circuits is already in use, `lpc` will automatically be placed as the top level above them.
-
-**2. Assign charging points**
-
-All charging points and heat pumps that should be controlled by external control must be assigned to this circuit in their respective configuration dialog.
-
-Now external control can be configured.
-Externally set limits are displayed in the load management status overview (`lpc` circuit).
+Configuration is done via **Configuration → External Control**.
+Limits are enforced via [Load Management](./loadmanagement).
+An "External Limit" circuit (`gridcontrol`) is automatically created and placed as the top level above any existing circuits.
 
 ## Configuration via Relay
 
@@ -144,7 +128,7 @@ The control box communicates directly with evcc via the EEBus protocol and autom
 - Network connection between evcc and control box
 
 EEBus is preconfigured.
-The evcc instance's SHIP-ID and SKI can be viewed under **Configuration > EEBus**.
+The evcc instance's SHIP-ID and SKI can be viewed under **Configuration → EEBus**.
 
 ### Connect Control Box
 
@@ -164,7 +148,7 @@ With EEBus, the power limit is automatically transmitted by the control box.
 
 #### Determine evcc SKI
 
-The SKI can be viewed under **Configuration > EEBus**.
+The SKI can be viewed under **Configuration → EEBus**.
 
 #### Perform Pairing
 
@@ -191,7 +175,7 @@ When the grid operator sends a reduction signal:
 1. **Relay**: The contact is closed, evcc activates the configured `maxPower` limit
 2. **EEBus**: The control box digitally transmits the calculated total limit
 
-evcc reduces all charging points assigned to the `lpc` circuit according to the limit.
+All charging points assigned to the "External Limit" circuit (`gridcontrol`) are reduced according to the limit.
 If total consumption is too high, charging processes can also be stopped.
 The control affects all modes (Solar, Min+Solar, Fast).
 
@@ -206,7 +190,7 @@ When a control limit is active, a **banner with control notice** is displayed on
 ## Logging
 
 All limitation requests from the grid operator are automatically documented.
-The log data can be downloaded as a CSV file under **Configuration > External Control**.
+The log data can be downloaded as a CSV file under **Configuration → External Control**.
 
 Each entry contains:
 
@@ -227,7 +211,7 @@ The system operator is responsible for proper operation and must keep the log fo
 In addition to charging points, other controllable consumers can also be integrated into German §14a load management.
 This applies e.g. to heat pumps or battery storage systems that are connected via EEBus or configured as meters with an additional relay output.
 
-The control takes into account the current power consumption of all consumers assigned to the internal `lpc` circuit.
+The control takes into account the current power consumption of all consumers assigned to the "External Limit" circuit (`gridcontrol`).
 This automatically includes all charging points and all meters with corresponding switching outputs or EEBus interface with LPC use case as other consumers.
 
 First, all other consumers are dimmed.

i18n/en/docusaurus-plugin-content-docs/current/features/loadmanagement.mdx

@@ -81,7 +81,12 @@ The charging points Carport A and Carport B are assigned to the `carport` circui
 The circuits `garage`, `carport`, and the heat pump are connected directly to the root circuit (`main`).
 The regulation ensures that the limits of the respective circuits are not exceeded at any time.
 
-**Important:** There must always be a main circuit. This has no `parent` property.
+**Important:** There must always be exactly one root circuit (a circuit without `parent` property).
+
+:::info External Control (§14a, §9)
+When [external control](./external-control) is configured, an "External Limit" circuit (`gridcontrol`) is automatically created above the existing root circuit.
+This becomes the new top-level circuit.
+:::
 
 ## Measuring