Plugins

Plugins können verwendet werden, um Geräte und externe Datenquellen in evcc zu integrieren, für die es keine direkte Unterstützung gibt. Plugins können für folgende Kategorien verwendet werden:

• meter: PV, Batterie, Netz, Zähler
• charger: Wallboxen, Smarte Schalter, Wärmepumpen, Heizstäbe
• vehicle: Fahrzeuge
• tariff: Tarife, Vorhersagen
• circuit: Lastmanagement

Zusätzlich können Plugins auch für die in Messaging beschriebenen Endpunkte zum Versenden von Lifecycle-Events genutzt werden.

Übersicht

Plugins

• Modbus Plugin - Plugin zum Auslesen von einem Modbus-fähigen Gerät.
• MQTT Plugin - Plugin um indirekt über MQTT mit den MQTT-fähigen Geräten zu kommunizieren.
• HTTP Plugin - Plugin, das über HTTP-API mit Endgeräten spricht.
• Websocket Plugin - Plugin zum Empfangen von Gerätedaten über einen eigenen Webserver. Kann nur zum Lesen von Daten genutzt werden.
• SMA/Speedwire Plugin - Plugin speziell für SMA Geräte, die mit dem Speedwire Protokoll kommunizieren können.
• Go Plugin - Plugin, das Werte über ein Go Skript bereitstellt oder entgegennimmt.
• JavaScript Plugin - Plugin, das Werte in über ein JavaScript Skript bereitstellt oder entgegennimmt.
• Shell Plugin - Plugin, das ein Shell Skript ausführen kann, um Daten zu extrahieren oder schreibend entgegennimmt.
• Prometheus Plugin - Plugin zum Lesen von Metriken aus Prometheus über PromQL.

Helpers

• Const Plugin - Spezielles Plugin das einfach einen konstanten Wert zurückliefert.
• Calc Plugin - Meta-Plugin um Ausgaben von anderen Plugins arithmetisch zu verknüpfen.
• Combined Plugin - Meta-Plugin speziell für charger um die booleschen Status-Werte für den angeschlossenen (plugged) und ladenden (charging) Zustand zu einem einzigen Ladestatus zu kombinieren.
• Valid Plugin - Meta-Plugin um Plugin-Werte basierend auf einer booleschen Validierung bereitzustellen.
• Meter Plugin - Plugin um ein anderes Messgerät als Datenquelle zu verwenden.
• Switch Plugin - Meta-Plugin für bedingte Schreibvorgänge basierend auf Eingabewerten (wie switch/case).
• Watchdog Plugin - Meta-Plugin zur automatischen Wiederholung von Schreibvorgängen in regelmäßigen Abständen.
• Sequence Plugin - Meta-Plugin zur sequentiellen Ausführung mehrerer Schreibvorgänge.
• Sleep Plugin - Hilfsplugin zum Verzögern von Aktionen (wird meist mit Sequence verwendet).
• Map Plugin - Meta-Plugin zur Übersetzung von Integer-Werten (z. B. gerätespezifische Modi in evcc-Modi).
• Convert Plugin - Meta-Plugin zur Datentyp-Konvertierung beim Schreiben (z. B. float zu int).
• Ignore Plugin - Meta-Plugin zum Unterdrücken spezifischer Fehlermeldungen.

Syntax

Jedes Plugin besitzt ein individuelles Konfigurationsschema. Dabei ist es wichtig zu wissen, ob das Plugin in einem lesenden oder schreibenden Kontext verwendet wird. Einige Konfigurationsparameter machen nur in einem lesenden Kontext Sinn, andere nur, wenn sie im Schreibmodus genutzt werden.

Beispielsweise kann über die folgende Konfiguration ein MQTT Plugin als meter eingebunden werden, bei dem der aktuelle Stromverbrauch über das spezifizierte MQTT Topic eingelesen wird:

Beispiel: MQTT Plugin für die Leistungswerte eines Strommessgeräts

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

Das Schema der Plugin Konfiguration hat dabei immer folgende Struktur:

- name: <name>
  type: custom
  <attr1>:
    source: <plugin>
    <p-attr1>: ...
    <p-attr2>: ...
    ....
  <attr2>:
    ....

Dabei steht <name> für den Namen des Geräts, <attr1> und <attr2> für eine der unten beschriebenen Geräte-spezifischen Attribute, <plugin> für den Plugin-Typ und <p-attr1>, <p-attr2> für Plugin-spezifische Konfigurationen (z.b. source, topic für Plugins vom Typ mqtt)

Lesen

Beim Lesen von Daten mithilfe eines Plugins können sogenannte Pipelines verwendet werden. Damit können Daten aus der Ausgabe des Plugins fein granular extrahiert werden. Dies ermöglicht es, komplexe Datenstrukturen wie JSON oder XML zu verarbeiten und die benötigten Informationen herauszufiltern. Mögliche Parameter für die Datenextraktion sind:

• regex: Ein regulärer Ausdruck, um Werte aus dem empfangenen Text zu extrahieren.
• jq: Ein jq-Ausdruck, um Werte aus JSON-Strukturen zu extrahieren. Die volle Syntax und Möglichkeiten finden sich in der jq-Dokumentation.
• quote: Boolean-Wert, der die Eingabedaten in Anführungszeichen einschließt, bevor sie an jq weitergegeben werden. Dies ermöglicht es jq, unquotierte Strings (z. B. von MQTT) zu verarbeiten. Bei einem MQTT-Wert wie Charging kann man quote: true und jq: '. == "Charging"' verwenden.
• unpack: Konvertiert Werte aus anderen Zahlenrepräsentationen, z. B. hex.
• decode: Dekodiert Binärformate wie uint32, float32 etc.

