Benutzerdefinierte Geräte

Beim Anlegen einer Wallbox, eines Heizgeräts, eines Netzzählers, einer Hausbatterie, einer PV-Anlage, eines weiteren Verbrauchers, eines Fahrzeugs, eines Tarifs, eines Einspeisebegrenzers oder eines Benachrichtigungsdienstes kannst du in der Geräteliste den Eintrag Benutzerdefiniertes Gerät wählen und eine eigene Logik auf Basis des Plugin-Systems beschreiben.

So lassen sich auch Geräte einbinden, für die es keine eingebaute Vorlage gibt, z. B. indem du die aktuelle Leistung über einen HTTP-Endpunkt liest oder einen Zielstrom per Modbus schreibst.

Ein Gerät definieren

In der Oberfläche steht bei jedem Gerätetyp der Eintrag Benutzerdefiniertes Gerät in der Vorlagenauswahl bereit. Damit öffnet sich der Editor für die eigene Konfiguration. Standardmäßig wird ein Gerät mit type: custom angelegt. Der Typ lässt sich bei Bedarf mit einem anderen Wert überschreiben (z. B. type: heatpump).

power:
  source: mqtt
  topic: home/current/imsys/chn2/raw

Alternativ kannst du die vollständige Konfiguration mit name, type: custom und den darunterliegenden Attributen direkt in die evcc.yaml schreiben:

meters:
  - name: imsys
    type: custom
    power:
      source: mqtt
      topic: home/current/imsys/chn2/raw

Alle weiteren Beispiele auf dieser Seite verwenden die flache Attributblock-Form, wie du sie in der Oberfläche eingibst.

Die Liste der verfügbaren Plugin-Quellen (http, mqtt, modbus, …) und Hilfsfunktionen (calc, map, watchdog, …) steht in der Plugin-Referenz.

Attribute und Features

Jedes benutzerdefinierte Gerät besteht aus drei Arten von Feldern:

• Leseattribute: Plugins, die evcc regelmäßig abfragt, um einen Wert zu erhalten (z. B. power, soc, status).
• Schreibattribute: Plugins, die evcc aufruft, um einen Wert zu setzen oder eine Aktion auszulösen (z. B. enable, maxcurrent, wakeup). Der zu schreibende Wert steht im Plugin zur Verfügung.
• Features: features-Liste, die abweichendes Verhalten freischaltet. Verfügbare Flags hängen vom Gerätetyp ab.

Allgemeine Form:

# Leseattribute
power:
  source: http
  uri: http://meter.local/power
soc:
  source: mqtt
  topic: battery/soc

# Schreibattribute
enable:
  source: http
  uri: "http://charger/relay?turn={{if .enable}}on{{else}}off{{end}}"
maxcurrent:
  source: mqtt
  topic: charger/maxcurrent
  payload: ${maxcurrent:%d}

# Features
features:
  - heating
  - integrateddevice

Welche Attributnamen und Feature-Flags verfügbar sind, hängt vom Gerätetyp ab und steht in den nachfolgenden Abschnitten.

Zähler

Stromzähler werden im Abschnitt meters konfiguriert. Zähler unter meters: können in site referenziert werden:

• grid: Netzzähler
• pv: PV-Zähler
• battery: Hausbatteriezähler
• charge: Zähler für die Ladeleistung der Wallbox
• aux: Verbrauchszähler für intelligente Verbraucher
• consumer: Zähler für einen regulären Verbraucher, erfasst für die Verbrauchsstatistik
• ext: Weiterer Zähler, der weder für die Regelung genutzt noch angezeigt, sondern nur protokolliert und exportiert wird

power ist das einzig erforderliche Attribut. Nicht alle Zählerrollen unterstützen alle Attribute:

• limitsoc und batterymode werden ausschließlich für Batteriezähler genutzt (referenziert in site.battery).
• curtail und curtailed werden gemeinsam für pv-Zähler verwendet, die eine Abregelung der Einspeisung unterstützen (§ 9 EEG).
• currents, voltages und powers sind Phasen-Attribute, die genau drei Plugin-Konfigurationen (als YAML-Array) erwarten und für Netzzähler (grid) und Wallboxen (charge) verwendet werden können.

Plugins müssen den richtigen Datentyp zurückliefern. Zur Konvertierung dienen die Lese-Pipelines.

Leseattribute

