Tariffs: explain tax, charges, formula (#693)

blog/2023-10-05/feature-highlights-10-2023.mdx

@@ -34,8 +34,8 @@ Seit einigen Releases ist der Algorithmus keine Blackbox, da wir das Planungserg
 Zur Funktionsweise des Algorithmus:
 
 1. Überschüssige Sonnenenergie wird priorisiert
-2. Zeiten mit günstigem Netzstrom (wenn [dynamischer Stromtarif](/docs/reference/configuration/tariffs#type-awattar) existiert)
-3. Zeiten mit sauberem Netzstrom (wenn [CO₂-Schnittstelle](/docs/reference/configuration/tariffs#co2) konfiguriert ist)
+2. Zeiten mit günstigem Netzstrom (wenn [dynamischer Stromtarif](/docs/features/dynamic-prices) existiert)
+3. Zeiten mit sauberem Netzstrom (wenn [CO₂-Schnittstelle](/docs/features/co2) konfiguriert ist)
 4. Zeitfenster kurz vor Abfahrt
 
 **Ausblick:** Aktuell experimentieren wir mit PV-Prognosedaten von [Solcast](https://solcast.com/).

docs/devices/tariffs.mdx

@@ -65,6 +65,75 @@ From                   To                     Price/Cost
 ...
 ```
 
+## Börsenstrompreise
+
+Du hast einen Vertrag der nach Börsenpreisen berechnet wird?
+Für viele Anbieter haben wir eine eigene Schnittstelle angebunden (z.B. [Awattar](#awattar) oder [Tibber](#tibber)).
+Die Liste aller verfügbaren Anbieter findest du im Abschnitt [Dynamischer Strompreis](#dynamischer-strompreis).
+
+### Gebühren und Steuern
+
+Falls dein Anbieter nicht dabei ist, kannst du deinen Tarif auf Basis der Day-Ahead-Preise der europäischen Strombörse selbst berechnen.
+Die [Energy-Charts API](https://www.energy-charts.info/charts/price_spot_market/chart.htm) vom Fraunhofer ISE liefert aktuelle und prognostizierte Preise.
+Diese werden von fast allen Anbietern als Grundlage für die Berechnung ihrer Energiepreise verwendet.
+
+```yaml
+tariffs:
+  grid:
+    type: template
+    template: energy-charts-api
+    bzn: DE-LU # Gebotszone, siehe https://api.energy-charts.info/#/prices/day_ahead_price_price_get
+    charges: 0.22 # Fester Aufschlag pro kWh (z.B. 20ct Netzentgelt, 2ct Gebühren)
+    tax: 0.19 # Prozentualer Aufschlag (z.B. 19% MwSt.)
+```
+
+Die Schnittstelle liefert die Börsenpreise in Euro ohne lokale Gebühren oder Steuern.
+Mit den Parametern `charges` und `tax` kannst du einen zusätzlichen festen und prozentualen Aufschlag pro kWh definieren.
+Die genauen Werte kannst du deinem Vertrag entnehmen.
+
+### Eigene Berechnungsformeln
+
+Falls das Modell des festen und prozentualen Aufschlags nicht ausreicht, kannst du eine individuelle Formel definieren.
+Verwende dafür den `formula` Parameter.
+
+```yaml
+tariffs:
+  grid:
+    type: template
+    template: energy-charts-api
+    bzn: DE-LU
+    charges: 0.22 # Fester Aufschlag pro kWh
+    tax: 0.19 # Prozentualer Aufschlag
+    formula: math.Min(0.5, (price + charges) * (1 + tax))
+```
+
+Im obigen Beispiel wird eine Preisobergrenze von 50 ct/kWh definiert.
+Die Formel wird in Go-Syntax geschrieben.
+Neben den Werten `price`, `charges` und `tax` steht dir die [`math`-Bibliothek](https://pkg.go.dev/math) zur Verfügung.
+
+### Börsenpreise mit Zeitkomponente
+
+Die Formel wird für den aktuellen Strompreis und jeden Zeitslot in der Prognose ausgeführt.
+Ist die Berechnung zeitabhängig, kannst du über `ts` auch auf die [Zeit](https://pkg.go.dev/time#Time) des jeweiligen Slots zugreifen.
+
+```yaml
+tariffs:
+  grid:
+    type: template
+    template: energy-charts-api
+    bzn: DE-LU
+    formula: extra := 0.1; if ts.Hour() < 6 || ts.Hour() > 22 { extra = 0.0 }; price + extra
+```
+
+In diesem Beispiel gibt es einen Aufschlag von 10 ct/kWh.
+In der Zeit von 22:00 Uhr bis 06:00 Uhr wird kein Aufschlag berechnet.
+Der Fantasie sind hier keine Grenzen gesetzt.
+
+Der `formula` Mechanismus funktioniert auch für viele andere Datenquellen.
+Schau dir die Konfigurationsoptionen der jeweiligen Quellen an.
+
+Der CLI Befehl `evcc tariff` ist hilfreich um die Berechnungsergebnisse zu überprüfen.
+
 <!-- AUTO-GENERATED CONTENT BELOW THIS LINE -->
 
 <!-- AUTO-GENERATED FROM TEMPLATE - PLEASE EDIT HERE https://github.com/evcc-io/evcc/tree/master/templates/definition/tariff  -->

docs/features/co2.mdx

@@ -26,8 +26,8 @@ tariffs:
     zip: 12349 # Deine Postleitzahl
 ```
 
-In diesem Beispiel verwenden wir die Daten von [GrünstromIndex](https://www.gruenstromindex.de/).
-Unter [tariffs](../devices/tariffs) findest du eine Liste aller unterstützten Datenquellen.
+In diesem Beispiel verwenden wir die Daten von [GrünstromIndex.de](https://www.gruenstromindex.de/).
+Unter [Stromtarife](../devices/tariffs) findest du eine Liste aller unterstützten Datenquellen.
 
 ## Sauberes Netzladen
 

docs/features/dynamic-prices.mdx

@@ -57,7 +57,7 @@ tariffs:
     token: "..." # Access Token
 ```
 
-Unter [tariffs](../devices/tariffs) findest du eine Liste aller unterstützten Tarife.
+Unter [Stromtarife](../devices/tariffs) findest du eine Liste aller unterstützten Tarife.
 Wenn dein Anbieter eine Schnittstelle hat, aber noch nicht von evcc unterstützt wird, dann mach gerne einen [Feature Request](https://github.com/evcc-io/evcc/issues/new/choose) auf.
 
 ## Günstiges Netzladen

docs/reference/configuration/messaging.md

@@ -148,8 +148,8 @@ Die von evcc bereitgestellten Variablen (siehe auch /api/state) müssen als rege
     - `pvConfigured` - Indikator, Solaranlagen/Photovoltaik-Meter konfiguriert (_bool_)
 - Infos zum Stromtarif
   - [`currency`](tariffs) - Tarif-Währung (_string_)
-  - [`tariffFeedIn`](tariffs#feedin) - PV-Einspeisevergütung pro kWh in der Tarif-Währung (float)
-  - [`tariffGrid`](tariffs#grid) - Netz-Abnahmepreis pro kWh in der Tarif-Währung (float)
+  - [`tariffFeedIn`](tariffs) - PV-Einspeisevergütung pro kWh in der Tarif-Währung (float)
+  - [`tariffGrid`](tariffs) - Netz-Abnahmepreis pro kWh in der Tarif-Währung (float)
 - Meter Infos
   - `batteryPower` - Aktuelle Hausbatterie/Powerwall-Leistung in Watt (_float_)
   - `batterySoc` - Aktueller Füllstand der Hausbatterie/Powerwall in Prozent (_integer_)
@@ -240,7 +240,6 @@ Im folgenden werden nun alle erforderlichen Parameter erklärt.
 - `ntfy`: [ntfy](https://ntfy.sh). Siehe [`ntfy`](#ntfy) Definition
 - `custom`: Ermöglicht die Nutzung von allen [Plugins](../plugins), die einen Schreibzugriff erlauben. Siehe [`custom`](#custom) Definition.
 
-
 ---
 
 ## Unterstützte Dienste
@@ -339,13 +338,14 @@ Der Typ `custom` ermöglicht es, beliebige [Plugins](../plugins) für die Verarb
 
 **Mögliche Werte**:
 
-* `send`: Definiert das zu verwendende Plugin mit dem Feld `source` und plugin-spezifische Parameter. Siehe das Beispiel weiter unten.
-* `encoding`: Definiert das Format, in dem der Wert für `${send}` bereitgestellt wird. Die möglichen Werte sind:
+- `send`: Definiert das zu verwendende Plugin mit dem Feld `source` und plugin-spezifische Parameter. Siehe das Beispiel weiter unten.
+- `encoding`: Definiert das Format, in dem der Wert für `${send}` bereitgestellt wird. Die möglichen Werte sind:
+
   - `json`: Der Wert wird als JSON-Objekt im Format `{ "msg": msg, "title": title }` bereitgestellt. Das Feld `title` wird nur hinzugefügt, wenn es im Abschnitt `events` definiert ist.
   - `csv`: Die Felder `title` und `msg` werden als kommaseparierte Liste bereitgestellt (`title, msg`)
   - `tsv`: Ähnlich wie `csv`, jedoch mit Tabulator als Trennzeichen.
   - `title`: Nur der Titel (`title`) wird bereitgestellt.
-  
+
   Wenn `encoding` nicht definiert ist, wird die Nachricht `msg` ohne Titel direkt verwendet. Dabei wird nur die in `msg` definierte Nachricht ohne Titel in `${send}` verwendet.
 
 **Beispiel**:
@@ -362,7 +362,7 @@ messaging:
       send:
         # Plugin Typ
         source: script
-        # Plugin-spezifische Konfiguration. 
+        # Plugin-spezifische Konfiguration.
         # {{.send}} enthält die JSON Nachricht
         cmd: /usr/local/bin/evcc_message "{{.send}}"
 ```