Schreiben

Beim Schreiben können Parameter in der Konfiguration durch Platzhalter ersetzt werden. Die Daten werden in Form von ${var[:format]} zur Verfügung gestellt. Wenn Format nicht angegeben wird, werden die Daten im Standard %v Go-Format bereitgestellt. Die Variablen werden mit dem entsprechenden Wert ersetzt, bevor das Plugin ausgeführt wird. Zusätzlich können sämtliche Funktionen der Go Template Library verwendet werden, um komplexere Datentransformationen durchzuführen.

Je nach Gerät (meter, charger oder vehicle) können andere Attribute mit Plugins gelesen oder gesetzt werden.

Meter

Stromzähler werden in der Konfigurationssektion meters konfiguriert. Zähler, die unter meters: definiert werden, können an verschiedenen Stellen innerhalb der site Konfiguration verwendet 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
• ext: weiterer Zähler, bspw. für Lastmanagement oder Datenerfassung

power ist das einzig zwingend erforderliche Attribut das in jeder meter Definition vorhanden sein muss, alle weiteren Attribute sind optional.

Jedoch unterstützen nicht alle Metertypen alle Pluginattribute:

• limitsoc und batterymode werden ausschließlich für Batteriezähler genutzt (d.h. für meter die in site.battery referenziert werden).
• currents, voltages und powers sind Phasen Attribute, die mit jeweils genau drei Plugin-Konfigurationen (in einem YAML Array) konfiguriert werden müssen und für Netzzähler (grid) und Wallboxen (charge) verwendet werden können.

Die folgenden Tabellen enthalten alle Attribute, die von Plugins bereitgestellt werden können, wenn sie für meter konfiguriert werden. Bei der Verwendung der Plugins ist es auch wichtig, dass diese den richtigen Datentyp zurückliefern. Um zu dem verlangten Datentypen zu konvertieren, können die in Lesen beschriebenen Pipelines genutzt werden.

Attribut	Typ	Erfordert	Kontext	Beschreibung
power	float	ja	alle	Aktuelle Leistung in W
energy	float	nein	alle	Zählerstand in kWh
maxpower	int	nein	pv (hybrid)	Maximale AC-Leistung in W
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).

Beispiel

In diesem Beispiel wird die Konfiguration eines Meters um die aktuelle elektrische Gridleistung über einen HTTP-Aufruf abgefragt:

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

site:
  meters:
    grid: volkszaehler
    ...
  ...

Neben den Attributen, die Plugins zur lesenden Auswertung bereitstellen, werden folgende Attribute von evcc genutzt, um Aktionen zu triggern:

Attribut	Typ	Erfordert	Kontext	Beschreibung
limitsoc	int	nein	battery	Setze Ladeziel für Batterie in %. Das Ladeziel wird aus den konfigurierten MinSoc, MaxSoc und dem aktuellen Ladestand (Attribut soc) berechnet.
batterymode	int	nein	battery	Setze Lademodus direkt (1: normal, 2: hold, 3: charge)

Charger

Wallboxen und Ladegeräte haben folgende Attribute die ausgelesen werden können:

Attribut	Typ	Erfordert	Beschreibung
status	string	ja	Status (A..F)
enabled	bool	ja	Ist Ladung freigegeben?
power	float	nein	Ladeleistung in W
energy	float	nein	Zählerstand in kWh
identify	string	nein	Aktuelle RFID-Kennung
soc	int	nein	Ladestand in %
phases	int	nein	Anzahl der physischen Phasen (1..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).
temp	float	nein	Aktuelle Temperatur in °C (Heizung)
templimit	int	nein	Temperaturlimit in °C (Heizung)
getmode	int	nein	SG-Ready Modus (Wärmepumpe)
getmaxpower	float	nein	Maximale Heizleistung in W (Heizung)

Allgemeine Konfigurationsoptionen

Zusätzlich zu den Plugin-Attributen können folgende Konfigurationsoptionen direkt am Charger gesetzt werden:

Attribut	Typ	Erfordert	Beschreibung
icon	string	nein	Icon für die Darstellung in der Benutzeroberfläche
features	[]string	nein	Feature-Flags für spezielle Charger-Eigenschaften (siehe unten)
standbypower	int	nein	Standby-Leistung in W (für switchsocket Typ)

Feature-Flags

Über das features Array können spezielle Eigenschaften des Chargers aktiviert werden:

Feature	Beschreibung
heating	Behandelt das Gerät als Heizung (z. B. Wärmepumpe, Heizstab). Beeinflusst die Darstellung in der Benutzeroberfläche.
integrateddevice	Gerät ohne Ladesitzungen und ohne angeschlossenes Fahrzeug (z. B. Smartes Schalter, fest installierte Verbraucher).
coarsecurrent	Ladestrom kann nur in 1 A Schritten eingestellt werden (wird in der Regelung berücksichtigt).
welcomecharge	Aktiviert Welcome Charge Funktion. Ladegerät liefert beim Anschließen kurz Strom, damit das Fahrzeug erkennt, dass der Charger funktioniert.