Attribut	Typ	Erforderlich	Kontext	Beschreibung
power	float	ja	alle	Aktuelle Leistung in W
energy	float	nein	alle	Zählerstand in kWh
returnenergy	float	nein	alle	Zählerstand in Gegenrichtung in kWh (siehe unten)
maxpower	int	nein	pv (hybrid)	Maximale AC-Leistung in W
curtailed	int	nein	pv	Aktuelles Einspeiselimit in % (0 bis 100). Nur zusammen mit curtail.
soc	int	nein	battery	Ladestand in %
capacity	float	nein	battery	Kapazität in kWh
powers	[float,float,float]	nein	alle	Phasenleistungen in W. Zur Vorzeichenerkennung bei vorzeichenlosen Strömen.
currents	[float,float,float]	nein	alle	Phasenströme in A. Zur Erkennung aktiver Phasen.
voltages	[float,float,float]	nein	alle	Phasenspannungen in V. Zur Anschlusserkennung (1p/3p).

Vorzeichen und Richtungen

Was ein positiver power-Wert und die beiden Energierichtungen bedeuten, hängt von der Zählerrolle ab:

Rolle	power positiv	energy	returnenergy
grid	Netzbezug	Bezogen	Eingespeist
pv	Erzeugung	Erzeugt	Verbraucht (selten)
battery	Entladen (negativ: Laden)	Entladen	Geladen
charge	Laden	Geladen	Entladen (V2X)
aux, ext, consumer	Verbrauch	Verbraucht	Erzeugt (selten)

energy und returnenergy sind steigende Zählerstände in kWh, idealerweise Gesamtwerte wie die Bezugs- und Einspeiseregister eines Netzzählers. Da die Differenzen zwischen den Zählerständen automatisch berechnet werden, muss das Plugin einen Zählerstand liefern, keine Verbrauchswerte pro Intervall. Auch ein Zähler, der sich regelmäßig zurücksetzt (z. B. täglich), funktioniert, da der Rücksprung automatisch erkannt wird. Ein Zählerstand von 0 wird als nicht verfügbar behandelt.

Beide Attribute sind optional. Ohne sie wird die Energiehistorie aus dem zeitlichen Verlauf von power abgeleitet. Echte Zählerstände liefern genauere Langzeitstatistiken.

Schreibattribute

Attribut	Typ	Erforderlich	Kontext	Beschreibung
limitsoc	int	nein	battery	Setzt das Ladeziel der Batterie in %. Das Ladeziel wird aus den konfigurierten MinSoc, MaxSoc und dem aktuellen Ladestand (Attribut soc) berechnet.
curtail	int	nein	pv	Setzt das Einspeiselimit in % der Nennleistung der Erzeugung (0 bis 100, 100 = kein Limit). Nur zusammen mit curtailed. Siehe Einspeisebegrenzer.
batterymode	int	nein	battery	Setzt den Steuerungsmodus der Batterie direkt. Die Modi sind unten aufgeführt.

Batteriemodi

Wert	Modus	Verhalten
1	normal	Normaler Betrieb: Laden aus Überschuss, Entladen für den Verbrauch
2	hold	Entladen verhindern, Laden aus Überschuss bleibt erlaubt
3	charge	Aus dem Netz laden, kein Entladen
4	holdcharge	Laden verhindern, Entladen für den Verbrauch bleibt erlaubt
5	discharge	Ins Netz entladen

Es werden nur die Batteriemodi genutzt, die das Gerät unterstützt. Ist batterymode ein switch, werden die unterstützten Modi aus dessen case-Werten übernommen. Das funktioniert auch, wenn der Switch in einem watchdog steckt. Für alle anderen Plugins müssen die unterstützten Modi in batterymodes angegeben werden, z. B. batterymodes: ["normal", "hold", "charge"]. evcc meter verifybatterymodes schaltet die konfigurierten Modi an der echten Batterie nacheinander durch und zeigt, ob die Batterieleistung wie erwartet reagiert.

Beispiele

Lies die aktuelle Netzleistung über einen HTTP-Endpunkt.

meters:
  - name: grid
    type: custom
    power:
      source: http
      uri: http://zaehler.network.local:8080/api/data.json?from=now
      jq: .data.tuples[0][1]

Lies Leistung und Ladestand einer Hausbatterie und setze ihren Modus über HTTP. Der switch deckt die Modi normal, hold und charge ab, evcc bietet also genau diese drei an.

meters:
  - name: battery
    type: custom
    capacity: 10 # kWh
    power:
      source: http
      uri: http://battery.local/api/power
    soc:
      source: http
      uri: http://battery.local/api/soc
    batterymode:
      source: switch
      switch:
        - case: 1 # normal
          set:
            source: http
            uri: http://battery.local/api/mode
            method: POST
            body: '{"mode": "auto"}'
        - case: 2 # hold
          set:
            source: http
            uri: http://battery.local/api/mode
            method: POST
            body: '{"mode": "hold"}'
        - case: 3 # charge
          set:
            source: http
            uri: http://battery.local/api/mode
            method: POST
            body: '{"mode": "charge"}'

