Plugins

Plugins can be used to integrate devices and external data sources into evcc for which there is no direct support. Plugins can be used for the following categories:

meter: PV, battery, grid, meters
charger: Wallboxes, Smart switches, Heat pumps, heating rods
vehicle: Vehicles
tariff: Tariffs, forecasts
circuit: Load management

Additionally, plugins can also be used for the endpoints described in Messaging for sending lifecycle events.

Overview

evcc offers the following plugins:

Modbus Plugin - Plugin for reading from a Modbus-capable device.
MQTT Plugin - Plugin for indirectly communicating with MQTT-capable devices via MQTT.
HTTP Plugin - Plugin that communicates with end devices via HTTP API.
Websocket Plugin - Plugin for receiving device data via its own web server. Can only be used for reading data.
SMA/Speedwire Plugin - Plugin specifically for SMA devices that can communicate with the Speedwire protocol.
JavaScript Plugin - Plugin that provides or receives values via a JavaScript script.
Shell Plugin - Plugin that can execute a shell script to extract data or receive data for writing.

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

Const Plugin - Special plugin that simply returns a constant value.
Calc Plugin - Meta-plugin for arithmetically linking outputs from other plugins.
Combined Plugin - Meta-plugin specifically for charger to combine the boolean status values for the connected (plugged) and charging (charging) state into a single charging status.

Syntax

Each plugin has an individual configuration schema. It's important to know whether the plugin is used in a reading or writing context. Some configuration parameters only make sense in a reading context, others only when used in writing mode.

For example, the following configuration can be used to integrate an MQTT plugin as a meter, where the current power consumption is read via the specified MQTT topic:

Example: MQTT Plugin for power values of a power meter
meters:
  - name: imsys
    type: custom
    power:
      source: mqtt
      topic: "home/current/imsys/chn2/raw"

The plugin configuration schema always has the following structure:

- name: <name>
  type: custom
  <attr1>:
    source: <plugin>
    <p-attr1>: ...
    <p-attr2>: ...
    ....
  <attr2>:
    ....

Where <name> stands for the device name, <attr1> and <attr2> for one of the device-specific attributes described below, <plugin> for the plugin type and <p-attr1>, <p-attr2> for plugin-specific configurations (e.g. source, topic for plugins of type mqtt)

Reading

When reading data using a plugin, so-called pipelines can be used. These allow data to be extracted in a fine-grained manner from the plugin's output. This makes it possible to process complex data structures such as JSON or XML and filter out the required information. Possible parameters for data extraction are:

regex: A regular expression to extract values from the received text.
jq: A jq-expression to extract values from JSON structures. The full syntax and possibilities can be found in the jq documentation.
unpack: Converts values from other number representations, e.g. hex.
decode: Decodes binary formats like uint32, float32 etc.

Writing

When writing, parameters in the configuration can be replaced by placeholders. The data is provided in the form ${var[:format]}. If format is not specified, the data is provided in the standard %v Go format. The variables are replaced with the corresponding value before the plugin is executed. Additionally, all functions of the Go Template Library can be used to perform more complex data transformations.

Depending on the device (meter, charger or vehicle), different attributes can be read or set with plugins.

Meter

Power meters are configured in the configuration section meters. Meters defined under meters: can be used at various places within the site configuration:

grid: Grid meter
pv: PV meter
battery: Home battery meter
charge: Meter for the charging power of the wallbox
aux: Consumption meter for intelligent consumers
ext: Additional meter, e.g. for load management or data collection

power is the only mandatory attribute that must be present in every meter definition, all other attributes are optional.

However, not all meter types support all plugin attributes:

limitsoc and batterymode are used exclusively for battery meters (i.e. for meter referenced in site.battery).
currents, voltages and powers are phase attributes that must be configured with exactly three plugin configurations each (in a YAML array) and can be used for grid meters (grid) and wallboxes (charge).

The following tables contain all attributes that can be provided by plugins when configured for meter. When using the plugins, it's also important that they return the correct data type. To convert to the required data type, the pipelines described in Reading can be used.

Attribute	Type	Required	Context	Description
power	float	yes	all	Current power in W
energy	float	no	all	Meter reading in kWh
maxpower	int	no	`pv` (hybrid)	Maximum AC power in W
soc	int	no	`battery`	State of charge in %
capacity	float	no	`battery`	Capacity in kWh
powers	[float,float,float]	no	all	Phase powers in W
currents	[float,float,float]	no	all	Phase currents in A
voltages	[float,float,float]	no	all	Phase voltages in V

Example

In this example, the configuration of a meter is queried for the current electrical grid power via an HTTP call:

