From 01d9929863ebf012193c87b0df05ac4dc7447e33 Mon Sep 17 00:00:00 2001 From: Michael Geers Date: Fri, 24 Oct 2025 11:00:59 +0200 Subject: [PATCH] Add documentation for valid plugin MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the new valid plugin introduced in evcc-io/evcc#21759. The valid plugin allows separating validity from actual values, which is particularly useful for integrations like ioBroker that provide these separately. When the validation returns false, the value is considered unavailable. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/devices/plugins.mdx | 156 ++++++++++-------- .../current/devices/plugins.mdx | 154 +++++++++-------- 2 files changed, 177 insertions(+), 133 deletions(-) diff --git a/docs/devices/plugins.mdx b/docs/devices/plugins.mdx index b5a8c69a4d..fceb31e1e5 100644 --- a/docs/devices/plugins.mdx +++ b/docs/devices/plugins.mdx @@ -2,7 +2,7 @@ sidebar_position: 6 --- -import Tag from '@site/src/components/Tag'; +import Tag from "@site/src/components/Tag"; # Plugins @@ -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 @@ -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 @@ -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. @@ -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** @@ -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** @@ -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** @@ -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 @@ -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 @@ -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 ``` @@ -537,3 +536,26 @@ charging: source: mqtt topic: openWB/lp/1/boolChargeStat ``` + +### Valid {#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. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx b/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx index 8780e1facc..cde7a37587 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx @@ -2,7 +2,7 @@ sidebar_position: 6 --- -import Tag from '../../../../../src/components/Tag'; +import Tag from "../../../../../src/components/Tag"; # Plugins @@ -15,7 +15,6 @@ Plugins can be used for the following categories: - `tariff`: [Tariffs, forecasts](../tariffs) - `circuit`: [Load management](../features/loadmanagement) - Additionally, plugins can also be used for the endpoints described in [Messaging](/docs/reference/configuration/messaging) for sending lifecycle events. ## Overview @@ -35,6 +34,7 @@ In addition to these integration plugins, there are also helper plugins that pro - [Const Plugin](#const) - Special plugin that simply returns a constant value. - [Calc Plugin](#calc) - Meta-plugin for arithmetically linking outputs from other plugins. - [Combined Plugin](#combined) - Meta-plugin specifically for `charger` to combine the boolean status values for the connected (_plugged_) and charging (_charging_) state into a single charging status. +- [Valid Plugin](#valid) - Meta-plugin for providing plugin values based on boolean validation. ### Syntax @@ -78,7 +78,7 @@ Possible parameters for data extraction are: - `regex`: A regular expression to extract values from the received text. - `jq`: A [jq](https://jqlang.github.io/jq/)-expression to extract values from JSON structures. -The full syntax and possibilities can be found in the jq documentation. + The full syntax and possibilities can be found in the jq documentation. - `quote`: Boolean value that wraps the input data in quotes before passing it to jq. This allows jq to process unquoted strings (e.g. from MQTT). For an MQTT value like `Charging`, you can use `quote: true` and `jq: '. == "Charging"'`. - `unpack`: Converts values from other number representations, e.g. `hex`. - `decode`: Decodes binary formats like `uint32`, `float32` etc. @@ -98,34 +98,34 @@ Depending on the device ([`meter`](#meter), [`charger`](#charger) or [`vehicle`] Power meters are configured in the configuration section [`meters`](/docs/reference/configuration/meters). Meters defined under `meters:` can be used at various places within the `site` configuration: -* `grid`: Grid meter -* `pv`: PV meter -* `battery`: Home battery meter -* `charge`: Meter for the charging power of the wallbox -* `aux`: Consumption meter for intelligent consumers -* `ext`: Additional meter, e.g. for load management or data collection +- `grid`: Grid meter +- `pv`: PV meter +- `battery`: Home battery meter +- `charge`: Meter for the charging power of the wallbox +- `aux`: Consumption meter for intelligent consumers +- `ext`: Additional meter, e.g. for load management or data collection `power` is the only mandatory attribute that must be present in every `meter` definition, all other attributes are optional. However, not all meter types support all plugin attributes: -* `limitsoc` and `batterymode` are used exclusively for battery meters (i.e. for `meter` referenced in `site.battery`). -* `currents`, `voltages` and `powers` are phase attributes that must be configured with exactly three plugin configurations each (in a YAML array) and can be used for grid meters (`grid`) and wallboxes (`charge`). +- `limitsoc` and `batterymode` are used exclusively for battery meters (i.e. for `meter` referenced in `site.battery`). +- `currents`, `voltages` and `powers` are phase attributes that must be configured with exactly three plugin configurations each (in a YAML array) and can be used for grid meters (`grid`) and wallboxes (`charge`). The following tables contain all attributes that can be provided by plugins when configured for `meter`. When using the plugins, it's also important that they return the correct data type. To convert to the required data type, the pipelines described in [Reading](#reading) can be used. -| Attribute | Type | Required | Context | Description | -|-----------|---------------------|----------|---------------|--------------------------| -| power | float | yes | all | Current power in W | -| energy | float | no | all | Meter reading in kWh | -| maxpower | int | no | `pv` (hybrid) | Maximum AC power in W | -| soc | int | no | `battery` | State of charge in % | -| capacity | float | no | `battery` | Capacity in kWh | -| powers | [float,float,float] | no | all | Phase powers in W | -| currents | [float,float,float] | no | all | Phase currents in A | -| voltages | [float,float,float] | no | all | Phase voltages in V | +| Attribute | Type | Required | Context | Description | +| --------- | ------------------- | -------- | ------------- | --------------------- | +| power | float | yes | all | Current power in W | +| energy | float | no | all | Meter reading in kWh | +| maxpower | int | no | `pv` (hybrid) | Maximum AC power in W | +| soc | int | no | `battery` | State of charge in % | +| capacity | float | no | `battery` | Capacity in kWh | +| powers | [float,float,float] | no | all | Phase powers in W | +| currents | [float,float,float] | no | all | Phase currents in A | +| voltages | [float,float,float] | no | all | Phase voltages in V | **Example** @@ -149,30 +149,30 @@ site: In addition to the attributes that plugins provide for reading evaluation, the following attributes are used by evcc to trigger actions: -| Attribute | Type | Required | Context | Description | -|--------------|------|-----------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| limitsoc | int | no | `battery` | Set charging target for battery in %. The charging target is calculated from the configured `MinSoc`, `MaxSoc` and the current state of charge (attribute `soc`). | -| batterymode | int | no | `battery` | Set charging mode directly (1: normal, 2: hold, 3: charge) | +| Attribute | Type | Required | Context | Description | +| ----------- | ---- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| limitsoc | int | no | `battery` | Set charging target for battery in %. The charging target is calculated from the configured `MinSoc`, `MaxSoc` and the current state of charge (attribute `soc`). | +| batterymode | int | no | `battery` | Set charging mode directly (1: normal, 2: hold, 3: charge) | ### Charger Wallboxes and chargers have the following attributes that can be read: -| Attribute | Type | Required | Description | -|-------------|---------------------|----------|------------------------------------| -| status | string | yes | Status (A..F) | -| enabled | bool | yes | Is charging enabled? | -| power | float | no | Charging power in W | -| energy | float | no | Meter reading in kWh | -| identify | string | no | Current RFID identifier | -| soc | int | no | State of charge in % | -| phases | int | no | Number of physical phases (1..3) | -| powers | [float,float,float] | no | Phase powers in W | -| currents | [float,float,float] | no | Phase currents in A | -| voltages | [float,float,float] | no | Phase voltages in V | -| temp | float | no | Current temperature in °C (heating)| -| templimit | int | no | Temperature limit in °C (heating) | -| getmode | int | no | SG-Ready mode (heat pump) | +| Attribute | Type | Required | Description | +| --------- | ------------------- | -------- | ----------------------------------- | +| status | string | yes | Status (A..F) | +| enabled | bool | yes | Is charging enabled? | +| power | float | no | Charging power in W | +| energy | float | no | Meter reading in kWh | +| identify | string | no | Current RFID identifier | +| soc | int | no | State of charge in % | +| phases | int | no | Number of physical phases (1..3) | +| powers | [float,float,float] | no | Phase powers in W | +| currents | [float,float,float] | no | Phase currents in A | +| voltages | [float,float,float] | no | Phase voltages in V | +| temp | float | no | Current temperature in °C (heating) | +| templimit | int | no | Temperature limit in °C (heating) | +| getmode | int | no | SG-Ready mode (heat pump) | **Example** @@ -195,15 +195,14 @@ chargers: In addition to read-only values, actions can also be triggered or configuration values set via plugins: -| Attribute | Type | Required | Description | -|-----------------|-------|----------|-----------------------------------------------------| -| enable | bool | yes | Enable / disable charging | -| maxcurrent | int | yes | Set maximum charging current in A | -| maxcurrentmilis | float | no | Set maximum charging current in A | -| phases1p3p | int | no | Perform phase switching (requires `tos: true`) | -| wakeup | bool | no | Wake up vehicle | -| setmode | int | no | Change SG-Ready mode (1: reduced, 2: normal, 3: boost)| - +| Attribute | Type | Required | Description | +| --------------- | ----- | -------- | ------------------------------------------------------ | +| enable | bool | yes | Enable / disable charging | +| maxcurrent | int | yes | Set maximum charging current in A | +| maxcurrentmilis | float | no | Set maximum charging current in A | +| phases1p3p | int | no | Perform phase switching (requires `tos: true`) | +| wakeup | bool | no | Wake up vehicle | +| setmode | int | no | Change SG-Ready mode (1: reduced, 2: normal, 3: boost) | **Example** @@ -224,22 +223,22 @@ chargers: Vehicle parameters can also be read via plugins. -| Attribute | Type | Required | Description | -|---------------|--------|----------|-------------------------------| -| soc | int | yes | State of charge in % | -| limitsoc | int | no | Charge limit in % | -| status | string | no | Status (A..F) | -| range | int | no | Range in km | -| odometer | int | no | Odometer reading in km | -| climater | bool | no | Climate control active? | -| getmaxcurrent | float | no | Maximum charging current in A | -| finishtime | string | no | Planned charging end (RFC3339)| +| Attribute | Type | Required | Description | +| ------------- | ------ | -------- | ------------------------------ | +| soc | int | yes | State of charge in % | +| limitsoc | int | no | Charge limit in % | +| status | string | no | Status (A..F) | +| range | int | no | Range in km | +| odometer | int | no | Odometer reading in km | +| climater | bool | no | Climate control active? | +| getmaxcurrent | float | no | Maximum charging current in A | +| finishtime | string | no | Planned charging end (RFC3339) | **Example** In the following example, the current range of the vehicle is read from MQTT messages: -``` yaml +```yaml vehicles: - name: Mazda type: custom @@ -250,17 +249,17 @@ vehicles: Additionally, special commands can be sent to the vehicle via plugins: -| Attribute | Type | Required | Description | -|--------------|------|----------|--------------------------------| -| wakeup | bool | no | Wake up vehicle | -| chargeenable | bool | no | Start/stop charging process | +| Attribute | Type | Required | Description | +| ------------ | ---- | -------- | --------------------------------- | +| wakeup | bool | no | Wake up vehicle | +| chargeenable | bool | no | Start/stop charging process | | maxcurrent | int | no | Set maximum charging current in A | **Example** To wake up a car via an HTTP ping to send further queries, the HTTP plugin can be used as in the following example: -``` yaml +```yaml vehicles: - name: model-y type: custom @@ -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 ``` @@ -537,3 +536,26 @@ charging: source: mqtt topic: openWB/lp/1/boolChargeStat ``` + +### Valid {#valid} + +The `valid` plugin allows providing plugin values based on boolean validation. +It separates the validity of a value from its actual content. +If the validation returns `false`, the value is considered unavailable. + +This is particularly useful for integrations like ioBroker that provide validity and value separately. + +**Reading Example**: + +```yaml +source: valid +valid: + source: mqtt + topic: iobroker/wallbox/power/valid +value: + source: mqtt + topic: iobroker/wallbox/power/value +``` + +In this example, the value is only used when the `valid` topic returns `true`. +If it returns `false`, the value is marked as unavailable.