diff --git a/docs/devices/plugins.mdx b/docs/devices/plugins.mdx index db701e852..7f4e13210 100644 --- a/docs/devices/plugins.mdx +++ b/docs/devices/plugins.mdx @@ -382,7 +382,20 @@ Schaue in die [Modbus Dokumentation](/docs/reference/modbus) für weitere Detail 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)). + +**Parameter (Lesen)**: + +| Parameter | Typ | Erfordert | Beschreibung | +| --------- | -------- | --------- | ------------------------------------------------------------------------ | +| topic | string | ja | MQTT Topic zum Lesen | +| timeout | duration | nein | Maximales Alter empfangener Werte | +| scale | float | nein | Skalierungsfaktor für Ergebnis (z. B. 0.001 für Wh zu kWh Konvertierung) | + +Das Plugin gibt einen Fehler zurück, wenn innerhalb der `timeout` Dauer kein neuer Wert empfangen wurde. +Wenn `timeout` nicht gesetzt ist, werden Werte beliebigen Alters akzeptiert, sobald die erste Nachricht empfangen wurde. +Es wird empfohlen, einen Timeout zu setzen, um zu erkennen, wenn die Quelle keine aktuellen Daten mehr liefert. + +Für die Datenextraktion stehen die unter [Lesen](#lesen) beschriebenen Pipeline-Parameter zur Verfügung (`regex`, `jq`, `quote`, etc.). **Beispiel Lesen**: @@ -393,6 +406,13 @@ timeout: 30s # don't accept values older than timeout scale: 0.001 # factor applied to result, e.g. for Wh to kWh conversion ``` +**Parameter (Schreiben)**: + +| Parameter | Typ | Erfordert | Beschreibung | +| --------- | ------ | --------- | ----------------------------------------------------------------------- | +| topic | string | ja | MQTT Topic zum Schreiben | +| payload | string | nein | Payload-Template (verwendet Wert im Standardformat, wenn nicht gesetzt) | + 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. diff --git a/docs/faq.mdx b/docs/faq.mdx index 66868439b..e11f22c17 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -191,6 +191,12 @@ Dort werden dann auch Fehlerhinweise gegeben, die den Start des Service verhinde Mittels der oben genannten Tests kann man diesen Fehlern auf den Grund gehen und sie beheben. Erst wenn alles fehlerfrei ist, sollte der Service gestartet werden. +### MQTT plugin gibt `outdated` Warnung + +Bei der Nutzung des [MQTT plugins](devices/plugins#mqtt) kann über den `timeout` parameter gesteuert werden, wie lange ein Wert der per MQTT erhalten wurde, gültig ist. +Wenn kein neuer Wert innerhalb dieser Zeit kommt, ist der Wert für evcc `outdated`. +Wichtig ist, dass hier eine Einheit mit angegeben werden muss, also z.B. `timeout: 30s` + ## Laden ### Auto lädt beim Einstecken obwohl kein Überschuss vorhanden ist 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 4253b7a1f..a8235cded 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx @@ -382,7 +382,20 @@ See the [Modbus Documentation](/docs/reference/modbus) for more details. The `mqtt` plugin enables reading values via MQTT topics. This is particularly useful for power meters, e.g. when they already provide their data via MQTT. See the [MBMD Documentation](https://github.com/volkszaehler/mbmd) for an example of how to get Modbus measurement data into MQTT. -The plugin also offers the ability to read or parse JSON data structures via jq-like queries (see [HTTP plugin](#http)). + +**Parameters (Reading)**: + +| Parameter | Type | Required | Description | +| --------- | -------- | -------- | --------------------------------------------------------------- | +| topic | string | yes | MQTT topic to read from | +| timeout | duration | no | Maximum age of received values | +| scale | float | no | Scaling factor for result (e.g. 0.001 for Wh to kWh conversion) | + +The plugin returns an error if no new value has been received within the `timeout` duration. +If `timeout` is not set, values of any age are accepted once the first message has been received. +It is recommended to set a timeout to detect when the source is no longer providing current data. + +For data extraction, the pipeline parameters described under [Reading](#reading) are available (`regex`, `jq`, `quote`, etc.). **Reading Example**: @@ -393,6 +406,13 @@ timeout: 30s # don't accept values older than timeout scale: 0.001 # factor applied to result, e.g. for Wh to kWh conversion ``` +**Parameters (Writing)**: + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ---------------------------------------------------------- | +| topic | string | yes | MQTT topic to write to | +| payload | string | no | Payload template (uses value in default format if not set) | + For write access, the data is provided with the `payload` attribute. If this parameter is missing from the configuration, the value is written in the default format. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/faq.mdx b/i18n/en/docusaurus-plugin-content-docs/current/faq.mdx index 57ab5832c..cd3af5b77 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/faq.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/faq.mdx @@ -195,6 +195,12 @@ It's not uncommon for errors to be overlooked in the configuration, saved, and t To help diagnose the problem, run `evcc` directly from the terminal - this should hopefully give you a better idea of what's going on. +### MQTT plugin shows `outdated` warning + +When using the [MQTT plugin](devices/plugins#mqtt), you can control how long a value received via MQTT remains valid using the `timeout` parameter. +If no new value arrives within this time, the value is considered `outdated` by evcc. +It is important to specify a unit here, e.g. `timeout: 30s`. + ## Charging ### Vehicle starts charging when plugged in, even though there's no surplus