diff --git a/README.md b/README.md index f69634fd4..dad1937b3 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ EVCC is an extensible EV Charge Controller with PV integration implemented in [G - multiple [chargers](#charger): Wallbe, Phoenix (includes ESL Walli), go-eCharger, NRGkick (direct Bluetooth or via Connect device), SimpleEVSE, EVSEWifi, KEBA/BMW, openWB, Mobile Charger Connect, and any other charger using scripting - multiple [meters](#meter): ModBus (Eastron SDM, MPM3PM, SBC ALE3 and many more), Discovergy (using HTTP plugin), SMA Home Manager 2.0 and SMA Energy Meter, KOSTAL Smart Energy Meter (KSEM, EMxx), any Sunspec-compatible inverter or home battery devices (Fronius, SMA, SolarEdge, KOSTAL, STECA, E3DC), Tesla PowerWall - wide support of vendor-specific [vehicles](#vehicle) interfaces (remote charge, battery and preconditioning status): Audi, BMW, Ford, Tesla, Nissan, Renault, Porsche, Volkswagen and any other vehicle using scripting -- [plugins](#plugins) for integrating with hardware devices and home automation: Modbus (meters and grid inverters), MQTT and shell scripts +- [plugins](#plugins) for integrating with hardware devices and home automation: Modbus (meters and grid inverters), HTTP, MQTT, Javascript, WebSockets and shell scripts - status notifications using [Telegram](https://telegram.org) and [PushOver](https://pushover.net) - logging using [InfluxDB](https://www.influxdata.com) and [Grafana](https://grafana.com/grafana/) - soft ramp-up/ramp-down of charge current ensures contactor only switched at minimum current @@ -42,9 +42,11 @@ EVCC is an extensible EV Charge Controller with PV integration implemented in [G - [Plugins](#plugins) - [Modbus](#modbus-read-only) - [MQTT](#mqtt-readwrite) - - [Script](#script-readwrite) - [HTTP](#http-readwrite) - [Websocket](#websocket-read-only) + - [Javascript](#javascript-readwrite) + - [Shell Script](#shell-script-readwrite) + - [Calc (meter aggregation)](#calc-read-only) - [Combined status](#combined-status-read-only) - [API](#api) - [Background](#background) @@ -250,32 +252,6 @@ Plugins are used to integrate various devices and external data sources with EVC Plugins support both *read* and *write* access. When using plugins for *write* access, the actual data is provided as variable in form of `${var[:format]}`. If `format` is omitted, data is formatted according to the default Go `%v` [format](https://golang.org/pkg/fmt/). The variable is replaced with the actual data before the plugin is executed. -### Calc (read only) - -The `calc` plugin allows calculating the sum of other plugins: - -```yaml -type: calc -add: -- type: ... - ... -- type: ... - ... -``` - -The `calc` plugin is useful e.g. to combine power values if import and export power are separate like with S0 meters. Use `scale` on one of the elements to implement a subtraction. - -### Javascript (read only) - -The `js` plugin is able to execute Javascript code from the `script` tag. Useful for quick prototyping: - -```yaml -type: js -script: | - var res = 500; - 2 * res; // returns 1000 -``` - ### Modbus (read only) The `modbus` plugin is able to read data from any Modbus meter or SunSpec-compatible solar inverter. Many meters are already pre-configured (see [MBMD Supported Devices](https://github.com/volkszaehler/mbmd#supported-devices)). @@ -382,26 +358,6 @@ payload: ${var:%d} For write access, the data is provided using the `payload` attribute. If `payload` is missing, the value will be written in default format. -### Script (read/write) - -The `script` plugin executes external scripts to read or update data. This plugin is useful to implement any type of external functionality. - -Sample read configuration: - -```yaml -type: script -cmd: /bin/bash -c "cat /dev/urandom" -timeout: 5s -``` - -Sample write configuration: - -```yaml -type: script -cmd: /home/user/my-script.sh ${enable:%b} # format boolean enable as 0/1 -timeout: 5s -``` - ### HTTP (read/write) The `http` plugin executes HTTP requests to read or update data. Includes the ability to read and parse JSON using jq-like queries for REST apis. @@ -444,6 +400,63 @@ scale: 0.001 # floating point factor applied to result, e.g. for Wh to kWh conve timeout: 30s # error if no update received in 30 seconds ``` +### Javascript (read/write) + +EVCC includes a bundled Javascript interpreter with Underscore.js library installed. The `js` plugin is able to execute Javascript code from the `script` tag. Useful for quick prototyping: + +```yaml +type: js +script: | + var res = 500; + 2 * res; // returns 1000 +``` + +When using the `js` plugin for writing, the value to write is handed to the script as pre-populated variable: + +```yaml +charger: +- type: generic + maxcurrent: + type: js + script: | + console.log(maxcurrent); +``` + +### Shell Script (read/write) + +The `script` plugin executes external scripts to read or update data. This plugin is useful to implement any type of external functionality. + +Sample read configuration: + +```yaml +type: script +cmd: /bin/bash -c "cat /dev/urandom" +timeout: 5s +``` + +Sample write configuration: + +```yaml +type: script +cmd: /home/user/my-script.sh ${enable:%b} # format boolean enable as 0/1 +timeout: 5s +``` + +### Calc (read only) + +The `calc` plugin allows calculating the sum of other plugins: + +```yaml +type: calc +add: +- type: ... + ... +- type: ... + ... +``` + +The `calc` plugin is useful e.g. to combine power values if import and export power are separate like with S0 meters. Use `scale: -1` on one of the elements to implement a subtraction or `scale: 1000` to implement Wh to kWh conversion. + ### Combined status (read only) The `combined` status plugin is used to convert a mixed boolean status of plugged/charging into an EVCC-compatible charger status of A..F. It is typically used together with OpenWB MQTT integration.