Zum Hauptinhalt springen

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:

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

Übersicht​

evcc bietet folgende Plugins an:

  • 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.
  • 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.

Neben diesen Integrations-Plugins, gibt es noch Helfer-Plugins, die Zusatzfunktionen bereit stellt:

  • 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.

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.
  • 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.

AttributTypErfordertKontextBeschreibung
powerfloatjaalleAktuelle Leistung in W
energyfloatneinalleZählerstand in kWh
maxpowerintneinpv (hybrid)Maximale AC-Leistung in W
socintneinbatteryLadestand in %
capacityfloatneinbatteryKapazität in kWh
powers[float,float,float]neinallePhasenleistungen in W
currents[float,float,float]neinallePhasenströme in A
voltages[float,float,float]neinallePhasenspannungen in V

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:

AttributTypErfordertKontextBeschreibung
limitsocintneinbatterySetze Ladeziel für Batterie in %. Das Ladeziel wird aus den konfigurierten MinSoc, MaxSoc und dem aktuellen Ladestand (Attribut soc) berechnet.
batterymodeintneinbatterySetze Lademodus direkt (1: normal, 2: hold, 3: charge)

Charger​

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

AttributTypErfordertBeschreibung
statusstringjaStatus (A..F)
enabledbooljaIst Ladung freigegeben?
powerfloatneinLadeleistung in W
energyfloatneinZählerstand in kWh
identifystringneinAktuelle RFID-Kennung
socintneinLadestand in %
phasesintneinAnzahl der physischen Phasen (1..3)
powers[float,float,float]neinPhasenleistungen in W
currents[float,float,float]neinPhasenströme in A
voltages[float,float,float]neinPhasenspannungen in V
tempfloatneinAktuelle Temperatur in °C (Heizung)
templimitintneinTemperaturlimit in °C (Heizung)
getmodeintneinSG-Ready Modus (Wärmepumpe)

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:

AttributTypErfordertBeschreibung
enablebooljaLadung freigeben / sperren
maxcurrentintjaSetze maximalen Ladestrom in A
maxcurrentmilisfloatneinSetze maximalen Ladestrom in A
phases1p3pintneinPhasenumschaltung durchführen (erfordert tos: true)
wakeupboolneinWecke Fahrzeug auf
setmodeintneinÄndere SG-Ready Modus (1: normal, 2: boost, 3: stop)

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.

AttributTypErfordertBeschreibung
socintjaLadestand in %
limitsocintneinLadelimit in %
statusstringneinStatus (A..F)
rangeintneinReichweite in km
odometerintneinKilometerstand in km
climaterboolneinKlimatisierung aktiv?
getmaxcurrentfloatneinMaximaler Ladestrom in A
finishtimestringneinGeplantes Ladeende (RFC3339)

Beispiel

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

vehicles:
  - name: Mazda
    type: custom
    range:
      source: mqtt
      topic: mazda2mqtt/c53/chargeInfo/drivingRangeKm

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

AttributTypErfordertBeschreibung
wakeupboolneinFahrzeug aufwecken
chargeenableboolneinStarte/stoppe den Ladevorgang
maxcurrentintneinSetze 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

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.

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).

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

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) und Multiplikation (mul) 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.

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