meters:
  - name: volkszaehler
    type: custom
    power:
      source: http
      uri: http://zaehler.network.local:8080/api/data.json?from=now
      jq: .data.tuples[0][1]

site:
  meters:
    grid: volkszaehler
    ...
  ...

In addition to the attributes that plugins provide for reading evaluation, the following attributes are used by evcc to trigger actions:

Attribute	Type	Required	Context	Description
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

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)

Example

This example shows how to query the charging status (charging/not charging) of a charger via the Modbus plugin:

chargers:
  - name: icharge
    type: custom
    enabled:
      source: modbus
      id: 4711
      uri: modbus.local:502
      rtu: false
      register:
        address: 100
        type: holding
        decode: uint16

In addition to read-only values, actions can also be triggered or configuration values set via plugins:

Attribute	Type	Required	Description
enable	bool	yes	Enable / disable charging
maxcurrent	int	yes	Set maximum charging current in A
maxcurrentmilis	float	no	Set maximum charging current in A
phases1p3p	int	no	Perform phase switching (requires `tos: true`)
wakeup	bool	no	Wake up vehicle
setmode	int	no	Change SG-Ready mode (1: normal, 2: boost, 3: stop)

Example

This example switches a Tasmota socket via an MQTT message:

chargers:
  - name: unu-charger
    type: custom
    enable:
      source: mqtt
      broker: mosquitto.local:883
      topic: cmd/unu-switch/Power
      payload: ON

Vehicle

Vehicle parameters can also be read via plugins.

Attribute	Type	Required	Description
soc	int	yes	State of charge in %
limitsoc	int	no	Charge limit in %
status	string	no	Status (A..F)
range	int	no	Range in km
odometer	int	no	Odometer reading in km
climater	bool	no	Climate control active?
getmaxcurrent	float	no	Maximum charging current in A
finishtime	string	no	Planned charging end (RFC3339)

Example

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

vehicles:
  - name: Mazda
    type: custom
    range:
      source: mqtt
      topic: mazda2mqtt/c53/chargeInfo/drivingRangeKm

Additionally, special commands can be sent to the vehicle via plugins:

Attribute	Type	Required	Description
wakeup	bool	no	Wake up vehicle
chargeenable	bool	no	Start/stop charging process
maxcurrent	int	no	Set maximum charging current in A

Example

To wake up a car via an HTTP ping to send further queries, the HTTP plugin can be used as in the following example:

vehicles:
  - name: model-y
    type: custom
    wakeup:
      source: http
      uri: http://teslalogger.local:5000/command/08154711/wake_up

Tariffs & Forecasts

See Tariffs & Forecasts > Custom Plugin for more details.

Load Management

Work in Progress

...

Messaging

Work in Progress

...

Plugins

The following plugins are available and can be configured for the above-described attributes to enable flexible integration with various systems.

Modbus read write

The modbus plugin can read data from any Modbus-capable device or SunSpec-compatible inverter. Many power meters are already pre-configured (see MBMD Supported Devices). It's also possible to write Modbus registers to integrate additional wallboxes.

See the Modbus Documentation for more details.

MQTT read write

The mqtt plugin enables reading values via MQTT topics. This is particularly useful for power meters, e.g. when they already provide their data via MQTT. See the MBMD Documentation for an example of how to get Modbus measurement data into MQTT. The plugin also offers the ability to read or parse JSON data structures via jq-like queries (see HTTP plugin).

Reading Example:

source: mqtt
topic: mbmd/sdm1-1/Power
timeout: 30s # don't accept values older than timeout
scale: 0.001 # factor applied to result, e.g. for Wh to kWh conversion

For write access, the data is provided with the payload attribute. If this parameter is missing from the configuration, the value is written in the default format.

Writing Example:

source: mqtt
topic: mbmd/charger/maxcurrent
payload: ${var:%d}

HTTP read write

The http plugin performs HTTP calls to read or update data. It also includes the ability to read or perform simple transformations on JSON data structures via jq queries (e.g. for REST APIs). The full functionality can be found in the official jq documentation.

Authentication methods are basic, bearer and digest. The names of the respective parameters can be found here.

Important

XML documents are automatically converted to JSON format internally, which can then be filtered with jq like a native JSON response. Attributes get the prefix attr.

tip

For testing jq queries, online tools like https://jqplay.org/ and for regex tests tools like https://regex101.com/ are useful.

Reading Example:

source: http
uri: https://volkszaehler/api/data/<uuid>.json?from=now
method: GET # default HTTP method
headers:
  - content-type: application/json
auth: # basic authentication
  type: basic
  user: foo
  password: bar
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

