Document eebus dimming

docs/features/14a-enwg-steuve.mdx

@@ -26,39 +26,17 @@ Wichtige Punkte:
 
 evcc unterstützt zwei Wege für die Anbindung: **Relais** (analog über einen Schaltkontakt) oder **EEBus** (digital über das EEBus-Protokoll).
 
-## Lastmanagement einrichten
+## Einrichtung
 
-Für die § 14a EnWG Steuerung muss das [Lastmanagement](./loadmanagement) konfiguriert sein.
-Dabei wird ein spezieller `lpc` (Local Power Control) Stromkreis angelegt, dem alle steuerbaren Verbraucher zugeordnet werden.
-Bei aktivem Reduzierungssignal setzt evcc automatisch ein temporäres Leistungslimit für diesen Stromkreis.
+Die § 14a EnWG Steuerung nutzt das [Lastmanagement](./loadmanagement) von evcc.
+Beim Einrichten von HEMS wird automatisch ein interner `lpc` (Local Power Control) Steuerstromkreis angelegt, dem alle Ladepunkte und sonstigen Verbraucher zugeordnet werden.
+Bei aktivem Reduzierungssignal setzt evcc ein temporäres Leistungslimit für diesen Stromkreis.
 
-### Minimale Konfiguration
+Eine separate Lastmanagement-Konfiguration ist nicht erforderlich.
+Falls du bereits Lastmanagement nutzt, wird der `lpc` Steuerstromkreis als oberste Ebene über deine bestehenden Stromkreise gesetzt.
 
-```yaml
-circuits:
-  - name: lpc # Local Power Control - Stromkreis für Netzanforderungen
-
-loadpoints:
-  - title: Garage
-    charger: charger1
-    circuit: lpc # steuerbarer Verbraucher
-  - title: Carport
-    charger: charger2
-    circuit: lpc # steuerbarer Verbraucher
-```
-
-Alle Ladepunkte, die dem `lpc` Stromkreis oder einem Unterstromkreis zugeordnet sind, werden bei einer Regelanforderung entsprechend reduziert.
-
-Für erweiterte Konfigurationen mit Unterstromkreisen siehe [Lastmanagement](./loadmanagement).
-
-:::info Höchste Ebene
-Der `lpc` Stromkreis hat immer die höchste Ebene.
-Definierst du ihn nicht manuell (wie oben), wird er bei konfiguriertem HEMS automatisch erstellt und über dem höchsten Stromkreis eingefügt.
-:::
-
-:::tip Konfigurationsoberfläche
-Lastmanagement und HEMS können auch über die Konfigurationsoberfläche eingerichtet werden.
-Wichtig: Konfiguriere zuerst das Lastmanagement, bevor du HEMS einrichtest.
+:::tip
+HEMS kann auch über die Konfigurationsoberfläche eingerichtet werden.
 :::
 
 ## Konfiguration via Relais (Analog)
@@ -253,6 +231,24 @@ Nach Ende der Leistungsreduzierung wird das Netzladen automatisch fortgesetzt.
 
 Wenn ein Regellimit aktiv ist, wird ein **Banner mit Regelhinweis** auf der Hauptseite in evcc angezeigt.
 
+## Steuerung weiterer Verbraucher
+
+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.
+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.
+Die verbleibende Leistung wird dann auf die aktiven Ladepunkte verteilt.
+Durch pauschale Dimmung der sonstigen Verbraucher kann die verfügbare Ladeleistung für aktive Ladepunkte in Ausnahmefällen sogar höher sein als im Normalzustand.
+Reicht die Drosselung der Ladepunkte einschließlich der Dimmung aller sonstigen Verbraucher nicht aus, werden Ladevorgänge an Ladepunkten unterbrochen.
+
+:::note Verfügbarkeit
+Aktuell existiert nur ein dimmbarer Zähler (EEBus Verbraucher).
+Diese Funktion wird weiter ausgebaut und entsprechende Zähler werden in der [Gerätedokumentation](/docs/devices/meters) markiert.
+:::
+
 ## Weiterführende Informationen
 
 - [Lastmanagement](./loadmanagement) - Grundlagen der Lastverteilung

