Merge branch 'main' of github.com:evcc-io/docs

naltatis · naltatis · commit e45b0e15ae2e · 2026-03-13T19:42:19.000+01:00
diff --git a/docs/devices/plugins.mdx b/docs/devices/plugins.mdx
@@ -37,6 +37,7 @@ Zusätzlich können Plugins auch für die in [Messaging](/docs/reference/configu
 - [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.
 - [Const Plugin](#const) - Spezielles Plugin das einfach einen konstanten Wert zurückliefert.
+- [Error Plugin](#error) - Spezielles Plugin das einen bekannten Fehlerwert zurückgibt.
 - [Convert Plugin](#convert) - Meta-Plugin zur Datentyp-Konvertierung beim Schreiben (z. B. float zu int).
 - [Delta Plugin](#delta) - Meta-Plugin zur Umwandlung von absoluten Werten in Änderungswerte (Deltas) beim Schreiben.
 - [Ignore Plugin](#ignore) - Meta-Plugin zum Unterdrücken spezifischer Fehlermeldungen.
@@ -95,6 +96,19 @@ Mögliche Parameter für die Datenextraktion sind:
 - `unpack`: Konvertiert Werte aus anderen Zahlenrepräsentationen, z. B. `hex`.
 - `decode`: Dekodiert Binärformate wie `uint32`, `float32` etc.
 
+##### Bekannte Fehlerwerte {#known-errors}
+
+[HTTP](#http)-, [MQTT](#mqtt)- und [Websocket](#websocket)-Plugins können spezielle Fehlerwerte als String zurückgeben.
+evcc erkennt diese und wandelt sie in interne Fehlercodes um, anstatt sie als Daten zu behandeln.
+Das ist z. B. nützlich für eigene Fahrzeugintegrationen, bei denen die Datenquelle den Zustand des Fahrzeugs kennt.
+
+- `ErrAsleep` — Fahrzeug schläft. evcc kann entscheiden, ob das Fahrzeug geweckt werden soll.
+- `ErrMustRetry` — Vorgang soll erneut versucht werden (z. B. bei Rate-Limiting).
+- `ErrNotAvailable` — Wert ist nicht verfügbar. evcc behandelt dies als permanenten Fehler bis zum nächsten Neustart.
+
+Wenn ein Plugin z. B. den String `ErrAsleep` als Antwort liefert, erzeugt evcc intern den entsprechenden Fehler.
+Das [Error Plugin](#error) nutzt denselben Mechanismus, um einen festen Fehlerwert als Konstante zurückzugeben.
+
 #### Schreiben
 
 Beim Schreiben können Parameter in der Konfiguration durch Platzhalter ersetzt werden.
@@ -780,6 +794,8 @@ 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.
 
+Für die Datenextraktion stehen die unter [Lesen](#lesen) beschriebenen Pipeline-Parameter zur Verfügung (`regex`, `jq`, `quote`, etc.).
+
 **Beispiel Lesen**:
 
 ```yaml
@@ -871,6 +887,25 @@ source: const
 value: -16247
 ```
 
+### Error <Tag label="lesen" category="read" /> {#error}
+
+Das `error` Plugin gibt immer einen [bekannten Fehlerwert](#known-errors) zurück.
+Es ist nützlich, um ein nicht implementiertes Attribut als explizit nicht verfügbar zu kennzeichnen.
+
+**Parameter**:
+
+| Parameter | Typ    | Erfordert | Beschreibung                                                    |
+| --------- | ------ | --------- | --------------------------------------------------------------- |
+| error     | string | ja        | Fehlerwert (`ErrAsleep`, `ErrMustRetry` oder `ErrNotAvailable`) |
+
+**Beispiel**:
+
+```yaml
+soc:
+  source: error
+  error: ErrNotAvailable
+```
+
 ### Convert <Tag label="schreiben" category="write" /> {#convert}
 
 Das `convert` Plugin konvertiert Datentypen beim Schreiben.
diff --git a/docs/integrations/mqtt-api.md b/docs/integrations/mqtt-api.md
@@ -4,85 +4,114 @@ sidebar_position: 2
 
 # MQTT API
 
-:::note
-Die Dokumentation ist noch nicht vollständig.
-Die meisten der über die [REST API](./rest-api) verfügbaren Daten und Funktionen sind auch via MQTT verfügbar.
-Nutze Tools wie [MQTT Explorer](https://mqtt-explorer.com/) um die Daten zu visualisieren.
+Alle Daten des [REST API](./rest-api) Endpunkts `/api/state` werden auch per MQTT veröffentlicht.
+Listen werden dabei in einzelne Sub-Topics aufgelöst (Index beginnt bei `1`).
+
+## Lesbare Topics {#read}
+
+### Site {#site-read}
+
+- `evcc/site/siteTitle`: Seitentitel
+- `evcc/site/currency`: konfigurierte Währung
+- `evcc/site/homePower`: aktueller Hausverbrauch (W)
+- `evcc/site/pvPower`: aktuelle PV-Erzeugung (W)
+- `evcc/site/grid/power`: aktuelle Netzleistung (W, positiv = Bezug)
+- `evcc/site/battery/power`: Batterieleistung (W, positiv = Entladung)
+- `evcc/site/battery/soc`: Batterie-Ladestand (%)
+- `evcc/site/greenShareHome`: Eigenerzeugungs-Anteil am Hausverbrauch (0–1)
+- `evcc/site/greenShareLoadpoints`: Eigenerzeugungs-Anteil am Ladepunktverbrauch (0–1)
+- `evcc/site/tariffGrid`: aktueller Netztarif
+- `evcc/site/tariffFeedIn`: aktuelle Einspeisevergütung
+- `evcc/site/tariffCo2`: aktuelle CO₂-Intensität
+- `evcc/site/batteryGridChargeActive`: Netzladen der Batterie aktiv (true/false)
+
+### Loadpoints {#loadpoint-read}
+
+Alle Loadpoint IDs beginnen bei `1`.
+
+- `evcc/loadpoints`: Anzahl der verfügbaren Ladepunkte
+- `evcc/loadpoints/<id>/title`: Ladepunkt-Titel
+- `evcc/loadpoints/<id>/connected`: Fahrzeug verbunden (true/false)
+- `evcc/loadpoints/<id>/charging`: lädt gerade (true/false)
+- `evcc/loadpoints/<id>/enabled`: Ladepunkt aktiviert (true/false)
+- `evcc/loadpoints/<id>/chargePower`: aktuelle Ladeleistung (W)
+- `evcc/loadpoints/<id>/chargedEnergy`: geladene Energie in Sitzung (Wh)
+- `evcc/loadpoints/<id>/chargeDuration`: Ladedauer (ns)
+- `evcc/loadpoints/<id>/chargeRemainingDuration`: verbleibende Ladedauer (ns)
+- `evcc/loadpoints/<id>/chargeRemainingEnergy`: verbleibende Energie (Wh)
+- `evcc/loadpoints/<id>/chargeTotalImport`: Zählerstand Ladezähler (Wh)
+- `evcc/loadpoints/<id>/vehicleName`: Fahrzeug-Bezeichner
+- `evcc/loadpoints/<id>/vehicleTitle`: Fahrzeug-Anzeigename
+- `evcc/loadpoints/<id>/vehicleSoc`: Fahrzeug-SoC (%)
+- `evcc/loadpoints/<id>/vehicleRange`: Fahrzeug-Reichweite (km)
+- `evcc/loadpoints/<id>/phasesActive`: aktive Phasen
+- `evcc/loadpoints/<id>/planActive`: Plan aktiv (true/false)
+- `evcc/loadpoints/<id>/sessionEnergy`: Sitzungsenergie (Wh)
+- `evcc/loadpoints/<id>/sessionSolarPercentage`: Eigenerzeugungs-Anteil der Sitzung (%)
+- `evcc/loadpoints/<id>/smartCostActive`: Smart Cost aktiv (true/false)
+- `evcc/loadpoints/<id>/effectivePriority`: effektive Priorität
+
+:::warning Weitere Topics
+Diese Liste ist nicht vollständig.
+Alle verfügbaren Topics kannst du mit [MQTT Explorer](https://mqtt-explorer.com/) einsehen.
 :::
 
-Die MQTT API folgt der [REST API](./rest-api) Struktur.
-Alle API IDs (z. B. die Loadpoint ID) beginnen bei `1`.
-
-- `evcc`: root topic
-- `evcc/status`: status (`online`/`offline`)
-- `evcc/updated`: timestamp of last update
-
-## Site
-
-- `evcc/site`: site dynamic state
-- `evcc/site/prioritySoc`: battery priority SoC (writable)
-- `evcc/site/bufferSoc`: battery buffer SoC (writable)
-- `evcc/site/bufferStartSoc`: battery buffer start SoC (writable)
-- `evcc/site/residualPower`: grid residual power (writable)
-- `evcc/site/batteryGridChargeLimit`: smart charging cost limit (previously known as "cheap" tariff) (writable)
-- `evcc/site/batteryDischargeControl`: enable/disable battery discharge control (true/false) (writable)
-- `evcc/site/batteryMode`: external battery mode (writable: `normal`, `hold`, `charge`) - directly controls all controllable batteries, overrules other evcc modes, resets after 60s
-
-## Vehicles
-
-**Note**: for vehicle names see `evcc/vehicles`.
-
-- `evcc/vehicles`: number of vehicles
-- `evcc/vehicles/<name>/minSoc`: minimum soc in % (writable)
-- `evcc/vehicles/<name>/limitSoc`: limit soc in % (writable)
-- `evcc/vehicles/<name>/planSoc`: plan soc (writable using JSON payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`)
-
-## Loadpoints
-
-- `evcc/loadpoints`: number of available loadpoints
-- `evcc/loadpoints/<id>`: dynamic state
-- `evcc/loadpoints/<id>/mode`: charge mode (writable)
-- `evcc/loadpoints/<id>/minSoc`: minimum SoC (writable)
-- `evcc/loadpoints/<id>/limitSoc`: limit SoC in % (writable) - only applicable for online vehicles
-- `evcc/loadpoints/<id>/limitEnergy`: limit energy in kWh (writable) - only applicable for offline vehicles
-- `evcc/loadpoints/<id>/plan/energy`: plan energy (writable using JSON payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`)
-- `evcc/loadpoints/<id>/phasesConfigured`: configured phases (writable)
-- `evcc/loadpoints/<id>/minCurrent`: current minCurrent value (writable)
-- `evcc/loadpoints/<id>/maxCurrent`: current maxCurrent value (writable)
-- `evcc/loadpoints/<id>/enableThreshold`: threshold value (writable)
-- `evcc/loadpoints/<id>/enableDelay`: delay value (s) (writable)
-- `evcc/loadpoints/<id>/disableThreshold`: threshold value (writable)
-- `evcc/loadpoints/<id>/disableDelay`: delay value (s) (writable)
-- `evcc/loadpoints/<id>/batteryboost`: battery boost enabled (writeable: [1/0])
-- `evcc/loadpoints/<id>/priority`: priority value (writable)
-
-:::note
-Um schreibbare Einstellungen durchzuführen, muss ein `/set` am Ende des Topics hinzugefügt werden an welches der neue Wert gesendet wird.
-Beispiel: `mosquitto_pub -t "evcc/loadpoints/1/phasesConfigured/set" -m "3"` um die Anzahl der netzseitigen Phasen am 1. Ladepunkt auf `3` festzulegen.
-:::
-
-:::info
-\*\* Zeitangabe efolgt in UTC im Format `yyyy-mm-ddThh:mm:ssZ`
-
-Beispiele:
-
-`2023-03-05T07:00:00Z` = 5. März 2023 um 8:00 Uhr MEZ
-
-`2023-08-17T19:30:00Z` = 17. August 2023 um 21:30 Uhr MESZ
-:::
-
-:::note
-\*\* Unterstützung leerer Werte:
-Folgende Zeichenfolgen werden als leere Werte erkannt:
-
-- `nil`
-- `null`
-- `none`
-- `-`
-
-Beispiele:
-
-- `evcc/site/batteryGridChargeLimit/set`: 'none'
-
-Um die Preisschwelle zum Laden der Batterie auf 'none' zu setzten, bzw. zu löschen.
-:::
+## Schreibbare Topics {#write}
+
+Um schreibbare Topics zu ändern, hänge `/set` an das Topic an und sende den neuen Wert.
+
+```bash
+mosquitto_pub -t "evcc/loadpoints/1/phasesConfigured/set" -m "3"
+```
+
+Zeitangaben erfolgen in UTC im Format `yyyy-mm-ddThh:mm:ssZ`, z. B. `2023-03-05T07:00:00Z` (= 5. März 2023, 8:00 MEZ).
+
+Folgende Zeichenfolgen werden als leere Werte erkannt: `nil`, `null`, `none`, `-`.
+Damit lassen sich z. B. gesetzte Schwellenwerte zurücksetzen:
+
+```bash
+mosquitto_pub -t "evcc/site/batteryGridChargeLimit/set" -m "none"
+```
+
+### Site {#site-write}
+
+- `evcc/site/prioritySoc`: Batterie-Prioritäts-SoC
+- `evcc/site/bufferSoc`: Batterie-Puffer-SoC
+- `evcc/site/bufferStartSoc`: Batterie-Puffer-Start-SoC
+- `evcc/site/residualPower`: Netz-Residualleistung
+- `evcc/site/batteryGridChargeLimit`: Preisschwelle für Netzladen
+- `evcc/site/batteryDischargeControl`: Entladeregelung aktivieren/deaktivieren (true/false)
+- `evcc/site/batteryMode`: externer Batteriemodus (`normal`, `hold`, `charge`) – steuert alle regelbaren Batterien direkt, überschreibt andere evcc-Modi, wird nach 60 s zurückgesetzt
+- `evcc/site/smartCostLimit`: Smart-Cost-Limit für alle Ladepunkte
+- `evcc/site/smartFeedInPriorityLimit`: Einspeise-Prioritäts-Limit für alle Ladepunkte
+
+### Loadpoints {#loadpoint-write}
+
+- `evcc/loadpoints/<id>/mode`: Lademodus
+- `evcc/loadpoints/<id>/minSoc`: minimaler SoC
+- `evcc/loadpoints/<id>/limitSoc`: Limit-SoC in % – nur für Online-Fahrzeuge
+- `evcc/loadpoints/<id>/limitEnergy`: Limit-Energie in kWh – nur für Offline-Fahrzeuge
+- `evcc/loadpoints/<id>/planEnergy`: Planenergie (JSON-Payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`)
+- `evcc/loadpoints/<id>/phasesConfigured`: konfigurierte Phasen
+- `evcc/loadpoints/<id>/minCurrent`: minimaler Ladestrom
+- `evcc/loadpoints/<id>/maxCurrent`: maximaler Ladestrom
+- `evcc/loadpoints/<id>/enableThreshold`: Einschaltschwelle
+- `evcc/loadpoints/<id>/enableDelay`: Einschaltverzögerung (s)
+- `evcc/loadpoints/<id>/disableThreshold`: Ausschaltschwelle
+- `evcc/loadpoints/<id>/disableDelay`: Ausschaltverzögerung (s)
+- `evcc/loadpoints/<id>/batteryboost`: Battery Boost aktiviert (1/0)
+- `evcc/loadpoints/<id>/batteryBoostLimit`: Battery Boost SoC-Limit
+- `evcc/loadpoints/<id>/priority`: Priorität
+- `evcc/loadpoints/<id>/smartCostLimit`: Smart-Cost-Limit
+- `evcc/loadpoints/<id>/smartFeedInPriorityLimit`: Einspeise-Prioritäts-Limit
+- `evcc/loadpoints/<id>/planStrategy`: Planstrategie (JSON)
+- `evcc/loadpoints/<id>/vehicle`: Fahrzeug setzen (Fahrzeugname)
+
+### Vehicles {#vehicle-write}
+
+Fahrzeugnamen siehe `evcc/vehicles`.
+
+- `evcc/vehicles/<name>/minSoc`: minimaler SoC in %
+- `evcc/vehicles/<name>/limitSoc`: Limit-SoC in %
+- `evcc/vehicles/<name>/planSoc`: Plan-SoC (JSON-Payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`)
+- `evcc/vehicles/<name>/planStrategy`: Planstrategie (JSON)
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx b/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx
@@ -37,6 +37,7 @@ Additionally, plugins can also be used for the endpoints described in [Messaging
 - [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.
 - [Const Plugin](#const) - Special plugin that simply returns a constant value.
+- [Error Plugin](#error) - Special plugin that returns a known error value.
 - [Convert Plugin](#convert) - Meta-plugin for data type conversion when writing (e.g., float to int).
 - [Delta Plugin](#delta) - Meta-plugin for converting absolute values to delta/increment values when writing.
 - [Ignore Plugin](#ignore) - Meta-plugin for suppressing specific error messages.
@@ -95,6 +96,19 @@ Possible parameters for data extraction are:
 - `unpack`: Converts values from other number representations, e.g. `hex`.
 - `decode`: Decodes binary formats like `uint32`, `float32` etc.
 
+##### Known Error Values {#known-errors}
+
+[HTTP](#http), [MQTT](#mqtt), and [Websocket](#websocket) plugins can return special error strings.
+evcc recognises these and converts them into internal error codes instead of treating them as data.
+This is useful e.g. for custom vehicle integrations where the data source knows the vehicle's state.
+
+- `ErrAsleep` — Vehicle is asleep. evcc may choose to wake up the vehicle and retry.
+- `ErrMustRetry` — Operation should be retried (e.g. due to rate limiting).
+- `ErrNotAvailable` — Value is not available. evcc treats this as a permanent error until the next restart.
+
+If a plugin returns the string `ErrAsleep` as its response, evcc generates the corresponding internal error.
+The [Error Plugin](#error) uses the same mechanism to return a fixed error value as a constant.
+
 #### Writing
 
 When writing, parameters in the configuration can be replaced by placeholders.
@@ -780,6 +794,8 @@ The `websocket` plugin provides a WebSocket listener.
 It also includes the ability to read or parse JSON data structures via jq-like queries.
 This can be used, for example, to receive data from Volkszähler's push server.
 
+For data extraction, the pipeline parameters described in [Reading](#reading) are available (`regex`, `jq`, `quote`, etc.).
+
 **Reading Example**:
 
 ```yaml
@@ -871,6 +887,25 @@ source: const
 value: -16247
 ```
 
+### Error <Tag label="read" category="read" /> {#error}
+
+The `error` plugin always returns a [known error value](#known-errors).
+It is useful to explicitly mark an unimplemented attribute as not available.
+
+**Parameters**:
+
+| Parameter | Type   | Required | Description                                                    |
+| --------- | ------ | -------- | -------------------------------------------------------------- |
+| error     | string | yes      | Error value (`ErrAsleep`, `ErrMustRetry` or `ErrNotAvailable`) |
+
+**Example**:
+
+```yaml
+soc:
+  source: error
+  error: ErrNotAvailable
+```
+
 ### Convert <Tag label="write" category="write" /> {#convert}
 
 The `convert` plugin converts data types when writing.
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/integrations/mqtt-api.md b/i18n/en/docusaurus-plugin-content-docs/current/integrations/mqtt-api.md