Wallbox

Der Standardtyp type: custom deckt Wallboxen mit stufenloser Stromregelung ab. Für andere Geräte stehen spezialisierte Wallbox-Typen unter schaltbare Steckdosen und Wärmepumpen bereit.

Leseattribute

Attribut	Typ	Erforderlich	Beschreibung
status	string	ja	Status (A bis F)
enabled	bool	ja	Ist das Laden freigegeben?
power	float	nein	Ladeleistung in W
energy	float	nein	Zählerstand in kWh
returnenergy	float	nein	Zählerstand in Gegenrichtung in kWh (Entladeenergie, V2X)
identify	string	nein	Aktuelle RFID-Kennung
soc	int	nein	Ladestand in %
limitsoc	int	nein	Ladelimit in %
temp	float	nein	Aktuelle Temperatur in °C (Heizung, Alias für soc)
limittemp	int	nein	Temperaturlimit in °C (Heizung, Alias für limitsoc)
finishtime	string	nein	Geschätztes Ladeende (RFC3339, Go-Duration, Unix-Zeitstempel oder verbleibende Sekunden)
phases	int	nein	Anzahl der physischen Phasen (1 bis 3)
powers	[float,float,float]	nein	Phasenleistungen in W. Zur Vorzeichenerkennung bei vorzeichenlosen Strömen.
currents	[float,float,float]	nein	Phasenströme in A. Zur Erkennung aktiver Phasen.
voltages	[float,float,float]	nein	Phasenspannungen in V. Zur Anschlusserkennung (1p/3p).

Schreibattribute

Attribut	Typ	Erforderlich	Beschreibung
enable	bool	ja	Laden freigeben/sperren
maxcurrent	int	ja	Setzt den maximalen Ladestrom in A
maxcurrentmillis	float	nein	Setzt den maximalen Ladestrom in A (mit Nachkommastellen)
phases1p3p	int	nein	Phasenumschaltung durchführen (erfordert tos: true)
wakeup	bool	nein	Fahrzeug aufwecken

Features

Feature	Beschreibung
integrateddevice	Keine Fahrzeugauswahl. Gerät läuft ohne angeschlossenes Fahrzeug und ohne Ladevorgänge (z. B. Wärmepumpe, Heizstab, fest installierter Verbraucher).
heating	Behandelt das Gerät als Heizung: Ladestand und Limits werden in °C statt in % dargestellt.
continuous	Gerät läuft im Zustand „deaktiviert“ eigenständig in seinem Normalbetrieb weiter. Statt „Standby“ wird „Normalbetrieb“ angezeigt. Eine Anforderung zur Leistungserhöhung (z. B. bei PV-Überschuss oder günstigem Netzstrom) wird als „Boost“ gekennzeichnet. Die Modi heißen Normal, Smart und Boost statt Aus, Smart und Schnell.
switchdevice	Gerät kann nur ein- und ausgeschaltet werden (keine stufenlose Stromregelung). Max-Strom und die Option Dauerhaft laden werden nicht angezeigt. Min-Strom und Phasen legen die PV-Einschaltleistung fest. Ohne continuous heißen die Modi Aus, Smart und Ein.

Häufige Feature-Kombinationen aus den eingebauten Vorlagen:

Heizstab:

features:
  - integrateddevice
  - heating

Steckdose:

features:
  - switchdevice
  - integrateddevice # optional, wenn die Steckdose einen festen Verbraucher schaltet
  - heating # optional, wenn ein Heizgerät geschaltet wird

Wärmepumpe:

features:
  - integrateddevice
  - heating
  - continuous
  - switchdevice # optional, wenn keine Stromregelung vorhanden (SG Ready)

Beispiele

Frage den Ladestatus einer Wallbox per Modbus ab.

features:
  - integrateddevice
enabled:
  source: modbus
  id: 4711
  uri: modbus.local:502
  rtu: false
  register:
    address: 100
    type: holding
    decode: uint16

Schalte eine Tasmota-Steckdose per MQTT-Nachricht.

enable:
  source: mqtt
  broker: mosquitto.local:883
  topic: cmd/unu-switch/Power
  payload: ON

Schaltbare Steckdosen

type: switchsocket

Für schaltbare Steckdosen und vergleichbare Relais-Geräte, die nur ein-/ausgeschaltet werden können, ohne stufenlose Stromregelung. Der Ladestatus wird aus der aktuellen Leistung abgeleitet (eine Leistung oberhalb von standbypower gilt als Laden). Die vollständige Einrichtung ist unter Schaltbare Steckdosen beschrieben.

Attribut	Typ	Erforderlich	Beschreibung
enabled	bool	ja	Status der Steckdose (an/aus)
power	float	ja	Aktuelle Leistung in W
energy	float	nein	Zählerstand in kWh
soc	float	nein	Ladestand in %
enable	bool	ja	Steckdose ein-/ausschalten
standbypower	float	nein	Schwellwert in W. Darüber: Laden, darunter: Standby. Negativ: statisch (keine Leistungsmessung)

Wärmepumpen

Für Wärmepumpen und vergleichbare Heizgeräte gibt es eigene Wallbox-Typen mit jeweils eigenen Attributen. Die vollständige Einrichtung ist unter Wärmepumpen, Heizstäbe beschrieben.

Wärmepumpe

type: heatpump

Für wechselrichtergesteuerte Wärmepumpen, die einen kontinuierlichen Leistungs-Sollwert per Modbus, HTTP o. Ä. annehmen. Die Ziel-Heizleistung wird direkt über setmaxpower geschrieben.

Attribut	Typ	Erforderlich	Beschreibung
power	float	nein	Aktuelle Leistung in W
energy	float	nein	Zählerstand in kWh
temp	float	nein	Aktuelle Temperatur in °C
limittemp	int	nein	Geräteinternes Temperaturlimit in °C
setmaxpower	int	ja	Setzt die maximale Heizleistung in W
getmaxpower	float	nein	Aktuelle maximale Heizleistung in W

SG-Ready

type: sgready

Für Wärmepumpen, die die standardisierte SG-Ready-Schnittstelle als einzelnen Modus-Wert bereitstellen. Drei Modi werden unterstützt: 1 reduziert, 2 normal, 3 boost.

Attribut	Typ	Erforderlich	Beschreibung
power	float	nein	Aktuelle Leistung in W
energy	float	nein	Zählerstand in kWh
temp	float	nein	Aktuelle Temperatur in °C
limittemp	int	nein	Geräteinternes Temperaturlimit in °C
setmode	int	ja	Ändert den SG-Ready-Modus (1: reduziert, 2: normal, 3: boost)
getmode	int	nein	Aktueller SG-Ready-Modus (1, 2, 3)
setmaxpower	int	nein	Setzt die maximale Heizleistung in W

SG-Ready über Relais

type: sgready-relay

Für Wärmepumpen, deren SG-Ready-Eingang als zwei potenzialfreie Relaiskontakte (boost + dim) ausgeführt ist. Jeder Kontakt wird über eine eigene untergeordnete Wallbox geschaltet, die per Typ statt per Plugin referenziert wird.

Attribut	Typ	Erforderlich	Beschreibung
power	float	nein	Aktuelle Leistung in W
energy	float	nein	Zählerstand in kWh
temp	float	nein	Aktuelle Temperatur in °C
limittemp	int	nein	Geräteinternes Temperaturlimit in °C
boost	charger-typed	ja	Relais für den SG-Ready-Boost-Kontakt
dim	charger-typed	nein	Relais für den SG-Ready-Dim-Kontakt

Fahrzeug

Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden.

Leseattribute

Attribut	Typ	Erforderlich	Beschreibung
soc	int	ja	Ladestand in %
limitsoc	int	nein	Ladelimit in %
status	string	nein	Status (A bis F)
range	int	nein	Reichweite in km
odometer	int	nein	Kilometerstand in km
climater	bool	nein	Klimatisierung aktiv?
getmaxcurrent	float	nein	Maximaler Ladestrom in A
finishtime	string	nein	Geschätztes Ladeende (RFC3339, Go-Duration, Unix-Zeitstempel oder verbleibende Sekunden)

Schreibattribute

Attribut	Typ	Erforderlich	Beschreibung
wakeup	bool	nein	Fahrzeug aufwecken
chargeenable	bool	nein	Startet/stoppt den Ladevorgang
maxcurrent	int	nein	Setzt den maximalen Ladestrom in A

Konfiguration

Attribut	Typ	Erforderlich	Beschreibung
title	string	nein	Anzeigename des Fahrzeugs
capacity	float	nein	Batteriekapazität in kWh
icon	string	nein	Icon in der Benutzeroberfläche

Features

Feature	Beschreibung
coarsecurrent	Fahrzeug akzeptiert den Ladestrom nur in ganzen 1-A-Schritten. Die Regelung wird auf grobe 1-A-Stufen beschränkt, auch wenn die Wallbox feiner regeln könnte.
streaming	Fahrzeug liefert Daten per Push statt per Polling (z. B. BMW Cardata). Ladestand-Updates außerhalb aktiver Ladevorgänge werden als zuverlässig behandelt.
welcomecharge	Fahrzeug erwartet beim Anschließen eine aktive Wallbox, um die Verbindung als funktionierend zu erkennen. Andernfalls meldet das Fahrzeug einen Fehler.

Beispiele

Lies die aktuelle Reichweite aus MQTT-Nachrichten.

title: Grüner Mazda # Anzeigename (optional)
capacity: 50 # Batteriekapazität in kWh (optional)
features:
  - coarsecurrent
range:
  source: mqtt
  topic: mazda2mqtt/c53/chargeInfo/drivingRangeKm

Wecke das Fahrzeug per HTTP-Ping auf, bevor weitere Abfragen folgen.

wakeup:
  source: http
  uri: http://teslalogger.local:5000/command/08154711/wake_up

onIdentify setzt den Lademodus automatisch, sobald das Fahrzeug erkannt wird.

soc:
  source: mqtt
  topic: car/soc
onIdentify:
  mode: smart

Verfügbare Modi sind: off, smart, now. Die veralteten Werte pv und minpv werden weiterhin akzeptiert und aktivieren smart mit ausgeschaltetem bzw. eingeschaltetem Dauerhaft laden.

Tarif und Vorhersage

Ein benutzerdefinierter Tarif bindet eine eigene Wertquelle über den Plugin-Mechanismus an. Das Attribut tariff legt fest, was die Quelle liefert und in welcher Einheit.

Leseattribute

Genau eines der Attribute price oder forecast muss konfiguriert sein.

Attribut	Typ	Beschreibung
price	float	Aktueller Wert. Float-Wert des Plugins.
forecast	string	Vorhersage als JSON-String mit einer Liste von Zeiträumen und Werten (siehe Schema unten). Wird stündlich abgefragt.

Konfiguration

Attribut	Typ	Erforderlich	Beschreibung
tariff	string	nein	price (Standard), co2, solar oder temperature. Bestimmt die Einheit der zurückgegebenen Werte: Preis in konfigurierter Währung pro kWh, CO₂-Intensität in g/kWh, PV-Vorhersage in W, Temperatur in °C.
charges	float	nein	Fester Aufschlag pro kWh, der zu jedem Wert addiert wird. Standard 0.
chargesZones	list	nein	Zeitabhängige Aufschläge (z. B. Netzentgelte), die charges für bestimmte Zeiträume überschreiben. Siehe zeitabhängige Netzentgelte.
tax	float	nein	Prozentualer Steuersatz auf das Ergebnis, z. B. 0.2 für 20%. Standard 0.
formula	string	nein	Go-Ausdruck für eine eigene Berechnung, in dem price, charges und tax als Variablen zur Verfügung stehen. Siehe Beispiele.
interval	duration	nein	Abfrageintervall für forecast. Standard 1h.
cache	duration	nein	Cache-Dauer für price. Standard 15m.

Features

Feature	Beschreibung
average	Glättet feingranulare Preisstufen (z. B. 15-Minuten-Werte) zu Stundenmittelwerten.
cacheable	Speichert abgerufene Werte persistent. Bei Neustart oder Ausfall des Anbieters dienen sie als Fallback (bis zu 24 Stunden).

Beispiele

Aktueller Preis via HTTP:

price:
  source: http
  uri: https://example.com/api/price

Vorhersage via HTTP:

forecast:
  source: http
  uri: https://api.allinpower.nl/troodon/api/p/spot_market/prices/?product_type=ELK
  jq: '[.timestamps, .prices] | transpose | map({ "start": (.[0] | strptime("%Y-%m-%dT%H:%M:%S.%f%z") | strftime("%Y-%m-%dT%H:%M:%SZ")), "end": (.[0] | strptime("%Y-%m-%dT%H:%M:%S.%f%z") | mktime + 3600 | strftime("%Y-%m-%dT%H:%M:%SZ")), "value": .[1] }) | tostring'

Das Plugin muss eine JSON-Struktur mit einer Liste von Zeiträumen und Preisen zurückgeben. Die Datumsfelder müssen in der Form YYYY-MM-DDTHH:MM:SSZ vorliegen, der Preis in der korrekten Währungseinheit (z. B. EUR). evcc arbeitet intern mit 15-Minuten-Intervallen, Plugins können aber auch stündliche Daten liefern, die automatisch umgerechnet werden.

[
  {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-01T00:15:00Z",
    "value": 25.0
  },
  {
    "start": "2025-01-01T00:15:00Z",
    "end": "2025-01-01T00:30:00Z",
    "value": 26.5
  },
  {
    "start": "2025-01-01T00:30:00Z",
    "end": "2025-01-01T00:45:00Z",
    "value": 24.8
  },
  {
    "start": "2025-01-01T00:45:00Z",
    "end": "2025-01-01T01:00:00Z",
    "value": 27.2
  }
]

Das formula-Feld akzeptiert einen Go-Ausdruck, in dem price, charges, tax und der Zeitstempel ts des Zeitfensters als Variablen zur Verfügung stehen. Die math-Bibliothek und time.Time-Methoden auf ts stehen zur Verfügung. Die Formel wird für den aktuellen Preis und jedes Zeitfenster der Vorhersage ausgeführt.

Preisobergrenze:

charges: 0.22
tax: 0.19
formula: math.Min(0.5, (price + charges) * (1 + tax))

Deckelt das Ergebnis bei 50 ct/kWh.

Keine Einspeisevergütung bei negativen Börsenpreisen (deutsche PV-Anlagen, Inbetriebnahme nach dem 25. Februar 2025):

formula: factor := 1.0; if price < 0 { factor = 0.0 }; factor * 0.07

Zahlt eine feste Einspeisevergütung von 7 ct/kWh, außer wenn der Börsenstrompreis negativ ist.

Externe Begrenzung

Eine benutzerdefinierte Integration für die Externe Begrenzung bindet eine Steuerbox oder ein Energiemanagementsystem an, das nicht durch eine eingebaute Integration abgedeckt ist. Wähle dazu in der Oberfläche unter Konfiguration → Externe Begrenzung die Option Benutzerdefinierte Integration.

Wie das Begrenzungssignal empfangen wird, legst du mit einem von vier Typen fest: relay (einzelner Schaltkontakt), fnn (FNN-Steuerbox mit mehreren Schaltkontakten), eebus (EEBUS-Protokoll) oder custom (dynamische Limitwerte über Plugins). Jedes Signal wird über eine Plugin-Konfiguration ausgelesen (GPIO, MQTT, HTTP, Modbus). Siehe auch die hems-Konfigurationsreferenz.

Relais

Die Anbindung über einen einzelnen Schaltkontakt ist die einfachste Lösung. Die Steuerbox aktiviert einen Kontakt, der von deiner evcc-Instanz ausgewertet wird.

Attribut	Typ	Erforderlich	Beschreibung
maxPower	int (W)	ja	Gesamtleistungslimit, das bei aktivem Signal angewendet wird.
limit	Plugin	ja	Plugin-Konfiguration zum Auslesen des Schaltkontakts. true/1 = begrenzt, false/0 = normal.
passthrough	Plugin	nein	Leitet das Begrenzungssignal an ein externes System weiter.
interval	duration	nein	Abfrageintervall für den Schaltkontakt. Standard 10s.

Das Leistungslimit wird dir vom Netzbetreiber mitgeteilt. Bei mehreren steuerbaren Verbrauchseinrichtungen (SteuVE) wird der Gleichzeitigkeitsfaktor berücksichtigt. Du kannst das Limit auch mit folgender Formel selbst berechnen: Gesamtlimit = Anzahl SteuVE × 4,2 kW × Gleichzeitigkeitsfaktor. Details zur Berechnung findest du hier.

Raspberry Pi GPIO

Bei Verwendung eines Raspberry Pi kann der GPIO-Pin direkt ausgelesen werden:

type: relay
maxPower: 8400 # Beispiel für 2 SteuVE
limit:
  source: gpio
  function: read
  pin: 17 # GPIO-Pin 17 auslesen
  # Rückgabewert: false = nicht begrenzt, true = begrenzt

Schließe den Öffnerkontakt (NC) des Relais zwischen Pin und Masse (GND) an. Ein geöffneter Kontakt oder ein Kabelbruch aktiviert dann die Begrenzung. Weitere Details zum GPIO-Plugin findest du in der Plugin-Dokumentation.

MQTT

Wenn die Steuerbox oder ein Gateway MQTT-Nachrichten sendet:

type: relay
maxPower: 11340 # Beispiel für 3 SteuVE mit Gleichzeitigkeitsfaktor 0,9
limit:
  source: mqtt
  topic: hems/limit/status
  # Erwartete Werte: 0/false = normal, 1/true = begrenzt

HTTP-API

Für Steuerboxen mit REST-API:

type: relay
maxPower: 13440 # Beispiel für 4 SteuVE mit Gleichzeitigkeitsfaktor 0,8
limit:
  source: http
  uri: http://steuerbox.local/api/limit
  jq: .limited # JSON-Pfad zum Boolean-Wert

Modbus

Wenn die Steuerbox oder ein Gateway das Leistungslimit via Modbus bereitstellt:

type: relay
maxPower: 4200 # Beispiel für 1 SteuVE
limit:
  source: modbus
  uri: 192.168.179.200:4703 # Beispiel: Relais am 2. S0-Zähler einer cFos Power Brain solar Wallbox
  id: 3 # Modbus Slave-ID
  timeout: 5s
  register:
    type: holding
    decode: uint16
    address: 8056
  # Rückgabewert: 0 = nicht begrenzt, 1 = begrenzt

FNN-Steuerbox

Steuerboxen nach FNN-Standard signalisieren Dimmung und Abregelung über separate Schaltkontakte. Dimmung des Verbrauchs (W4) und Abregelung der Einspeisung (W3, S2, S1) arbeiten unabhängig voneinander. Mindestens eines der Signale w4 oder w3 muss konfiguriert sein.

Attribut	Typ	Erforderlich	Beschreibung
maxDimPower	int (W)	ja¹	Verbrauchslimit, während das Dimmsignal (W4) aktiv ist.
maxCurtailPower	int (W)	ja²	Installierte PV-Leistung, Basiswert für die Abregelungsstufen.
w4	Plugin	nein	Liest das Dimmsignal. Begrenzt den Verbrauch auf maxDimPower.
w3	Plugin	nein	Liest das Abregelungssignal. Begrenzt die Einspeisung auf 0% von maxCurtailPower.
s2	Plugin	nein	Liest das Abregelungssignal. Begrenzt die Einspeisung auf 30% von maxCurtailPower.
s1	Plugin	nein	Liest das Abregelungssignal. Begrenzt die Einspeisung auf 60% von maxCurtailPower.
interval	duration	nein	Abfrageintervall für die Schaltkontakte. Standard 10s.

¹ erforderlich, wenn w4 konfiguriert ist, ² erforderlich, wenn w3 konfiguriert ist.

type: fnn
maxDimPower: 4200 # Verbrauchslimit während Dimmung (in Watt)
maxCurtailPower: 10000 # Installierte PV-Leistung, Basis für Abregelungsstufen (in Watt)
w4:
  source: gpio
  function: read
  pin: 17 # GPIO-Pin 17 auslesen
  # Rückgabewert: false = normal, true = aktiv
w3:
  source: gpio
  function: read
  pin: 27
s2:
  source: gpio
  function: read
  pin: 22
s1:
  source: gpio
  function: read
  pin: 23

Verwende bei GPIO den Öffnerkontakt (NC) jedes Relais, damit ein geöffneter Kontakt oder ein Kabelbruch als aktiv erkannt wird. Details findest du beim GPIO-Plugin.

EEBUS

Hier erfolgt die Anbindung digital über das EEBUS-Protokoll. Die Steuerbox kommuniziert direkt mit deiner evcc-Instanz und übermittelt das Leistungslimit automatisch. Steuerbox und evcc müssen einmalig gekoppelt werden.

Attribut	Typ	Erforderlich	Beschreibung
ski	string	ja	SKI (Subject Key Identifier) der Steuerbox.
contractualConsumptionNominalMax	int (W)	nein	Vertragliche maximale Bezugsleistung.
failsafeConsumptionActivePowerLimit	int (W)	nein	Failsafe-Limit für die Bezugsleistung.
productionNominalMax	int (W)	nein	Installierte Generatorleistung (Wp).
failsafeProductionActivePowerLimit	int (W)	nein	Failsafe-Limit für die Einspeiseleistung.
failsafeDurationMinimum	duration	nein	Failsafe-Mindestdauer, z. B. 2h.
passthrough	Plugin	nein	Leitet das Begrenzungssignal an ein externes System weiter.

type: eebus
ski: "1234-5678-90AB-CDEF" # SKI der Steuerbox

Benutzerdefiniert

Diese generische Integration ist für Steuerungssysteme gedacht, die dynamische Limitwerte statt Schaltkontakten liefern. Verbrauchslimit und Abregelung der Einspeisung werden über Plugins ausgelesen und arbeiten unabhängig voneinander. Mindestens eines der Attribute maxConsumptionPower oder curtailedPercent muss konfiguriert sein.