i18n/en/docusaurus-plugin-content-docs/current/features/14a-enwg-steuve.mdx

@@ -0,0 +1,255 @@
+---
+sidebar_position: 10
+---
+
+# § 14a EnWG & SteuVE
+
+:::info Current Development
+The implementation of § 14a EnWG is still being rolled out.
+Control boxes and Smart Meter Gateways are currently being deployed.
+:::
+
+evcc supports external control of charging points by grid operators in accordance with § 14a EnWG.
+This enables reduced grid fees whilst ensuring grid stability.
+
+## Background
+
+§ 14a of the German Energy Industry Act (EnWG) regulates grid-friendly control of controllable consumption devices (SteuVE).
+Grid operators can temporarily reduce the power of large consumers such as wallboxes, heat pumps or battery storage systems in the event of grid overload.
+In return, customers receive reduced grid fees.
+
+Important points:
+
+- Affects consumers from 4.2 kW power
+- Control via Smart Meter Gateway and control box
+- Customers benefit from reduced grid fees
+
+evcc supports two connection methods: **Relay** (analogue via a switch contact) or **EEBus** (digital via the EEBus protocol).
+
+## Setup
+
+§ 14a EnWG control uses evcc's [Load Management](./loadmanagement).
+When setting up HEMS, an internal `lpc` (Local Power Control) control circuit is automatically created, to which all charging points and other consumers are assigned.
+When a reduction signal is active, evcc sets a temporary power limit for this circuit.
+
+No separate load management configuration is required.
+If you already use load management, the `lpc` control circuit will be placed as the highest level above your existing circuits.
+
+:::tip
+HEMS can also be set up via the configuration interface.
+:::
+
+## Configuration via Relay (Analogue)
+
+The analogue connection via a switch contact is the simplest solution.
+The control box activates a contact which is evaluated by evcc.
+
+### Basic Configuration
+
+```yaml
+hems:
+  type: relay
+  maxPower: 8400 # Total power limit when signal is active (in watts)
+  limit:
+    # Plugin-specific configuration
+```
+
+### Determining the Power Limit
+
+The power limit is communicated to you by the grid operator.
+For multiple controllable consumption devices (SteuVE), the simultaneity factor is taken into account.
+You can also calculate the limit yourself using the formula: **Total limit = Number of SteuVE × 4.2 kW × Simultaneity factor**. Details on the calculation can be found [here](https://www.inexogy.com/blog/14a-enwg/).
+
+### Examples for Different Connections
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+<Tabs>
+<TabItem value="gpio" label="Raspberry Pi GPIO">
+
+When using a Raspberry Pi, the GPIO pin can be read directly:
+
+```yaml
+hems:
+  type: relay
+  maxPower: 8400 # Example for 2 SteuVE
+  limit:
+    source: script
+    cmd: gpioget gpiochip0 17 # Read GPIO pin 17
+    # Return value: 0 = not limited, 1 = limited
+```
+
+</TabItem>
+<TabItem value="mqtt" label="MQTT">
+
+If the control box or gateway sends MQTT messages:
+
+```yaml
+hems:
+  type: relay
+  maxPower: 11340 # Example for 3 SteuVE with simultaneity factor 0.9
+  limit:
+    source: mqtt
+    topic: hems/limit/status
+    # Expected values: 0/false = normal, 1/true = limited
+```
+
+</TabItem>
+<TabItem value="http" label="HTTP API">
+
+For control boxes with REST API:
+
+```yaml
+hems:
+  type: relay
+  maxPower: 13440 # Example for 4 SteuVE with simultaneity factor 0.8
+  limit:
+    source: http
+    uri: http://steuerbox.local/api/limit
+    jq: .limited # JSON path to boolean value
+```
+
+</TabItem>
+</Tabs>
+
+## Configuration via EEBus (Digital)
+
+The digital connection via EEBus is the future-proof and preferred solution.
+The control box communicates directly with evcc via the EEBus protocol and automatically transmits the power limit.
+
+### Prerequisites
+
+- evcc installation with EEBus support
+- Control box with EEBus interface
+- Network connection between evcc and control box
+
+### Step 1: Generate Certificates
+
+EEBus requires certificates for secure communication. These must be created once.
+Run the following command in the console:
+
+```bash
+evcc eebus-cert
+```
+
+This command creates the required certificates and displays the configuration that must be inserted into `evcc.yaml`.
+
+### Step 2: Basic EEBus Configuration
+
+Add the EEBus configuration to `evcc.yaml`:
+
+```yaml
+# Basic EEBus configuration
+eebus:
+  certificate:
+    public: |
+      -----BEGIN CERTIFICATE-----
+      # Insert public key here
+      -----END CERTIFICATE-----
+    private: |
+      -----BEGIN EC PRIVATE KEY-----
+      # Insert private key here
+      -----END EC PRIVATE KEY-----
+  # Optional: Specify network interface (recommended)
+  interfaces:
+    - eth0 # or the appropriate interface
+  # Optional: Define your own SKI
+  shipid: EVCC-1234567890abcdef
+```
+
+### Step 3: HEMS Configuration
+
+Configure the HEMS interface for § 14a EnWG:
+
+```yaml
+hems:
+  type: eebus
+  ski: "1234-5678-90AB-CDEF" # SKI of the control box
+  # You can find the SKI in your control box documentation
+```
+
+:::note Note
+With EEBus, the power limit is automatically transmitted by the control box.
+:::
+
+### Step 4: Determine SKI and Pairing
+
+#### Determine evcc SKI
+
+After starting evcc, your own SKI is displayed in the logs:
+
+```bash
+evcc --log debug | grep -i ski
+```
+
+#### Perform Pairing
+
+1. **In the control box**: Add evcc as HEMS
+   - Enter the SKI of evcc
+   - Specify the IP address of evcc
+   - Start the pairing process
+
+2. **In evcc**: Add the control box SKI to the HEMS configuration
+   - Enter the control box SKI in the HEMS configuration
+   - Restart evcc
+
+3. **Check connection**:
+   ```bash
+   # Activate trace logging for EEBus
+   evcc -l trace eebus
+   ```
+
+:::tip Important
+
+- Certificates only need to be generated once
+- After successful pairing, the configuration must not be changed
+  :::
+
+## How It Works
+
+### Normal Operation
+
+In normal operation, evcc charges without power limitation by the HEMS.
+The charging points operate with their normal configuration and are coordinated by additional [Load Management](./loadmanagement) restrictions if applicable.
+
+### Reduction Signal Active
+
+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.
+If total consumption is too high, charging processes can also be stopped.
+The control affects all modes (Solar, Min+Solar, Fast).
+
+**Battery control during reduction:**
+If [active battery control](./battery#battery-control) is configured and grid charging of the home battery is active, this is automatically paused.
+The battery is set to "hold" mode so that it neither charges nor discharges.
+After the power reduction ends, grid charging automatically resumes.
+
+When a control limit is active, a **banner with control notice** is displayed on the main page in evcc.
+
+## Controlling Additional Consumers
+
+In addition to charging points, other controllable consumers can also be integrated into § 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.
+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.
+The remaining power is then distributed to the active charging points.
+Due to flat dimming of other consumers, the available charging power for active charging points can in exceptional cases even be higher than in normal state.
+If throttling the charging points including dimming all other consumers is not sufficient, charging processes at charging points are interrupted.
+
+:::note Availability
+Currently, only one dimmable meter (EEBus consumer) exists.
+This feature is being expanded and compatible meters will be marked in the [device documentation](/docs/devices/meters).
+:::
+
+## Further Information
+
+- [Load Management](./loadmanagement) - Basics of load distribution
+- [Plugins](../devices/plugins) - Advanced plugin configurations