Skip to content

Document plugin features, add missing entries #914

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 24, 2025
Merged

Document plugin features, add missing entries #914

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
140346b
Document meter plugin
naltatis Oct 24, 2025
d7a3282
Document plugin features and configuration options
naltatis Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 110 additions & 20 deletions docs/devices/plugins.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ evcc bietet folgende Plugins an:
- [SMA/Speedwire Plugin](#speedwire) - Plugin speziell für SMA Geräte, die mit dem Speedwire Protokoll kommunizieren können.
- [JavaScript Plugin](#javascript) - Plugin, das Werte in über ein JavaScript Skript bereitstellt oder entgegennimmt.
- [Shell Plugin](#shell) - Plugin, das ein Shell Skript ausführen kann, um Daten zu extrahieren oder schreibend entgegennimmt.
- [Meter Plugin](#meter-plugin) - Plugin um ein anderes Messgerät als Datenquelle zu verwenden.

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

Expand Down Expand Up @@ -154,25 +155,63 @@ Neben den Attributen, die Plugins zur lesenden Auswertung bereitstellen, werden
| 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. |
| batterymode | int | nein | `battery` | Setze Lademodus direkt (1: normal, 2: hold, 3: charge) |

### Charger
### Charger {#charger}

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

| Attribut | Typ | Erfordert | Beschreibung |
| --------- | ------------------- | --------- | ----------------------------------- |
| status | string | ja | Status (A..F) |
| enabled | bool | ja | Ist Ladung freigegeben? |
| power | float | nein | Ladeleistung in W |
| energy | float | nein | Zählerstand in kWh |
| identify | string | nein | Aktuelle RFID-Kennung |
| soc | int | nein | Ladestand in % |
| phases | int | nein | Anzahl der physischen Phasen (1..3) |
| powers | [float,float,float] | nein | Phasenleistungen in W |
| currents | [float,float,float] | nein | Phasenströme in A |
| voltages | [float,float,float] | nein | Phasenspannungen in V |
| temp | float | nein | Aktuelle Temperatur in °C (Heizung) |
| templimit | int | nein | Temperaturlimit in °C (Heizung) |
| getmode | int | nein | SG-Ready Modus (Wärmepumpe) |
| Attribut | Typ | Erfordert | Beschreibung |
| ----------- | ------------------- | --------- | ------------------------------------ |
| status | string | ja | Status (A..F) |
| enabled | bool | ja | Ist Ladung freigegeben? |
| power | float | nein | Ladeleistung in W |
| energy | float | nein | Zählerstand in kWh |
| identify | string | nein | Aktuelle RFID-Kennung |
| soc | int | nein | Ladestand in % |
| phases | int | nein | Anzahl der physischen Phasen (1..3) |
| powers | [float,float,float] | nein | Phasenleistungen in W |
| currents | [float,float,float] | nein | Phasenströme in A |
| voltages | [float,float,float] | nein | Phasenspannungen in V |
| temp | float | nein | Aktuelle Temperatur in °C (Heizung) |
| templimit | int | nein | Temperaturlimit in °C (Heizung) |
| getmode | int | nein | SG-Ready Modus (Wärmepumpe) |
| getmaxpower | float | nein | Maximale Heizleistung in W (Heizung) |

#### Allgemeine Konfigurationsoptionen {#charger-config}

Zusätzlich zu den Plugin-Attributen können folgende Konfigurationsoptionen direkt am Charger gesetzt werden:

| Attribut | Typ | Erfordert | Beschreibung |
| ------------ | -------- | --------- | --------------------------------------------------------------- |
| icon | string | nein | Icon für die Darstellung in der Benutzeroberfläche |
| features | []string | nein | Feature-Flags für spezielle Charger-Eigenschaften (siehe unten) |
| standbypower | int | nein | Standby-Leistung in W (für `switchsocket` Typ) |

##### Feature-Flags {#charger-features}

Über das `features` Array können spezielle Eigenschaften des Chargers aktiviert werden:

| Feature | Beschreibung |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| heating | Behandelt das Gerät als Heizung (z. B. Wärmepumpe, Heizstab). Beeinflusst die Darstellung in der Benutzeroberfläche. |
| integrateddevice | Gerät ohne Ladesitzungen und ohne angeschlossenes Fahrzeug (z. B. Smartes Schalter, fest installierte Verbraucher). |
| coarsecurrent | Ladestrom kann nur in 1 A Schritten eingestellt werden (wird in der Regelung berücksichtigt). |
| welcomecharge | Aktiviert Welcome Charge Funktion. Ladegerät liefert beim Anschließen kurz Strom, damit das Fahrzeug erkennt, dass der Charger funktioniert. |

**Beispiel mit Features**:

```yaml
chargers:
- name: heizstab
type: custom
features:
- heating
- integrateddevice
icon: heater
status:
source: mqtt
topic: heater/status
# ... weitere Attribute
```

**Beispiel**

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

**Beispiel**

Expand All @@ -219,7 +259,7 @@ chargers:
payload: ON
```

### Vehicle
### Vehicle {#vehicle}

Fahrzeugparameter können ebenfalls über Plugins ausgelesen werden.

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

#### Allgemeine Konfigurationsoptionen {#vehicle-config}

Folgende Konfigurationsoptionen können direkt am Fahrzeug gesetzt werden:

| Attribut | Typ | Erfordert | Beschreibung |
| -------- | ------ | --------- | --------------------------------------------------- |
| title | string | nein | Anzeigename des Fahrzeugs in der Benutzeroberfläche |
| icon | string | nein | Icon für die Darstellung in der Benutzeroberfläche |
| capacity | float | nein | Batteriekapazität in kWh |

**Beispiel**

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

```yaml
vehicles:
- name: Mazda
- name: mazda
type: custom
title: Grüner Mazda
capacity: 50
range:
source: mqtt
topic: mazda2mqtt/c53/chargeInfo/drivingRangeKm
Expand Down Expand Up @@ -377,8 +429,7 @@ insecure: false # set to true to trust self-signed certificates
jq: .data.tuples[0][1] # parse response json
scale: 0.001 # factor applied to result, e.g. for kW to W conversion
cache: 60s # response cache duration
timeout: 10s # timeout in golang duration format,
# see https://golang.org/pkg/time/#ParseDuration
timeout: 10s # timeout in golang duration format, see https://golang.org/pkg/time/#ParseDuration
```

```yaml
Expand Down Expand Up @@ -579,3 +630,42 @@ value:

In diesem Beispiel wird der Wert nur verwendet, wenn das `valid` Topic `true` zurückgibt.
Wenn es `false` zurückgibt, wird der Wert als nicht verfügbar markiert.

### Meter <Tag label="lesen" category="read" /> {#meter-plugin}

Das `meter` Plugin ermöglicht es, ein anderes Messgerät als Datenquelle zu verwenden.
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.

Die `config` Sektion enthält dabei die vollständige Template-Konfiguration des einzubettenden Messgeräts.

**Beispiel Lesen**:

```yaml
meters:
- name: battery
type: custom
power:
source: meter
config:
type: template
template: shelly-1pm
host: 192.168.178.21
channel: 0
method: power
scale: -1
energy:
source: meter
config:
type: template
template: shelly-1pm
host: 192.168.178.21
channel: 0
method: energy
soc:
source: mqtt
topic: Haus/Batterie
jq: .soc
timeout: 60s
```

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.
130 changes: 110 additions & 20 deletions i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ evcc offers the following plugins:
- [SMA/Speedwire Plugin](#speedwire) - Plugin specifically for SMA devices that can communicate with the Speedwire protocol.
- [JavaScript Plugin](#javascript) - Plugin that provides or receives values via a JavaScript script.
- [Shell Plugin](#shell) - Plugin that can execute a shell script to extract data or receive data for writing.
- [Meter Plugin](#meter-plugin) - Plugin to use another meter as a data source.

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

Expand Down Expand Up @@ -154,25 +155,63 @@ In addition to the attributes that plugins provide for reading evaluation, the f
| 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`). |
| batterymode | int | no | `battery` | Set charging mode directly (1: normal, 2: hold, 3: charge) |

### Charger
### Charger {#charger}

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

| Attribute | Type | Required | Description |
| --------- | ------------------- | -------- | ----------------------------------- |
| status | string | yes | Status (A..F) |
| enabled | bool | yes | Is charging enabled? |
| power | float | no | Charging power in W |
| energy | float | no | Meter reading in kWh |
| identify | string | no | Current RFID identifier |
| soc | int | no | State of charge in % |
| phases | int | no | Number of physical phases (1..3) |
| powers | [float,float,float] | no | Phase powers in W |
| currents | [float,float,float] | no | Phase currents in A |
| voltages | [float,float,float] | no | Phase voltages in V |
| temp | float | no | Current temperature in °C (heating) |
| templimit | int | no | Temperature limit in °C (heating) |
| getmode | int | no | SG-Ready mode (heat pump) |
| Attribute | Type | Required | Description |
| ----------- | ------------------- | -------- | ------------------------------------ |
| status | string | yes | Status (A..F) |
| enabled | bool | yes | Is charging enabled? |
| power | float | no | Charging power in W |
| energy | float | no | Meter reading in kWh |
| identify | string | no | Current RFID identifier |
| soc | int | no | State of charge in % |
| phases | int | no | Number of physical phases (1..3) |
| powers | [float,float,float] | no | Phase powers in W |
| currents | [float,float,float] | no | Phase currents in A |
| voltages | [float,float,float] | no | Phase voltages in V |
| temp | float | no | Current temperature in °C (heating) |
| templimit | int | no | Temperature limit in °C (heating) |
| getmode | int | no | SG-Ready mode (heat pump) |
| getmaxpower | float | no | Maximum heating power in W (heating) |

#### General Configuration Options {#charger-config}

In addition to plugin attributes, the following configuration options can be set directly on the charger:

| Attribute | Type | Required | Description |
| ------------ | -------- | -------- | -------------------------------------------------------- |
| icon | string | no | Icon for display in the user interface |
| features | []string | no | Feature flags for special charger properties (see below) |
| standbypower | int | no | Standby power in W (for `switchsocket` type) |

##### Feature Flags {#charger-features}

The `features` array can be used to activate special charger properties:

| Feature | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| heating | Treat device as heating (e.g. heat pump, heating rod). Affects display in the user interface. |
| integrateddevice | Device without charging sessions and without connected vehicle (e.g. smart switch, permanently installed consumers). |
| coarsecurrent | Charging current can only be set in 1 A steps (considered in the control logic). |
| welcomecharge | Enable Welcome Charge function. Charger briefly supplies power when connecting, so the vehicle recognises that the charger is working. |

**Example with Features**:

```yaml
chargers:
- name: heating-rod
type: custom
features:
- heating
- integrateddevice
icon: heater
status:
source: mqtt
topic: heater/status
# ... additional attributes
```

**Example**

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

**Example**

Expand All @@ -219,7 +259,7 @@ chargers:
payload: ON
```

### Vehicle
### Vehicle {#vehicle}

Vehicle parameters can also be read via plugins.

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

#### General Configuration Options {#vehicle-config}

The following configuration options can be set directly on the vehicle:

| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------- |
| title | string | no | Display name of the vehicle in the user interface |
| icon | string | no | Icon for display in the user interface |
| capacity | float | no | Battery capacity in kWh |

**Example**

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

```yaml
vehicles:
- name: Mazda
- name: mazda
type: custom
title: Green Mazda
capacity: 50
range:
source: mqtt
topic: mazda2mqtt/c53/chargeInfo/drivingRangeKm
Expand Down Expand Up @@ -377,8 +429,7 @@ insecure: false # set to true to trust self-signed certificates
jq: .data.tuples[0][1] # parse response json
scale: 0.001 # factor applied to result, e.g. for kW to W conversion
cache: 60s # response cache duration
timeout: 10s # timeout in golang duration format,
# see https://golang.org/pkg/time/#ParseDuration
timeout: 10s # timeout in golang duration format, see https://golang.org/pkg/time/#ParseDuration
```

```yaml
Expand Down Expand Up @@ -579,3 +630,42 @@ value:

In this example, the value is only used when the `valid` topic returns `true`.
If it returns `false`, the value is marked as unavailable.

### Meter <Tag label="read" category="read" /> {#meter-plugin}

The `meter` plugin allows using another meter as a data source.
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.

The `config` section contains the complete template configuration of the meter to be embedded.

**Reading Example**:

```yaml
meters:
- name: battery
type: custom
power:
source: meter
config:
type: template
template: shelly-1pm
host: 192.168.178.21
channel: 0
method: power
scale: -1
energy:
source: meter
config:
type: template
template: shelly-1pm
host: 192.168.178.21
channel: 0
method: energy
soc:
source: mqtt
topic: Haus/Batterie
jq: .soc
timeout: 60s
```

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.