Skip to content

Commit ae792c8

Browse files
naltatisclaude
naltatis
and
claude
authored
Document plugin features, add missing entries (#914)
Co-authored-by: Claude <noreply@anthropic.com>
1 parent 7f1aa24 commit ae792c8

File tree

2 files changed

+220
-40
lines changed

2 files changed

+220
-40
lines changed

‎docs/devices/plugins.mdx‎

Lines changed: 110 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ evcc bietet folgende Plugins an:
2828
- [SMA/Speedwire Plugin](#speedwire) - Plugin speziell für SMA Geräte, die mit dem Speedwire Protokoll kommunizieren können.
2929
- [JavaScript Plugin](#javascript) - Plugin, das Werte in über ein JavaScript Skript bereitstellt oder entgegennimmt.
3030
- [Shell Plugin](#shell) - Plugin, das ein Shell Skript ausführen kann, um Daten zu extrahieren oder schreibend entgegennimmt.
31+
- [Meter Plugin](#meter-plugin) - Plugin um ein anderes Messgerät als Datenquelle zu verwenden.
3132

3233
Neben diesen Integrations-Plugins, gibt es noch Helfer-Plugins, die Zusatzfunktionen bereit stellt:
3334

@@ -154,25 +155,63 @@ Neben den Attributen, die Plugins zur lesenden Auswertung bereitstellen, werden
154155
| limitsoc | int | nein | `battery` | Setze Ladeziel für Batterie in %. Das Ladeziel wird aus den konfigurierten `MinSoc`, `MaxSoc` und dem aktuellen Ladestand (Attribut `soc`) berechnet. |
155156
| batterymode | int | nein | `battery` | Setze Lademodus direkt (1: normal, 2: hold, 3: charge) |
156157

157-
### Charger
158+
### Charger {#charger}
158159

159160
Wallboxen und Ladegeräte haben folgende Attribute die ausgelesen werden können:
160161

161-
| Attribut | Typ | Erfordert | Beschreibung |
162-
| --------- | ------------------- | --------- | ----------------------------------- |
163-
| status | string | ja | Status (A..F) |
164-
| enabled | bool | ja | Ist Ladung freigegeben? |
165-
| power | float | nein | Ladeleistung in W |
166-
| energy | float | nein | Zählerstand in kWh |
167-
| identify | string | nein | Aktuelle RFID-Kennung |
168-
| soc | int | nein | Ladestand in % |
169-
| phases | int | nein | Anzahl der physischen Phasen (1..3) |
170-
| powers | [float,float,float] | nein | Phasenleistungen in W |
171-
| currents | [float,float,float] | nein | Phasenströme in A |
172-
| voltages | [float,float,float] | nein | Phasenspannungen in V |
173-
| temp | float | nein | Aktuelle Temperatur in °C (Heizung) |
174-
| templimit | int | nein | Temperaturlimit in °C (Heizung) |
175-
| getmode | int | nein | SG-Ready Modus (Wärmepumpe) |
162+
| Attribut | Typ | Erfordert | Beschreibung |
163+
| ----------- | ------------------- | --------- | ------------------------------------ |
164+
| status | string | ja | Status (A..F) |
165+
| enabled | bool | ja | Ist Ladung freigegeben? |
166+
| power | float | nein | Ladeleistung in W |
167+
| energy | float | nein | Zählerstand in kWh |
168+
| identify | string | nein | Aktuelle RFID-Kennung |
169+
| soc | int | nein | Ladestand in % |
170+
| phases | int | nein | Anzahl der physischen Phasen (1..3) |
171+
| powers | [float,float,float] | nein | Phasenleistungen in W |
172+
| currents | [float,float,float] | nein | Phasenströme in A |
173+
| voltages | [float,float,float] | nein | Phasenspannungen in V |
174+
| temp | float | nein | Aktuelle Temperatur in °C (Heizung) |
175+
| templimit | int | nein | Temperaturlimit in °C (Heizung) |
176+
| getmode | int | nein | SG-Ready Modus (Wärmepumpe) |
177+
| getmaxpower | float | nein | Maximale Heizleistung in W (Heizung) |
178+
179+
#### Allgemeine Konfigurationsoptionen {#charger-config}
180+
181+
Zusätzlich zu den Plugin-Attributen können folgende Konfigurationsoptionen direkt am Charger gesetzt werden:
182+
183+
| Attribut | Typ | Erfordert | Beschreibung |
184+
| ------------ | -------- | --------- | --------------------------------------------------------------- |
185+
| icon | string | nein | Icon für die Darstellung in der Benutzeroberfläche |
186+
| features | []string | nein | Feature-Flags für spezielle Charger-Eigenschaften (siehe unten) |
187+
| standbypower | int | nein | Standby-Leistung in W (für `switchsocket` Typ) |
188+
189+
##### Feature-Flags {#charger-features}
190+
191+
Über das `features` Array können spezielle Eigenschaften des Chargers aktiviert werden:
192+
193+
| Feature | Beschreibung |
194+
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
195+
| heating | Behandelt das Gerät als Heizung (z. B. Wärmepumpe, Heizstab). Beeinflusst die Darstellung in der Benutzeroberfläche. |
196+
| integrateddevice | Gerät ohne Ladesitzungen und ohne angeschlossenes Fahrzeug (z. B. Smartes Schalter, fest installierte Verbraucher). |
197+
| coarsecurrent | Ladestrom kann nur in 1 A Schritten eingestellt werden (wird in der Regelung berücksichtigt). |
198+
| welcomecharge | Aktiviert Welcome Charge Funktion. Ladegerät liefert beim Anschließen kurz Strom, damit das Fahrzeug erkennt, dass der Charger funktioniert. |
199+
200+
**Beispiel mit Features**:
201+
202+
```yaml
203+
chargers:
204+
- name: heizstab
205+
type: custom
206+
features:
207+
- heating
208+
- integrateddevice
209+
icon: heater
210+
status:
211+
source: mqtt
212+
topic: heater/status
213+
# ... weitere Attribute
214+
```
176215

177216
**Beispiel**
178217

@@ -203,6 +242,7 @@ Neben den read-only Werten können über Plugins auch Aktionen getriggert oder K
203242
| phases1p3p | int | nein | Phasenumschaltung durchführen (erfordert `tos: true`) |
204243
| wakeup | bool | nein | Wecke Fahrzeug auf |
205244
| setmode | int | nein | Ändere SG-Ready Modus (1: reduced, 2: normal, 3: boost) |
245+
| setmaxpower | int | nein | Setze maximale Heizleistung in W (Heizung) |
206246

207247
**Beispiel**
208248

@@ -219,7 +259,7 @@ chargers:
219259
payload: ON
220260
```
221261

222-
### Vehicle
262+
### Vehicle {#vehicle}
223263

224264
Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden.
225265

@@ -234,14 +274,26 @@ Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden.
234274
| getmaxcurrent | float | nein | Maximaler Ladestrom in A |
235275
| finishtime | string | nein | Geplantes Ladeende (RFC3339) |
236276

277+
#### Allgemeine Konfigurationsoptionen {#vehicle-config}
278+
279+
Folgende Konfigurationsoptionen können direkt am Fahrzeug gesetzt werden:
280+
281+
| Attribut | Typ | Erfordert | Beschreibung |
282+
| -------- | ------ | --------- | --------------------------------------------------- |
283+
| title | string | nein | Anzeigename des Fahrzeugs in der Benutzeroberfläche |
284+
| icon | string | nein | Icon für die Darstellung in der Benutzeroberfläche |
285+
| capacity | float | nein | Batteriekapazität in kWh |
286+
237287
**Beispiel**
238288

239289
Im folgenden Beispiel wird die aktuelle Reichweite des Fahrzeugs aus MQTT Nachrichten gelesen:
240290

241291
```yaml
242292
vehicles:
243-
- name: Mazda
293+
- name: mazda
244294
type: custom
295+
title: Grüner Mazda
296+
capacity: 50
245297
range:
246298
source: mqtt
247299
topic: mazda2mqtt/c53/chargeInfo/drivingRangeKm
@@ -377,8 +429,7 @@ insecure: false # set to true to trust self-signed certificates
377429
jq: .data.tuples[0][1] # parse response json
378430
scale: 0.001 # factor applied to result, e.g. for kW to W conversion
379431
cache: 60s # response cache duration
380-
timeout: 10s # timeout in golang duration format,
381-
# see https://golang.org/pkg/time/#ParseDuration
432+
timeout: 10s # timeout in golang duration format, see https://golang.org/pkg/time/#ParseDuration
382433
```
383434

384435
```yaml
@@ -579,3 +630,42 @@ value:
579630

580631
In diesem Beispiel wird der Wert nur verwendet, wenn das `valid` Topic `true` zurückgibt.
581632
Wenn es `false` zurückgibt, wird der Wert als nicht verfügbar markiert.
633+
634+
### Meter <Tag label="lesen" category="read" /> {#meter-plugin}
635+
636+
Das `meter` Plugin ermöglicht es, ein anderes Messgerät als Datenquelle zu verwenden.
637+
Dies ist nützlich, wenn man ein bestehendes Gerät für mehrere Messwerte verwenden möchte oder wenn man verschiedene Methoden eines Geräts für unterschiedliche Attribute nutzen will.
638+
639+
Die `config` Sektion enthält dabei die vollständige Template-Konfiguration des einzubettenden Messgeräts.
640+
641+
**Beispiel Lesen**:
642+
643+
```yaml
644+
meters:
645+
- name: battery
646+
type: custom
647+
power:
648+
source: meter
649+
config:
650+
type: template
651+
template: shelly-1pm
652+
host: 192.168.178.21
653+
channel: 0
654+
method: power
655+
scale: -1
656+
energy:
657+
source: meter
658+
config:
659+
type: template
660+
template: shelly-1pm
661+
host: 192.168.178.21
662+
channel: 0
663+
method: energy
664+
soc:
665+
source: mqtt
666+
topic: Haus/Batterie
667+
jq: .soc
668+
timeout: 60s
669+
```
670+
671+
In diesem Beispiel wird ein Shelly 1PM Gerät als Datenquelle für Leistung und Energie einer Batterie verwendet, während der Ladestand (SoC) über MQTT abgerufen wird.

‎i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx‎

Lines changed: 110 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ evcc offers the following plugins:
2828
- [SMA/Speedwire Plugin](#speedwire) - Plugin specifically for SMA devices that can communicate with the Speedwire protocol.
2929
- [JavaScript Plugin](#javascript) - Plugin that provides or receives values via a JavaScript script.
3030
- [Shell Plugin](#shell) - Plugin that can execute a shell script to extract data or receive data for writing.
31+
- [Meter Plugin](#meter-plugin) - Plugin to use another meter as a data source.
3132

3233
In addition to these integration plugins, there are also helper plugins that provide additional functions:
3334

@@ -154,25 +155,63 @@ In addition to the attributes that plugins provide for reading evaluation, the f
154155
| limitsoc | int | no | `battery` | Set charging target for battery in %. The charging target is calculated from the configured `MinSoc`, `MaxSoc` and the current state of charge (attribute `soc`). |
155156
| batterymode | int | no | `battery` | Set charging mode directly (1: normal, 2: hold, 3: charge) |
156157

157-
### Charger
158+
### Charger {#charger}
158159

159160
Wallboxes and chargers have the following attributes that can be read:
160161

161-
| Attribute | Type | Required | Description |
162-
| --------- | ------------------- | -------- | ----------------------------------- |
163-
| status | string | yes | Status (A..F) |
164-
| enabled | bool | yes | Is charging enabled? |
165-
| power | float | no | Charging power in W |
166-
| energy | float | no | Meter reading in kWh |
167-
| identify | string | no | Current RFID identifier |
168-
| soc | int | no | State of charge in % |
169-
| phases | int | no | Number of physical phases (1..3) |
170-
| powers | [float,float,float] | no | Phase powers in W |
171-
| currents | [float,float,float] | no | Phase currents in A |
172-
| voltages | [float,float,float] | no | Phase voltages in V |
173-
| temp | float | no | Current temperature in °C (heating) |
174-
| templimit | int | no | Temperature limit in °C (heating) |
175-
| getmode | int | no | SG-Ready mode (heat pump) |
162+
| Attribute | Type | Required | Description |
163+
| ----------- | ------------------- | -------- | ------------------------------------ |
164+
| status | string | yes | Status (A..F) |
165+
| enabled | bool | yes | Is charging enabled? |
166+
| power | float | no | Charging power in W |
167+
| energy | float | no | Meter reading in kWh |
168+
| identify | string | no | Current RFID identifier |
169+
| soc | int | no | State of charge in % |
170+
| phases | int | no | Number of physical phases (1..3) |
171+
| powers | [float,float,float] | no | Phase powers in W |
172+
| currents | [float,float,float] | no | Phase currents in A |
173+
| voltages | [float,float,float] | no | Phase voltages in V |
174+
| temp | float | no | Current temperature in °C (heating) |
175+
| templimit | int | no | Temperature limit in °C (heating) |
176+
| getmode | int | no | SG-Ready mode (heat pump) |
177+
| getmaxpower | float | no | Maximum heating power in W (heating) |
178+
179+
#### General Configuration Options {#charger-config}
180+
181+
In addition to plugin attributes, the following configuration options can be set directly on the charger:
182+
183+
| Attribute | Type | Required | Description |
184+
| ------------ | -------- | -------- | -------------------------------------------------------- |
185+
| icon | string | no | Icon for display in the user interface |
186+
| features | []string | no | Feature flags for special charger properties (see below) |
187+
| standbypower | int | no | Standby power in W (for `switchsocket` type) |
188+
189+
##### Feature Flags {#charger-features}
190+
191+
The `features` array can be used to activate special charger properties:
192+
193+
| Feature | Description |
194+
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
195+
| heating | Treat device as heating (e.g. heat pump, heating rod). Affects display in the user interface. |
196+
| integrateddevice | Device without charging sessions and without connected vehicle (e.g. smart switch, permanently installed consumers). |
197+
| coarsecurrent | Charging current can only be set in 1 A steps (considered in the control logic). |
198+
| welcomecharge | Enable Welcome Charge function. Charger briefly supplies power when connecting, so the vehicle recognises that the charger is working. |
199+
200+
**Example with Features**:
201+
202+
```yaml
203+
chargers:
204+
- name: heating-rod
205+
type: custom
206+
features:
207+
- heating
208+
- integrateddevice
209+
icon: heater
210+
status:
211+
source: mqtt
212+
topic: heater/status
213+
# ... additional attributes
214+
```
176215

177216
**Example**
178217

@@ -203,6 +242,7 @@ In addition to read-only values, actions can also be triggered or configuration
203242
| phases1p3p | int | no | Perform phase switching (requires `tos: true`) |
204243
| wakeup | bool | no | Wake up vehicle |
205244
| setmode | int | no | Change SG-Ready mode (1: reduced, 2: normal, 3: boost) |
245+
| setmaxpower | int | no | Set maximum heating power in W (heating) |
206246

207247
**Example**
208248

@@ -219,7 +259,7 @@ chargers:
219259
payload: ON
220260
```
221261

222-
### Vehicle
262+
### Vehicle {#vehicle}
223263

224264
Vehicle parameters can also be read via plugins.
225265

@@ -234,14 +274,26 @@ Vehicle parameters can also be read via plugins.
234274
| getmaxcurrent | float | no | Maximum charging current in A |
235275
| finishtime | string | no | Planned charging end (RFC3339) |
236276

277+
#### General Configuration Options {#vehicle-config}
278+
279+
The following configuration options can be set directly on the vehicle:
280+
281+
| Attribute | Type | Required | Description |
282+
| --------- | ------ | -------- | ------------------------------------------------- |
283+
| title | string | no | Display name of the vehicle in the user interface |
284+
| icon | string | no | Icon for display in the user interface |
285+
| capacity | float | no | Battery capacity in kWh |
286+
237287
**Example**
238288

239289
In the following example, the current range of the vehicle is read from MQTT messages:
240290

241291
```yaml
242292
vehicles:
243-
- name: Mazda
293+
- name: mazda
244294
type: custom
295+
title: Green Mazda
296+
capacity: 50
245297
range:
246298
source: mqtt
247299
topic: mazda2mqtt/c53/chargeInfo/drivingRangeKm
@@ -377,8 +429,7 @@ insecure: false # set to true to trust self-signed certificates
377429
jq: .data.tuples[0][1] # parse response json
378430
scale: 0.001 # factor applied to result, e.g. for kW to W conversion
379431
cache: 60s # response cache duration
380-
timeout: 10s # timeout in golang duration format,
381-
# see https://golang.org/pkg/time/#ParseDuration
432+
timeout: 10s # timeout in golang duration format, see https://golang.org/pkg/time/#ParseDuration
382433
```
383434

384435
```yaml
@@ -579,3 +630,42 @@ value:
579630

580631
In this example, the value is only used when the `valid` topic returns `true`.
581632
If it returns `false`, the value is marked as unavailable.
633+
634+
### Meter <Tag label="read" category="read" /> {#meter-plugin}
635+
636+
The `meter` plugin allows using another meter as a data source.
637+
This is useful when you want to use an existing device for multiple measurements or when you need different methods of a device for different attributes.
638+
639+
The `config` section contains the complete template configuration of the meter to be embedded.
640+
641+
**Reading Example**:
642+
643+
```yaml
644+
meters:
645+
- name: battery
646+
type: custom
647+
power:
648+
source: meter
649+
config:
650+
type: template
651+
template: shelly-1pm
652+
host: 192.168.178.21
653+
channel: 0
654+
method: power
655+
scale: -1
656+
energy:
657+
source: meter
658+
config:
659+
type: template
660+
template: shelly-1pm
661+
host: 192.168.178.21
662+
channel: 0
663+
method: energy
664+
soc:
665+
source: mqtt
666+
topic: Haus/Batterie
667+
jq: .soc
668+
timeout: 60s
669+
```
670+
671+
In this example, a Shelly 1PM device is used as a data source for power and energy of a battery, while the state of charge (SoC) is retrieved via MQTT.

0 commit comments

Comments
 (0)