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/17] 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 81132dae9..bf746f133 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/17] 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 bf746f133..1b6299930 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/17] 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 1b6299930..aadeafa91 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/17] 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 aadeafa91..01d58cf40 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/17] 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 01d58cf40..45b4bafbe 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/17] 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 45b4bafbe..d5e0e4402 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 000000000..c682888e8 --- /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/17] 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 d5e0e4402..6d8d3decb 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/17] 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 6d8d3decb..2c99ced01 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 c682888e8..000000000 --- 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 000000000..5b34068fb --- /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 53f7645a4..a7cc7438a 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/17] 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 2c99ced01..f79124cc6 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/17] 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 b2d6de306..343cd7430 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 f79124cc6..723739392 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 d98147d04..92c7f1e0b 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/17] 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 723739392..007056348 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/17] 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 007056348..d182c3e1d 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/17] 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 d182c3e1d..e661d95f7 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 888226c5b..aeffe9542 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/17] 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 fa2009f12..d8b1cc780 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 e661d95f7..b31957f52 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 5d9f8289d..fd83eeb49 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 104b018ee..984bba5ff 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 c4ddbd6e7..285c604fb 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 7fa27f692..b1ec1d50a 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/17] 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 984bba5ff..ab76719de 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/17] 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 60c35d8e7..916a35fa0 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 ac5503a04..7e3dadc4e 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 7e2f2a2b5..a2aaded04 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 632725333..ee6dd507f 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 88eb07bf1..19d98cc55 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 6b723aca2..08a71f3fb 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/17] 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 ee6dd507f..eb99ba16f 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**: