Skip to content

Commit 3face09

Browse files
naltatisnaltatis
authored
Messaging: explain and update vars (#1015)
1 parent 44c109f commit 3face09

File tree

2 files changed

+219
-276
lines changed
  • docs/reference/configuration
  • i18n/en/docusaurus-plugin-content-docs/current/reference/configuration

2 files changed

+219
-276
lines changed

‎docs/reference/configuration/messaging.md‎

Lines changed: 109 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -51,167 +51,85 @@ title: Charge started
5151
### `msg`
5252

5353
`msg` definiert den Text für den Nachrichteninhalt.
54-
Im Text können verschiedene Variablen im Format `${<Variablenname>}` zur Anzeige von evcc Informationen verwendet werden.
54+
Im Text können verschiedene Variablen zur Anzeige von evcc Informationen verwendet werden.
55+
56+
Es gibt zwei Schreibweisen:
57+
58+
- **Einfach**: `${<Variablenname>}` — z. B. `${vehicleTitle}`, mit optionaler Formatierung wie `${pvPower:%.1fk}`
59+
- **Go-Template**: `{{.variablenname}}` — ermöglicht Berechnungen, Bedingungen und [sprig-Funktionen](http://masterminds.github.io/sprig/)
60+
5561
:::note
5662
Bei Nutzung der Variablen ist auf die korrekte Schreibweise (groß/klein) zu achten!
5763
:::
5864

59-
**Nützliche Auswahl zur Nutzung in evcc Benachrichtungen**:
65+
#### Verfügbare Variablen {#variables}
6066

61-
| msg Variable | Beschreibung |
62-
| ------------------------ | ------------------------------------------------------------------------------------- |
63-
| `${chargedEnergy:%.1fk}` | Geladene Energiemenge in kWh |
64-
| `${chargeDuration}` | Dauer der Ladezeit |
65-
| `${connectedDuration}` | Dauer der Wallbox Verbindung |
66-
| `${loadpoint}` | Nummer des [`loadpoints`](loadpoints) (Ladepunkt) 1,2... |
67-
| `${mode}` | Aktiver Lademodus (vgl. [`mode`](loadpoints#mode) des [`loadpoints`](loadpoints)) |
68-
| `${pvPower:%.1fk}` | Aktuell gemessene PV Leistung in kW |
69-
| `${title}` | Ladepunkt: Text des [`loadpoints`](loadpoints) [`title`](loadpoints#title) Parameters |
70-
| `${vehicleTitle}` | Fahrzeug: Text des [`vehicles`](vehicles) [`title`](vehicles#title) Parameters |
67+
Die verfügbaren Variablen entsprechen den Daten der evcc REST API unter `http://evcc.local:7070/api/state`.
68+
Beim Versand einer Nachricht werden die Daten des jeweiligen Ladepunkts und die globalen Daten in einer flachen Struktur zusammengeführt.
69+
D. h. sowohl globale Werte (z. B. `pvPower`, `grid.Power`) als auch ladepunktspezifische Werte (z. B. `mode`, `chargedEnergy`, `vehicleTitle`) sind direkt verfügbar.
7170

72-
**Beispiel**:
71+
Eine [Auswahl nützlicher Variablen](#variable-reference) findest du am Ende dieser Seite.
72+
73+
**Beispiel** (einfache Syntax):
7374

7475
```yaml
75-
# Message examples using evcc variables
76-
# start
77-
msg: Wallbox ${title} started charging ${vehicleTitle} in ${mode} mode
78-
# stop
79-
msg: Wallbox ${title} finished charging ${vehicleTitle} with ${chargedEnergy:%.1fk}kWh in ${chargeDuration}
80-
# connect
81-
msg: ${vehicleTitle} connected on wallbox ${title} at ${pvPower:%.1fk}kW PV
82-
# disconnect
83-
msg: ${vehicleTitle} disconnected of wallbox ${title} after ${connectedDuration}
76+
messaging:
77+
events:
78+
start:
79+
title: Laden gestartet
80+
msg: >-
81+
${title} lädt ${vehicleTitle} im Modus ${mode}
82+
stop:
83+
title: Laden beendet
84+
msg: >-
85+
${title}: ${vehicleTitle} geladen mit ${chargedEnergy:%.1fk}kWh in ${chargeDuration}.
86+
Sonnenanteil: ${sessionSolarPercentage:%.0f}%
87+
connect:
88+
title: Fahrzeug verbunden
89+
msg: >-
90+
${vehicleTitle} verbunden an ${title} bei ${pvPower:%.1fk}kW PV
91+
disconnect:
92+
title: Fahrzeug getrennt
93+
msg: >-
94+
${vehicleTitle} getrennt von ${title} nach ${connectedDuration}
8495
```
8596

8697
:::note
8798
Zum Rendern der `msg`-Texte kann auch die [go-Text-Template](https://pkg.go.dev/text/template)-Syntax in Kombination mit [sprig-Funktionen](http://masterminds.github.io/sprig/) genutzt werden.
99+
Damit sind Berechnungen (z. B. Umrechnung W → kW) und Bedingungen möglich.
88100

89101
```yaml
90-
# Message config using evcc go-text-template rendering, evcc variables and sprig-functions
91102
messaging:
92103
events:
93-
start: # charge start event
94-
title: Charge of {{.vehicleTitle}} started
104+
start:
105+
title: "{{.vehicleTitle}}: Laden gestartet"
95106
msg: |
96-
Wallbox {{.title}} started charging {{.vehicleTitle}} in {{ toString .mode | upper }} mode.
97-
--------------------------
98-
evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
99-
Netz-Leistung: {{round (divf .grid.Power 1000) 3 }} kW
100-
Solar-Leistung: {{round (divf .pvPower 1000) 3 }} kW
101-
Eigenverbrauch: {{round (divf .homePower 1000) 3 }} kW
102-
{{if .batteryConfigured}}Batteriespeicher-Status: {{round (divf .battery.Power 1000) 3 }} kW ({{.battery.Soc }} %){{end}}
103-
stop: # charge stop event
104-
title: Charge of {{.vehicleTitle}} finished
107+
{{.title}} lädt {{.vehicleTitle}} im Modus {{ toString .mode | upper }}.
108+
PV: {{round (divf .pvPower 1000) 1 }} kW
109+
Netz: {{round (divf .grid.Power 1000) 1 }} kW
110+
{{if .battery}}Batterie: {{round (divf .battery.Power 1000) 1 }} kW ({{.battery.Soc }} %){{end}}
111+
stop:
112+
title: "{{.vehicleTitle}}: Laden beendet"
105113
msg: |
106-
Wallbox {{.title}} finished charging {{.vehicleTitle}}
107-
with {{round (divf .chargedEnergy 1000) 2 }} kWh in {{.chargeDuration}}.
108-
--------------------------
109-
evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
110-
Netz-Leistung: {{round (divf .grid.Power 1000) 3 }} kW
111-
Solar-Leistung: {{round (divf .pvPower 1000) 3 }} kW
112-
Eigenverbrauch: {{round (divf .homePower 1000) 3 }} kW
113-
{{if .batteryConfigured}}Batteriespeicher-Status: {{round (divf .battery.Power 1000) 3 }} kW ({{.battery.Soc }} %){{end}}
114-
connect: # vehicle connect event
115-
title: "{{.vehicleTitle}} connected on wallbox {{.title}}"
114+
{{.title}}: {{round (divf .chargedEnergy 1000) 1 }} kWh in {{.chargeDuration}}.
115+
Sonnenanteil: {{round .sessionSolarPercentage 0 }}%
116+
{{- if .sessionPrice}}
117+
Kosten: {{round .sessionPrice 2 }} {{.currency}} ({{round .sessionPricePerKWh 2 }} {{.currency}}/kWh)
118+
{{- end}}
119+
connect:
120+
title: "{{.vehicleTitle}} verbunden"
116121
msg: |
117-
{{.vehicleTitle}} connected on wallbox {{.title}} at {{round (divf .pvPower 1000) 2 }} kW PV.
118-
--------------------------
119-
evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
120-
Netz-Leistung: {{round (divf .grid.Power 1000) 3 }} kW
121-
Solar-Leistung: {{round (divf .pvPower 1000) 3 }} kW
122-
Eigenverbrauch: {{round (divf .homePower 1000) 3 }} kW
123-
{{if .batteryConfigured}}Batteriespeicher-Status: {{round (divf .battery.Power 1000) 3 }} kW ({{.battery.Soc }} %){{end}}
124-
disconnect: # vehicle connected event
125-
title: "{{.vehicleTitle}} disconnected of wallbox {{.title}}"
122+
{{.vehicleTitle}} verbunden an {{.title}}.
123+
Ladestand: {{.vehicleSoc }}% ({{.vehicleRange }} km)
124+
PV: {{round (divf .pvPower 1000) 1 }} kW
125+
disconnect:
126+
title: "{{.vehicleTitle}} getrennt"
126127
msg: |
127-
{{.vehicleTitle}} disconnected of wallbox {{.title}} after {{.connectedDuration}}.
128-
--------------------------
129-
evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
130-
Netz-Leistung: {{round (divf .grid.Power 1000) 3 }} kW
131-
Solar-Leistung: {{round (divf .pvPower 1000) 3 }} kW
132-
Eigenverbrauch: {{round (divf .homePower 1000) 3 }} kW
133-
{{if .batteryConfigured}}Batteriespeicher-Status: {{round (divf .battery.Power 1000) 3 }} kW ({{.battery.Soc }} %){{end}}
128+
{{.vehicleTitle}} getrennt von {{.title}} nach {{.connectedDuration}}.
134129
```
135130

136131
:::
137132

138-
**Liste aller von evcc bereitgestellten Variablen**:
139-
140-
Die von evcc bereitgestellten Variablen (siehe auch /api/state) müssen als regex-Funktion `${<Variablenname>}` oder im go-Template-Format `{{<Variablenname>}}` im Text der Meldung definiert werden. Mehrere Variablen im Meldungstext sind möglich.
141-
142-
- Site
143-
- Konfiguration
144-
- [`siteTitle`](site) - Hauptüberschrift der evcc App (_string_)
145-
- `prioritySoc` - Mindest-Füllstand der Powerwall in Prozent, vor [PV mode](loadpoints#mode) Freigabe (_integer_)
146-
- Information
147-
- `batteryConfigured` - Indikator, Hausbatterie/Powerwall-Meter konfiguriert (_bool_)
148-
- `gridConfigured` - Indikator, Smart/Grid-Meter konfiguriert (_bool_)
149-
- `pvConfigured` - Indikator, Solaranlagen/Photovoltaik-Meter konfiguriert (_bool_)
150-
- Infos zum Stromtarif
151-
- [`currency`](tariffs) - Tarif-Währung (_string_)
152-
- [`tariffFeedIn`](tariffs) - PV-Einspeisevergütung pro kWh in der Tarif-Währung (float)
153-
- [`tariffGrid`](tariffs) - Netz-Abnahmepreis pro kWh in der Tarif-Währung (float)
154-
- Meter Infos
155-
- `battery.Power` - Aktuelle Hausbatterie/Powerwall-Leistung in Watt (_float_)
156-
- `battery.Soc` - Aktueller Füllstand der Hausbatterie/Powerwall in Prozent (_integer_)
157-
- `grid.Power` - Aktuelle Netz-Einspeisung(-) oder -Abnahme(+) in Watt (_float_)
158-
- `homePower` - Aktuelle Haus-Abnahmeleistung (ohne Wallboxverbrauch) in Watt (_float_)
159-
- `pvPower` - Aktuelle Solaranlagen-Leistung in Watt (_float_)
160-
- Ladepunkte (loadpoint)
161-
- Konfiguration
162-
- [`loadpoint`](loadpoints) - Laufende Nummer des Ladepunktes (_integer_)
163-
- `maxCurrent` - Maximale Lade-Stromstärke in Ampere (_float_)
164-
- `minCurrent` - Minimale Lade-Stromstärke in Ampere (_float_)
165-
- [`mode`](loadpoints#mode) - Initialer Modus des Ladepunktes nach evcc-Start `off`/`now`/`min`/`pv` (_string_)
166-
- [`phases`](loadpoints#phases) - Initial aktive Anzahl Stromphasen des Ladepunktes nach evcc-Start (_integer_)
167-
- [`title`](loadpoints#title) - Bezeichnung des Ladepunktes in der evcc App (_string_)
168-
- Information
169-
- `activePhases`- Aktuell aktive Anzahl Stromphasen des Ladepunktes (_integer_)
170-
- `chargeCurrent` - Aktuelle Gesamt-Lade-Stromstärke in Ampere (_float_)
171-
- `chargeCurrents` - Aktuelle Lade-Stromstärke pro aktiver Stromphase in Ampere (_float_)
172-
- `chargeDuration` - Ladedauer in Nanosekunden (_integer_)
173-
- `chargePower` - Aktuelle Lade-Leistung in Watt (_float_)
174-
- `chargeRemainingDuration` - Ladezeit in Nanosekunden bis zum Ziel-Füllstand (_integer_)
175-
- `chargeRemainingEnergy` - Notwendige Energie bis zum Ziel-Füllstand in Wh (_float_)
176-
- `chargedEnergy` - Bisher geladene Energie in Wh (_float_)
177-
- `charging` - Indikator, Ladevorgang aktiv (_bool_)
178-
- `enabled` - Indikator, Beladung freigegeben (_bool_)
179-
- `hasVehicle` - Indikator, Fahrzeug-Definitionen sind dem Ladepunkt zugewiesen (_bool_)
180-
- `targetTime` - Zielladezeit in Nanosekunden seit 1970 UTC (_integer_)
181-
- `pvAction` - Kontrollvariable zur PV-Timer Steuerung `enable`/`disable` (_string_)
182-
- `pvRemaining` - Notwendige PV-Restladezeit bei aktivierter Timer Steuerung in Nanosekunden (_integer_)
183-
- Fahrzeuge (vehicles)
184-
- Konfiguration
185-
- [`vehicleName`](vehicles#name) - Name des Fahrzeugs (_string_)
186-
- [`vehicleCapacity`](vehicles#capacity)- Kapazität der Fahrzeugbatterie in Wh (_float_)
187-
- [`vehicleTitle`](vehicles#title) - Bezeichnung des Fahrzeugs in der evcc App (_string_)
188-
- Information
189-
- `climater` - Status der Fahrzeug-Klimatisierung `on`/`off`/`heating`/`cooling` (_string_)
190-
- `connected` - Indikator, Fahrzeug am Ladepunkt angeschlossen (_bool_)
191-
- `connectedDuration` - Anschlußdauer des Fahrzeugs in Nanosekunden (_integer_)
192-
- `vehicleOdometer` - Aktueller Kilometerstand des Fahrzeugs in km (_float_)
193-
- `vehiclePresent` - Indikator, evcc kann auf die Fahrzeugdaten zugreifen (_bool_)
194-
- `vehicleRange` - Aktuelle Reichweite des Fahrzeugs in km (_float_)
195-
- `vehicleSoc` - Aktueller Füllstand der Fahrzeugbatterie in Prozent (_integer_)
196-
- Infos zur Einsparungseffizienz
197-
- `savingsAmount` - Summe der evcc-Einsparung (_float_)
198-
- `savingsEffectivePrice` - Kalkulierter Einsparungs-Preis (_float_)
199-
- `savingsGridCharged` - Geladene Netzenergie in Wh (_float_)
200-
- `savingsSelfConsumptionCharged` - Geladene Sonnenenergie in Wh (_float_)
201-
- `savingsSelfConsumptionPercent` - Anteil der geladenen Sonnenenergie in Wh (_float_)
202-
- `savingsSince` - Zeitperiode der Ersparnisberechnung in Nanosekunden (_integer_)
203-
- `savingsTotalCharged` - Geladene Gesamtenergie in Wh (_float_)
204-
- Infos zur Ladesitzung
205-
- `sessionSolarPercentage` - Sonnenanteil der Sitzung
206-
- `sessionPrice` - Preis des geladenen Stroms der Sitzung
207-
- `sessionPricePerKWh` - Durchschnittlicher Preis des Stroms pro kWh der Sitzung
208-
- `sessionCo2PerKWh` - Durchschnittliche CO2 pro kWh
209-
- Sponsor
210-
- Konfiguration
211-
- [`auth`](sponsortoken) - Authentication Token des evcc-Sponsors (_string_)
212-
- Information
213-
- `sponsor` - Name des evcc-Sponsors (_string_)
214-
215133
## `services`
216134

217135
`services` definiert eine Liste von zu verwendeten Nachrichtendiensten.
@@ -369,3 +287,57 @@ messaging:
369287
```
370288

371289
In diesem Beispiel wird ein Shell-Script (`cmd`) mit dem Argument `{"title": "...", "msg": "...."}` aufgerufen.
290+
291+
## Variablen-Referenz {#variable-reference}
292+
293+
Die folgende Liste zeigt eine Auswahl häufig genutzter Variablen.
294+
Die vollständige Liste aller verfügbaren Felder findest du in der API-Antwort unter `http://evcc.local:7070/api/state`.
295+
296+
### Ladepunkt (loadpoint)
297+
298+
Die Ladepunkt-Daten stammen aus dem `loadpoints`-Array der API-Antwort, werden aber in der Nachricht direkt (ohne Präfix) bereitgestellt.
299+
300+
- `title` - Name des Ladepunkts
301+
- `loadpoint` - Nummer des Ladepunkts 1, 2, ...
302+
- `mode` - Lademodus: `off`/`now`/`minpv`/`pv`
303+
- `charging` - Ladevorgang aktiv
304+
- `enabled` - Ladefreigabe erteilt
305+
- `connected` - Fahrzeug angeschlossen
306+
- `chargedEnergy` - Geladene Energie der Sitzung in Wh
307+
- `chargeDuration` - Ladedauer
308+
- `chargePower` - Aktuelle Ladeleistung in W
309+
- `connectedDuration` - Anschlussdauer
310+
- `chargeRemainingDuration` - Restladezeit bis Ziel
311+
- `chargeRemainingEnergy` - Restenergie bis Ziel in Wh
312+
- `phasesActive` - Aktuell aktive Phasen
313+
- `vehicleTitle` - Name des Fahrzeugs
314+
- `vehicleName` - Technischer Name des Fahrzeugs
315+
- `vehicleSoc` - Fahrzeug-Ladestand in %
316+
- `vehicleRange` - Fahrzeug-Reichweite in km
317+
- `vehicleOdometer` - Kilometerstand in km
318+
- `sessionSolarPercentage` - Sonnenanteil der Ladesitzung in %
319+
- `sessionPrice` - Kosten der Ladesitzung
320+
- `sessionPricePerKWh` - Durchschnittspreis pro kWh
321+
- `sessionCo2PerKWh` - Durchschnittliche CO₂-Emissionen pro kWh
322+
- `planActive` - Ladeplan aktiv
323+
- `smartCostActive` - Günstiges Laden aktiv
324+
325+
### Global (site)
326+
327+
Die globalen Daten stammen aus der obersten Ebene der API-Antwort.
328+
329+
- `siteTitle` - Name der evcc-Instanz
330+
- `pvPower` - Aktuelle PV-Leistung in W
331+
- `homePower` - Aktueller Hausverbrauch in W
332+
- `grid.Power` - Netzbezug (+) / Einspeisung (-) in W
333+
- `battery.Power` - Batterieleistung in W
334+
- `battery.Soc` - Batterie-Ladestand in %
335+
- `currency` - Tarif-Währung
336+
- `tariffGrid` - Aktueller Netzpreis pro kWh
337+
- `tariffFeedIn` - Einspeisevergütung pro kWh
338+
- `tariffCo2` - Aktuelle CO₂-Intensität
339+
- `statistics` - Ladestatistiken, verfügbar für die Zeiträume `30d`, `365d`, `thisYear` und `total`
340+
- `statistics.<zeitraum>.avgCo2` - Durchschnittliche CO₂-Emissionen pro kWh
341+
- `statistics.<zeitraum>.avgPrice` - Durchschnittspreis pro kWh
342+
- `statistics.<zeitraum>.chargedKWh` - Geladene Energie in kWh
343+
- `statistics.<zeitraum>.solarPercentage` - Sonnenanteil in %

0 commit comments

Comments
 (0)