From 1fbaf25e034e60be20b32f2b5d944c1ee5cf924a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Sun, 15 Dec 2024 11:56:35 +0100 Subject: [PATCH 01/19] Started refactoring of plugins documentation --- docs/reference/plugins.md | 196 +++++++++++++++++++++++++++++++++++--- 1 file changed, 185 insertions(+), 11 deletions(-) diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index 81132dae9f..bf746f133e 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -4,17 +4,191 @@ sidebar_position: 3 # Plugins -Plugins können verwendet werden, um verschiedene Geräte und externe Datenquellen in evcc zu integrieren. Diese können über den Wert `custom` des Parameters `type` in [`meter`](/docs/reference/configuration/meters#custom) (Strommessgeräte), [`charger`](/docs/reference/configuration/chargers#type) (Wallboxen) oder [`vehicle`](/docs/devices/vehicles#manuell) (Fahrzeuge) verwendet werden. +Plugins können verwendet werden, um verschiedene Geräte und externe Datenquellen in evcc zu integrieren für die es keine direkte Unterstützung gibt. +Sie können für die Gerätekategorien [`meter`](/docs/reference/configuration/meters#custom) (Strommessgeräte), [`charger`](/docs/reference/configuration/chargers#type) (Wallboxen) oder [`vehicle`](/docs/devices/vehicles#manuell) (Fahrzeuge) verwendet werden. +Plugins können auch für die in [Messaging](/docs/reference/configuration/messaging) beschriebenen Endpunkte für Events genutzt werden. + +Je nach Verwendung werden Plugins **lesend** oder **schreibend** eingesetzt. + +## Übersicht + +Folgende Plugins koennen verwendet werden um externe Datenquellen einzubinden: + +* [Modbus Plugin](#modbus) - Plugin zum Auslesen von einem ModBus-fähigen Gerät (lesen/schreiben). +* [MQTT Plugin](#mqtt) - Plugin um indirekt über MQTT mit den MQTT-fähigen Geräten zu kommunizieren (lesen/schreiben). +* [HTTP Plugin](#http) - Plugin das über HTTP-API mit Endgeräten spricht (lesen/schreiben). +* [Websocket Plugin](#websocket) - Plugin zum Empfangen von Gerätedaten über einen eigenen Webserver. Kann nur zum Lesen von Daten genutzt werden (lesen). +* [SMA/Speedwire Plugin](#speedwire) - Plugin speziell für SMA Geräte die mit dem Speedwire Protokoll kommunizieren koennen (lesen). +* [Javascript Plugin](#javascript) - Plugin das Werte in über ein Javascript Skript bereitstellt oder entgegennimmt (lesen/schreiben). +* [Shell Plugin](#shell) - Plugin das ein Shell Skript ausführen kann um Daten zu erxtrahieren oder schreibend entgegennimmt (lesen/schreiben). + +Neben diesen Plugins, die externe Daten integrieren, gibt es folgende Helfer-Plugins, die Daten direkt bereitstellen koennen. Diese koennen nur in einem lesenden Kontext genutzt werden: + +* [Const Plugin](#const) - Spezielles Plugin das einfach einen konstanten Wert zurückliefert. +* [Calc Plugin](#calc) - Meta-Plugin um Ausgaben von anderen Plugins arithmetisch zu verknüpfen. +* [Combined Plugin](#combined) - Meta-Plugin speziell für `charger` um die boolschen Status-Werte für den _angeschlossen_ und _charging_ Zustand, die von Plugins ausgelesen werden, zu einem einzigen Ladestatus zu kombinieren. + +### Plugin Syntax + +Jedes Plugin besitzt eine 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. +Die meisten Konfigurationsparameter sind plugin spezifisch, jedoch gibt eine handvoll Parameter die beim Lesen von einem Plugin bzw. beim Schreiben via eines Plugins generell genutzt werden können. + +Beispielsweise kann über die folgende Konfiguration ein MQTT Plugin als `meter` eingebunden werden bei dem der aktuelle Stromverbrauch über das spezifierte MQTT topic eingelesen wird: + +```yaml title="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 hat dabei immer folgende Struktur: + +```yaml +- name: + type: custom + : + source: + : ... + : ... + .... + : + .... +``` + +Dabei stehen ``für den Namen des Geräts, `` und `` für eine der unten beschriebenen Geräteattribute, `` für den Plugintyp und ``, `` für Plugin-spezifische Konfigurationen. + +#### 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](https://jqlang.github.io/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. + +Die folgende Abschnitte geben einen Überblick jeweils für die einzelnen Geräte welche Attribute mit Plugins konfiguriert werden können und welche Datentypen von dem Plugin erwartet wird. + +### Meter + +Folgende Attribute können für die Konfiguration von Strommessgeräten genutzt werden. +Dabei werden alle Werte lesend von konfigurierten Plugins übernommen. + +| Attribut | Typ | Beschreibung | +|---------------|----------------|----------------------| +| power | float | Leistung | +| energy | float | Energie | +| soc | int | Ladestand | +| limitsoc | int | Ladeziel in % | +| currents | float / array | Strom (pro Phase) | +| batterymode | | | +| voltages | | | +| powers | | | +| maxpower | | | +| capacity | | | + +**Beispiel** + +In diesem Beispiel wird die Konfiguration eines `meter`s um die gemessene Gesamtenergie über einen REST Aufruf mithilfe des HTTP-Plugins abgefragt: + + +``` yaml +// TODO ... +``` + +### Charger + +Ladergeräte haben folgende Attribute die ausgelesen werden können: + +| Attribut | Typ | Beschreibung | +|---------------|--------|----------------------| +| power | float | Leistung | +| energy | float | Energie | +| enabled | bool | Eingeschaltet? | +| status | bool | Status | +| maxcurrentmilis | | | +| soc | | | +| phases1p3p | | | +| power | | | +| currents | | | +| voltages | | | + +**Beispiel** + +Dieses Beispiel zeigt wie man mit einem Shell Skript den Ladestatus (ladend/nicht ladend) eines `charger`s abfragen kann: + +``` yaml +// TODO ... +``` + + +Neben den read-only Werten können über Plugins auch Aktionen getriggert oder Konfigurationswerte gesetzt werden: + +| Attribut | Typ | Beschreibung | +|---------------|--------|----------------------| +| enable | float | Schalte an/aus | +| maxcurrent | float | Max. Ladestrom | + +**Beispiel** + +Diese Beispiel begrenzt den maximalen Ladestrom in dem eine MQTT message gesendet wird: + +``` yaml +// TODO ... +``` + +### Vehicle + +Fahrzeuge Parameter können ebenfalls über Plugins ausgelesen werden. + +| Attribut | Typ | Beschreibung | +|---------------|----------------|----------------------| +| soc | int | Ladestand | +| status | bool / A .. F | Status | +| range | int | Reichweite | +| odometer | int | Zählerstand | +| climater | bool | Klimaanlage (?) | +| wakeup | ? | Aufweck-Ping | +| limitsoc | int | Ladeziel in % | +| maxcurrent | int | Maximaler Ladestrom | +| finishtime | | | + +Zusätzlich könen spezielle Kommandos über Plugins an das Fahrzeug geschickt werden: + +| Attribut | Typ | Beschreibung | +|---------------|----------------|----------------------| +| wakeup | ? | Aufweck-Ping | + + +Plugins können verwendet werden, um verschiedene Geräte und externe Datenquellen in evcc zu integrieren. Diese können über den Wert `custom` des Parameters `type` in verwendet werden. Plugins erlauben sowohl _Schreibenzugriff_ also auch _Lesezugriff_. Wenn das Plugin zum _Schreiben_ verwendet wird, werden die Daten in Form von `${var[:format]}` zur Verfügung gestellt. Wenn `format` nicht angegeben wird, werden die Daten im Standard `%v` [Go Format](https://golang.org/pkg/fmt/) 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](https://pkg.go.dev/text/template) verwendet werden um komplexere Datentransformationen durchzuführen. -## Modbus (lesen/schreiben) + +## 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 erlauben. + +### Modbus 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](https://github.com/volkszaehler/mbmd#supported-devices)). Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu integrieren. Für weitere Details siehe die [Modbus Dokumentation](modbus) -## MQTT (lesen/schreiben) +### MQTT Das `mqtt` Plugin erlaubt 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. Siehe [MBMD](https://github.com/volkszaehler/mbmd) 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](#http-lesenschreiben)). @@ -38,7 +212,7 @@ topic: mbmd/charger/maxcurrent payload: ${var:%d} ``` -## HTTP (lesen/schreiben) +### HTTP 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](https://jqlang.github.io/jq/manual/) zu finden. @@ -88,7 +262,7 @@ enable: uri: "http://charger/relay/0?turn={{if .enable}}on{{else}}off{{end}}" ``` -## Websocket (nur lesen) +### Websocket 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. @@ -102,7 +276,7 @@ scale: 0.001 # floating point factor applied to result, e.g. for Wh to kWh conve timeout: 30s # error if no update received in 30 seconds ``` -## SMA/Speedwire (nur lesen) +### SMA/Speedwire {#speedwire} Das `sma` Plugin bietet eine Schnittstelle zu SMA Geräten welche das Speedwire Protokoll beherrschen. @@ -122,7 +296,7 @@ Unterstützte Wert für `value` können in der Diagnoseausgabe über das Kommand Alle möglichen Werte können als Konstanten [hier](https://gitlab.com/bboehmke/sunny/-/blob/master/values.go#L24) gefunden werden (verwende den Namen der Konstante für `value`). -## Javascript (lesen/schreiben) +### Javascript evcc integriert einen Javascript Interpreter mit der [Underscore.js](https://underscorejs.org) 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: @@ -148,7 +322,7 @@ charger: console.log(maxcurrent); ``` -## Shell Script (lesen/schreiben) +### Shell Script 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. @@ -168,7 +342,7 @@ cmd: /home/user/my-script.sh ${enable:%b} # format boolean enable as 0/1 timeout: 5s ``` -## Const (nur lesen) +### Const 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. @@ -179,7 +353,7 @@ source: const value: -16247 ``` -## Calc (nur lesen) +### Calc Das `calc` Plugin erlaubt es mehrere Einzelwerte mathematisch weiterzuverarbeiten: @@ -224,7 +398,7 @@ Das `calc` Plugin ist hilfreich um z.B. Konstante Hilfswerte (z. B. für Offsets) lassen sich mit Hilfe des `const` Plugins als Operand erzeugen. ::: -## Kombinierter Status (nur lesen) +### Combined 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. From 2ff3ecd5c96c7aab4c5c17a0d305638554267616 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Sun, 15 Dec 2024 12:26:59 +0100 Subject: [PATCH 02/19] removed duplicated explanation --- docs/reference/plugins.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index bf746f133e..1b62999302 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -173,11 +173,6 @@ Zusätzlich könen spezielle Kommandos über Plugins an das Fahrzeug geschickt w | wakeup | ? | Aufweck-Ping | -Plugins können verwendet werden, um verschiedene Geräte und externe Datenquellen in evcc zu integrieren. Diese können über den Wert `custom` des Parameters `type` in verwendet werden. - -Plugins erlauben sowohl _Schreibenzugriff_ also auch _Lesezugriff_. Wenn das Plugin zum _Schreiben_ verwendet wird, werden die Daten in Form von `${var[:format]}` zur Verfügung gestellt. Wenn `format` nicht angegeben wird, werden die Daten im Standard `%v` [Go Format](https://golang.org/pkg/fmt/) 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](https://pkg.go.dev/text/template) verwendet werden um komplexere Datentransformationen durchzuführen. - - ## 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 erlauben. From 8951ccddd240a43dae0cf9fe5fbe7d3b26452183 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Sun, 15 Dec 2024 12:32:19 +0100 Subject: [PATCH 03/19] fixed links --- docs/reference/plugins.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index 1b62999302..aadeafa915 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -186,7 +186,7 @@ Für weitere Details siehe die [Modbus Dokumentation](modbus) ### MQTT Das `mqtt` Plugin erlaubt 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. -Siehe [MBMD](https://github.com/volkszaehler/mbmd) 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](#http-lesenschreiben)). +Siehe [MBMD](https://github.com/volkszaehler/mbmd) 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](#http)). **Beispiel Lesen**: @@ -317,7 +317,7 @@ charger: console.log(maxcurrent); ``` -### Shell Script +### Shell Script {#shell} 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. From fa1b18112f5e6413d5258ce3354dde1b0937cece Mon Sep 17 00:00:00 2001 From: Michael Geers Date: Sun, 15 Dec 2024 19:09:41 +0100 Subject: [PATCH 04/19] typos, wording --- docs/reference/plugins.md | 227 +++++++++++++++++++------------------- 1 file changed, 116 insertions(+), 111 deletions(-) diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index aadeafa915..01d58cf407 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -4,46 +4,46 @@ sidebar_position: 3 # Plugins -Plugins können verwendet werden, um verschiedene Geräte und externe Datenquellen in evcc zu integrieren für die es keine direkte Unterstützung gibt. +Plugins können verwendet werden, um verschiedene Geräte und externe Datenquellen in evcc zu integrieren, für die es keine direkte Unterstützung gibt. Sie können für die Gerätekategorien [`meter`](/docs/reference/configuration/meters#custom) (Strommessgeräte), [`charger`](/docs/reference/configuration/chargers#type) (Wallboxen) oder [`vehicle`](/docs/devices/vehicles#manuell) (Fahrzeuge) verwendet werden. Plugins können auch für die in [Messaging](/docs/reference/configuration/messaging) beschriebenen Endpunkte für Events genutzt werden. Je nach Verwendung werden Plugins **lesend** oder **schreibend** eingesetzt. -## Übersicht +## Übersicht -Folgende Plugins koennen verwendet werden um externe Datenquellen einzubinden: +Folgende Plugins können verwendet werden, um externe Datenquellen einzubinden: -* [Modbus Plugin](#modbus) - Plugin zum Auslesen von einem ModBus-fähigen Gerät (lesen/schreiben). -* [MQTT Plugin](#mqtt) - Plugin um indirekt über MQTT mit den MQTT-fähigen Geräten zu kommunizieren (lesen/schreiben). -* [HTTP Plugin](#http) - Plugin das über HTTP-API mit Endgeräten spricht (lesen/schreiben). -* [Websocket Plugin](#websocket) - Plugin zum Empfangen von Gerätedaten über einen eigenen Webserver. Kann nur zum Lesen von Daten genutzt werden (lesen). -* [SMA/Speedwire Plugin](#speedwire) - Plugin speziell für SMA Geräte die mit dem Speedwire Protokoll kommunizieren koennen (lesen). -* [Javascript Plugin](#javascript) - Plugin das Werte in über ein Javascript Skript bereitstellt oder entgegennimmt (lesen/schreiben). -* [Shell Plugin](#shell) - Plugin das ein Shell Skript ausführen kann um Daten zu erxtrahieren oder schreibend entgegennimmt (lesen/schreiben). +- [Modbus Plugin](#modbus) - Plugin zum Auslesen von einem Modbus-fähigen Gerät (lesen/schreiben). +- [MQTT Plugin](#mqtt) - Plugin um indirekt über MQTT mit den MQTT-fähigen Geräten zu kommunizieren (lesen/schreiben). +- [HTTP Plugin](#http) - Plugin, das über HTTP-API mit Endgeräten spricht (lesen/schreiben). +- [Websocket Plugin](#websocket) - Plugin zum Empfangen von Gerätedaten über einen eigenen Webserver. Kann nur zum Lesen von Daten genutzt werden (lesen). +- [SMA/Speedwire Plugin](#speedwire) - Plugin speziell für SMA Geräte, die mit dem Speedwire Protokoll kommunizieren können (lesen). +- [JavaScript Plugin](#javascript) - Plugin, das Werte in über ein JavaScript Skript bereitstellt oder entgegennimmt (lesen/schreiben). +- [Shell Plugin](#shell) - Plugin, das ein Shell Skript ausführen kann, um Daten zu extrahieren oder schreibend entgegennimmt (lesen/schreiben). -Neben diesen Plugins, die externe Daten integrieren, gibt es folgende Helfer-Plugins, die Daten direkt bereitstellen koennen. Diese koennen nur in einem lesenden Kontext genutzt werden: +Neben diesen Plugins, die externe Daten integrieren, gibt es folgende Helfer-Plugins, die Daten direkt bereitstellen können. Diese können nur in einem lesenden Kontext genutzt werden: -* [Const Plugin](#const) - Spezielles Plugin das einfach einen konstanten Wert zurückliefert. -* [Calc Plugin](#calc) - Meta-Plugin um Ausgaben von anderen Plugins arithmetisch zu verknüpfen. -* [Combined Plugin](#combined) - Meta-Plugin speziell für `charger` um die boolschen Status-Werte für den _angeschlossen_ und _charging_ Zustand, die von Plugins ausgelesen werden, zu einem einzigen Ladestatus zu kombinieren. +- [Const Plugin](#const) - Spezielles Plugin das einfach einen konstanten Wert zurückliefert. +- [Calc Plugin](#calc) - Meta-Plugin um Ausgaben von anderen Plugins arithmetisch zu verknüpfen. +- [Combined Plugin](#combined) - Meta-Plugin speziell für `charger` um die booleschen Status-Werte für den _angeschlossen_ und _charging_ Zustand, die von Plugins ausgelesen werden, zu einem einzigen Ladestatus zu kombinieren. ### Plugin Syntax -Jedes Plugin besitzt eine 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. -Die meisten Konfigurationsparameter sind plugin spezifisch, jedoch gibt eine handvoll Parameter die beim Lesen von einem Plugin bzw. beim Schreiben via eines Plugins generell genutzt werden können. +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. +Die meisten Konfigurationsparameter sind Plugin spezifisch, jedoch gibt es eine handvoll Parameter, die beim Lesen von einem Plugin bzw. beim Schreiben via eines Plugins generell genutzt werden können. -Beispielsweise kann über die folgende Konfiguration ein MQTT Plugin als `meter` eingebunden werden bei dem der aktuelle Stromverbrauch über das spezifierte MQTT topic eingelesen wird: +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: ```yaml title="Beispiel: MQTT Plugin für die Leistungswerte eines Strommessgeräts" meters: -- name: imsys - type: custom - power: - source: mqtt - topic: "home/current/imsys/chn2/raw" + - name: imsys + type: custom + power: + source: mqtt + topic: "home/current/imsys/chn2/raw" ``` Das Schema hat dabei immer folgende Struktur: @@ -56,137 +56,139 @@ Das Schema hat dabei immer folgende Struktur: : ... : ... .... - : + : .... ``` -Dabei stehen ``für den Namen des Geräts, `` und `` für eine der unten beschriebenen Geräteattribute, `` für den Plugintyp und ``, `` für Plugin-spezifische Konfigurationen. +Dabei stehen ``für den Namen des Geräts, `` und `` für eine der unten beschriebenen Geräteattribute, `` für den Plugin-Typ und ``, `` für Plugin-spezifische Konfigurationen. #### Lesen -Beim Lesen von Daten mithilfe eines Plugins können sogenannte _Pipelines_ verwendet werden. +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](https://jqlang.github.io/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. +- `regex`: Ein regulärer Ausdruck, um Werte aus dem empfangenen Text zu extrahieren. +- `jq`: Ein [jq](https://jqlang.github.io/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. +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. -Die folgende Abschnitte geben einen Überblick jeweils für die einzelnen Geräte welche Attribute mit Plugins konfiguriert werden können und welche Datentypen von dem Plugin erwartet wird. +Die folgenden Abschnitte geben einen Überblick für die einzelnen Geräte. +Dabei werden die per Plugin konfigurierbaren Attribute und deren Datentypen aufgeführt. ### Meter -Folgende Attribute können für die Konfiguration von Strommessgeräten genutzt werden. -Dabei werden alle Werte lesend von konfigurierten Plugins übernommen. - -| Attribut | Typ | Beschreibung | -|---------------|----------------|----------------------| -| power | float | Leistung | -| energy | float | Energie | -| soc | int | Ladestand | -| limitsoc | int | Ladeziel in % | -| currents | float / array | Strom (pro Phase) | -| batterymode | | | -| voltages | | | -| powers | | | -| maxpower | | | -| capacity | | | +Folgende Attribute können für die Konfiguration von Strommessgeräten genutzt werden. +Dabei werden alle Werte lesend von konfigurierten Plugins übernommen. + +| Attribut | Typ | Beschreibung | +| ----------- | ------------- | ----------------- | +| power | float | Leistung | +| energy | float | Energie | +| soc | int | Ladestand | +| limitsoc | int | Ladeziel in % | +| currents | float / array | Strom (pro Phase) | +| batterymode | | | +| voltages | | | +| powers | | | +| maxpower | | | +| capacity | | | **Beispiel** In diesem Beispiel wird die Konfiguration eines `meter`s um die gemessene Gesamtenergie über einen REST Aufruf mithilfe des HTTP-Plugins abgefragt: - -``` yaml +```yaml // TODO ... ``` ### Charger -Ladergeräte haben folgende Attribute die ausgelesen werden können: +Wallboxen und Ladegeräte haben folgende Attribute die ausgelesen werden können: + +| Attribut | Typ | Beschreibung | +| --------------- | ----- | -------------- | +| power | float | Leistung | +| energy | float | Energie | +| enabled | bool | Eingeschaltet? | +| status | bool | Status | +| maxcurrentmilis | | | +| soc | | | +| phases1p3p | | | +| power | | | +| currents | | | +| voltages | | | -| Attribut | Typ | Beschreibung | -|---------------|--------|----------------------| -| power | float | Leistung | -| energy | float | Energie | -| enabled | bool | Eingeschaltet? | -| status | bool | Status | -| maxcurrentmilis | | | -| soc | | | -| phases1p3p | | | -| power | | | -| currents | | | -| voltages | | | - -**Beispiel** +**Beispiel** -Dieses Beispiel zeigt wie man mit einem Shell Skript den Ladestatus (ladend/nicht ladend) eines `charger`s abfragen kann: +Dieses Beispiel zeigt, wie man mit einem Shell Skript den Ladestatus (ladend/nicht ladend) eines `charger`s abfragen kann: -``` yaml +```yaml // TODO ... ``` +Neben den read-only Werten können über Plugins auch Aktionen getriggert oder Konfigurationswerte gesetzt werden: -Neben den read-only Werten können über Plugins auch Aktionen getriggert oder Konfigurationswerte gesetzt werden: - -| Attribut | Typ | Beschreibung | -|---------------|--------|----------------------| -| enable | float | Schalte an/aus | -| maxcurrent | float | Max. Ladestrom | +| Attribut | Typ | Beschreibung | +| ---------- | ----- | -------------- | +| enable | float | Schalte an/aus | +| maxcurrent | float | Max. Ladestrom | **Beispiel** -Diese Beispiel begrenzt den maximalen Ladestrom in dem eine MQTT message gesendet wird: +Dieses Beispiel begrenzt den maximalen Ladestrom in dem eine MQTT Nachricht gesendet wird: -``` yaml +```yaml // TODO ... ``` ### Vehicle -Fahrzeuge Parameter können ebenfalls über Plugins ausgelesen werden. - -| Attribut | Typ | Beschreibung | -|---------------|----------------|----------------------| -| soc | int | Ladestand | -| status | bool / A .. F | Status | -| range | int | Reichweite | -| odometer | int | Zählerstand | -| climater | bool | Klimaanlage (?) | -| wakeup | ? | Aufweck-Ping | -| limitsoc | int | Ladeziel in % | -| maxcurrent | int | Maximaler Ladestrom | -| finishtime | | | +Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden. -Zusätzlich könen spezielle Kommandos über Plugins an das Fahrzeug geschickt werden: +| Attribut | Typ | Beschreibung | +| ---------- | ------------- | ------------------- | +| soc | int | Ladestand | +| status | bool / A .. F | Status | +| range | int | Reichweite | +| odometer | int | Zählerstand | +| climater | bool | Klimaanlage (?) | +| wakeup | ? | Aufweck-Ping | +| limitsoc | int | Ladeziel in % | +| maxcurrent | int | Maximaler Ladestrom | +| finishtime | | | -| Attribut | Typ | Beschreibung | -|---------------|----------------|----------------------| -| wakeup | ? | Aufweck-Ping | +Zusätzlich können spezielle Kommandos über Plugins an das Fahrzeug geschickt werden: +| Attribut | Typ | Beschreibung | +| -------- | --- | ------------ | +| wakeup | ? | Aufweck-Ping | ## 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 erlauben. +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 -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](https://github.com/volkszaehler/mbmd#supported-devices)). Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu integrieren. +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](https://github.com/volkszaehler/mbmd#supported-devices)). +Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu integrieren. -Für weitere Details siehe die [Modbus Dokumentation](modbus) +Schaue in die [Modbus Dokumentation](modbus) für weitere Details. ### MQTT -Das `mqtt` Plugin erlaubt 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. -Siehe [MBMD](https://github.com/volkszaehler/mbmd) 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](#http)). +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](https://github.com/volkszaehler/mbmd) 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](#http)). **Beispiel Lesen**: @@ -209,12 +211,13 @@ payload: ${var:%d} ### HTTP -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](https://jqlang.github.io/jq/manual/) zu finden. +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](https://jqlang.github.io/jq/manual/) zu finden. Methoden der Authentifizierung sind `basic`, `bearer` und `digest`. Die Namen der jeweiligen Parameter finden sich [hier](https://github.com/evcc-io/evcc/blob/master/provider/http.go#L140). :::important Wichtig -XML-Dokumente werden intern automatisch in JSON-Form überführt, welche dann mit jq wie eine native JSON-Antwort weiter gefiltert werden kann. Attribute bekommen das prefix `attr`. +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`. ::: :::tip @@ -259,7 +262,7 @@ enable: ### Websocket -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. +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**: @@ -273,7 +276,7 @@ timeout: 30s # error if no update received in 30 seconds ### SMA/Speedwire {#speedwire} -Das `sma` Plugin bietet eine Schnittstelle zu SMA Geräten welche das Speedwire Protokoll beherrschen. +Das `sma` Plugin bietet eine Schnittstelle zu SMA Geräten, welche das Speedwire Protokoll beherrschen. **Beispiel Lesen**: @@ -287,13 +290,13 @@ interface: eth0 # optional scale: 1 # optional scale factor for value ``` -Unterstützte Wert für `value` können in der Diagnoseausgabe über das Kommando `evcc meter` (mit konfigurierten SMA `meter` Geräten) gefunden werden. +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](https://gitlab.com/bboehmke/sunny/-/blob/master/values.go#L24) gefunden werden (verwende den Namen der Konstante für `value`). -### Javascript +### JavaScript -evcc integriert einen Javascript Interpreter mit der [Underscore.js](https://underscorejs.org) 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: +evcc integriert einen JavaScript Interpreter mit der [Underscore.js](https://underscorejs.org) 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**: @@ -304,7 +307,7 @@ script: | 2 * res; // returns 1000 ``` -Wenn das `js` Plugin zum schreiben verwendet wird, wird der zu schreibende Wert dem Script als Variable übergeben: +Wenn das `js` Plugin zum Schreiben verwendet wird, wird der zu schreibende Wert dem Script als Variable übergeben: **Beispiel Schreiben**: @@ -339,7 +342,8 @@ timeout: 5s ### Const -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. +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**: @@ -374,9 +378,9 @@ mul: ... ``` -Als Operanden werden dabei die Grundrechenarten Addition (add) und Multiplikation (mul) unterstützt. +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 `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. @@ -390,12 +394,13 @@ Das `calc` Plugin ist hilfreich um z.B. - Bekannte Offsets zu eliminieren (addieren mit `const` Plugin) :::tip -Konstante Hilfswerte (z. B. für Offsets) lassen sich mit Hilfe des `const` Plugins als Operand erzeugen. +Konstante Hilfswerte (z. B. für Offsets) lassen sich mithilfe des `const` Plugins als Operand erzeugen. ::: ### Combined -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. +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**: From ef018bf0f4af9eb1f314527b7406fa0ae083c7fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Mon, 16 Dec 2024 08:32:25 +0100 Subject: [PATCH 05/19] wording --- docs/reference/plugins.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index 01d58cf407..45b4bafbe2 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -6,7 +6,7 @@ sidebar_position: 3 Plugins können verwendet werden, um verschiedene Geräte und externe Datenquellen in evcc zu integrieren, für die es keine direkte Unterstützung gibt. Sie können für die Gerätekategorien [`meter`](/docs/reference/configuration/meters#custom) (Strommessgeräte), [`charger`](/docs/reference/configuration/chargers#type) (Wallboxen) oder [`vehicle`](/docs/devices/vehicles#manuell) (Fahrzeuge) verwendet werden. -Plugins können auch für die in [Messaging](/docs/reference/configuration/messaging) beschriebenen Endpunkte für Events genutzt werden. +Plugins können auch für die in [Messaging](/docs/reference/configuration/messaging) beschriebenen Endpunkte zum Versenden von Lifecycle-Events genutzt werden. Je nach Verwendung werden Plugins **lesend** oder **schreibend** eingesetzt. @@ -26,9 +26,9 @@ Neben diesen Plugins, die externe Daten integrieren, gibt es folgende Helfer-Plu - [Const Plugin](#const) - Spezielles Plugin das einfach einen konstanten Wert zurückliefert. - [Calc Plugin](#calc) - Meta-Plugin um Ausgaben von anderen Plugins arithmetisch zu verknüpfen. -- [Combined Plugin](#combined) - Meta-Plugin speziell für `charger` um die booleschen Status-Werte für den _angeschlossen_ und _charging_ Zustand, die von Plugins ausgelesen werden, zu einem einzigen Ladestatus zu kombinieren. +- [Combined Plugin](#combined) - 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. -### Plugin Syntax +### Syntax Jedes Plugin besitzt ein individuelles Konfigurationsschema. Dabei ist es wichtig zu wissen, ob das Plugin in einem **lesenden** oder **schreibenden** Kontext verwendet wird. @@ -80,8 +80,7 @@ Wenn Format nicht angegeben wird, werden die Daten im Standard %v Go-Format bere 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. -Die folgenden Abschnitte geben einen Überblick für die einzelnen Geräte. -Dabei werden die per Plugin konfigurierbaren Attribute und deren Datentypen aufgeführt. +Je nach Gerät ([`meter`](#meter), [`charger`](#charger) oder [`vehicle`](#vehicle)) können andere Attribute mit Plugins gelesen oder gesetzt werden. ### Meter From 151a9e93221aa185320da142e406eb67a3a5bc1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Mon, 16 Dec 2024 20:25:16 +0100 Subject: [PATCH 06/19] added labels for read and write --- docs/reference/plugins.md | 39 +++++++++++++++++++++------------------ src/components/Tag.js | 26 ++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 18 deletions(-) create mode 100644 src/components/Tag.js diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index 45b4bafbe2..d5e0e44029 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -1,6 +1,7 @@ --- sidebar_position: 3 --- +import Tag from '@site/src/components/Tag'; # Plugins @@ -14,13 +15,13 @@ Je nach Verwendung werden Plugins **lesend** oder **schreibend** eingesetzt. Folgende Plugins können verwendet werden, um externe Datenquellen einzubinden: -- [Modbus Plugin](#modbus) - Plugin zum Auslesen von einem Modbus-fähigen Gerät (lesen/schreiben). -- [MQTT Plugin](#mqtt) - Plugin um indirekt über MQTT mit den MQTT-fähigen Geräten zu kommunizieren (lesen/schreiben). -- [HTTP Plugin](#http) - Plugin, das über HTTP-API mit Endgeräten spricht (lesen/schreiben). -- [Websocket Plugin](#websocket) - Plugin zum Empfangen von Gerätedaten über einen eigenen Webserver. Kann nur zum Lesen von Daten genutzt werden (lesen). -- [SMA/Speedwire Plugin](#speedwire) - Plugin speziell für SMA Geräte, die mit dem Speedwire Protokoll kommunizieren können (lesen). -- [JavaScript Plugin](#javascript) - Plugin, das Werte in über ein JavaScript Skript bereitstellt oder entgegennimmt (lesen/schreiben). -- [Shell Plugin](#shell) - Plugin, das ein Shell Skript ausführen kann, um Daten zu extrahieren oder schreibend entgegennimmt (lesen/schreiben). +- [Modbus Plugin](#modbus) - Plugin zum Auslesen von einem Modbus-fähigen Gerät. +- [MQTT Plugin](#mqtt) - Plugin um indirekt über MQTT mit den MQTT-fähigen Geräten zu kommunizieren. +- [HTTP Plugin](#http) - Plugin, das über HTTP-API mit Endgeräten spricht. +- [Websocket Plugin](#websocket) - Plugin zum Empfangen von Gerätedaten über einen eigenen Webserver. Kann nur zum Lesen von Daten genutzt werden. +- [SMA/Speedwire Plugin](#speedwire) - Plugin speziell für SMA Geräte, die mit dem Speedwire Protokoll kommunizieren können. +- [JavaScript Plugin](#javascript) - Plugin, das Werte in über ein JavaScript Skript bereitstellt oder entgegennimmt. +- [Shell Plugin](#shell) - Plugin, das ein Shell Skript ausführen kann, um Daten zu extrahieren oder schreibend entgegennimmt. Neben diesen Plugins, die externe Daten integrieren, gibt es folgende Helfer-Plugins, die Daten direkt bereitstellen können. Diese können nur in einem lesenden Kontext genutzt werden: @@ -80,7 +81,7 @@ Wenn Format nicht angegeben wird, werden die Daten im Standard %v Go-Format bere 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`](#meter), [`charger`](#charger) oder [`vehicle`](#vehicle)) können andere Attribute mit Plugins gelesen oder gesetzt werden. +Je nach Gerät ([`meter`](#meter), [`charger`](#charger) oder [`vehicle`](#vehicle)) können andere Attribute mit Plugins gelesen oder gesetzt werden. ### Meter @@ -174,7 +175,8 @@ Zusätzlich können spezielle Kommandos über Plugins an das Fahrzeug geschickt 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 +### Modbus + 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](https://github.com/volkszaehler/mbmd#supported-devices)). @@ -182,7 +184,7 @@ Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu i Schaue in die [Modbus Dokumentation](modbus) für weitere Details. -### MQTT +### MQTT 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. @@ -208,7 +210,7 @@ topic: mbmd/charger/maxcurrent payload: ${var:%d} ``` -### HTTP +### HTTP 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](https://jqlang.github.io/jq/manual/) zu finden. @@ -259,7 +261,7 @@ enable: uri: "http://charger/relay/0?turn={{if .enable}}on{{else}}off{{end}}" ``` -### Websocket +### Websocket 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. @@ -273,7 +275,8 @@ scale: 0.001 # floating point factor applied to result, e.g. for Wh to kWh conve timeout: 30s # error if no update received in 30 seconds ``` -### SMA/Speedwire {#speedwire} +### SMA/Speedwire {#speedwire} + Das `sma` Plugin bietet eine Schnittstelle zu SMA Geräten, welche das Speedwire Protokoll beherrschen. @@ -293,7 +296,7 @@ Unterstützte Werte für `value` können in der Diagnoseausgabe über das Komman Alle möglichen Werte können als Konstanten [hier](https://gitlab.com/bboehmke/sunny/-/blob/master/values.go#L24) gefunden werden (verwende den Namen der Konstante für `value`). -### JavaScript +### JavaScript evcc integriert einen JavaScript Interpreter mit der [Underscore.js](https://underscorejs.org) 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: @@ -319,7 +322,7 @@ charger: console.log(maxcurrent); ``` -### Shell Script {#shell} +### Shell Script {#shell} 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. @@ -339,7 +342,7 @@ cmd: /home/user/my-script.sh ${enable:%b} # format boolean enable as 0/1 timeout: 5s ``` -### Const +### Const 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. @@ -351,7 +354,7 @@ source: const value: -16247 ``` -### Calc +### Calc Das `calc` Plugin erlaubt es mehrere Einzelwerte mathematisch weiterzuverarbeiten: @@ -396,7 +399,7 @@ Das `calc` Plugin ist hilfreich um z.B. Konstante Hilfswerte (z. B. für Offsets) lassen sich mithilfe des `const` Plugins als Operand erzeugen. ::: -### Combined +### Combined 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. diff --git a/src/components/Tag.js b/src/components/Tag.js new file mode 100644 index 0000000000..c682888e84 --- /dev/null +++ b/src/components/Tag.js @@ -0,0 +1,26 @@ +import React from 'react'; + +// Predefined color mappings +const colorMap = { + "read": { bgColor: "#2196f3", textColor: "#ffffff" }, + "write": { bgColor: "#ff9800", textColor: "#ffffff" }, + "default": { bgColor: "#4ea72a", textColor: "#ffffff" } +}; + +export default function Tag({ label, category }) { + const { bgColor, textColor } = colorMap[category] || colorMap["default"]; + + const style = { + backgroundColor: bgColor, + color: textColor, + padding: '0px 10px', + borderRadius: '10px', + display: 'inline-block', + marginLeft: '2px', + verticalAlign: 'middle', + fontSize: '0.75rem', + fontWeight: 'bold', + }; + + return {label}; +} From 17120535bbeda7f89df9e35cc9d857cf5649495b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Mon, 16 Dec 2024 20:30:14 +0100 Subject: [PATCH 07/19] fixed linking --- docs/reference/plugins.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index d5e0e44029..6d8d3decb8 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -175,7 +175,7 @@ Zusätzlich können spezielle Kommandos über Plugins an das Fahrzeug geschickt 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 +### Modbus {#modbus} Das `modbus` Plugin kann Daten von jedem Modbus-fähigen Gerät oder SunSpec-kompatiblen Wechselrichter lesen. @@ -184,7 +184,7 @@ Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu i Schaue in die [Modbus Dokumentation](modbus) für weitere Details. -### MQTT +### MQTT {#mqtt} 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. @@ -210,7 +210,7 @@ topic: mbmd/charger/maxcurrent payload: ${var:%d} ``` -### HTTP +### HTTP {#http} 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](https://jqlang.github.io/jq/manual/) zu finden. @@ -261,7 +261,7 @@ enable: uri: "http://charger/relay/0?turn={{if .enable}}on{{else}}off{{end}}" ``` -### Websocket +### Websocket {#websocket} 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. @@ -296,7 +296,7 @@ Unterstützte Werte für `value` können in der Diagnoseausgabe über das Komman Alle möglichen Werte können als Konstanten [hier](https://gitlab.com/bboehmke/sunny/-/blob/master/values.go#L24) gefunden werden (verwende den Namen der Konstante für `value`). -### JavaScript +### JavaScript {#javascript} evcc integriert einen JavaScript Interpreter mit der [Underscore.js](https://underscorejs.org) 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: @@ -342,7 +342,7 @@ cmd: /home/user/my-script.sh ${enable:%b} # format boolean enable as 0/1 timeout: 5s ``` -### Const +### Const {#const} 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. @@ -354,7 +354,7 @@ source: const value: -16247 ``` -### Calc +### Calc {#calc} Das `calc` Plugin erlaubt es mehrere Einzelwerte mathematisch weiterzuverarbeiten: @@ -399,7 +399,7 @@ Das `calc` Plugin ist hilfreich um z.B. Konstante Hilfswerte (z. B. für Offsets) lassen sich mithilfe des `const` Plugins als Operand erzeugen. ::: -### Combined +### Combined {#combined} 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. From 6cb905898db69e1486864fa953b9d4b53092bb9e Mon Sep 17 00:00:00 2001 From: Michael Geers Date: Mon, 16 Dec 2024 21:02:24 +0100 Subject: [PATCH 08/19] tag styles --- docs/reference/plugins.md | 23 +++++++++++------------ src/components/Tag.js | 26 -------------------------- src/components/Tag.jsx | 5 +++++ src/css/custom.css | 21 +++++++++++++++++++++ 4 files changed, 37 insertions(+), 38 deletions(-) delete mode 100644 src/components/Tag.js create mode 100644 src/components/Tag.jsx diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index 6d8d3decb8..2c99ced01d 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -1,6 +1,7 @@ --- sidebar_position: 3 --- + import Tag from '@site/src/components/Tag'; # Plugins @@ -175,8 +176,7 @@ Zusätzlich können spezielle Kommandos über Plugins an das Fahrzeug geschickt 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 {#modbus} - +### Modbus {#modbus} 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](https://github.com/volkszaehler/mbmd#supported-devices)). @@ -184,7 +184,7 @@ Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu i Schaue in die [Modbus Dokumentation](modbus) für weitere Details. -### MQTT {#mqtt} +### MQTT {#mqtt} 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. @@ -210,7 +210,7 @@ topic: mbmd/charger/maxcurrent payload: ${var:%d} ``` -### HTTP {#http} +### HTTP {#http} 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](https://jqlang.github.io/jq/manual/) zu finden. @@ -261,7 +261,7 @@ enable: uri: "http://charger/relay/0?turn={{if .enable}}on{{else}}off{{end}}" ``` -### Websocket {#websocket} +### Websocket {#websocket} 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. @@ -275,8 +275,7 @@ scale: 0.001 # floating point factor applied to result, e.g. for Wh to kWh conve timeout: 30s # error if no update received in 30 seconds ``` -### SMA/Speedwire {#speedwire} - +### SMA/Speedwire {#speedwire} Das `sma` Plugin bietet eine Schnittstelle zu SMA Geräten, welche das Speedwire Protokoll beherrschen. @@ -296,7 +295,7 @@ Unterstützte Werte für `value` können in der Diagnoseausgabe über das Komman Alle möglichen Werte können als Konstanten [hier](https://gitlab.com/bboehmke/sunny/-/blob/master/values.go#L24) gefunden werden (verwende den Namen der Konstante für `value`). -### JavaScript {#javascript} +### JavaScript {#javascript} evcc integriert einen JavaScript Interpreter mit der [Underscore.js](https://underscorejs.org) 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: @@ -322,7 +321,7 @@ charger: console.log(maxcurrent); ``` -### Shell Script {#shell} +### Shell Script {#shell} 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. @@ -342,7 +341,7 @@ cmd: /home/user/my-script.sh ${enable:%b} # format boolean enable as 0/1 timeout: 5s ``` -### Const {#const} +### Const {#const} 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. @@ -354,7 +353,7 @@ source: const value: -16247 ``` -### Calc {#calc} +### Calc {#calc} Das `calc` Plugin erlaubt es mehrere Einzelwerte mathematisch weiterzuverarbeiten: @@ -399,7 +398,7 @@ Das `calc` Plugin ist hilfreich um z.B. Konstante Hilfswerte (z. B. für Offsets) lassen sich mithilfe des `const` Plugins als Operand erzeugen. ::: -### Combined {#combined} +### Combined {#combined} 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. diff --git a/src/components/Tag.js b/src/components/Tag.js deleted file mode 100644 index c682888e84..0000000000 --- a/src/components/Tag.js +++ /dev/null @@ -1,26 +0,0 @@ -import React from 'react'; - -// Predefined color mappings -const colorMap = { - "read": { bgColor: "#2196f3", textColor: "#ffffff" }, - "write": { bgColor: "#ff9800", textColor: "#ffffff" }, - "default": { bgColor: "#4ea72a", textColor: "#ffffff" } -}; - -export default function Tag({ label, category }) { - const { bgColor, textColor } = colorMap[category] || colorMap["default"]; - - const style = { - backgroundColor: bgColor, - color: textColor, - padding: '0px 10px', - borderRadius: '10px', - display: 'inline-block', - marginLeft: '2px', - verticalAlign: 'middle', - fontSize: '0.75rem', - fontWeight: 'bold', - }; - - return {label}; -} diff --git a/src/components/Tag.jsx b/src/components/Tag.jsx new file mode 100644 index 0000000000..5b34068fbb --- /dev/null +++ b/src/components/Tag.jsx @@ -0,0 +1,5 @@ +import React from "react"; + +export default function Tag({ label, category }) { + return {label}; +} diff --git a/src/css/custom.css b/src/css/custom.css index 53f7645a44..a7cc7438a9 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -122,3 +122,24 @@ article.margin-bottom--xl footer .text--right a { text-decoration: underline; font-size: 1.1rem; } + +.tag { + font-size: 0.75rem; + border: 0.1rem solid rgba(0, 0, 0, 0.1); + font-weight: bold; + padding: 0.2em 0.8em; + border-radius: 10px; + display: inline-block; + margin-left: 0.5rem; + vertical-align: middle; +} + +.tag--read { + background-color: rgba(84, 199, 236, 0.15); + color: var(--ifm-color-info-contrast-foreground); +} + +.tag--write { + background-color: rgba(255, 186, 0, 0.15); + color: var(--ifm-color-warning-contrast-foreground); +} From 22dee97af4ffb7dcd2c3c0c0851c79bc27c28cab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Mon, 16 Dec 2024 21:50:37 +0100 Subject: [PATCH 09/19] added some (fictional) examples --- docs/reference/plugins.md | 66 ++++++++++++++++++++++++++++++++++----- 1 file changed, 59 insertions(+), 7 deletions(-) diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index 2c99ced01d..f79124cc67 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -62,7 +62,7 @@ Das Schema hat dabei immer folgende Struktur: .... ``` -Dabei stehen ``für den Namen des Geräts, `` und `` für eine der unten beschriebenen Geräteattribute, `` für den Plugin-Typ und ``, `` für Plugin-spezifische Konfigurationen. +Dabei stehen `` für den Namen des Geräts, `` und `` für eine der unten beschriebenen Geräteattribute, `` für den Plugin-Typ und ``, `` für Plugin-spezifische Konfigurationen. #### Lesen @@ -104,10 +104,16 @@ Dabei werden alle Werte lesend von konfigurierten Plugins übernommen. **Beispiel** -In diesem Beispiel wird die Konfiguration eines `meter`s um die gemessene Gesamtenergie über einen REST Aufruf mithilfe des HTTP-Plugins abgefragt: +In diesem Beispiel wird die Konfiguration eines `meter`s um die aktuelle elektrische Leistung über einen HTTP Aufruf abgefragt: ```yaml -// TODO ... +meters: + - name: volkszaehler + type: custom + power: + source: http + uri: http://zaehler.network.local:8080/api/data.json?from=now + jq: .data.tuples[0][1] ``` ### Charger @@ -129,10 +135,21 @@ Wallboxen und Ladegeräte haben folgende Attribute die ausgelesen werden können **Beispiel** -Dieses Beispiel zeigt, wie man mit einem Shell Skript den Ladestatus (ladend/nicht ladend) eines `charger`s abfragen kann: +Dieses Beispiel zeigt, wie man über das Modbus Plugin den Ladestatus (ladend/nicht ladend) eines `charger`s abfragen kann: ```yaml -// TODO ... +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: @@ -144,10 +161,17 @@ Neben den read-only Werten können über Plugins auch Aktionen getriggert oder K **Beispiel** -Dieses Beispiel begrenzt den maximalen Ladestrom in dem eine MQTT Nachricht gesendet wird: +Dieses Beispiel schaltet eine Tasmota Steckdose über eine MQTT Nachricht gesendet an: ```yaml -// TODO ... +chargers: + - name: unu-charger + type: custom + enable: + source: mqtt + broker: mosquitto.local:883 + topic: cmd/unu-switch/Power + payload: ON ``` ### Vehicle @@ -166,11 +190,39 @@ Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden. | maxcurrent | int | Maximaler Ladestrom | | finishtime | | | +**Beispiel** + +Im folgenden Beispiel wie die aktuelle Reichweite des Fahrzeugs aus MQTT Nachrichten gelesen: + +``` yaml +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: | Attribut | Typ | Beschreibung | | -------- | --- | ------------ | | wakeup | ? | Aufweck-Ping | +| chargeEnable | ? | Start/Stop des Ladevorgangs über das Vehicle | +| maxCurrent | ? | Begrenze maximalen Ladestrom | + +**Beispiel** + +Um ein Auto über einen HTTP Ping aufzuwecken um weiter Abfragen zu senden, kann wie im folgenden Beispiel das HTTP Plugin genutzt werden: + +``` yaml +vehicles: + - name: model-y + type: custom + wakeup: + source: http + uri: http://teslalogger.local:5000/command/08154711/wake_up +``` ## Plugins From 9f27e84ec53f1ec7151e0bbc9b528c79d2c22aa2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Wed, 18 Dec 2024 19:41:35 +0100 Subject: [PATCH 10/19] worked on a bit on meters --- .gitignore | 6 ++++++ docs/reference/plugins.md | 28 +++++++++++++++++----------- docusaurus.config.js | 3 +++ 3 files changed, 26 insertions(+), 11 deletions(-) diff --git a/.gitignore b/.gitignore index b2d6de3062..343cd74306 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,9 @@ npm-debug.log* yarn-debug.log* yarn-error.log* + +# Emacs backup file +*~ + +# IDEs +/.idea \ No newline at end of file diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index f79124cc67..7237393922 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -50,10 +50,10 @@ meters: Das Schema hat dabei immer folgende Struktur: -```yaml +```yaml {3,5-6,8} - name: type: custom - : + : source: : ... : ... @@ -62,7 +62,7 @@ Das Schema hat dabei immer folgende Struktur: .... ``` -Dabei stehen `` für den Namen des Geräts, `` und `` für eine der unten beschriebenen Geräteattribute, `` für den Plugin-Typ und ``, `` für Plugin-spezifische Konfigurationen. +Dabei stehen `` für den Namen des Geräts, `` und `` für eine der unten beschriebenen Geräte-spezifischen Attribute, `` für den Plugin-Typ und ``, `` für Plugin-spezifische Konfigurationen. #### Lesen @@ -88,15 +88,16 @@ Je nach Gerät ([`meter`](#meter), [`charger`](#charger) oder [`vehicle`](#vehic Folgende Attribute können für die Konfiguration von Strommessgeräten genutzt werden. Dabei werden alle Werte lesend von konfigurierten Plugins übernommen. - -| Attribut | Typ | Beschreibung | -| ----------- | ------------- | ----------------- | -| power | float | Leistung | -| energy | float | Energie | -| soc | int | Ladestand | -| limitsoc | int | Ladeziel in % | +Bei der Verwendung der Plugins ist es wichtig, dass diese den richtigen Datentyp zurückliefern. +Um zu dem verlangten Datentypen zu konvertieren können die in [Lesen](#lesen) beschriebenen Pipelines genutzt werde. + +| Attribut | Typ | Beschreibung | Einheit | +| ----------- | ------------- | ----------------- | ------- | +| power | float | Aktuelle elektrische Leistung | W | +| energy | float | Total gemessene Energie | Wh | +| soc | int | Batterie Ladestand | +| batterymode | int | | 0,1,2,3 | | currents | float / array | Strom (pro Phase) | -| batterymode | | | | voltages | | | | powers | | | | maxpower | | | @@ -116,6 +117,11 @@ meters: jq: .data.tuples[0][1] ``` + +| Attribut | Typ | Beschreibung | Einheit | +| ---------- | ----- | -------------- | ------- | +| limitsoc | int | Ladeziel für Batterie | 0 ... 100 %| + ### Charger Wallboxen und Ladegeräte haben folgende Attribute die ausgelesen werden können: diff --git a/docusaurus.config.js b/docusaurus.config.js index d98147d048..92c7f1e0bc 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -149,6 +149,9 @@ import { themes as prismThemes } from "prism-react-renderer"; prism: { theme: prismThemes.github, darkTheme: prismThemes.oceanicNext, + plugins: [ + 'line-highlight', + ], }, algolia: { appId: "4D0L431W8V", From 5bab8a32b34ce7d9fabd749bbb2138f73253ec78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Sat, 18 Jan 2025 16:30:56 +0100 Subject: [PATCH 11/19] worked on --- docs/reference/plugins.md | 49 +++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 17 deletions(-) diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index 7237393922..007056348d 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -86,26 +86,33 @@ Je nach Gerät ([`meter`](#meter), [`charger`](#charger) oder [`vehicle`](#vehic ### Meter -Folgende Attribute können für die Konfiguration von Strommessgeräten genutzt werden. -Dabei werden alle Werte lesend von konfigurierten Plugins übernommen. -Bei der Verwendung der Plugins ist es wichtig, dass diese den richtigen Datentyp zurückliefern. +Alle `meter` haben gemeinsam, dass sie Stromzähler sind, die den aktuellen Verbrauch messen. +Wie an [anderer Stelle](/devices/meters) beschrieben, können Zähler in verschiedenen Kontexten innerhalb der `site` Konfiguration verwendet werden: Als Netzzähler (`grid`), Zähler für die PV Produktion (`pv`), Hausbatteriezähler (`battery`). Zähler für die Ladeleistung der Wallbox (`charge`) oder Verbrauchszähler für intelligente Verbraucher (`aux`). + +`power` ist das einzige erforderliche Attribut, alle weiteren Attribute sind optional. +Nicht alle Metertypen unterstützen alle Pluginattribute: + +* `limitsoc` und `batterymode` werden ausschliesslich für Batterierzä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. + +Die folgende 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](#lesen) beschriebenen Pipelines genutzt werde. -| Attribut | Typ | Beschreibung | Einheit | +| Attribut | Typ | Kontext | Beschreibung | Einheit | | ----------- | ------------- | ----------------- | ------- | -| power | float | Aktuelle elektrische Leistung | W | -| energy | float | Total gemessene Energie | Wh | -| soc | int | Batterie Ladestand | -| batterymode | int | | 0,1,2,3 | -| currents | float / array | Strom (pro Phase) | -| voltages | | | -| powers | | | -| maxpower | | | -| capacity | | | +| power | float | alle | Aktuelle Verbrauchsleistung | W | +| energy | float | alle | Total gemessene Energie | Wh | +| soc | int | `battery` | Batterie Ladestand (in %) | 0 ... 100 | +| currents | float | `grid`, `charge` | Strom (pro Phase) | | +| voltages | float | `grid`, `charge` | | | +| powers | float | | | | +| maxpower | | | | | +| capacity | | | | | **Beispiel** -In diesem Beispiel wird die Konfiguration eines `meter`s um die aktuelle elektrische Leistung über einen HTTP Aufruf abgefragt: +In diesem Beispiel wird die Konfiguration eines `meter`s um die aktuelle elektrische Gridleistung über einen HTTP Aufruf abgefragt: ```yaml meters: @@ -115,12 +122,20 @@ meters: 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 | Beschreibung | Einheit | -| ---------- | ----- | -------------- | ------- | -| limitsoc | int | Ladeziel für Batterie | 0 ... 100 %| +| Attribut | Typ | Kontext | Beschreibung | Werte | +| ---------- | ----- | ------- | -------------- | ------- | +| limitsoc | int | `battery` | Setze Ladeziel für Batterie (in %). Das Ladezeziel je nach Lademodus aus den konfigurierten `MinSoc`, `MaxSoc` und dem aktuellen Ladestand (Attribut `soc`) berechnet. | 0 ... 100 | +| batterymode | int | `battery` | Setze Lademodus direkt | 1 (Normal), 2 (Hold), 3 (Charge) | ### Charger From 4d9ae9f9ef14726a97c4d002b39f0657528196d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Mon, 20 Jan 2025 11:07:03 +0100 Subject: [PATCH 12/19] fixed broken link --- docs/reference/plugins.md | 53 +++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md index 007056348d..d182c3e1d5 100644 --- a/docs/reference/plugins.md +++ b/docs/reference/plugins.md @@ -6,15 +6,13 @@ import Tag from '@site/src/components/Tag'; # Plugins -Plugins können verwendet werden, um verschiedene Geräte und externe Datenquellen in evcc zu integrieren, für die es keine direkte Unterstützung gibt. -Sie können für die Gerätekategorien [`meter`](/docs/reference/configuration/meters#custom) (Strommessgeräte), [`charger`](/docs/reference/configuration/chargers#type) (Wallboxen) oder [`vehicle`](/docs/devices/vehicles#manuell) (Fahrzeuge) verwendet werden. -Plugins können auch für die in [Messaging](/docs/reference/configuration/messaging) beschriebenen Endpunkte zum Versenden von Lifecycle-Events genutzt werden. - -Je nach Verwendung werden Plugins **lesend** oder **schreibend** eingesetzt. +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 die Kategorien [`meter`](/docs/reference/configuration/meters#custom) (Strommessgeräte), [`charger`](/docs/reference/configuration/chargers#type) (Wallboxen) oder [`vehicle`](/docs/devices/vehicles#manuell) (Fahrzeuge) verwendet werden. +Zusätzlich können Plugins auch für die in [Messaging](/docs/reference/configuration/messaging) beschriebenen Endpunkte zum Versenden von Lifecycle-Events genutzt werden. ## Übersicht -Folgende Plugins können verwendet werden, um externe Datenquellen einzubinden: +evcc bietet folgende Plugins an: - [Modbus Plugin](#modbus) - Plugin zum Auslesen von einem Modbus-fähigen Gerät. - [MQTT Plugin](#mqtt) - Plugin um indirekt über MQTT mit den MQTT-fähigen Geräten zu kommunizieren. @@ -24,7 +22,7 @@ Folgende Plugins können verwendet werden, um externe Datenquellen einzubinden: - [JavaScript Plugin](#javascript) - Plugin, das Werte in über ein JavaScript Skript bereitstellt oder entgegennimmt. - [Shell Plugin](#shell) - Plugin, das ein Shell Skript ausführen kann, um Daten zu extrahieren oder schreibend entgegennimmt. -Neben diesen Plugins, die externe Daten integrieren, gibt es folgende Helfer-Plugins, die Daten direkt bereitstellen können. Diese können nur in einem lesenden Kontext genutzt werden: +Neben diesen Integrations-Plugins, gibt es noch Helfer-Plugins, die Zusatzfunktionen bereit stellt: - [Const Plugin](#const) - Spezielles Plugin das einfach einen konstanten Wert zurückliefert. - [Calc Plugin](#calc) - Meta-Plugin um Ausgaben von anderen Plugins arithmetisch zu verknüpfen. @@ -35,7 +33,6 @@ Neben diesen Plugins, die externe Daten integrieren, gibt es folgende Helfer-Plu 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. -Die meisten Konfigurationsparameter sind Plugin spezifisch, jedoch gibt es eine handvoll Parameter, die beim Lesen von einem Plugin bzw. beim Schreiben via eines Plugins generell genutzt werden können. 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: @@ -48,12 +45,12 @@ meters: topic: "home/current/imsys/chn2/raw" ``` -Das Schema hat dabei immer folgende Struktur: +Das Schema der Plugin Konfiguration hat dabei immer folgende Struktur: ```yaml {3,5-6,8} - name: type: custom - : + : source: : ... : ... @@ -62,7 +59,7 @@ Das Schema hat dabei immer folgende Struktur: .... ``` -Dabei stehen `` für den Namen des Geräts, `` und `` für eine der unten beschriebenen Geräte-spezifischen Attribute, `` für den Plugin-Typ und ``, `` für Plugin-spezifische Konfigurationen. +Dabei steht `` für den Namen des Geräts, `` und `` für eine der unten beschriebenen Geräte-spezifischen Attribute, `` für den Plugin-Typ und ``, `` für Plugin-spezifische Konfigurationen (z.b. `source`, `topic` für Plugins vom Typ `mqtt`) #### Lesen @@ -86,21 +83,28 @@ Je nach Gerät ([`meter`](#meter), [`charger`](#charger) oder [`vehicle`](#vehic ### Meter -Alle `meter` haben gemeinsam, dass sie Stromzähler sind, die den aktuellen Verbrauch messen. -Wie an [anderer Stelle](/devices/meters) beschrieben, können Zähler in verschiedenen Kontexten innerhalb der `site` Konfiguration verwendet werden: Als Netzzähler (`grid`), Zähler für die PV Produktion (`pv`), Hausbatteriezähler (`battery`). Zähler für die Ladeleistung der Wallbox (`charge`) oder Verbrauchszähler für intelligente Verbraucher (`aux`). +Stromzähler werden in der Konfigurationssektion [`meters`](/docs/reference/configuration/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 + +`power` ist das einzig zwingend erfordeliche Attribut das in jeder `meter` Definition vorhanden sein muss, alle weiteren Attribute sind optional. -`power` ist das einzige erforderliche Attribut, alle weiteren Attribute sind optional. -Nicht alle Metertypen unterstützen alle Pluginattribute: +Jedoch unterstützen nicht alle Metertypen alle Pluginattribute: * `limitsoc` und `batterymode` werden ausschliesslich für Batterierzä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. +* `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 folgende 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](#lesen) beschriebenen Pipelines genutzt werde. | Attribut | Typ | Kontext | Beschreibung | Einheit | -| ----------- | ------------- | ----------------- | ------- | +| ----------- | ------------- | --------| ----------------- | ------- | | power | float | alle | Aktuelle Verbrauchsleistung | W | | energy | float | alle | Total gemessene Energie | Wh | | soc | int | `battery` | Batterie Ladestand (in %) | 0 ... 100 | @@ -112,7 +116,7 @@ Um zu dem verlangten Datentypen zu konvertieren können die in [Lesen](#lesen) b **Beispiel** -In diesem Beispiel wird die Konfiguration eines `meter`s um die aktuelle elektrische Gridleistung über einen HTTP Aufruf abgefragt: +In diesem Beispiel wird die Konfiguration eines meters um die aktuelle elektrische Gridleistung über einen HTTP Aufruf abgefragt: ```yaml meters: @@ -156,7 +160,7 @@ Wallboxen und Ladegeräte haben folgende Attribute die ausgelesen werden können **Beispiel** -Dieses Beispiel zeigt, wie man über das Modbus Plugin den Ladestatus (ladend/nicht ladend) eines `charger`s abfragen kann: +Dieses Beispiel zeigt, wie man über das Modbus Plugin den Ladestatus (ladend/nicht ladend) eines chargers abfragen kann: ```yaml chargers: @@ -178,7 +182,7 @@ Neben den read-only Werten können über Plugins auch Aktionen getriggert oder K | Attribut | Typ | Beschreibung | | ---------- | ----- | -------------- | | enable | float | Schalte an/aus | -| maxcurrent | float | Max. Ladestrom | +| maxcurrent | float | Setze maximalen Ladestrom | **Beispiel** @@ -270,7 +274,7 @@ Das Plugin bietet auch die Fähigkeit JSON Datenstrukturen über jq-ähnliche Ab source: mqtt topic: mbmd/sdm1-1/Power timeout: 30s # don't accept values older than timeout -scale: 0.001 # floating point factor applied to result, e.g. for Wh to kWh conversion +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. @@ -312,8 +316,9 @@ auth: # basic authentication password: bar insecure: false # set to true to trust self-signed certificates jq: .data.tuples[0][1] # parse response json -scale: 0.001 # floating point factor applied to result, e.g. for kW to W conversion -timeout: 10s # timeout in golang duration format, see https://golang.org/pkg/time/#ParseDuration +scale: 0.001 # factor applied to result, e.g. for kW to W conversion +timeout: 10s # timeout in golang duration format, + # see https://golang.org/pkg/time/#ParseDuration ``` ```yaml @@ -344,7 +349,7 @@ Das `websocket` Plugin bietet einen Websocket Listener. Es beinhaltet auch die F source: http uri: ws:///socket jq: .data | select(.uuid=="") .tuples[0][1] # parse message json -scale: 0.001 # floating point factor applied to result, e.g. for Wh to kWh conversion +scale: 0.001 # factor applied to result, e.g. for Wh to kWh conversion timeout: 30s # error if no update received in 30 seconds ``` From 836ac043e524821b87ac49fba9d37fb6b2b8b76a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Mon, 20 Jan 2025 14:53:48 +0100 Subject: [PATCH 13/19] moved plugins to the device category --- docs/{reference/plugins.md => devices/plugins.mdx} | 2 +- docs/devices/smartswitches.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/{reference/plugins.md => devices/plugins.mdx} (99%) diff --git a/docs/reference/plugins.md b/docs/devices/plugins.mdx similarity index 99% rename from docs/reference/plugins.md rename to docs/devices/plugins.mdx index d182c3e1d5..e661d95f75 100644 --- a/docs/reference/plugins.md +++ b/docs/devices/plugins.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 6 --- import Tag from '@site/src/components/Tag'; diff --git a/docs/devices/smartswitches.mdx b/docs/devices/smartswitches.mdx index 888226c5bf..aeffe9542c 100644 --- a/docs/devices/smartswitches.mdx +++ b/docs/devices/smartswitches.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 5 --- import Tabs from "@theme/Tabs"; @@ -42,7 +42,7 @@ chargers: standbypower: 50 ``` -Das heißt, in diesem Modus wird der Zustand des Ladepunkts abhängig von der gemessenen Leistung bestimmt: +Das heißt, in diesem Modus wird der Zustand des Ladepunkts abhängig von der gemessenen Leistung bestimmt: - Laden: (Leistung > `standbypower`) - Geladen: (Leistung ≤ `standbypower`) From 7d1f3a2565b80ff552c1d95093e1cc571b4d9f3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Sat, 25 Jan 2025 10:38:00 +0100 Subject: [PATCH 14/19] Fixed links to plugin page --- docs/Home.md | 2 +- docs/devices/plugins.mdx | 2 +- docs/reference/configuration/chargers.mdx | 2 +- docs/reference/configuration/messaging.md | 6 +++--- docs/reference/configuration/meters.md | 2 +- docs/reference/index.md | 6 ------ 6 files changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/Home.md b/docs/Home.md index fa2009f120..d8b1cc7808 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -19,7 +19,7 @@ Dazu wird evcc auf einem System im lokalen Netzwerk installiert, so dass es mit - [Wallboxen und schaltbaren Steckdosen](/docs/devices/chargers) - [Erzeugungsanlagen, Batteriespeichern und Energiemessgeräten (Zähler)](/docs/devices/meters) - [Fahrzeugen](/docs/devices/vehicles) -- [Plugins](/docs/reference/plugins) um nahezu beliebige Wallboxen / Zähler / Fahrzeuge hinzuzufügen: Modbus, HTTP, MQTT, Javascript, WebSockets und Shell Skripte +- [Plugins](/docs/devices/plugins) um nahezu beliebige Wallboxen / Zähler / Fahrzeuge hinzuzufügen: Modbus, HTTP, MQTT, Javascript, WebSockets und Shell Skripte - Status [Benachrichtigungen](/docs/reference/configuration/messaging) über [Telegram](https://telegram.org), [PushOver](https://pushover.net) und [viele mehr](https://containrrr.dev/shoutrrr/) - Datenanalyse mit [InfluxDB](https://www.influxdata.com) und [Grafana](https://grafana.com/grafana/) - Stufenlose Regelung der Ladeströme mit unterstützten Wallboxen (z.b. bei smartWB als [OLC](https://board.evse-wifi.de/viewtopic.php?f=16&t=187) bezeichnet) diff --git a/docs/devices/plugins.mdx b/docs/devices/plugins.mdx index e661d95f75..b31957f52c 100644 --- a/docs/devices/plugins.mdx +++ b/docs/devices/plugins.mdx @@ -259,7 +259,7 @@ Das `modbus` Plugin kann Daten von jedem Modbus-fähigen Gerät oder SunSpec-kom Viele Strommessgeräte sind bereits vorkonfiguriert (siehe [MBMD Supported Devices](https://github.com/volkszaehler/mbmd#supported-devices)). Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu integrieren. -Schaue in die [Modbus Dokumentation](modbus) für weitere Details. +Schaue in die [Modbus Dokumentation](/docs/reference/modbus) für weitere Details. ### MQTT {#mqtt} diff --git a/docs/reference/configuration/chargers.mdx b/docs/reference/configuration/chargers.mdx index 5d9f8289d1..fd83eeb49b 100644 --- a/docs/reference/configuration/chargers.mdx +++ b/docs/reference/configuration/chargers.mdx @@ -39,7 +39,7 @@ name: wallbox1 Dies ist der evcc spezifische Wallbox Typ, mit Hilfe dessen mit der Wallbox kommuniziert werden kann. Bekannte Wallboxen könne über den Typ `template` eingebunden werden. Den passenden (Template)Typ findet man unter [Geräte - Wallboxen](/docs/devices/chargers). -Für unbekannte Wallboxen (oder aus anderen individuellen Gründen) kann die Standard Implementierung über [Plugins](/docs/reference/plugins) genutzt werden. +Für unbekannte Wallboxen (oder aus anderen individuellen Gründen) kann die Standard Implementierung über [Plugins](/docs/devices/plugins) genutzt werden.g **Beispiel**: diff --git a/docs/reference/configuration/messaging.md b/docs/reference/configuration/messaging.md index 104b018eec..984bba5ff2 100644 --- a/docs/reference/configuration/messaging.md +++ b/docs/reference/configuration/messaging.md @@ -49,7 +49,7 @@ title: Charge started ### `msg` -`msg` definiert den Text für den Nachrichteninhalt. +`msg` definiert den Text für den Nachrichteninhalt. Im Text können verschiedene Variablen im Format `${}` zur Anzeige von evcc Informationen verwendet werden. :::note Bei Nutzung der Variablen ist auf die korrekte Schreibweise (groß/klein) zu achten! @@ -102,7 +102,7 @@ messaging: stop: # charge stop event title: Charge of {{.vehicleTitle}} finished msg: | - Wallbox {{.title}} finished charging {{.vehicleTitle}} + Wallbox {{.title}} finished charging {{.vehicleTitle}} with {{round (divf .chargedEnergy 1000) 2 }} kWh in {{.chargeDuration}}. -------------------------- evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}} @@ -238,7 +238,7 @@ Im folgenden werden nun alle erforderlichen Parameter erklärt. - `email`: Email. Siehe [`email`](#email) Definition - `shout`: [shoutrrr](https://containrrr.dev/shoutrrr). Siehe [`shout`](#shout) Definition - `ntfy`: [ntfy](https://ntfy.sh). Siehe [`ntfy`](#ntfy) Definition -- `custom`: Ermöglicht die Nutzung von allen [Plugins](../plugins), die einen Schreibzugriff erlauben. Siehe [`custom`](#custom) Definition. +- `custom`: Ermöglicht die Nutzung von allen [Plugins](/docs/devices/plugins), die einen Schreibzugriff erlauben. Siehe [`custom`](#custom) Definition. --- diff --git a/docs/reference/configuration/meters.md b/docs/reference/configuration/meters.md index c4ddbd6e75..285c604fb4 100644 --- a/docs/reference/configuration/meters.md +++ b/docs/reference/configuration/meters.md @@ -354,7 +354,7 @@ password: "DasPasswort" ### `custom` -Standard Implementierung, bei welchem die einzelnen Werte über [Plugins](/docs/reference/plugins) definiert werden. +Standard Implementierung, bei welchem die einzelnen Werte über [Plugins](/docs/devices/plugins) definiert werden. **Beispiel**: diff --git a/docs/reference/index.md b/docs/reference/index.md index 7fa27f6925..b1ec1d50a8 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -12,12 +12,6 @@ Hier werden die verschiedenen möglichen Einstellungen erklärt. [Weiterlesen...](./reference/configuration) -### Plugins - -Hier wird beschrieben wie man durch ein Plugin ein bisher nicht unterstütztes Gerät anbinden kann. - -[Weiterlesen...](./reference/plugins) - ### Modbus Hier befindet sich die Modbus Dokumentation, welche in verschiedenen Bereichen genutzt werden kann. From 694584080108f10187840b1e3c15d2638b4eef6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Sat, 25 Jan 2025 10:46:07 +0100 Subject: [PATCH 15/19] Fixed links to plugin page --- docs/reference/configuration/messaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration/messaging.md b/docs/reference/configuration/messaging.md index 984bba5ff2..ab76719de5 100644 --- a/docs/reference/configuration/messaging.md +++ b/docs/reference/configuration/messaging.md @@ -334,7 +334,7 @@ Weitere Informationen sind in der [ntfy Dokumentation](https://docs.ntfy.sh) zu ### `custom` -Der Typ `custom` ermöglicht es, beliebige [Plugins](../plugins) für die Verarbeitung von Nachrichten zu verwenden. Das Plugin muss den Schreibmodus unterstützen. Die Nachricht selbst wird in der Plugin Konfiguration mit dem Parameter `${send}` (bzw. als Template Parameter `{{.send}}`) bereitgestellt. +Der Typ `custom` ermöglicht es, beliebige [Plugins](/docs/devices/plugins) für die Verarbeitung von Nachrichten zu verwenden. Das Plugin muss den Schreibmodus unterstützen. Die Nachricht selbst wird in der Plugin Konfiguration mit dem Parameter `${send}` (bzw. als Template Parameter `{{.send}}`) bereitgestellt. **Mögliche Werte**: From 300f68d0016edec96cd19c9671f7990be9558c88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Sat, 25 Jan 2025 11:00:03 +0100 Subject: [PATCH 16/19] fixed links for english docs --- i18n/en/docusaurus-plugin-content-docs/current/Home.md | 2 +- .../current/{reference => devices}/plugins.md | 2 +- .../current/reference/configuration/chargers.mdx | 2 +- .../current/reference/configuration/messaging.md | 4 ++-- .../current/reference/configuration/meters.md | 2 +- .../docusaurus-plugin-content-docs/current/reference/index.md | 4 ---- 6 files changed, 6 insertions(+), 10 deletions(-) rename i18n/en/docusaurus-plugin-content-docs/current/{reference => devices}/plugins.md (99%) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/Home.md b/i18n/en/docusaurus-plugin-content-docs/current/Home.md index 60c35d8e71..916a35fa08 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/Home.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/Home.md @@ -20,7 +20,7 @@ evcc is installed onto a system in the local network, so that it can communicate - [Wallboxes & Switchable Sockets](/docs/devices/chargers) - [Inverters, Battery Storage, & Energy Meters](/docs/devices/meters) - [Vehicles](/docs/devices/vehicles) -- [Plugins](/docs/reference/plugins) support a wide variety of wallboxes, meters, & vehicles over Modbus, HTTP, MQTT, JavaScript, Websockets, and Shell Scripts +- [Plugins](/docs/devices/plugins) support a wide variety of wallboxes, meters, & vehicles over Modbus, HTTP, MQTT, JavaScript, Websockets, and Shell Scripts - Status [Notifications](/docs/reference/configuration/messaging) via [Telegram](https://telegram.org), [PushOver](https://pushover.net) and [many more](https://containrrr.dev/shoutrrr/) - Data Export via [InfluxDB](https://www.influxdata.com) and [Grafana](https://grafana.com/grafana/) - Stepless regulation of charging flows with supported wall boxes (e.g the smartWB's [OLC](https://board.evse-wifi.de/viewtopic.php?f=16&t=187) functionality) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/reference/plugins.md b/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.md similarity index 99% rename from i18n/en/docusaurus-plugin-content-docs/current/reference/plugins.md rename to i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.md index ac5503a043..7e3dadc4e2 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/reference/plugins.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 6 --- # Plugins diff --git a/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/chargers.mdx b/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/chargers.mdx index 7e2f2a2b5a..a2aaded044 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/chargers.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/chargers.mdx @@ -39,7 +39,7 @@ name: charger1 This is the evcc-specific charger type that allows communication with the charger. Known chargers can be integrated using the `template` type. The appropriate (template) type can be found under [devices - chargers](/docs/devices/chargers). -For unknown chargers (or for other individual reasons), the default implementation can be used through [Plugins](/docs/reference/plugins). +For unknown chargers (or for other individual reasons), the default implementation can be used through [Plugins](/docs/devices/plugins). **For example**: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/messaging.md b/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/messaging.md index 632725333c..ee6dd507f6 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/messaging.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/messaging.md @@ -101,7 +101,7 @@ messaging: stop: # charge stop event title: Charge of {{.vehicleTitle}} finished msg: | - Charger {{.title}} finished charging {{.vehicleTitle}} + Charger {{.title}} finished charging {{.vehicleTitle}} with {{round (divf .chargedEnergy 1000) 2 }} kWh in {{.chargeDuration}}. -------------------------- evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}} @@ -239,7 +239,7 @@ The following sections will now explain all the required parameters. - `email`: Email. See [`email`](#email) definition - `shout`: [shoutrrr](https://containrrr.dev/shoutrrr/). See [`shout`](#shout) definition - `ntfy`: [ntfy](https://ntfy.sh). See [`ntfy`](#ntfy) definition -- `custom`: Allows the usage of any [plugin](../plugins) that supports write access. See [`custom`](#custom) definition. +- `custom`: Allows the usage of any [plugin](/docs/devices/plugins) that supports write access. See [`custom`](#custom) definition. --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/meters.md b/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/meters.md index 88eb07bf16..19d98cc557 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/meters.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/meters.md @@ -350,7 +350,7 @@ password: "ThePassword" ### `custom` -Standard implementation, in which individual values are defined via [plugins](/docs/reference/plugins). +Standard implementation, in which individual values are defined via [plugins](/docs/devices/plugins). **For example**: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/reference/index.md b/i18n/en/docusaurus-plugin-content-docs/current/reference/index.md index 6b723aca23..08a71f3fb4 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/reference/index.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/reference/index.md @@ -10,10 +10,6 @@ Below is technical documentation on various aspects of evcc. [An explanation of the settings and configuration files.](./reference/configuration) -### Plug-ins - -[A description of how a plug-in can connect to a previously unsupported device.](./reference/plugins) - ### Modbus [Documentation for Modbus, which is used in turn by various of the devices supported.](./reference/modbus) From 8b882fc474f00d210426d6d9e9213bc022ed8bb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roland=20Hu=C3=9F?= Date: Sat, 25 Jan 2025 11:01:42 +0100 Subject: [PATCH 17/19] fixed links for english docs --- .../current/reference/configuration/messaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/messaging.md b/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/messaging.md index ee6dd507f6..eb99ba16f6 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/messaging.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/reference/configuration/messaging.md @@ -335,7 +335,7 @@ Further information can be found in the [ntfy documentation](https://docs.ntfy.s ### `custom` -The `custom` type allows the use of any [plugin](../plugins) to process messages. The plugin must support write mode. The message itself is provided in the plugin configuration using the parameter `${send}` (or as a template parameter `{{.send}}`). +The `custom` type allows the use of any [plugin](/docs/devices/plugins) to process messages. The plugin must support write mode. The message itself is provided in the plugin configuration using the parameter `${send}` (or as a template parameter `{{.send}}`). **Possible Values**: From fe7d48629b4fd56ee677800efb1cca194d4d29b0 Mon Sep 17 00:00:00 2001 From: Michael Geers Date: Fri, 21 Mar 2025 16:20:32 +0100 Subject: [PATCH 18/19] typos, add tarif, circuit, ext --- docs/devices/plugins.mdx | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/docs/devices/plugins.mdx b/docs/devices/plugins.mdx index b31957f52c..39e25c3a6a 100644 --- a/docs/devices/plugins.mdx +++ b/docs/devices/plugins.mdx @@ -7,7 +7,15 @@ import Tag from '@site/src/components/Tag'; # 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 die Kategorien [`meter`](/docs/reference/configuration/meters#custom) (Strommessgeräte), [`charger`](/docs/reference/configuration/chargers#type) (Wallboxen) oder [`vehicle`](/docs/devices/vehicles#manuell) (Fahrzeuge) verwendet werden. +Plugins können für folgende Kategorien verwendet werden: + +- `meter`: [PV, Batterie, Netz, Zähler](./meters) +- `charger`: [Wallboxen](./chargers), [Smarte Schalter](./smartswitches), [Wärmepumpen, Heizstäbe](./heating) +- `vehicle`: [Fahrzeuge](./vehicles) +- `tariff`: [Tarife, Vorhersagen](../tariffs) +- `circuit`: [Lastmanagement](../features/loadmanagement) + + Zusätzlich können Plugins auch für die in [Messaging](/docs/reference/configuration/messaging) beschriebenen Endpunkte zum Versenden von Lifecycle-Events genutzt werden. ## Übersicht @@ -91,6 +99,7 @@ Zähler, die unter `meters:` definiert werden, können an verschiedenen Stellen * `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 erfordeliche Attribut das in jeder `meter` Definition vorhanden sein muss, alle weiteren Attribute sind optional. @@ -99,9 +108,9 @@ Jedoch unterstützen nicht alle Metertypen alle Pluginattribute: * `limitsoc` und `batterymode` werden ausschliesslich für Batterierzä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 folgende Tabellen enthalten alle Attribute, die von Plugins bereitgestellt werden können, wenn sie für `meter` konfiguriert werden. +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](#lesen) beschriebenen Pipelines genutzt werde. +Um zu dem verlangten Datentypen zu konvertieren können die in [Lesen](#lesen) beschriebenen Pipelines genutzt werden. | Attribut | Typ | Kontext | Beschreibung | Einheit | | ----------- | ------------- | --------| ----------------- | ------- | @@ -217,7 +226,7 @@ Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden. **Beispiel** -Im folgenden Beispiel wie die aktuelle Reichweite des Fahrzeugs aus MQTT Nachrichten gelesen: +Im folgenden Beispiel wird die aktuelle Reichweite des Fahrzeugs aus MQTT Nachrichten gelesen: ``` yaml vehicles: @@ -249,6 +258,24 @@ vehicles: uri: http://teslalogger.local:5000/command/08154711/wake_up ``` +### Tarife + +:::note Work in Progress +... +::: + +### Lastmanagement + +:::note Work in Progress +... +::: + +### Messaging + +:::note 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. From 1c64f2c7b5732c33c83840b6cc725ec54b883e1f Mon Sep 17 00:00:00 2001 From: Michael Geers Date: Fri, 21 Mar 2025 18:39:25 +0100 Subject: [PATCH 19/19] add missing attributes, grammar, consistancy, ... --- docs/Home.md | 4 +- docs/devices/heating.mdx | 4 +- docs/devices/plugins.mdx | 170 ++++++++++-------- docs/faq.mdx | 12 +- docs/features/sessions.mdx | 2 +- docs/installation/docker.mdx | 2 +- docs/installation/home-assistant.mdx | 4 +- docs/installation/linux.mdx | 2 +- docs/installation/macos.md | 2 +- docs/integrations/home-assistant.mdx | 2 +- docs/integrations/mqtt-api.md | 2 +- docs/reference/configuration/chargers.mdx | 2 +- docs/reference/configuration/hems.md | 2 +- docs/reference/configuration/index.md | 6 +- docs/reference/configuration/loadpoints.md | 5 +- docs/reference/configuration/log.md | 2 +- docs/reference/configuration/modbusproxy.md | 4 +- docs/reference/configuration/vehicles.mdx | 2 +- docs/reference/modbus.md | 8 +- docs/tariffs.mdx | 8 +- docs/tariffs/_dynamischer_strompreis.mdx | 2 +- .../current/devices/heating.mdx | 2 +- .../current/tariffs.mdx | 2 +- .../tariffs/_dynamic_electricity_price.mdx | 2 +- 24 files changed, 134 insertions(+), 119 deletions(-) diff --git a/docs/Home.md b/docs/Home.md index d8b1cc7808..421fc039ad 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -22,8 +22,8 @@ Dazu wird evcc auf einem System im lokalen Netzwerk installiert, so dass es mit - [Plugins](/docs/devices/plugins) um nahezu beliebige Wallboxen / Zähler / Fahrzeuge hinzuzufügen: Modbus, HTTP, MQTT, Javascript, WebSockets und Shell Skripte - Status [Benachrichtigungen](/docs/reference/configuration/messaging) über [Telegram](https://telegram.org), [PushOver](https://pushover.net) und [viele mehr](https://containrrr.dev/shoutrrr/) - Datenanalyse mit [InfluxDB](https://www.influxdata.com) und [Grafana](https://grafana.com/grafana/) -- Stufenlose Regelung der Ladeströme mit unterstützten Wallboxen (z.b. bei smartWB als [OLC](https://board.evse-wifi.de/viewtopic.php?f=16&t=187) bezeichnet) -- [REST](/docs/integrations/rest-api)- und [MQTT](/docs/integrations/mqtt-api)-APIs zur Integration in andere Heimautomationssysteme (z.B. [HomeAssistant](/docs/integrations/home-assistant)) +- Stufenlose Regelung der Ladeströme mit unterstützten Wallboxen (z. B. bei smartWB als [OLC](https://board.evse-wifi.de/viewtopic.php?f=16&t=187) bezeichnet) +- [REST](/docs/integrations/rest-api)- und [MQTT](/docs/integrations/mqtt-api)-APIs zur Integration in andere Heimautomationssysteme (z. B. [HomeAssistant](/docs/integrations/home-assistant)) ## Anforderungen diff --git a/docs/devices/heating.mdx b/docs/devices/heating.mdx index ede5994e34..e59490cbaa 100644 --- a/docs/devices/heating.mdx +++ b/docs/devices/heating.mdx @@ -68,7 +68,7 @@ loadpoints: charger: heatpump_control meter: heatpump_power # Hier können auch die bekannten Parameter für loadpoints angegeben werden, - # insbesondere auch um zu kurze Laufzeiten zu verhindern, z.B. + # insbesondere auch um zu kurze Laufzeiten zu verhindern, z. B. enable: threshold: -1300 # aktivieren bei 1.300 W Überschuss für 5 Minuten delay: 5m @@ -141,7 +141,7 @@ Dieses Code-Beispiel enthält einige Redundanzen. Wir werden später Templates für die einfachere Konfiguration gängiger Konstellationen bereitstellen. ::: -Neben `setmode` und `getmode`, kannst du optional auch die aktuelle Temperatur (`temp`) [via Plugin](/docs/reference/plugins) hinzufügen. +Neben `setmode` und `getmode`, kannst du optional auch die aktuelle Temperatur (`temp`) [via Plugin](./plugins) hinzufügen. Diese dient lediglich zur Anzeige und wird bei Wärmepumpen nicht für die Steuerung verwendet. ## Heizstäbe diff --git a/docs/devices/plugins.mdx b/docs/devices/plugins.mdx index 39e25c3a6a..2750ee3437 100644 --- a/docs/devices/plugins.mdx +++ b/docs/devices/plugins.mdx @@ -72,17 +72,20 @@ Dabei steht `` für den Namen des Geräts, `` und `` für ei #### 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. +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](https://jqlang.github.io/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`. +- `jq`: Ein [jq](https://jqlang.github.io/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. +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. @@ -101,31 +104,31 @@ Zähler, die unter `meters:` definiert werden, können an verschiedenen Stellen * `aux`: Verbrauchszähler für intelligente Verbraucher * `ext`: weiterer Zähler, bspw. für Lastmanagement oder Datenerfassung -`power` ist das einzig zwingend erfordeliche Attribut das in jeder `meter` Definition vorhanden sein muss, alle weiteren Attribute sind optional. +`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 ausschliesslich für Batterierzä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. +* `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](#lesen) beschriebenen Pipelines genutzt werden. - -| Attribut | Typ | Kontext | Beschreibung | Einheit | -| ----------- | ------------- | --------| ----------------- | ------- | -| power | float | alle | Aktuelle Verbrauchsleistung | W | -| energy | float | alle | Total gemessene Energie | Wh | -| soc | int | `battery` | Batterie Ladestand (in %) | 0 ... 100 | -| currents | float | `grid`, `charge` | Strom (pro Phase) | | -| voltages | float | `grid`, `charge` | | | -| powers | float | | | | -| maxpower | | | | | -| capacity | | | | | +Um zu dem verlangten Datentypen zu konvertieren, können die in [Lesen](#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 | +| currents | [float,float,float] | nein | alle | Phasenströme in A | +| voltages | [float,float,float] | nein | alle | Phasenspannungen in V | **Beispiel** -In diesem Beispiel wird die Konfiguration eines meters um die aktuelle elektrische Gridleistung über einen HTTP Aufruf abgefragt: +In diesem Beispiel wird die Konfiguration eines Meters um die aktuelle elektrische Gridleistung über einen HTTP-Aufruf abgefragt: ```yaml meters: @@ -143,33 +146,36 @@ site: ... ``` -Neben den Attributen, die Plugins zur lesenden Auswertung bereitstellen werden folgende Attribute von `evcc` genutzt um Aktionen zu triggern: +Neben den Attributen, die Plugins zur lesenden Auswertung bereitstellen, werden folgende Attribute von evcc genutzt, um Aktionen zu triggern: -| Attribut | Typ | Kontext | Beschreibung | Werte | -| ---------- | ----- | ------- | -------------- | ------- | -| limitsoc | int | `battery` | Setze Ladeziel für Batterie (in %). Das Ladezeziel je nach Lademodus aus den konfigurierten `MinSoc`, `MaxSoc` und dem aktuellen Ladestand (Attribut `soc`) berechnet. | 0 ... 100 | -| batterymode | int | `battery` | Setze Lademodus direkt | 1 (Normal), 2 (Hold), 3 (Charge) | +| 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 | Beschreibung | -| --------------- | ----- | -------------- | -| power | float | Leistung | -| energy | float | Energie | -| enabled | bool | Eingeschaltet? | -| status | bool | Status | -| maxcurrentmilis | | | -| soc | | | -| phases1p3p | | | -| power | | | -| currents | | | -| voltages | | | +| 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 | +| currents | [float,float,float] | nein | Phasenströme in A | +| voltages | [float,float,float] | nein | Phasenspannungen in V | +| temp | float | nein | Aktuelle Temperatur in °C (Heizung) | +| templimit | int | nein | Temperaturlimit in °C (Heizung) | +| getmode | int | nein | SG-Ready Modus (Wärmepumpe) | **Beispiel** -Dieses Beispiel zeigt, wie man über das Modbus Plugin den Ladestatus (ladend/nicht ladend) eines chargers abfragen kann: +Dieses Beispiel zeigt, wie man über das Modbus-Plugin den Ladestatus (ladend/nicht ladend) eines Chargers abfragen kann: ```yaml chargers: @@ -188,14 +194,19 @@ chargers: Neben den read-only Werten können über Plugins auch Aktionen getriggert oder Konfigurationswerte gesetzt werden: -| Attribut | Typ | Beschreibung | -| ---------- | ----- | -------------- | -| enable | float | Schalte an/aus | -| maxcurrent | float | Setze maximalen Ladestrom | +| 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: normal, 2: boost, 3: stop) | + **Beispiel** -Dieses Beispiel schaltet eine Tasmota Steckdose über eine MQTT Nachricht gesendet an: +Dieses Beispiel schaltet eine Tasmota-Steckdose über eine MQTT Nachricht gesendet an: ```yaml chargers: @@ -212,17 +223,16 @@ chargers: Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden. -| Attribut | Typ | Beschreibung | -| ---------- | ------------- | ------------------- | -| soc | int | Ladestand | -| status | bool / A .. F | Status | -| range | int | Reichweite | -| odometer | int | Zählerstand | -| climater | bool | Klimaanlage (?) | -| wakeup | ? | Aufweck-Ping | -| limitsoc | int | Ladeziel in % | -| maxcurrent | int | Maximaler Ladestrom | -| finishtime | | | +| 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) | **Beispiel** @@ -239,15 +249,15 @@ vehicles: Zusätzlich können spezielle Kommandos über Plugins an das Fahrzeug geschickt werden: -| Attribut | Typ | Beschreibung | -| -------- | --- | ------------ | -| wakeup | ? | Aufweck-Ping | -| chargeEnable | ? | Start/Stop des Ladevorgangs über das Vehicle | -| maxCurrent | ? | Begrenze maximalen Ladestrom | +| 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: +Um ein Auto über einen HTTP Ping aufzuwecken, um weiter Abfragen zu senden, kann wie im folgenden Beispiel das HTTP-Plugin genutzt werden: ``` yaml vehicles: @@ -258,11 +268,9 @@ vehicles: uri: http://teslalogger.local:5000/command/08154711/wake_up ``` -### Tarife +### Tarife & Vorhersagen -:::note Work in Progress -... -::: +Siehe [Tarife & Vorhersagen > Eigenes Plugin](../tariffs#plugin) für mehr Details. ### Lastmanagement @@ -282,7 +290,7 @@ Folgende Plugins stehen zur Verfügung und können für die oben beschriebenen A ### Modbus {#modbus} -Das `modbus` Plugin kann Daten von jedem Modbus-fähigen Gerät oder SunSpec-kompatiblen Wechselrichter lesen. +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](https://github.com/volkszaehler/mbmd#supported-devices)). Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu integrieren. @@ -290,8 +298,8 @@ Schaue in die [Modbus Dokumentation](/docs/reference/modbus) für weitere Detail ### MQTT {#mqtt} -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. +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](https://github.com/volkszaehler/mbmd) 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](#http)). @@ -304,7 +312,8 @@ 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. +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**: @@ -316,9 +325,12 @@ payload: ${var:%d} ### HTTP {#http} -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](https://jqlang.github.io/jq/manual/) zu finden. +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](https://jqlang.github.io/jq/manual/) zu finden. -Methoden der Authentifizierung sind `basic`, `bearer` und `digest`. Die Namen der jeweiligen Parameter finden sich [hier](https://github.com/evcc-io/evcc/blob/master/provider/http.go#L140). +Methoden der Authentifizierung sind `basic`, `bearer` und `digest`. +Die Namen der jeweiligen Parameter finden sich [hier](https://github.com/evcc-io/evcc/blob/master/provider/http.go#L140). :::important 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. @@ -368,7 +380,9 @@ enable: ### Websocket {#websocket} -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. +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**: @@ -402,7 +416,8 @@ Alle möglichen Werte können als Konstanten [hier](https://gitlab.com/bboehmke/ ### JavaScript {#javascript} -evcc integriert einen JavaScript Interpreter mit der [Underscore.js](https://underscorejs.org) 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: +evcc integriert einen JavaScript Interpreter mit der [Underscore.js](https://underscorejs.org) 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**: @@ -449,7 +464,7 @@ timeout: 5s ### Const {#const} 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. +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**: @@ -486,11 +501,12 @@ mul: 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 `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 `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. +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) @@ -518,4 +534,4 @@ plugged: charging: source: mqtt topic: openWB/lp/1/boolChargeStat -``` +``` \ No newline at end of file diff --git a/docs/faq.mdx b/docs/faq.mdx index 0677f896fe..d82fe04d13 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -26,7 +26,7 @@ site: Hier gibt es verschiedene Nutzungsmöglichkeiten. Notwendig ist auf jeden Fall ein auslesbarer Netzzähler. -Bei einem [variablen Stromtarif](./features/dynamic-prices) (z.B. Nachtstrom, Tibber, Awattar) ist automatisches preisabhängiges Laden möglich. +Bei einem [variablen Stromtarif](./features/dynamic-prices) (z. B. Nachtstrom, Tibber, Awattar) ist automatisches preisabhängiges Laden möglich. Ansonsten kann man evcc zur Fernsteuerung (start/stop) der Wallbox nutzen. Darüber hinaus kann man die Ladung einer Fahrzeugbatterie auf einen bestimmten Ladestand (SoC) begrenzen. In diesem Fall ist es aber zwingend notwendig, dass das Fahrzeug in die Konfiguration mit aufgenommen wird. @@ -52,7 +52,7 @@ Mehrere Wallboxen und damit Ladepunkte können in evcc verwendet werden. Es ist Bei kleinen PV-Anlagen und/oder im Winter macht es Sinn nur 1-phasig zu laden, um den vorhandenen Überschuss bestmöglich ohne Netzbezug zu nutzen. -Bei Wallboxen die keine automatische Phasenumschaltung beherrschen, kann man in der Zuleitung zur Wallbox mittels eines Lasttrennschalters (z.B. Hager HAB304) die Phasen 2 & 3 abschalten. Wenn die volle Leistung benötigt wird, schaltet man die Phasen wieder zu. +Bei Wallboxen die keine automatische Phasenumschaltung beherrschen, kann man in der Zuleitung zur Wallbox mittels eines Lasttrennschalters (z. B. Hager HAB304) die Phasen 2 & 3 abschalten. Wenn die volle Leistung benötigt wird, schaltet man die Phasen wieder zu. :::danger Achtung Dieses manuelle Umschalten darf nur erfolgen, wenn das Fahrzeug **NICHT** mit der Wallbox verbunden ist. @@ -68,7 +68,7 @@ Damit evcc weiß, dass nicht mehr 3-phasig geladen werden kann muss die entsprec yaml ist sehr syntax-empfindlich. Fehler fallen nicht immer sofort ins Auge. -Eine schnelle Hilfe bieten yaml-Tester wie z.B. (https://onlineyamltools.com/validate-yaml) +Eine schnelle Hilfe bieten yaml-Tester wie z. B. (https://onlineyamltools.com/validate-yaml) ### Etwas funktioniert nicht. Was nun? @@ -152,7 +152,7 @@ Die IP-Verbindung zum betreffenden Gerät ist prinzipiell vorhanden, jedoch wird Die Gründe dafür können vielfältig sein. Typisch sind: - Der am Gerät offene Port stimmt nicht mit dem in der evcc-Konfiguration angegebenen Zielport überein. -- Der externe Zugriff auf das Gerät ist nicht aktiviert (z.B. bei Solaredge-Wechselrichtern im Auslieferungszustand). +- Der externe Zugriff auf das Gerät ist nicht aktiviert (z. B. bei Solaredge-Wechselrichtern im Auslieferungszustand). - Die maximal mögliche Anzahl an parallelen Verbindungen, die das Zielgerät verwalten kann, ist erschöpft. Andere Verbindungen z. B. von Hausautomationen, Skripten oder weiteren Instanzen von evcc müssen ggf. zunächst beendet werden, bevor eine neue Verbindung möglich ist. Im ungünstigsten Fall lässt das Zielsystem nur eine einzige Verbindung zu. - Blockade durch eine Firewall. @@ -325,7 +325,7 @@ Batterieverluste durch die Umwandlung werden nicht berücksichtigt. **Berechnung von Ersparnis und effektivem Energiepreis** Der Algorithmus unterscheidet zwischen Netzstrom und selbst erzeugter Sonnenenergie (PV, Batterie). -Der Kostenvorteil deiner Sonnenenergie ergibt sich aus der Differenz zwischen deinem Netzbezugspreis (z.B. 30 ct/kWh) und deinem Einspeisetarif (z.B. 8 ct/kWh). +Der Kostenvorteil deiner Sonnenenergie ergibt sich aus der Differenz zwischen deinem Netzbezugspreis (z. B. 30 ct/kWh) und deinem Einspeisetarif (z. B. 8 ct/kWh). Jede geladene kWh selbst produzierter Energie ist in diesem Beispiel 22 ct (30 ct - 8 ct) günstiger als der Netzbezug. Hast du 2 kWh eigene Energie geladen entspricht das einer **Ersparnis** von 44 ct. @@ -341,7 +341,7 @@ evcc hilft dir aber den Anteil der geladenen Sonnenenergie zu maximieren. **Berechnung des Sonnenenergieanteils** -Wenn du gleichzeitig Energie aus verschiedenen Quellen beziehst (z.B. 50% PV, 50% Netzbezug), wird die selbst erzeugte Energie zuerst dem Haus, also allen nicht von evcc gesteuerten Verbrauchern, zugeordnet. +Wenn du gleichzeitig Energie aus verschiedenen Quellen beziehst (z. B. 50% PV, 50% Netzbezug), wird die selbst erzeugte Energie zuerst dem Haus, also allen nicht von evcc gesteuerten Verbrauchern, zugeordnet. Der verbleibende Anteil wird dann auf die Ladevorgänge aufgeteilt. Beispiel: Deine PV-Anlage erzeugt 3 kW. Diese 3 kW werden komplett vom Haus verbraucht (bspw. Waschmaschine). Parallel lädst du dein Auto mit 3 kW (bspw. Modus = schnell). diff --git a/docs/features/sessions.mdx b/docs/features/sessions.mdx index 0d64a3e522..9377650007 100644 --- a/docs/features/sessions.mdx +++ b/docs/features/sessions.mdx @@ -86,7 +86,7 @@ Wurde ein Fahrzeug nicht korrekt erkannt, kannst du in dieser Ansicht auch die F ## Schaltbare Steckdosen -Im Gegensatz zu Wallboxen gibt es bei schaltbaren Steckdosen (z.B. Schuko-Ladegerät, E-Bike, ...) oder fest verkabelten Anlagen (z.B. Wärmepumpe, Heizstab, ...) keine Möglichkeit, den Ladevorgang zu erkennen. +Im Gegensatz zu Wallboxen gibt es bei schaltbaren Steckdosen (z. B. Schuko-Ladegerät, E-Bike, ...) oder fest verkabelten Anlagen (z. B. Wärmepumpe, Heizstab, ...) keine Möglichkeit, den Ladevorgang zu erkennen. Diese Verbraucher tauchen aktuell trotzdem in der Liste der Ladevorgänge mit langen Zeiträumen auf. Wird evcc neu gestartet, wird ein neuer Ladevorgang protokolliert. Dies kann auch über aktives Stoppen und Starten am Ladepunkt (Modus: aus) manuell erfolgen. diff --git a/docs/installation/docker.mdx b/docs/installation/docker.mdx index 4e2a78ab80..8782040a60 100644 --- a/docs/installation/docker.mdx +++ b/docs/installation/docker.mdx @@ -61,7 +61,7 @@ In diesem Abschnitt werden drei Möglichkeiten zur Installation von evcc über D ### via Docker UI -Hast du ein System mit einer Docker GUI (z.B. Synology, QNAP, Portainer, Unraid, ...) kannst du die Installation auch über diese Oberfläche vornehmen. +Hast du ein System mit einer Docker GUI (z. B. Synology, QNAP, Portainer, Unraid, ...) kannst du die Installation auch über diese Oberfläche vornehmen. Hier sind die relevanten Angaben, die du eintragen musst: #### Verfügbare Docker Images {#images} diff --git a/docs/installation/home-assistant.mdx b/docs/installation/home-assistant.mdx index fb8e110fac..03c6a04504 100644 --- a/docs/installation/home-assistant.mdx +++ b/docs/installation/home-assistant.mdx @@ -96,7 +96,7 @@ Falls dieser Ordner noch nicht exisiert, erstelle ihn manuell. Um die Konfigurationsdatei anzulegen bzw. zu editieren, hast du verschiedene Möglichkeiten, hier ein paar zur Auswahl: - [Visual Studio Code](https://github.com/hassio-addons/addon-vscode), in Visual Studio Code wähle das Hamburger-Menü oben links aus und wähle "File", "Open Folder...", select `/addon_configs/49686a9f_evcc` - [File Editor](https://github.com/home-assistant/addons/tree/master/configurator), stelle sicher, dass Du die Option "Enforce Basepath" in der Addon Konfiguration deaktiviert hast, starte das Addon neu und navigiere nach `/addon_configs/49686a9f_evcc` -- [Advanced SSH & Web Terminal](https://github.com/hassio-addons/addon-ssh), navigiere nach `/addon_configs/49686a9f_evcc` und verwende z.B. nano +- [Advanced SSH & Web Terminal](https://github.com/hassio-addons/addon-ssh), navigiere nach `/addon_configs/49686a9f_evcc` und verwende z. B. nano Unter [Konfiguration](./configuration) findest du eine Anleitung, wie du den Inhalt für die `evcc.yaml` erstellen kannst. @@ -110,7 +110,7 @@ Die Aktualisierung auf die neueste Version von evcc ist in den Home Assistant Up ## Erweiterte Tips -Um die folgenden Funktionen auszuführen, benötigst du SSH Zugriff auf Home Assistant. Diesen kannst du z.B. mit dem oben erwähnten SSH Addon bekommen. +Um die folgenden Funktionen auszuführen, benötigst du SSH Zugriff auf Home Assistant. Diesen kannst du z. B. mit dem oben erwähnten SSH Addon bekommen. - Installiere [Advanced SSH & Web Terminal](https://github.com/hassio-addons/addon-ssh) - deaktiviere den "secure mode" in der Addon Konfiguration diff --git a/docs/installation/linux.mdx b/docs/installation/linux.mdx index 530974c26a..551d30d76c 100644 --- a/docs/installation/linux.mdx +++ b/docs/installation/linux.mdx @@ -235,7 +235,7 @@ Neben dem Debian/Ubuntu APT Paket, stellen wir auch weitere Binaries für Linux - 64-Bit ARM CPU: [evcc_X.XX_linux_arm64.tar.gz](https://github.com/evcc-io/evcc/releases/latest) - 32-Bit ARM CPU (e.g. Raspberry Pi 32-Bit OS): [evcc_X.XX_linux_armv6.tar.gz](https://github.com/evcc-io/evcc/releases/latest) -- Entpacke die heruntergeladene Datei (z.B. per Doppelklick auf die Datei). +- Entpacke die heruntergeladene Datei (z. B. per Doppelklick auf die Datei). - Im entpackten Ordner befindet sich ein `evcc` Programm. - Öffne ein Terminal und gehe in den Ordner neuen Ordner. - Mit folgendem Befehl kannst du prüfen, ob evcc funktioniert: diff --git a/docs/installation/macos.md b/docs/installation/macos.md index ae520b0722..6b219b26b2 100644 --- a/docs/installation/macos.md +++ b/docs/installation/macos.md @@ -137,7 +137,7 @@ Hier findest du die Anleitung für die manuelle Installation von evcc auf macOS. - Lade die entsprechende Datei auf dein System herunter: - 64-Bit ARM oder Intel CPU: [evcc_X.XX_macOS_all.tar.gz](https://github.com/evcc-io/evcc/releases/latest) -- Entpacke die heruntergeladene Datei (z.B. per Doppelklick auf die Datei) +- Entpacke die heruntergeladene Datei (z. B. per Doppelklick auf die Datei) - Es gibt nun einen neuen Ordner mit dem Programm `evcc`. - Öffne ein Terminal und gehe in den Ordner mit dem Programm `evcc` - Starte evcc mit folgendem Befehl: diff --git a/docs/integrations/home-assistant.mdx b/docs/integrations/home-assistant.mdx index c41c10a76f..9a9feb6407 100644 --- a/docs/integrations/home-assistant.mdx +++ b/docs/integrations/home-assistant.mdx @@ -14,7 +14,7 @@ Wenn du nach einer Installationsanleitung suchst, findest du diese unter [Instal ## Schnittstellen Falls du Geräte, wie Chargers, Meters oder Fahrzeuge, in evcc integrieren möchtest die von Geräten stammen die evcc nicht -unterstützt (z.B. Zigbee Smartplugs) kannst du dies über [MQTT](./mqtt-api) oder das +unterstützt (z. B. Zigbee Smartplugs) kannst du dies über [MQTT](./mqtt-api) oder das [REST API](./rest-api) realisieren. Dank der beiden evcc Schnittstellen können zusätzliche Ladepunkte für eine Vielzahl von verschiebbaren Lasten (Verbrauchern), diff --git a/docs/integrations/mqtt-api.md b/docs/integrations/mqtt-api.md index 951db2aec3..0db1e4d399 100644 --- a/docs/integrations/mqtt-api.md +++ b/docs/integrations/mqtt-api.md @@ -11,7 +11,7 @@ Nutze Tools wie [MQTT Explorer](https://mqtt-explorer.com/) um die Daten zu visu ::: Die MQTT API folgt der [REST API](./rest-api) Struktur. -Alle API IDs (z.B. die Loadpoint ID) beginnen bei `1`. +Alle API IDs (z. B. die Loadpoint ID) beginnen bei `1`. - `evcc`: root topic - `evcc/status`: status (`online`/`offline`) diff --git a/docs/reference/configuration/chargers.mdx b/docs/reference/configuration/chargers.mdx index fd83eeb49b..d2861d46fb 100644 --- a/docs/reference/configuration/chargers.mdx +++ b/docs/reference/configuration/chargers.mdx @@ -53,7 +53,7 @@ type: custom ### `integrateddevice` -Dieser Parameter bewirkt, dass bei Ladegeräten, die ohne "Fahrzeug" betrieben werden (z.B. Wärmepumpe, eBike) kein Fahrzeug angezeigt wird und dadurch auch die Fahrzeugerkennung ausbleibt. +Dieser Parameter bewirkt, dass bei Ladegeräten, die ohne "Fahrzeug" betrieben werden (z. B. Wärmepumpe, eBike) kein Fahrzeug angezeigt wird und dadurch auch die Fahrzeugerkennung ausbleibt. In Zusammenhang mit diesem Parameter kann auch ein Icon vergeben werden (siehe [`vehicle.icon`](/docs/reference/configuration/vehicles#icon)), welches dann am Ladepunkt angezeigt wird. diff --git a/docs/reference/configuration/hems.md b/docs/reference/configuration/hems.md index 247e1c5425..1187f680ee 100644 --- a/docs/reference/configuration/hems.md +++ b/docs/reference/configuration/hems.md @@ -141,7 +141,7 @@ Um dies zu verhindern, sollte die Geräte ID vom bisherigen System übernommen w Bietet Unterstützung für den SMA Sunny Home Manager 2.0 (SHM). -Durch die Integration können die [Ladepunkte](loadpoints) dem SHM hinzugefügt werden und somit z.B. für dessen Steuerung berücksichtigt werden. +Durch die Integration können die [Ladepunkte](loadpoints) dem SHM hinzugefügt werden und somit z. B. für dessen Steuerung berücksichtigt werden. **Beispiel**: diff --git a/docs/reference/configuration/index.md b/docs/reference/configuration/index.md index c39461932a..3e54714f4a 100644 --- a/docs/reference/configuration/index.md +++ b/docs/reference/configuration/index.md @@ -6,11 +6,11 @@ sidebar_position: 1 evcc benötigt eine Konfigurationsdatei in der die Installation beschrieben wird. Ohne diese Datei kann evcc nicht genutzt werden. Die Datei selbst ist im [YAML](https://de.wikipedia.org/wiki/YAML) Format geschrieben. Dieses Format definiert eine Syntax wodurch eine strukturierte Datenstruktur in Textform erstellt werden kann. -Zur Bearbeitung bzw. Erstellung der Konfigurationsdatei empfehlen wir einen Texteditor zu verwenden, welcher die YAML Synthax beherrscht und damit Fehler aufzeigen kann, z.B. [VS Code](https://code.visualstudio.com) mit der [YAML Erweiterung](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). +Zur Bearbeitung bzw. Erstellung der Konfigurationsdatei empfehlen wir einen Texteditor zu verwenden, welcher die YAML Synthax beherrscht und damit Fehler aufzeigen kann, z. B. [VS Code](https://code.visualstudio.com) mit der [YAML Erweiterung](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). Die Konfigurationsdatei hat standardmäßig den Namen `evcc.yaml` und ist entweder im gleichen Verzeichnis wie das Programm selbst abzulegen, oder bei Linux-Systemen unter `/etc/evcc.yaml`. -Wenn die Konfigurationsdatei nicht gefunden wird, kann diese über einen Parameter beim Aufruf evcc übergeben werden: z.B. `evcc -c /home/evcc.yaml` +Wenn die Konfigurationsdatei nicht gefunden wird, kann diese über einen Parameter beim Aufruf evcc übergeben werden: z. B. `evcc -c /home/evcc.yaml` ### Struktur @@ -93,7 +93,7 @@ _Loadpoints_ (Ladepunkte) beschreiben die Ladeinfrastruktur und kombinieren vorh ### Chargers -_Chargers_ (Wallboxen) beinhaltet eine Liste von Wallboxen und deren Eigenschaften, z.B. wie sie angesprochen werden. +_Chargers_ (Wallboxen) beinhaltet eine Liste von Wallboxen und deren Eigenschaften, z. B. wie sie angesprochen werden. [Weiterlesen...](./configuration/chargers) diff --git a/docs/reference/configuration/loadpoints.md b/docs/reference/configuration/loadpoints.md index 790d6f701d..3f37d7a3b3 100644 --- a/docs/reference/configuration/loadpoints.md +++ b/docs/reference/configuration/loadpoints.md @@ -16,7 +16,7 @@ loadpoints: mode: pv # charge mode (off, now, minpv, pv) ``` -Referenzen sind hierbei immer die Werte des Parameters `name` (z.B. `wallbox`) in der jeweiligen Gerätekonfiguration. +Referenzen sind hierbei immer die Werte des Parameters `name` (z. B. `wallbox`) in der jeweiligen Gerätekonfiguration. Im folgenden werden nun alle möglichen Parameter erklärt. @@ -73,7 +73,7 @@ Wobei hier der Wert `charge` dem Wert eines `name` Parameters in der [Strommessg Beim Anschluss eines Fahrzeugs an den Ladepunkt wird damit immer davon ausgegangen dass dieses Fahrzeug angeschlossen wurde. Die automatische Fahrzeugerkennung wird umgangen. -Falls doch ausnahmsweise ein anderes Fahrzeug angeschlossen wurde (z.B. Gastfahrzeug) lässt sich dies im Anschluss manuell zuweisen. +Falls doch ausnahmsweise ein anderes Fahrzeug angeschlossen wurde (z. B. Gastfahrzeug) lässt sich dies im Anschluss manuell zuweisen. **Beispiel**: @@ -279,7 +279,6 @@ delay: 10m --- - ### `phases` :::note veraltet in yaml diff --git a/docs/reference/configuration/log.md b/docs/reference/configuration/log.md index 507892efda..80ecdaa2b9 100644 --- a/docs/reference/configuration/log.md +++ b/docs/reference/configuration/log.md @@ -41,7 +41,7 @@ Definiert den Detailgrad der Protokollierung für verschiedene evcc Komponenten - `lp-X`: Der jeweilige Ladepunkt, wobei `X` in der Reihenfolge der Konfiguration der [`loadpoints`](loadpoints) (Ladepunkte) durchnummeriert ist, beginnend bei `1` - `sma`: Die SMA HEMS Komponente, falls der SMA Sunnay Home Manager 2.0 per [`hems`](hems) eingebunden ist - _`fahrzeug`_: Jedes definierte [`vehicle`](vehicles) (Fahrzeug), hier ist der jeweilige Wert des Parameters [`type`](vehicles#type) (bzw. des templates) anzugeben. -- Darüber hinaus können je nach Anwendungsfall noch weitere Komponenten spezifiziert werden (z.B. `cache`, `db`, `influx`, `mqtt`, ...) +- Darüber hinaus können je nach Anwendungsfall noch weitere Komponenten spezifiziert werden (z. B. `cache`, `db`, `influx`, `mqtt`, ...) **Mögliche Werte jede Komponente**: Identisch zu den Werten von [`log`](#log) diff --git a/docs/reference/configuration/modbusproxy.md b/docs/reference/configuration/modbusproxy.md index f0ceec49c0..5fb3c307d5 100644 --- a/docs/reference/configuration/modbusproxy.md +++ b/docs/reference/configuration/modbusproxy.md @@ -6,7 +6,7 @@ sidebar_position: 17 _modbusproxy_ ist eine Liste von Geräten welche für Drittsysteme via Modbus TCP im Netzwerk freigeben werden. -Einige Geräte lassen nur eine sehr beschränkte Anzahl an Modbus TCP Clients zu. Im ungünstigsten Fall nur genau eine einzige Verbindung wie z.B. bei SolarEdge-Komponenten. Aber auch bei seriellen Modbus RTU RS485-Bussystemen ist ohnehin immer nur ein Master erlaubt. +Einige Geräte lassen nur eine sehr beschränkte Anzahl an Modbus TCP Clients zu. Im ungünstigsten Fall nur genau eine einzige Verbindung wie z. B. bei SolarEdge-Komponenten. Aber auch bei seriellen Modbus RTU RS485-Bussystemen ist ohnehin immer nur ein Master erlaubt. Mit Hilfe von `modbusproxy` ist es möglich, evcc zusätzlich als Modbus-Proxy einzurichten welcher die bestehenden Modbus-Verbindungen mit weiteren Systemen teilen kann. Damit kommuniziert evcc direkt mit dem Gerät, weitere Systeme aber stattdessen mit evcc, welches die Kommunikationverbindungen bündelt und stellvertretend an das Zielgerät weiterreicht. @@ -28,7 +28,7 @@ modbusproxy: ``` :::info -Die Proxy-Funktion unterstützt _eingehend_ (d.h. von Drittsystemen wie z.B. Hausautomation, Logger) ausschließlich Modbus TCP. +Die Proxy-Funktion unterstützt _eingehend_ (d.h. von Drittsystemen wie z. B. Hausautomation, Logger) ausschließlich Modbus TCP. _Ausgehend_ in Richtung des abzufragenden Gerätes (z. B. Wechselrichter, Energiezähler) wird das Protokoll ggf. entsprechend der Zielgerätekonfiguration übersetzt. ::: diff --git a/docs/reference/configuration/vehicles.mdx b/docs/reference/configuration/vehicles.mdx index 987466337b..1857b2e24d 100644 --- a/docs/reference/configuration/vehicles.mdx +++ b/docs/reference/configuration/vehicles.mdx @@ -204,7 +204,7 @@ Markiert dass ein Fahrzeug nicht mit stufenloser Ladestrombegrenzung geregelt we Diese Einstellung sollte für folgende Kombination genutzt werden: - Fahrzeug kann nur in ganzen Ampere-Schritten regeln -- Wallbox kann feiner aufgelöste Ladestromvorgaben (z.B. 1 mA) verarbeiten. +- Wallbox kann feiner aufgelöste Ladestromvorgaben (z. B. 1 mA) verarbeiten. In dieser Kombination kann es vorkommen, dass bei Änderungen von wenigen mA der Phasenstrom für die Regelung unerwartet um 1A verändert wird. Die Regelung fängt dann ggf. an zu schwingen. Dieses Feature beschränkt auch die Regelung auf grobe 1A-Stufen. diff --git a/docs/reference/modbus.md b/docs/reference/modbus.md index 78fbcb8f08..5033b9ce07 100644 --- a/docs/reference/modbus.md +++ b/docs/reference/modbus.md @@ -128,8 +128,8 @@ Die Definition eines Registers benötigt folgende Parameter: Weitere zulässige Parameter einer manuellen Konfiguration sind: -- `scale`: Fließkommazahl, die zur Konvertierung von gelesenen Werten (z.B. W in kW oder umgekehrt) verwendet werden kann. Dieser Wert wird mit dem gelesenen und decodierten Rohwert multipliziert. -- `timeout`: modbus timeout. Ohne Einheit ist der Wertt in ns, ansonsten Einheit mit angeben, z.B. 10s für 10 Sekunden. +- `scale`: Fließkommazahl, die zur Konvertierung von gelesenen Werten (z. B. W in kW oder umgekehrt) verwendet werden kann. Dieser Wert wird mit dem gelesenen und decodierten Rohwert multipliziert. +- `timeout`: modbus timeout. Ohne Einheit ist der Wertt in ns, ansonsten Einheit mit angeben, z. B. 10s für 10 Sekunden. **Beispiel**: @@ -145,7 +145,7 @@ scale: -1.0 # floating point factor applied to result, e.g. for kW to W conversi timeout: 2s # timeout, without unit in ns ``` -Bei den `int32s/uint32s` Dekodierungen wird die Wortreihenfolge vertauscht und sind z.B. bei E3/DC Geräten nützlich. +Bei den `int32s/uint32s` Dekodierungen wird die Wortreihenfolge vertauscht und sind z. B. bei E3/DC Geräten nützlich. ### Schreiben von Registern @@ -165,7 +165,7 @@ register: ### Gesamtbeispiel -Ein vollständiges Beispiel für einen custom Charger mit modbus Interface (hier ein Phoenix EM-CP-PP-ETH mit der IP-Adresse 192.168.1.10) könnte z.B. so aussehen: +Ein vollständiges Beispiel für einen custom Charger mit modbus Interface (hier ein Phoenix EM-CP-PP-ETH mit der IP-Adresse 192.168.1.10) könnte z. B. so aussehen: **Beispiel**: diff --git a/docs/tariffs.mdx b/docs/tariffs.mdx index f6b5bc0b49..760824c1a6 100644 --- a/docs/tariffs.mdx +++ b/docs/tariffs.mdx @@ -76,7 +76,7 @@ From To Price/Cost ## Börsenstrompreise Du hast einen Vertrag der nach Börsenpreisen berechnet wird? -Für viele Anbieter haben wir eine eigene Schnittstelle angebunden (z.B. [Awattar](#awattar) oder [Tibber](#tibber)). +Für viele Anbieter haben wir eine eigene Schnittstelle angebunden (z. B. [Awattar](#awattar) oder [Tibber](#tibber)). Die Liste aller verfügbaren Anbieter findest du im Abschnitt [Dynamischer Strompreis](#dynamischer-strompreis). ### Gebühren und Steuern @@ -91,8 +91,8 @@ tariffs: type: template template: energy-charts-api bzn: DE-LU # Gebotszone, siehe https://api.energy-charts.info/#/prices/day_ahead_price_price_get - charges: 0.22 # Fester Aufschlag pro kWh (z.B. 20ct Netzentgelt, 2ct Gebühren) - tax: 0.19 # Prozentualer Aufschlag (z.B. 19% MwSt.) + charges: 0.22 # Fester Aufschlag pro kWh (z. B. 20ct Netzentgelt, 2ct Gebühren) + tax: 0.19 # Prozentualer Aufschlag (z. B. 19% MwSt.) ``` Die Schnittstelle liefert die Börsenpreise in Euro ohne lokale Gebühren oder Steuern. @@ -186,7 +186,7 @@ In diesem Beispiel betragen die Gebühren im Juni um 4 Uhr 0,1467 DKK/kWh. ## Dynamischer Strompreis -### Eigenes Plugin +### Eigenes Plugin {#plugin} Über mit dem Plugin Mechanismus kann eine eigene Tarif-Quelle angebunden werden. diff --git a/docs/tariffs/_dynamischer_strompreis.mdx b/docs/tariffs/_dynamischer_strompreis.mdx index 7d1270bfb9..3eef613e3f 100644 --- a/docs/tariffs/_dynamischer_strompreis.mdx +++ b/docs/tariffs/_dynamischer_strompreis.mdx @@ -1,4 +1,4 @@ -### Eigenes Plugin +### Eigenes Plugin {#plugin} Über mit dem Plugin Mechanismus kann eine eigene Tarif-Quelle angebunden werden. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/devices/heating.mdx b/i18n/en/docusaurus-plugin-content-docs/current/devices/heating.mdx index b02daaa5e7..ee7dc95caf 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/devices/heating.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/devices/heating.mdx @@ -136,7 +136,7 @@ This code example contains some redundancies. We will later provide templates for easier configuration of common hardware constellations. ::: -In addition to `setmode` and `getmode`, you can optionally add the current temperature (`temp`) [via Plugin](/docs/reference/plugins). +In addition to `setmode` and `getmode`, you can optionally add the current temperature (`temp`) [via Plugin](./plugins). This is only used for display. evcc does not use this value for regulation. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/tariffs.mdx b/i18n/en/docusaurus-plugin-content-docs/current/tariffs.mdx index 8a37733763..d48dfb7a7e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/tariffs.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/tariffs.mdx @@ -192,7 +192,7 @@ In this example the grid fee is 0.1467 DKK/kWh at 4am in June. ## Dynamic electricity price -### Custom Plugin +### Custom Plugin {#plugin} Use the plugin mechanism to connect a custom tariff source. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/tariffs/_dynamic_electricity_price.mdx b/i18n/en/docusaurus-plugin-content-docs/current/tariffs/_dynamic_electricity_price.mdx index 628811fe0d..48e5d77f9b 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/tariffs/_dynamic_electricity_price.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/tariffs/_dynamic_electricity_price.mdx @@ -1,4 +1,4 @@ -### Custom Plugin +### Custom Plugin {#plugin} Use the plugin mechanism to connect a custom tariff source.