diff --git a/docs/integrations/mqtt-api.md b/docs/integrations/mqtt-api.md index d021ff37a..813e57ce0 100644 --- 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//title`: Ladepunkt-Titel +- `evcc/loadpoints//connected`: Fahrzeug verbunden (true/false) +- `evcc/loadpoints//charging`: lädt gerade (true/false) +- `evcc/loadpoints//enabled`: Ladepunkt aktiviert (true/false) +- `evcc/loadpoints//chargePower`: aktuelle Ladeleistung (W) +- `evcc/loadpoints//chargedEnergy`: geladene Energie in Sitzung (Wh) +- `evcc/loadpoints//chargeDuration`: Ladedauer (ns) +- `evcc/loadpoints//chargeRemainingDuration`: verbleibende Ladedauer (ns) +- `evcc/loadpoints//chargeRemainingEnergy`: verbleibende Energie (Wh) +- `evcc/loadpoints//chargeTotalImport`: Zählerstand Ladezähler (Wh) +- `evcc/loadpoints//vehicleName`: Fahrzeug-Bezeichner +- `evcc/loadpoints//vehicleTitle`: Fahrzeug-Anzeigename +- `evcc/loadpoints//vehicleSoc`: Fahrzeug-SoC (%) +- `evcc/loadpoints//vehicleRange`: Fahrzeug-Reichweite (km) +- `evcc/loadpoints//phasesActive`: aktive Phasen +- `evcc/loadpoints//planActive`: Plan aktiv (true/false) +- `evcc/loadpoints//sessionEnergy`: Sitzungsenergie (Wh) +- `evcc/loadpoints//sessionSolarPercentage`: Eigenerzeugungs-Anteil der Sitzung (%) +- `evcc/loadpoints//smartCostActive`: Smart Cost aktiv (true/false) +- `evcc/loadpoints//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//minSoc`: minimum soc in % (writable) -- `evcc/vehicles//limitSoc`: limit soc in % (writable) -- `evcc/vehicles//planSoc`: plan soc (writable using JSON payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`) - -## Loadpoints - -- `evcc/loadpoints`: number of available loadpoints -- `evcc/loadpoints/`: dynamic state -- `evcc/loadpoints//mode`: charge mode (writable) -- `evcc/loadpoints//minSoc`: minimum SoC (writable) -- `evcc/loadpoints//limitSoc`: limit SoC in % (writable) - only applicable for online vehicles -- `evcc/loadpoints//limitEnergy`: limit energy in kWh (writable) - only applicable for offline vehicles -- `evcc/loadpoints//plan/energy`: plan energy (writable using JSON payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`) -- `evcc/loadpoints//phasesConfigured`: configured phases (writable) -- `evcc/loadpoints//minCurrent`: current minCurrent value (writable) -- `evcc/loadpoints//maxCurrent`: current maxCurrent value (writable) -- `evcc/loadpoints//enableThreshold`: threshold value (writable) -- `evcc/loadpoints//enableDelay`: delay value (s) (writable) -- `evcc/loadpoints//disableThreshold`: threshold value (writable) -- `evcc/loadpoints//disableDelay`: delay value (s) (writable) -- `evcc/loadpoints//batteryboost`: battery boost enabled (writeable: [1/0]) -- `evcc/loadpoints//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//mode`: Lademodus +- `evcc/loadpoints//minSoc`: minimaler SoC +- `evcc/loadpoints//limitSoc`: Limit-SoC in % – nur für Online-Fahrzeuge +- `evcc/loadpoints//limitEnergy`: Limit-Energie in kWh – nur für Offline-Fahrzeuge +- `evcc/loadpoints//planEnergy`: Planenergie (JSON-Payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`) +- `evcc/loadpoints//phasesConfigured`: konfigurierte Phasen +- `evcc/loadpoints//minCurrent`: minimaler Ladestrom +- `evcc/loadpoints//maxCurrent`: maximaler Ladestrom +- `evcc/loadpoints//enableThreshold`: Einschaltschwelle +- `evcc/loadpoints//enableDelay`: Einschaltverzögerung (s) +- `evcc/loadpoints//disableThreshold`: Ausschaltschwelle +- `evcc/loadpoints//disableDelay`: Ausschaltverzögerung (s) +- `evcc/loadpoints//batteryboost`: Battery Boost aktiviert (1/0) +- `evcc/loadpoints//batteryBoostLimit`: Battery Boost SoC-Limit +- `evcc/loadpoints//priority`: Priorität +- `evcc/loadpoints//smartCostLimit`: Smart-Cost-Limit +- `evcc/loadpoints//smartFeedInPriorityLimit`: Einspeise-Prioritäts-Limit +- `evcc/loadpoints//planStrategy`: Planstrategie (JSON) +- `evcc/loadpoints//vehicle`: Fahrzeug setzen (Fahrzeugname) + +### Vehicles {#vehicle-write} + +Fahrzeugnamen siehe `evcc/vehicles`. + +- `evcc/vehicles//minSoc`: minimaler SoC in % +- `evcc/vehicles//limitSoc`: Limit-SoC in % +- `evcc/vehicles//planSoc`: Plan-SoC (JSON-Payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`) +- `evcc/vehicles//planStrategy`: Planstrategie (JSON) 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 index 8558b6d50..9ee80280d 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/integrations/mqtt-api.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/integrations/mqtt-api.md @@ -4,88 +4,114 @@ sidebar_position: 2 # MQTT API -:::note -The documentation is not yet complete. -The most of the data and functions available via the [REST API](./rest-api) are also available via MQTT. -Use tools like [MQTT Explorer](https://mqtt-explorer.com/) to visualize your data. -::: - -The MQTT API has the same structure as the [REST API](./rest-api). -All API IDs (e.g. the loadpoint ID) begin at `1`. - -- `evcc`: root topic -- `evcc/status`: status (`online`/`offline`) -- `evcc/updated`: timestamp of last update - -## Site +All data from the [REST API](./rest-api) endpoint `/api/state` is also published via MQTT. +Lists are converted into individual sub-topics (index starts at `1`). -- `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 +## Read-Only Topics {#read} -## Vehicles +### Site {#site-read} -**Note**: for vehicle names see `evcc/vehicles`. +- `evcc/site/siteTitle`: site title +- `evcc/site/currency`: configured currency +- `evcc/site/homePower`: current home consumption (W) +- `evcc/site/pvPower`: current solar production (W) +- `evcc/site/grid/power`: current grid power (W, positive = import) +- `evcc/site/battery/power`: battery power (W, positive = discharge) +- `evcc/site/battery/soc`: battery state of charge (%) +- `evcc/site/greenShareHome`: self-produced energy share of home consumption (0–1) +- `evcc/site/greenShareLoadpoints`: self-produced energy share of loadpoint consumption (0–1) +- `evcc/site/tariffGrid`: current grid tariff +- `evcc/site/tariffFeedIn`: current feed-in tariff +- `evcc/site/tariffCo2`: current CO₂ intensity +- `evcc/site/batteryGridChargeActive`: battery grid charging active (true/false) -- `evcc/vehicles`: number of vehicles -- `evcc/vehicles//minSoc`: minimum soc in % (writable) -- `evcc/vehicles//limitSoc`: limit soc in % (writable) -- `evcc/vehicles//planSoc`: plan soc (writable using JSON payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`) +### Loadpoints {#loadpoint-read} -## Loadpoints +All loadpoint IDs begin at `1`. - `evcc/loadpoints`: number of available loadpoints -- `evcc/loadpoints/`: dynamic state -- `evcc/loadpoints//mode`: charge mode (writable) -- `evcc/loadpoints//minSoc`: minimum SoC (writable) -- `evcc/loadpoints//limitSoc`: limit SoC in % (writable) - only applicable for online vehicles -- `evcc/loadpoints//limitEnergy`: limit energy in kWh (writable) - only applicable for offline vehicles -- `evcc/loadpoints//plan/energy`: plan energy (writable using JSON payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`) -- `evcc/loadpoints//phasesConfigured`: configured phases (writable) -- `evcc/loadpoints//minCurrent`: current minCurrent value (writable) -- `evcc/loadpoints//maxCurrent`: current maxCurrent value (writable) -- `evcc/loadpoints//enableThreshold`: threshold value (writable) -- `evcc/loadpoints//enableDelay`: delay value (s) (writable) -- `evcc/loadpoints//disableThreshold`: threshold value (writable) -- `evcc/loadpoints//disableDelay`: delay value (s) (writable) -- `evcc/loadpoints//batteryboost`: battery boost enabled (writeable: [1/0]) -- `evcc/loadpoints//priority`: priority value (writable) - -:::note -To set any of the writable values, add a `/set` at the end of the topic for which a -change should be made. - -Example: `mosquitto_pub -t "evcc/loadpoints/1/phasesConfigured/set" -m "3"` to set the number of -configured phases for the first loadpoint to `3`. -::: - -:::info -\*\* Times are in UTC in the following format: `yyyy-mm-ddThh:mm:ssZ` - -Examples: - -`2023-03-05T07:00:00Z` = 5th of March 2023 at 8:00 CET - -`2023-08-17T19:30:00Z` = 17th of August 2023 at 21:30 CEST +- `evcc/loadpoints//title`: loadpoint title +- `evcc/loadpoints//connected`: vehicle connected (true/false) +- `evcc/loadpoints//charging`: currently charging (true/false) +- `evcc/loadpoints//enabled`: charger enabled (true/false) +- `evcc/loadpoints//chargePower`: current charge power (W) +- `evcc/loadpoints//chargedEnergy`: energy charged in session (Wh) +- `evcc/loadpoints//chargeDuration`: charge duration (ns) +- `evcc/loadpoints//chargeRemainingDuration`: remaining charge duration (ns) +- `evcc/loadpoints//chargeRemainingEnergy`: remaining energy (Wh) +- `evcc/loadpoints//chargeTotalImport`: charge meter total (Wh) +- `evcc/loadpoints//vehicleName`: vehicle identifier +- `evcc/loadpoints//vehicleTitle`: vehicle display name +- `evcc/loadpoints//vehicleSoc`: vehicle SoC (%) +- `evcc/loadpoints//vehicleRange`: vehicle range (km) +- `evcc/loadpoints//phasesActive`: active phases +- `evcc/loadpoints//planActive`: plan currently active (true/false) +- `evcc/loadpoints//sessionEnergy`: session energy (Wh) +- `evcc/loadpoints//sessionSolarPercentage`: self-produced energy share of session (%) +- `evcc/loadpoints//smartCostActive`: smart cost currently active (true/false) +- `evcc/loadpoints//effectivePriority`: effective priority + +:::warning More Topics +This list is incomplete. +For all available topics, use [MQTT Explorer](https://mqtt-explorer.com/). ::: -:::note -\*\* Support for empty values: -The following strings are recognized as empty values: - -- `nil` -- `null` -- `none` -- `-` - -Examples: - -- `evcc/site/batteryGridChargeLimit/set`: 'none' - -To set the price threshold for charging the battery to 'none' or to delete it. -::: +## Writable Topics {#write} + +To change writable topics, append `/set` to the topic and send the new value. + +```bash +mosquitto_pub -t "evcc/loadpoints/1/phasesConfigured/set" -m "3" +``` + +Times are in UTC using the format `yyyy-mm-ddThh:mm:ssZ`, e.g. `2023-03-05T07:00:00Z` (= 5 March 2023, 8:00 CET). + +The following strings are recognised as empty values: `nil`, `null`, `none`, `-`. +Use these to reset previously set thresholds: + +```bash +mosquitto_pub -t "evcc/site/batteryGridChargeLimit/set" -m "none" +``` + +### Site {#site-write} + +- `evcc/site/prioritySoc`: battery priority SoC +- `evcc/site/bufferSoc`: battery buffer SoC +- `evcc/site/bufferStartSoc`: battery buffer start SoC +- `evcc/site/residualPower`: grid residual power +- `evcc/site/batteryGridChargeLimit`: smart charging cost limit +- `evcc/site/batteryDischargeControl`: enable/disable battery discharge control (true/false) +- `evcc/site/batteryMode`: external battery mode (`normal`, `hold`, `charge`) — directly controls all controllable batteries, overrules other evcc modes, resets after 60 s +- `evcc/site/smartCostLimit`: smart cost limit for all loadpoints +- `evcc/site/smartFeedInPriorityLimit`: feed-in priority limit for all loadpoints + +### Loadpoints {#loadpoint-write} + +- `evcc/loadpoints//mode`: charge mode +- `evcc/loadpoints//minSoc`: minimum SoC +- `evcc/loadpoints//limitSoc`: limit SoC in % — only applicable for online vehicles +- `evcc/loadpoints//limitEnergy`: limit energy in kWh — only applicable for offline vehicles +- `evcc/loadpoints//planEnergy`: plan energy (JSON payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`) +- `evcc/loadpoints//phasesConfigured`: configured phases +- `evcc/loadpoints//minCurrent`: minimum current value +- `evcc/loadpoints//maxCurrent`: maximum current value +- `evcc/loadpoints//enableThreshold`: threshold value +- `evcc/loadpoints//enableDelay`: delay value (s) +- `evcc/loadpoints//disableThreshold`: threshold value +- `evcc/loadpoints//disableDelay`: delay value (s) +- `evcc/loadpoints//batteryboost`: battery boost enabled (1/0) +- `evcc/loadpoints//batteryBoostLimit`: battery boost SoC limit +- `evcc/loadpoints//priority`: priority value +- `evcc/loadpoints//smartCostLimit`: smart cost limit +- `evcc/loadpoints//smartFeedInPriorityLimit`: feed-in priority limit +- `evcc/loadpoints//planStrategy`: plan strategy (JSON) +- `evcc/loadpoints//vehicle`: set vehicle by name + +### Vehicles {#vehicle-write} + +For vehicle names see `evcc/vehicles`. + +- `evcc/vehicles//minSoc`: minimum SoC in % +- `evcc/vehicles//limitSoc`: limit SoC in % +- `evcc/vehicles//planSoc`: plan SoC (JSON payload: `{"value": 50, "time": "2023-03-05T07:00:00Z"}`) +- `evcc/vehicles//planStrategy`: plan strategy (JSON)