Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Refactoring of plugins.md #690

Draft
wants to merge 17 commits into
base: main
Choose a base branch
from
Prev Previous commit
Next Next commit
added labels for read and write
  • Loading branch information
rhuss committed Jan 25, 2025
commit 151a9e93221aa185320da142e406eb67a3a5bc1e
39 changes: 21 additions & 18 deletions docs/reference/plugins.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
sidebar_position: 3
---
import Tag from '@site/src/components/Tag';

# Plugins

Expand All @@ -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:

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -174,15 +175,16 @@ 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 <Tag label="lesen" category="read" /> <Tag label="schreiben" category="write" />


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.

Schaue in die [Modbus Dokumentation](modbus) für weitere Details.

### MQTT
### MQTT <Tag label="lesen" category="read" /> <Tag label="schreiben" category="write" />

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.
Expand All @@ -208,7 +210,7 @@ topic: mbmd/charger/maxcurrent
payload: ${var:%d}
```

### HTTP
### HTTP <Tag label="lesen" category="read" /> <Tag label="schreiben" category="write" />

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.

Expand Down Expand Up @@ -259,7 +261,7 @@ enable:
uri: "http://charger/relay/0?turn={{if .enable}}on{{else}}off{{end}}"
```

### Websocket
### Websocket <Tag label="lesen" category="read" />

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.

Expand All @@ -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} <Tag label="lesen" category="read" />


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

Expand All @@ -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 <Tag label="lesen" category="read" /> <Tag label="schreiben" category="write" />

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:

Expand All @@ -319,7 +322,7 @@ charger:
console.log(maxcurrent);
```

### Shell Script {#shell}
### Shell Script {#shell} <Tag label="lesen" category="read" /> <Tag label="schreiben" category="write" />

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.

Expand All @@ -339,7 +342,7 @@ cmd: /home/user/my-script.sh ${enable:%b} # format boolean enable as 0/1
timeout: 5s
```

### Const
### Const <Tag label="lesen" category="read" />

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.
Expand All @@ -351,7 +354,7 @@ source: const
value: -16247
```

### Calc
### Calc <Tag label="lesen" category="read" />

Das `calc` Plugin erlaubt es mehrere Einzelwerte mathematisch weiterzuverarbeiten:

Expand Down Expand Up @@ -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 <Tag label="lesen" category="read" />

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.
Expand Down
26 changes: 26 additions & 0 deletions src/components/Tag.js
Original file line number Diff line number Diff line change
@@ -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 <span style={style}>{label}</span>;
}