Attribut	Typ	Erforderlich	Beschreibung
maxConsumptionPower	Plugin	nein¹	Liest das Gesamtleistungslimit in W. 0 = kein Limit.
curtailedPercent	Plugin	nein¹	Liest die erlaubte Einspeisung in % von productionNominalMax (0 bis 100). 100 = keine Abregelung.
productionNominalMax	int (W)	nein²	Installierte Generatorleistung (Wp).
interval	duration	nein	Abfrageintervall für die Plugins. Standard 10s.

¹ mindestens eines von beiden ist erforderlich, ² erforderlich, wenn curtailedPercent konfiguriert ist.

type: custom
maxConsumptionPower:
  source: http
  uri: http://steuerbox.local/api/limit
  jq: .maxPower # Leistungslimit in Watt, 0 = kein Limit
curtailedPercent:
  source: mqtt
  topic: hems/curtail/percent # Erlaubte Einspeisung in Prozent, 100 = keine Abregelung
productionNominalMax: 10000 # Installierte Generatorleistung (Wp)

Einspeisebegrenzer

Ein benutzerdefinierter Einspeisebegrenzer begrenzt die Einspeisung der PV-Anlage auf Anforderung des Netzbetreibers (§ 9 EEG), wenn der Wechselrichter nicht über seine Zähler-Konfiguration abgeregelt werden kann. Wähle dazu in der Oberfläche unter Konfiguration → Netzanschluss → Einspeisebegrenzung hinzufügen die Option Benutzerdefiniertes Gerät. Siehe auch die curtailers-Konfigurationsreferenz und Externe Begrenzung.

Das Gerät erhält die erlaubte Einspeisung in Prozent der installierten Generatorleistung und muss sie am Wechselrichter umsetzen. 100 bedeutet kein Limit.

Attribute

Attribut	Typ	Erforderlich	Beschreibung
curtail	Plugin	ja	Setzt das Einspeiselimit in % der Nennleistung der Erzeugung (0 bis 100). Muss Schreibzugriff unterstützen.
curtailed	Plugin	ja	Liest das aktuelle Einspeiselimit in %. Kann das Gerät es nicht liefern, wird das error-Plugin verwendet (siehe Beispiel).

Beispiele

HTTP

curtail:
  source: http
  uri: http://inverter.local/api/limit?percent={{ .curtail }}
  method: POST
curtailed:
  source: http
  uri: http://inverter.local/api/limit
  jq: .percent

Modbus

Der Wechselrichter kann sein Limit nicht zurückmelden, curtailed liefert daher ErrNotAvailable und das Limit wird bei jeder Änderung geschrieben.

curtail:
  source: modbus
  uri: 192.168.0.10:502
  id: 1
  register:
    type: writesingle
    address: 40016
    encoding: uint16
curtailed:
  source: error
  error: ErrNotAvailable

Benachrichtigungsdienst

Ein benutzerdefinierter Benachrichtigungsdienst verarbeitet Benachrichtigungen über ein beliebiges Plugin mit Schreibzugriff, z. B. ein Shell-Skript, einen HTTP-Aufruf oder eine MQTT-Nachricht. Wähle dazu in der Oberfläche unter Konfiguration → Benachrichtigungen → Dienste die Option Benutzerdefinierter Dienst.

Die Nachricht wird dem Plugin im Parameter ${send} (bzw. als Template-Parameter {{.send}}) bereitgestellt.

Konfiguration

Attribut	Typ	Erforderlich	Beschreibung
send	Plugin	ja	Plugin, das für jede Nachricht aufgerufen wird. Muss Schreibzugriff unterstützen.
encoding	string	nein	Format des Werts in ${send}. Siehe unten.

Die möglichen Werte für encoding sind:

Encoding	Inhalt von ${send}
json	JSON-Objekt { "msg": msg, "title": title }. Das Feld title wird nur hinzugefügt, wenn es für das Ereignis definiert ist.
csv	title und msg als kommagetrennte Liste
tsv	Wie csv, jedoch mit Tabulator als Trennzeichen
title	Nur der Titel
(nicht gesetzt)	Nur die Nachricht (msg)

Beispiel

messaging:
  events:
    connect:
      title: "${vehicleTitle} verbunden"
      msg: "${vehicleTitle} wurde verbunden (Lademodus: ${mode})."
  services:
    - type: custom
      encoding: json
      send:
        # Plugin-Typ
        source: script
        # Plugin-spezifische Konfiguration;
        # {{.send}} enthält die JSON-Nachricht
        cmd: /usr/local/bin/evcc_message "{{.send}}"

In diesem Beispiel wird ein Shell-Skript (cmd) mit dem Argument {"title": "...", "msg": "..."} aufgerufen.