Beispiel mit Features:

chargers:
  - name: heizstab
    type: custom
    features:
      - heating
      - integrateddevice
    icon: heater
    status:
      source: mqtt
      topic: heater/status
    # ... weitere Attribute

Beispiel

Dieses Beispiel zeigt, wie man über das Modbus-Plugin den Ladestatus (ladend/nicht ladend) eines Chargers abfragen kann:

chargers:
  - name: icharge
    type: custom
    enabled:
      source: modbus
      id: 4711
      uri: modbus.local:502
      rtu: false
      register:
        address: 100
        type: holding
        decode: uint16

Neben den read-only Werten können über Plugins auch Aktionen getriggert oder Konfigurationswerte gesetzt werden:

Attribut	Typ	Erfordert	Beschreibung
enable	bool	ja	Ladung freigeben / sperren
maxcurrent	int	ja	Setze maximalen Ladestrom in A
maxcurrentmilis	float	nein	Setze maximalen Ladestrom in A
phases1p3p	int	nein	Phasenumschaltung durchführen (erfordert tos: true)
wakeup	bool	nein	Wecke Fahrzeug auf
setmode	int	nein	Ändere SG-Ready Modus (1: reduced, 2: normal, 3: boost)
setmaxpower	int	nein	Setze maximale Heizleistung in W (Heizung)

Beispiel

Dieses Beispiel schaltet eine Tasmota-Steckdose über eine MQTT Nachricht gesendet an:

chargers:
  - name: unu-charger
    type: custom
    enable:
      source: mqtt
      broker: mosquitto.local:883
      topic: cmd/unu-switch/Power
      payload: ON

Vehicle

Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden.