source: http
uri: http://charger/status
jq: .total_power > 10 # Converts a json integer to a boolean value

Writing Example:

body: %v # only applicable for PUT or POST requests

enable:
  source: http
  uri: "http://charger/relay/0?turn={{if .enable}}on{{else}}off{{end}}"

Websocket read

The websocket plugin provides a WebSocket listener. It also includes the ability to read or parse JSON data structures via jq-like queries. This can be used, for example, to receive data from Volkszähler's push server.

Reading Example:

source: http
uri: ws://<volkszaehler host:port>/socket
jq: .data | select(.uuid=="<uuid>") .tuples[0][1] # parse message json
scale: 0.001 # factor applied to result, e.g. for Wh to kWh conversion
timeout: 30s # error if no update received in 30 seconds

SMA/Speedwire read

The sma plugin provides an interface to SMA devices that support the Speedwire protocol.

Reading Example:

source: sma
uri: 192.168.4.51 # alternative to serial
serial: 123456 # alternative to uri
value: ActivePowerPlus # ID of value to read
password: "0000" # optional (default: 0000)
interface: eth0 # optional
scale: 1 # optional scale factor for value

Supported values for value can be found in the diagnostic output using the evcc meter command (with configured SMA meter devices).

All possible values can be found as constants here (use the constant name for value).

JavaScript read write

evcc integrates a JavaScript interpreter with the Underscore.js library, which is directly accessible via _., e.g. _.random(0,5). The js plugin can execute JavaScript code via the script parameter. Very helpful for rapid prototyping:

Reading Example:

source: js
script: |
  var res = 500;
  2 * res; // returns 1000

When the js plugin is used for writing, the value to be written is passed to the script as a variable:

Writing Example:

charger:
  - type: custom
    maxcurrent:
      source: js
      script: |
        console.log(maxcurrent);

Shell Script read write

The script plugin executes external scripts to read or update data. The plugin is useful for integrating any kind of external functionality.

Reading Example:

source: script
cmd: /bin/bash -c "cat /dev/urandom"
timeout: 5s

Writing Example:

source: script
cmd: /home/user/my-script.sh ${enable:%b} # format boolean enable as 0/1
timeout: 5s

Const read

The const plugin returns a constant value. It's suitable, for example, to apply fixed correction values (offset) to a variable value in conjunction with the calc plugin or to simulate measurement and status values for testing purposes.

Reading Example:

source: const
value: -16247

Calc read

The calc plugin allows mathematical processing of multiple individual values:

Reading Example:

source: calc
add:
- source: ...
  ...
- source: ...
  ...

source: calc
mul:
- source: calc
  sign:
    source: ... (power)
  ...
- source: ... (current)
  ...

The basic arithmetic operations addition (add) and multiplication (mul) are supported as operands.

With scale: -1 on one of the values, simple subtraction can be performed, with scale: 0.001 division, e.g. for converting kWh to Wh.

With sign: (every positive number becomes +1, every negative number becomes -1, 0 remains 0), signs can be transferred to other values (in conjunction with mul). E.g. to transfer the "direction" of power (feed-in or consumption) to the measured currents for meters.

The calc plugin is helpful for e.g.

Summing power values from individual PV strings (addition)
Calculating apparent power from voltage and current (multiplication)
Combining separate power values for import and export into a signed single value (subtraction).
Calculating percentage fill levels (division)
Determining the correct direction of current flow (sign)
Eliminating known offsets (addition with const plugin)

tip

Constant auxiliary values (e.g. for offsets) can be generated as operands using the const plugin.

Combined read

The combined status plugin is used to convert mixed boolean status values of Plugged (connected) / Charging (charging) into an evcc-compatible charging status of A..F. It's used, for example, with an OpenWB MQTT integration.

Reading Example:

source: combined
plugged:
  source: mqtt
  topic: openWB/lp/1/boolPlugStat
charging:
  source: mqtt
  topic: openWB/lp/1/boolChargeStat

Overview​

Syntax​

Reading​

Writing​

Meter​

Charger​

Vehicle​

Tariffs & Forecasts​

Load Management​

Messaging​

Plugins​

Modbus read write​

MQTT read write​

HTTP read write​

Websocket read​

SMA/Speedwire read​

JavaScript read write​

Shell Script read write​

Const read​

Calc read​

Combined read​

Overview

Syntax

Reading

Writing

Meter

Charger

Vehicle

Tariffs & Forecasts

Load Management

Messaging

Plugins

Modbus read write

MQTT read write

HTTP read write

Websocket read

SMA/Speedwire read

JavaScript read write

Shell Script read write

Const read

Calc read

Combined read