Skip to content

Add documentation for valid plugin #912

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Oct 24, 2025
Merged

Add documentation for valid plugin #912

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 89 additions & 67 deletions docs/devices/plugins.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
sidebar_position: 6
---

import Tag from '@site/src/components/Tag';
import Tag from "@site/src/components/Tag";

# Plugins

Expand All @@ -15,7 +15,6 @@ Plugins können für folgende Kategorien verwendet werden:
- `tariff`: [Tarife, Vorhersagen](../tariffs)
- `circuit`: [Lastmanagement](../features/loadmanagement)


Zusätzlich können Plugins auch für die in [Messaging](/docs/reference/configuration/messaging) beschriebenen Endpunkte zum Versenden von Lifecycle-Events genutzt werden.

## Übersicht
Expand All @@ -35,6 +34,7 @@ Neben diesen Integrations-Plugins, gibt es noch Helfer-Plugins, die Zusatzfunkti
- [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 angeschlossenen (_plugged_) und ladenden (_charging_) Zustand zu einem einzigen Ladestatus zu kombinieren.
- [Valid Plugin](#valid) - Meta-Plugin um Plugin-Werte basierend auf einer booleschen Validierung bereitzustellen.

### Syntax

Expand Down Expand Up @@ -78,7 +78,7 @@ 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.
Die volle Syntax und Möglichkeiten finden sich in der jq-Dokumentation.
- `quote`: Boolean-Wert, der die Eingabedaten in Anführungszeichen einschließt, bevor sie an jq weitergegeben werden. Dies ermöglicht es jq, unquotierte Strings (z. B. von MQTT) zu verarbeiten. Bei einem MQTT-Wert wie `Charging` kann man `quote: true` und `jq: '. == "Charging"'` verwenden.
- `unpack`: Konvertiert Werte aus anderen Zahlenrepräsentationen, z. B. `hex`.
- `decode`: Dekodiert Binärformate wie `uint32`, `float32` etc.
Expand All @@ -98,34 +98,34 @@ Je nach Gerät ([`meter`](#meter), [`charger`](#charger) oder [`vehicle`](#vehic
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
* `ext`: weiterer Zähler, bspw. für Lastmanagement oder Datenerfassung
- `grid`: Netzzähler
- `pv`: PV Zähler
- `battery`: Hausbatteriezähler
- `charge`: Zähler für die Ladeleistung der Wallbox
- `aux`: Verbrauchszähler für intelligente Verbraucher
- `ext`: weiterer Zähler, bspw. für Lastmanagement oder Datenerfassung

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

Jedoch unterstützen nicht alle Metertypen alle Pluginattribute:

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

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

| Attribut | Typ | Erfordert | Kontext | Beschreibung |
|-----------|---------------------|-----------|----------------|---------------------------|
| power | float | ja | alle | Aktuelle Leistung in W |
| energy | float | nein | alle | Zählerstand in kWh |
| maxpower | int | nein | `pv` (hybrid) | Maximale AC-Leistung in W |
| soc | int | nein | `battery` | Ladestand in % |
| capacity | float | nein | `battery` | Kapazität in kWh |
| powers | [float,float,float] | nein | alle | Phasenleistungen in W |
| currents | [float,float,float] | nein | alle | Phasenströme in A |
| voltages | [float,float,float] | nein | alle | Phasenspannungen in V |
| Attribut | Typ | Erfordert | Kontext | Beschreibung |
| -------- | ------------------- | --------- | ------------- | ------------------------- |
| power | float | ja | alle | Aktuelle Leistung in W |
| energy | float | nein | alle | Zählerstand in kWh |
| maxpower | int | nein | `pv` (hybrid) | Maximale AC-Leistung in W |
| soc | int | nein | `battery` | Ladestand in % |
| capacity | float | nein | `battery` | Kapazität in kWh |
| powers | [float,float,float] | nein | alle | Phasenleistungen in W |
| currents | [float,float,float] | nein | alle | Phasenströme in A |
| voltages | [float,float,float] | nein | alle | Phasenspannungen in V |

**Beispiel**

Expand All @@ -149,30 +149,30 @@ site:

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

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

### Charger

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

| Attribut | Typ | Erfordert | Beschreibung |
|-------------|---------------------|-----------|-------------------------------------|
| status | string | ja | Status (A..F) |
| enabled | bool | ja | Ist Ladung freigegeben? |
| power | float | nein | Ladeleistung in W |
| energy | float | nein | Zählerstand in kWh |
| identify | string | nein | Aktuelle RFID-Kennung |
| soc | int | nein | Ladestand in % |
| phases | int | nein | Anzahl der physischen Phasen (1..3) |
| powers | [float,float,float] | nein | Phasenleistungen in W |
| currents | [float,float,float] | nein | Phasenströme in A |
| voltages | [float,float,float] | nein | Phasenspannungen in V |
| temp | float | nein | Aktuelle Temperatur in °C (Heizung) |
| templimit | int | nein | Temperaturlimit in °C (Heizung) |
| getmode | int | nein | SG-Ready Modus (Wärmepumpe) |
| Attribut | Typ | Erfordert | Beschreibung |
| --------- | ------------------- | --------- | ----------------------------------- |
| status | string | ja | Status (A..F) |
| enabled | bool | ja | Ist Ladung freigegeben? |
| power | float | nein | Ladeleistung in W |
| energy | float | nein | Zählerstand in kWh |
| identify | string | nein | Aktuelle RFID-Kennung |
| soc | int | nein | Ladestand in % |
| phases | int | nein | Anzahl der physischen Phasen (1..3) |
| powers | [float,float,float] | nein | Phasenleistungen in W |
| currents | [float,float,float] | nein | Phasenströme in A |
| voltages | [float,float,float] | nein | Phasenspannungen in V |
| temp | float | nein | Aktuelle Temperatur in °C (Heizung) |
| templimit | int | nein | Temperaturlimit in °C (Heizung) |
| getmode | int | nein | SG-Ready Modus (Wärmepumpe) |

**Beispiel**

Expand All @@ -195,15 +195,14 @@ chargers:

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

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

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

**Beispiel**

Expand All @@ -224,22 +223,22 @@ chargers:

Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden.

| Attribut | Typ | Erfordert | Beschreibung |
|---------------|---------|-----------|---------------------------------|
| soc | int | ja | Ladestand in % |
| limitsoc | int | nein | Ladelimit in % |
| status | string | nein | Status (A..F) |
| range | int | nein | Reichweite in km |
| odometer | int | nein | Kilometerstand in km |
| climater | bool | nein | Klimatisierung aktiv? |
| getmaxcurrent | float | nein | Maximaler Ladestrom in A |
| finishtime | string | nein | Geplantes Ladeende (RFC3339) |
| Attribut | Typ | Erfordert | Beschreibung |
| ------------- | ------ | --------- | ---------------------------- |
| soc | int | ja | Ladestand in % |
| limitsoc | int | nein | Ladelimit in % |
| status | string | nein | Status (A..F) |
| range | int | nein | Reichweite in km |
| odometer | int | nein | Kilometerstand in km |
| climater | bool | nein | Klimatisierung aktiv? |
| getmaxcurrent | float | nein | Maximaler Ladestrom in A |
| finishtime | string | nein | Geplantes Ladeende (RFC3339) |

**Beispiel**

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

``` yaml
```yaml
vehicles:
- name: Mazda
type: custom
Expand All @@ -250,17 +249,17 @@ vehicles:

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

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

**Beispiel**

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

``` yaml
```yaml
vehicles:
- name: model-y
type: custom
Expand Down Expand Up @@ -357,7 +356,7 @@ auth: # basic authentication
insecure: false # set to true to trust self-signed certificates
jq: .data.tuples[0][1] # parse response json
scale: 0.001 # factor applied to result, e.g. for kW to W conversion
cache: 60s # response cache duration
cache: 60s # response cache duration
timeout: 10s # timeout in golang duration format,
# see https://golang.org/pkg/time/#ParseDuration
```
Expand Down Expand Up @@ -537,3 +536,26 @@ charging:
source: mqtt
topic: openWB/lp/1/boolChargeStat
```

### Valid <Tag label="lesen" category="read" /> {#valid}

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

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

**Beispiel Lesen**:

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

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