Attribut	Typ	Erfordert	Beschreibung
soc	int	ja	Ladestand in %
limitsoc	int	nein	Ladelimit in %
status	string	nein	Status (A..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	Geplantes Ladeende (RFC3339)

Allgemeine Konfigurationsoptionen

Folgende Konfigurationsoptionen können direkt am Fahrzeug gesetzt werden:

Attribut	Typ	Erfordert	Beschreibung
title	string	nein	Anzeigename des Fahrzeugs in der Benutzeroberfläche
icon	string	nein	Icon für die Darstellung in der Benutzeroberfläche
capacity	float	nein	Batteriekapazität in kWh

Beispiel

Im folgenden Beispiel wird die aktuelle Reichweite des Fahrzeugs aus MQTT Nachrichten gelesen:

vehicles:
  - name: mazda
    type: custom
    title: Grüner Mazda
    capacity: 50
    range:
      source: mqtt
      topic: mazda2mqtt/c53/chargeInfo/drivingRangeKm

Zusätzlich können spezielle Kommandos über Plugins an das Fahrzeug geschickt werden:

Attribut	Typ	Erfordert	Beschreibung
wakeup	bool	nein	Fahrzeug aufwecken
chargeenable	bool	nein	Starte/stoppe den Ladevorgang
maxcurrent	int	nein	Setze maximalen Ladestrom in A

Beispiel

Um ein Auto über einen HTTP Ping aufzuwecken, um weiter Abfragen zu senden, kann wie im folgenden Beispiel das HTTP-Plugin genutzt werden:

vehicles:
  - name: model-y
    type: custom
    wakeup:
      source: http
      uri: http://teslalogger.local:5000/command/08154711/wake_up

Lademodus bei Fahrzeugerkennung

Bei benutzerdefinierten Fahrzeugen kann der Lademodus beim Erkennen des Fahrzeugs mit onIdentify konfiguriert werden. Dies ist nützlich, wenn der gewünschte Lademodus automatisch gesetzt werden soll, sobald das Fahrzeug identifiziert wird.

Beispiel:

vehicles:
  - name: my-car
    type: custom
    soc:
      source: mqtt
      topic: car/soc
    onIdentify:
      mode: pv

Verfügbare Modi sind: off, now, minpv, pv.

Tarife & Vorhersagen

Siehe Tarife & Vorhersagen > Eigenes Plugin für mehr Details.

Lastmanagement

Work in Progress

...

Messaging

Work in Progress

...

Plugins

Folgende Plugins stehen zur Verfügung und können für die oben beschriebenen Attribute konfiguriert werden, um eine flexible Anbindung an die verschiedenen Systeme zu ermöglichen.

Modbus lesen schreiben

Das modbus-Plugin kann Daten von jedem Modbus-fähigen Gerät oder SunSpec-kompatiblen Wechselrichter lesen. Viele Strommessgeräte sind bereits vorkonfiguriert (siehe MBMD Supported Devices). Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu integrieren.

Schaue in die Modbus Dokumentation für weitere Details.

MQTT lesen schreiben

Das mqtt-Plugin ermöglicht das Lesen von Werten über MQTT-Topics. Das ist insbesondere für Strommessgeräte nützlich, z. B. wenn diese ihre Daten bereits über MQTT bereitstellen. Schaue in die MBMD Dokumentation für ein Beispiel, wie man Modbus Messdaten in MQTT bekommt. Das Plugin bietet auch die Fähigkeit JSON Datenstrukturen über jq-ähnliche Abfragen zu lesen oder zu parsen (Siehe HTTP plugin).

Beispiel Lesen:

source: mqtt
topic: mbmd/sdm1-1/Power
timeout: 30s # don't accept values older than timeout
scale: 0.001 # factor applied to result, e.g. for Wh to kWh conversion

Für den Schreibzugriff werden die Daten mit dem Attribut payload bereitgestellt. Falls dieser Parameter in der Konfiguration fehlt, wird der Wert im Standardformat geschrieben.

Beispiel Schreiben:

source: mqtt
topic: mbmd/charger/maxcurrent
payload: ${var:%d}

HTTP lesen schreiben

Das http-Plugin führt HTTP Aufrufe durch, um Daten zu lesen oder zu aktualisieren. Es beinhaltet auch die Fähigkeit, JSON-Datenstrukturen über jq-Abfragen (z. B. für REST-APIs) zu lesen oder einfache Transformationen durchzuführen. Der volle Funktionsumfang ist in der offiziellen jq Dokumentation zu finden.

Methoden der Authentifizierung sind basic, bearer und digest. Die Namen der jeweiligen Parameter finden sich hier.

Authentifizierung

Für HTTP-Anfragen stehen verschiedene Authentifizierungsmethoden zur Verfügung:

Basic Authentication:

auth:
  type: basic
  user: <benutzername>
  password: <passwort>

Bearer Token (z. B. für JWT):

auth:
  type: bearer
  token: <token>

Digest Authentication:

auth:
  type: digest
  user: <benutzername>
  password: <passwort>

Benutzerdefinierte Authentifizierung:

Für komplexere Authentifizierungsszenarien können benutzerdefinierte Authentifizierungs-Plugins entwickelt werden. Diese werden über den Parameter source eingebunden:

auth:
  source: <plugin-name>
  user: <benutzername>
  password: <passwort>
  # weitere plugin-spezifische Parameter

Dies ermöglicht die Integration von Geräten mit speziellen Authentifizierungsanforderungen, ohne den gesamten HTTP-Plugin-Code anpassen zu müssen.

Wichtig

XML-Dokumente werden intern automatisch in JSON-Form überführt, welche dann mit jq wie eine native JSON-Antwort weiter gefiltert werden können. Attribute bekommen das prefix attr.

tipp

Für den Test von jq-Abfragen bietet sich z. B. das Online-Tool https://jqplay.org/ und für Regex-Tests z. B. das Online-Tool https://regex101.com/ an.

Beispiel Lesen:

source: http
uri: https://volkszaehler/api/data/<uuid>.json?from=now
method: GET # default HTTP method
headers:
  - content-type: application/json
auth: # basic authentication
  type: basic
  user: foo
  password: bar
insecure: false # set to true to trust self-signed certificates
jq: .data.tuples[0][1] # parse response json
scale: 0.001 # factor applied to result, e.g. for kW to W conversion
cache: 60s # response cache duration
timeout: 10s # timeout in golang duration format, see https://golang.org/pkg/time/#ParseDuration

source: http
uri: http://charger/status
jq: .total_power > 10 # Converts a json integer to a boolean value

Beispiel Schreiben:

body: %v # only applicable for PUT or POST requests

enable:
  source: http
  uri: "http://charger/relay/0?turn={{if .enable}}on{{else}}off{{end}}"

Websocket lesen

Das websocket-Plugin bietet einen WebSocket-Listener. Es beinhaltet auch die Fähigkeit, JSON-Datenstrukturen über jq-ähnliche Abfragen zu lesen oder zu parsen. Dies kann z. B. verwendet werden, um Daten von Volkszählers Push Server zu empfangen.

Beispiel Lesen:

source: http
uri: ws://<volkszaehler host:port>/socket
jq: .data | select(.uuid=="<uuid>") .tuples[0][1] # parse message json
scale: 0.001 # factor applied to result, e.g. for Wh to kWh conversion
timeout: 30s # error if no update received in 30 seconds

SMA/Speedwire lesen

Das sma Plugin bietet eine Schnittstelle zu SMA Geräten, welche das Speedwire Protokoll beherrschen.

Beispiel Lesen:

source: sma
uri: 192.168.4.51 # alternative to serial
serial: 123456 # alternative to uri
value: ActivePowerPlus # ID of value to read
password: "0000" # optional (default: 0000)
interface: eth0 # optional
scale: 1 # optional scale factor for value

Unterstützte Werte für value können in der Diagnoseausgabe über das Kommando evcc meter (mit konfigurierten SMA meter Geräten) gefunden werden.

Alle möglichen Werte können als Konstanten hier gefunden werden (verwende den Namen der Konstante für value).

Go lesen schreiben

Das go Plugin verwendet den Yaegi Interpreter, um Go Code zur Laufzeit auszuführen. Es ist besonders nützlich für typsichere Berechnungen und komplexe Datenverarbeitungslogik.

Verfügbare Go Standardbibliotheken

Folgende Go Pakete stehen automatisch zur Verfügung und müssen nicht importiert werden:

• fmt - Formatierte Ein-/Ausgabe
• math - Mathematische Funktionen
• strings - String-Manipulation
• time - Zeit- und Datumsfunktionen

Beispiel Lesen:

source: go
script: |
  res := 500.0
  res * 2 // returns 1000.0

Beispiel mit Zeitfunktionen:

source: go
script: |
  hour := time.Now().Hour()
  price := 50.0 // Nachttarif
  if hour >= 9 && hour < 17 {
    price = 100.0 // Tagestarif
  }
  price // returns 50.0 oder 100.0 abhängig von der Uhrzeit

Beispiel mit String-Verarbeitung:

source: go
script: |
  text := "hello world"
  strings.ToUpper(text) // returns "HELLO WORLD"

Wenn das go Plugin zum Schreiben verwendet wird, wird der zu schreibende Wert dem Script als Variable übergeben:

Beispiel Schreiben:

charger:
  - type: custom
    maxcurrent:
      source: go
      script: |
        fmt.Printf("Setze Ladestrom: %d A\n", maxcurrent)
        // maxcurrent Variable ist automatisch verfügbar

Input-Transformationen verwenden

Mit dem in Parameter können Werte aus anderen Quellen als Variablen im Script verwendet werden. Dieses Beispiel zeigt eine bedingte Logik, die mit den einfachen Calc-Operationen nicht möglich ist:

power:
  source: go
  script: |
    // Leistung abhängig vom SoC und Standby
    power := 5000.0 // normal
    if standby {
      power = 0.0 // im Standby keine Last
    } else if soc < 20.0 {
      power = 1000.0 // niedrig
    }
    power // returns 5000.0 (standby=false, soc>=20)
  in:
    - name: soc
      type: float
      config:
        source: const
        value: 85.0
    - name: standby
      type: bool
      config:
        source: const
        value: false

JavaScript lesen schreiben

evcc integriert einen JavaScript Interpreter mit der Underscore.js Bibliothek, welche direkt über _. zugreifbar ist, z. B. _.random(0,5). Das js Plugin kann JavaScript code über den script Parameter ausführen. Sehr hilfreich für das schnelle Erstellen von Prototypen:

Beispiel Lesen:

source: js
script: |
  var res = 500;
  2 * res; // returns 1000

Wenn das js Plugin zum Schreiben verwendet wird, wird der zu schreibende Wert dem Script als Variable übergeben:

Beispiel Schreiben:

charger:
  - type: custom
    maxcurrent:
      source: js
      script: |
        console.log(maxcurrent);

Shell Script lesen schreiben

Das script Plugin führt externe Skripte zum Lesen oder Aktualisieren von Daten aus. Das Plugin ist hilfreich um jede Art von externer Funktionalität einzubinden.

Beispiel Lesen:

source: script
cmd: /bin/bash -c "cat /dev/urandom"
timeout: 5s

Beispiel Schreiben:

source: script
cmd: /home/user/my-script.sh ${enable:%b} # format boolean enable as 0/1
timeout: 5s

Prometheus lesen

Das prometheus Plugin liest Metriken aus einer Prometheus-Instanz über PromQL-Abfragen. Dies ist nützlich, wenn bereits Monitoring-Daten in Prometheus vorliegen, die in evcc verwendet werden sollen.

Parameter:

Parameter	Typ	Erfordert	Beschreibung
uri	string	ja	Prometheus Server URL
query	string	ja	PromQL-Abfrage
timeout	duration	nein	Timeout (Standard: 2 Minuten)

Unterstützte Abfrageergebnisse:

• Scalar: Ein einzelner Zahlenwert
• Vector: Ein Vektor mit genau einem Metrik-Eintrag

Beispiel:

power:
  source: prometheus
  uri: http://prometheus.local:9090
  query: "sum(household_power_watts)"
  timeout: 30s

Beispiel mit Zeitbereich:

energy:
  source: prometheus
  uri: http://prometheus.local:9090
  query: "increase(energy_total_kwh[1h])"

Die Abfrage muss einen einzelnen numerischen Wert zurückgeben. Bei Vektor-Ergebnissen muss genau eine Metrik enthalten sein.

Helpers

Const lesen

Das const Plugin gibt einen konstanten Wert zurück. Es eignet sich z. B. um in Verbindung mit dem calc Plugin feste Korrekturwerte (Offset) auf einen variablen Wert anzuwenden oder auch zur Simulation von Mess- und Statuswerten zu Testzwecken.

Beispiel Lesen:

source: const
value: -16247

Calc lesen

Das calc Plugin erlaubt es mehrere Einzelwerte mathematisch weiterzuverarbeiten:

Beispiel Lesen:

source: calc
add:
- source: ...
  ...
- source: ...
  ...

source: calc
mul:
- source: calc
  sign:
    source: ... (power)
  ...
- source: ... (current)
  ...

Als Operanden werden dabei die Grundrechenarten Addition (add), Multiplikation (mul) unterstützt, Division (div), Vorzeichenumkehr (sign), Absolutwert (abs), Minimalwert (min) und Maximalwert (max) unterstützt.

Mit scale: -1 bei einem der Werte kann eine einfache Subtraktion durchgeführt werden, mit scale: 0.001 eine Division z. B. zur Konvertierung von kWh in Wh.

Mit sign: (jede positive Zahl wird zu +1, jede negative Zahl wird zu -1, 0 bleibt 0) können (in Verbindung mit mul) Vorzeichen auf andere Werte übertragen werden. Z. B. um bei Zählern die „Richtung“ der Leistung (Einspeisung oder Bezug) auf die gemessenen Ströme zu übertragen.

Mit abs: wird der Absolutwert einer Zahl berechnet.

Mit min: und max: wird der Minimalwert bzw. der Maximalwert berechnet.

Das calc Plugin ist hilfreich um z. B.

• Leistungswerte von einzelnen PV-Strings zu summieren (addieren)
• Die Scheinleistung aus Spannung und Strom zu berechnen (multiplizieren)
• Getrennte Leistungswerte für Import und Export zu einem vorzeichenbehafteten Einzelwert zu kombinieren (subtrahieren).
• Prozentuale Füllstände zu berechnen (dividieren)
• Die richtige Richtung des Stromflusses festlegen (sign)
• Bekannte Offsets zu eliminieren (addieren mit const Plugin)

tipp

Konstante Hilfswerte (z. B. für Offsets) lassen sich mithilfe des const Plugins als Operand erzeugen.

Combined lesen

Das combined Status Plugin wird verwendet um gemischte Boolean Status Werte von Plugged (angeschlossen) / Charging (Laden) in einen evcc-kompatiblen Ladestatus von A..F zu konvertieren. Es wird z.b. zusammen mit einer OpenWB MQTT Integration verwendet.

Beispiel Lesen:

source: combined
plugged:
  source: mqtt
  topic: openWB/lp/1/boolPlugStat
charging:
  source: mqtt
  topic: openWB/lp/1/boolChargeStat

Valid lesen

Das valid Plugin ermöglicht es, Plugin-Werte basierend auf einer booleschen Validierung bereitzustellen. Es trennt die Gültigkeit eines Werts von dessen eigenem Inhalt. Wenn die Validierung false zurückgibt, wird der Wert als nicht verfügbar betrachtet.

Dies ist besonders nützlich für Integrationen wie ioBroker, die Gültigkeit und Wert getrennt bereitstellen.

Beispiel Lesen:

source: valid
valid:
  source: mqtt
  topic: iobroker/wallbox/power/valid
value:
  source: mqtt
  topic: iobroker/wallbox/power/value

In diesem Beispiel wird der Wert nur verwendet, wenn das valid Topic true zurückgibt. Wenn es false zurückgibt, wird der Wert als nicht verfügbar markiert.

Meter lesen

Das meter Plugin ermöglicht es, ein anderes Messgerät als Datenquelle zu verwenden. Dies ist nützlich, wenn man ein bestehendes Gerät für mehrere Messwerte verwenden möchte oder wenn man verschiedene Methoden eines Geräts für unterschiedliche Attribute nutzen will.

Die config Sektion enthält dabei die vollständige Template-Konfiguration des einzubettenden Messgeräts.

Beispiel Lesen:

meters:
  - name: battery
    type: custom
    power:
      source: meter
      config:
        type: template
        template: shelly-1pm
        host: 192.168.178.21
        channel: 0
      method: power
      scale: -1
    energy:
      source: meter
      config:
        type: template
        template: shelly-1pm
        host: 192.168.178.21
        channel: 0
      method: energy
    soc:
      source: mqtt
      topic: Haus/Batterie
      jq: .soc
      timeout: 60s

In diesem Beispiel wird ein Shelly 1PM Gerät als Datenquelle für Leistung und Energie einer Batterie verwendet, während der Ladestand (SoC) über MQTT abgerufen wird.

Switch schreiben

Das switch Plugin führt bedingte Schreibvorgänge durch, ähnlich einer switch/case-Anweisung in Programmiersprachen. Basierend auf dem Eingabewert wird die entsprechende Aktion ausgeführt.

Parameter:

Parameter	Typ	Erfordert	Beschreibung
switch	[case]	ja	Array von Fällen mit case und set Konfiguration
default	config	nein	Fallback-Plugin, wenn kein Fall zutrifft

Funktionsweise:

1. Eingabewert wird mit den case Werten verglichen
2. Bei Übereinstimmung wird das entsprechende set Plugin ausgeführt
3. Falls kein Fall zutrifft und default definiert ist, wird dieses ausgeführt
4. Falls kein Fall zutrifft und kein default definiert ist, gibt es einen Fehler

Unterstützte Datentypen: int64 (nur Integer-Werte)

Beispiel:

setmode:
  source: switch
  switch:
    - case: 1 # reduced
      set:
        source: http
        uri: http://device.local/api/mode
        body: "eco"
    - case: 2 # normal
      set:
        source: http
        uri: http://device.local/api/mode
        body: "normal"
    - case: 3 # boost
      set:
        source: http
        uri: http://device.local/api/mode
        body: "boost"

Watchdog schreiben

Das watchdog Plugin ist ein Wrapper-Plugin, das Schreibvorgänge automatisch in regelmäßigen Abständen wiederholt. Manche Geräte (z. B. Batteriespeicher, Wechselrichter) erwarten, dass Steuerbefehle regelmäßig wiederholt werden, um aktiv zu bleiben. Das Watchdog-Plugin überwacht Schreibvorgänge und wiederholt diese automatisch in der Hälfte des konfigurierten Timeout-Intervalls.

Parameter:

Parameter	Typ	Erfordert	Beschreibung
timeout	duration	ja	Zeitintervall für Wiederholungen (Wert wird alle timeout/2 erneut geschrieben)
reset	string | [string]	nein	Wert(e), bei denen Wiederholungen gestoppt werden
initial	string	nein	Wert, der beim Start einmalig geschrieben wird
set	config	ja	Verschachteltes Plugin für den eigentlichen Schreibvorgang

Funktionsweise:

1. Start: Falls initial konfiguriert ist, wird dieser Wert beim Start einmalig geschrieben
2. Schreiben: Wenn ein Wert geschrieben wird, prüft das Plugin, ob dieser in der reset Liste steht
3. Watchdog aktiv: Falls der Wert nicht in reset steht, startet der Watchdog und schreibt den Wert automatisch alle timeout/2 Sekunden erneut
4. Watchdog stoppt: Falls der Wert in reset steht, werden keine Wiederholungen durchgeführt

reset Parameter:

• Definiert Werte, bei denen der Watchdog gestoppt wird
• Kann ein einzelner Wert (reset: 0) oder mehrere Werte (reset: [0, 1]) sein
• Typischerweise für "sichere" oder "Standard" Zustände verwendet, die keine kontinuierliche Wiederholung benötigen

initial Parameter:

• Optionaler Wert, der beim Pluginstart einmalig geschrieben wird
• Nützlich, um einen definierten Startzustand zu setzen
• Wird vor allen anderen Schreibvorgängen ausgeführt

Unterstützte Datentypen: int64, float64, bool

Beispiel Schreiben:

source: watchdog
timeout: 60s
reset: 0
set:
  source: modbus
  uri: 192.168.1.10:502
  id: 1
  register:
    address: 100
    type: writemultiple
    encoding: uint16

In diesem Beispiel werden Werte automatisch alle 30 s wiederholt, außer wenn der Wert 0 geschrieben wird.

Ablaufbeispiel mit timeout: 60s, reset: 0:

• Plugin startet
• Schreibe Wert 100 → Watchdog läuft, Wert wird alle 30 s wiederholt
• Nach 2 Minuten: Wert 100 wurde bereits 4x geschrieben (0s, 30s, 60s, 90s, 120s)
• Schreibe Wert 200 → Watchdog läuft weiter, jetzt mit neuem Wert 200 alle 30 s
• Schreibe Wert 0 → Watchdog stoppt (da 0 in reset definiert)
• Keine weiteren Wiederholungen, bis ein neuer Wert != 0 geschrieben wird

Beispiel mit Batteriesteuerung (batterymode verwendet Werte 1=normal, 2=hold, 3=charge):

batterymode:
  source: watchdog
  timeout: 60s
  reset: 1 # Stoppe Wiederholungen im Normalbetrieb
  set:
    source: switch
    switch:
      - case: 1 # normal
        set:
          source: modbus
          # ... Modbus-Konfiguration für Normalbetrieb
      - case: 2 # hold
        set:
          source: modbus
          # ... Modbus-Konfiguration für Haltemodus
      - case: 3 # charge
        set:
          source: modbus
          # ... Modbus-Konfiguration für Lademodus

Sequence schreiben

Das sequence Plugin führt mehrere Schreibvorgänge nacheinander aus. Alle verschachtelten Plugins erhalten denselben Eingabewert und werden in der definierten Reihenfolge ausgeführt. Bei einem Fehler stoppt die Ausführung sofort.

Parameter:

Parameter	Typ	Erfordert	Beschreibung
set	[config]	ja	Array von verschachtelten Plugin-Konfigurationen

Funktionsweise:

1. Eingabewert wird empfangen
2. Jedes Plugin in der set Liste wird nacheinander mit diesem Wert aufgerufen
3. Bei einem Fehler wird die Sequenz abgebrochen und der Fehler zurückgegeben
4. Erfolgreiche Ausführung bedeutet, dass alle Plugins erfolgreich ausgeführt wurden

Unterstützte Datentypen: int64, float64, bool

Anwendungsfälle:

• Mehrere HTTP-Aufrufe nacheinander ausführen
• Kombination mit sleep Plugin für zeitlich verzögerte Aktionen
• Mehrere Modbus-Register gleichzeitig setzen
• Propagierung von Werten an mehrere Ziele

Beispiel 1: Mehrere HTTP-Aufrufe

setmode:
  source: sequence
  set:
    - source: http
      uri: http://device.local/api/pin1
      method: POST
      body: '{"value": "on"}'
    - source: http
      uri: http://device.local/api/pin4
      method: POST
      body: '{"value": "off"}'

Beispiel 2: Kombination mit switch

batterymode:
  source: sequence
  set:
    - source: switch
      switch:
        - case: 1 # normal
          set:
            source: http
            uri: http://battery.local/api/mode
            body: "automatic"
        - case: 3 # charge
          set:
            source: sequence
            set:
              - source: sleep
                duration: 1s
              - source: http
                uri: http://battery.local/api/charge
                body: "5000" # 5 kW
    - source: mqtt
      topic: home/battery/status
      payload: "mode_${batterymode}"

Ablauf bei batterymode: 1 (normal):

1. Äußere sequence empfängt Wert 1
2. Erster Schritt: switch prüft den Wert 1
   • Fall 1 trifft zu → HTTP-Aufruf zu /api/mode mit Body automatic
3. Zweiter Schritt: mqtt sendet Nachricht zu home/battery/status mit Payload mode_1
4. Fertig

Ablauf bei batterymode: 3 (charge):

1. Äußere sequence empfängt Wert 3
2. Erster Schritt: switch prüft den Wert 3
   • Fall 3 trifft zu → Innere sequence wird ausgeführt:
     • Warte 1 Sekunde (sleep)
     • HTTP-Aufruf zu /api/charge mit Body 5000
3. Zweiter Schritt: mqtt sendet Nachricht zu home/battery/status mit Payload mode_3
4. Fertig

Der Wert fließt durch alle Plugins, wobei switch unterschiedliche Aktionen basierend auf dem Wert ausführt und mqtt am Ende immer benachrichtigt wird.

Sleep schreiben

Das sleep Plugin fügt eine Verzögerung ein. Wird typischerweise innerhalb eines sequence Plugins verwendet, um zeitliche Abstände zwischen Aktionen zu schaffen.

Parameter:

Parameter	Typ	Erfordert	Beschreibung
duration	duration	ja	Wartezeit (z. B. 1s, 500ms, 0s für keine Verzögerung)

Beispiel:

setmode:
  source: sequence
  set:
    - source: http
      uri: http://device.local/api/prepare
      method: POST
    - source: sleep
      duration: 500ms
    - source: http
      uri: http://device.local/api/activate
      method: POST

Map lesen schreiben

Das map Plugin übersetzt Integer-Werte in andere Integer-Werte mithilfe einer Lookup-Tabelle. Es wird häufig verwendet, um gerätespezifische Werte in evcc-Standardwerte zu konvertieren und umgekehrt.

Parameter:

Parameter	Typ	Erfordert	Beschreibung
values	map[int64]int64	ja	Lookup-Tabelle mit Eingabe → Ausgabe Zuordnung
get	config	nein	Plugin zum Lesen (nur beim Lesen erforderlich)
set	config	nein	Plugin zum Schreiben (nur beim Schreiben erforderlich)

Funktionsweise:

Beim Lesen:

1. get Plugin liefert einen Wert (z. B. 0)
2. Wert wird in der values Tabelle nachgeschlagen
3. Der zugeordnete Wert wird zurückgegeben (z. B. 0 → 2)

Beim Schreiben:

1. Eingabewert wird empfangen (z. B. 3)
2. Wert wird in der values Tabelle nachgeschlagen
3. Der zugeordnete Wert wird an das set Plugin übergeben (z. B. 3 → 6)

Falls kein passender Wert in der Tabelle gefunden wird, gibt es einen Fehler.

Unterstützte Datentypen: int64 (nur Integer-Werte)

Beispiel Lesen (Gerätewert → evcc):

getmode:
  source: map
  values:
    0: 2 # Gerät "Free" → evcc "normal"
    1: 1 # Gerät "Forced off" → evcc "reduced"
    2: 3 # Gerät "Recommended on" → evcc "boost"
    3: 3 # Gerät "Forced on" → evcc "boost"
  get:
    source: modbus
    uri: 192.168.1.10:502
    id: 1
    register:
      address: 55
      type: holding
      encoding: int16

Beispiel Schreiben (evcc → Gerätewert):

setmode:
  source: map
  values:
    1: 1 # evcc "reduced" → Gerät "Forced off"
    2: 0 # evcc "normal" → Gerät "Free"
    3: 3 # evcc "boost" → Gerät "Forced on"
  set:
    source: modbus
    uri: 192.168.1.10:502
    id: 1
    register:
      address: 55
      type: writeholding
      encoding: int16

Convert schreiben

Das convert Plugin konvertiert Datentypen beim Schreiben. Es wird verwendet, wenn ein Plugin einen anderen Datentyp erwartet als evcc liefert.

Parameter:

Parameter	Typ	Erfordert	Beschreibung
convert	string	ja	Konvertierungstyp
set	config	ja	Plugin zum Schreiben nach Konvertierung

Unterstützte Konvertierungen:

Konvertierung	Beschreibung
float2int	Float64 → Int64 (Nachkommastellen werden abgeschnitten)
int2float	Int64 → Float64
int2bytes	Int64 → Byte-Array (Big Endian, 8 Bytes)

Beispiel (evcc liefert float, Gerät erwartet int):

limitsoc:
  source: convert
  convert: float2int
  set:
    source: modbus
    uri: 192.168.1.10:502
    id: 1
    register:
      address: 41009
      type: writesingle
      encoding: uint16

In diesem Beispiel konvertiert evcc einen Float-Wert wie 85.5 in 85 bevor er an das Modbus-Register geschrieben wird.

Ignore schreiben

Das ignore Plugin unterdrückt spezifische Fehlermeldungen beim Schreiben. Es wird verwendet, wenn ein Gerät harmlose Fehler zurückgibt, die ignoriert werden können.

Parameter:

Parameter	Typ	Erfordert	Beschreibung
error	string	ja	Fehlertext-Präfix, der ignoriert werden soll
set	config	ja	Plugin zum Schreiben

Funktionsweise:

1. Das verschachtelte set Plugin wird ausgeführt
2. Falls ein Fehler auftritt, wird geprüft, ob die Fehlermeldung mit dem error String beginnt
3. Wenn ja, wird der Fehler ignoriert und Erfolg zurückgegeben
4. Wenn nein, wird der Fehler normal weitergegeben

Unterstützte Datentypen: int64, float64, bool, []byte

Beispiel:

batterymode:
  source: switch
  switch:
    - case: 1 # normal
      set:
        source: const
        value: 2
        set:
          source: ignore
          error: "modbus: response data size '18' does not match count '4'"
          set:
            source: modbus
            uri: 192.168.1.10:502
            id: 1
            register:
              address: 0x1110
              type: writemultiple
              encoding: int16

In diesem Beispiel gibt das Gerät einen harmlosen Modbus-Fehler zurück, der ignoriert wird.