evcc

https://docs.evcc.io/
Admin
evcc is an open-source EV charge controller that optimizes electric vehicle charging using...
Tokens:621,035
Snippets:4,424
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example from parameter: from

Source: https://docs.evcc.io/en/integrations/rest-api/operations/deleteenergymetrics

Example value for the 'from' query parameter, a start time in RFC3339 format.

```plaintext
2026-07-01T00:00:00Z
```

--------------------------------

### Start evcc with configuration file

Source: https://docs.evcc.io/en/installation/windows

Use this command to start evcc with an evcc.yaml configuration file instead of the web interface. The configuration file is an alternative setup method; see the Configuration documentation for details.

```bash
./evcc -c evcc.yaml

```

--------------------------------

### Install completions for every new session on Linux

Source: https://docs.evcc.io/en/reference/cli/evcc_completion_bash

Execute this command once to install bash completions for every new session on Linux. You will need to start a new shell for the setup to take effect.

```bash
evcc completion bash > /etc/bash_completion.d/evcc
```

--------------------------------

### Minimal evcc.yaml configuration example

Source: https://docs.evcc.io/en/installation/configuration

A template file containing demo devices to serve as a starting point for your configuration. Replace the demo templates with your actual hardware settings.

```yaml

## minimal configuration example


site:
  title: Home # display name for UI
  meters:
    grid: my_grid
    pv:
      - my_pv
    battery:
      - my_battery


# see https://docs.evcc.io/en/docs/reference/configuration/loadpoints
loadpoints:
  - title: Garage # display name for UI
    charger: my_charger # charger
    vehicle: my_car # default vehicle


# meter definitions
# name can be freely chosen and is used as reference when assigning meters to site and loadpoints
# for documentation see https://docs.evcc.io/docs/meters
meters:
  # replace with your real grid meter
  - name: my_grid
    type: template
    template: demo-meter
    usage: grid
    power: -1000 # 1 kW feed-in
  # replace with your real solar system
  - name: my_pv
    type: template
    template: demo-meter
    usage: pv
    power: 4000 # 4 kW production
  # replace with your real battery
  - name: my_battery
    type: template
    template: demo-battery
    usage: battery
    power: -1000 # 1 kW battery charging
    soc: 50 # 50 % state of charge


# replace with your real charger
# see https://docs.evcc.io/docs/chargers
chargers:
  - name: my_charger
    type: template
    template: demo-charger
    status: C # charging
    power: 2000 # 2 kW charging power
    enabled: true # optional


# replace with your real vehicle (optional)
# see https://docs.evcc.io/docs/vehicles
vehicles:
  - name: my_car
    type: template
    template: offline
    title: blue e-Golf
    capacity: 50 # in kWh


# enter your real grid tariff and feed-in price
# see https://docs.evcc.io/docs/tariffs
tariffs:
  currency: EUR
  grid:
    type: fixed
    price: 0.29 # EUR/kWh
  feedin:
    type: fixed
    price: 0.10 # EUR/kWh
```

--------------------------------

### Start Claude Code and query solar charging

Source: https://docs.evcc.io/en/integrations/mcp

Starts Claude Code and shows an example query about solar charging. The query requires a configured PV forecast to work.

```bash
claude


╭──────────────────────────────────────────────────────────────────────────────────────────╮
│ > Will I be able to fill my car with solar energy today?                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
```

--------------------------------

### Example curtailers and site configuration

Source: https://docs.evcc.io/en/reference/configuration/curtailers

Shows a curtailer device configuration using the solaredge template and its reference in site.curtailers. The limit is passed as a percentage of the installed generator power (productionnominalmax).

```yaml
curtailers:
  - name: my_curtailer
    type: template
    template: solaredge
    modbus: tcpip
    host: 192.168.0.10
    port: 1502
    id: 1
    productionnominalmax: 15000 # installed generator power of the whole installation (Wp)


site:
  curtailers:
    - my_curtailer

```

--------------------------------

### Docker CLI Installation for SMA Devices and EEBus

Source: https://docs.evcc.io/en/installation/docker

Command for setups requiring host networking and machine-id access for SMA Sunny Home Manager or EEBus.

```bash
sudo docker run -d --name evcc \
-v /home/user/evcc.yaml:/etc/evcc.yaml \
-v /home/user/.evcc:/root/.evcc \
-p 7070:7070 \
-p 8887:8887 \
-p 9522:9522/udp \
-p 5353:5353/udp \
-p 4712:4712 \
--network host \
-v /etc/machine-id:/etc/machine-id \
# highlight-end
evcc/evcc:latest
```

--------------------------------

### Install completions for every new session on macOS

Source: https://docs.evcc.io/en/reference/cli/evcc_completion_bash

Execute this command once to install bash completions for every new session on macOS. You will need to start a new shell for the setup to take effect.

```bash
evcc completion bash > $(brew --prefix)/etc/bash_completion.d/evcc
```

--------------------------------

### Complete site configuration example

Source: https://docs.evcc.io/en/reference/configuration/site

A comprehensive example showing the structure of the site configuration, including meters, curtailers, and residual power settings.

```yaml
site:
  title: Home # display name for UI
  meters:
    grid: mygridmeter # grid meter reference
    pv:
      - mypv1 # first pv meter reference
      - mypv9 # second pv meter reference
    battery:
      - mybat5 # battery meter reference
    aux:
      - myaux1 # self-regulating consumer
    consumer:
      - myconsumer1 # regular consumer, recorded for consumption statistics
    ext:
      - myext1 # for data logging, load management, etc.
  curtailers:
    - my_curtailer # curtailment device reference
  residualPower: 100
```

--------------------------------

### Add a Server Example

Source: https://docs.evcc.io/en/reference/app

Example of a fully populated evcc://server URL with encoded parameters.

```text
evcc://server?url=https://demo.evcc.io&title=Demo%20Server&username=admin&password=secret
```

--------------------------------

### Fetch and cURL requests for GET /history/energy

Source: https://docs.evcc.io/en/integrations/rest-api/operations/getenergyhistory

Example requests for the GET /history/energy endpoint. The fetch example uses JavaScript with async/await and logs the JSON response. The curl example sends a GET request with the same query parameters.

```javascript
const url = 'https://demo.evcc.io/api/history/energy?from=2026-07-01T00%3A00%3A00Z&to=2026-07-02T00%3A00%3A00Z&aggregate=15m&grouped=false&group=forecast&name=db%3A8&title=Battery&format=json&lang=de';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```bash
curl --request GET \
  --url 'https://demo.evcc.io/api/history/energy?from=2026-07-01T00%3A00%3A00Z&to=2026-07-02T00%3A00%3A00Z&aggregate=15m&grouped=false&group=forecast&name=db%3A8&title=Battery&format=json&lang=de'
```

--------------------------------

### Fetch example for POST /batterygriddischarge/true

Source: https://docs.evcc.io/en/integrations/rest-api/operations/setbatterygriddischarge

JavaScript example using fetch to call the endpoint with enable=true. Logs the response or error.

```javascript
const url = 'https://demo.evcc.io/api/batterygriddischarge/true';
const options = {method: 'POST'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

--------------------------------

### Event definition example for start event

Source: https://docs.evcc.io/en/reference/configuration/messaging

Example of defining a start event with title and message using simple placeholder syntax.

```yaml
start: # charge start event
  title: Charge started
  msg: Started charging in "${mode}" mode

```

--------------------------------

### Start evcc

Source: https://docs.evcc.io/en/installation/linux

Launch the evcc application to begin the web-based configuration process.

```bash
./evcc
```

--------------------------------

### cURL example for GET /sessions

Source: https://docs.evcc.io/en/integrations/rest-api/operations/getsessions

Uses cURL to send a GET request to the same endpoint with the same query parameters. The response is not processed further in the example.

```bash
curl --request GET \
  --url 'https://demo.evcc.io/api/sessions?format=csv&lang=de&month=2&year=2025'
```

--------------------------------

### Get State Response Example

Source: https://docs.evcc.io/en/integrations/rest-api/operations/getstate

Example JSON response from the Get State API. Shows the structure of the state object including loadpoints, battery, tariffs, and other configuration sections.

```json
{
  "loadpoints": [
    {
      "chargerStatusReason": "unknown",
      "mode": "off",
      "phaseAction": "inactive",
      "pvAction": "inactive",
      "suggestion": {
        "action": "charge"
      }
    }
  ],
  "currency": "AUD",
  "system": "linux/amd64",
  "timezone": "CEST +02:00",
  "battery": {
    "devices": [
      {
        "suggestion": {
          "action": "normal"
        }
      }
    ]
  },
  "batteryMode": "unknown",
  "tariffs": {
    "yamlSource": "file"
  },
  "hems": {
    "yamlSource": "file"
  },
  "sponsor": {
    "yamlSource": "file"
  },
  "eebus": {
    "yamlSource": "file"
  },
  "remote": {
    "yamlSource": "file"
  },
  "modbusproxy": [
    {
      "readonly": "false",
      "settings": {
        "baudrate": 1200,
        "comset": "8N1"
      }
    }
  ],
  "messaging": {
    "yamlSource": "file"
  },
  "smartCostType": "co2",
  "vehicles": {
    "additionalProperty": {
      "mode": "off"
    }
  },
  "ocpp": {
    "status": {
      "stations": [
        {
          "status": "unknown"
        }
      ]
    }
  },
  "ocppforwarder": {
    "yamlSource": "file"
  }
}
```

--------------------------------

### integrateddevice feature example

Source: https://docs.evcc.io/en/reference/configuration/chargers

Shows how to use the integrateddevice feature and assign an icon.

```yaml
features:
  - integrateddevice
icon: bike
```

--------------------------------

### Create labwc autostart file for kiosk mode

Source: https://docs.evcc.io/en/chargers/openwb-embedded-software-replacement

Contents for /home/pi/.config/labwc/autostart to start Firefox in kiosk mode and configure screen idle behavior.

```bash
/usr/bin/firefox-esr --kiosk http://localhost:7070/ &
/usr/bin/swayidle -w timeout 600 'wlopm --off \*' resume 'wlopm --on \*' &

```

--------------------------------

### Path parameter example: id=1

Source: https://docs.evcc.io/en/integrations/rest-api/operations/deleteloadpointenergyplan

Example value for the required 'id' path parameter, which is the loadpoint index starting at 1.

```text
1
```

--------------------------------

### Configuration example for evcc.yaml

Source: https://docs.evcc.io/en/meters/tq-energy-manager-em420

Use this YAML block to configure the TQ Energy Manager EM420 manually in your evcc.yaml file instead of using the UI.

```yaml
meters:
    - name: my_grid
      type: template
      template: tq-em420
      usage: grid
      host: 192.0.2.2 # IP address or hostname
      token: ey... # Access token, Access token for EM420 (Create in Profile -> Access tokens)
      port: 80 # Port, optional
      device: local # API Device Path, JSON-API -> Data Endpoint (optional)
```

--------------------------------

### Set battery buffer start SoC using cURL

Source: https://docs.evcc.io/en/integrations/rest-api/operations/setbufferstartsoc

Example request using cURL to set the buffer start SoC to 60%.

```bash
curl --request POST \
  --url https://demo.evcc.io/api/bufferstartsoc/60
```

--------------------------------

### Set battery buffer start SoC using Fetch

Source: https://docs.evcc.io/en/integrations/rest-api/operations/setbufferstartsoc

Example request using the JavaScript Fetch API to set the buffer start SoC to 60%.

```javascript
const url = 'https://demo.evcc.io/api/bufferstartsoc/60';
const options = {method: 'POST'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

--------------------------------

### Basic meters configuration example

Source: https://docs.evcc.io/en/reference/configuration/meters

Shows the structure of the `meters` list with entries for grid, pv, battery, charge, and aux. Each entry requires a name and a type.

```yaml
meters:
  - name: grid
    type: ...
  - name: pv
    type: ...
  - name: battery
    type: ...
  - name: charge
    type: ...
  - name: aux
    type: ...

```

--------------------------------

### Configuration example for evcc.yaml

Source: https://docs.evcc.io/en/chargers/compleo-solo

Use this YAML block to configure the Compleo Solo charger manually in your evcc.yaml file instead of using the UI.

```yaml
chargers:
    - name: my_charger
      type: template
      template: compleo-solo


      # Modbus TCP
      modbus: tcpip
      id: 1
      host:  # Hostname
      port: 502 # Port
```

--------------------------------

### Fetch JavaScript example

Source: https://docs.evcc.io/integrations/rest-api/operations/getenergyhistory

JavaScript example using fetch to retrieve energy history data from the demo endpoint. Uses GET method and logs the response or error.

```javascript
const url = 'https://demo.evcc.io/api/history/energy?from=2026-07-01T00%3A00%3A00Z&to=2026-07-02T00%3A00%3A00Z&aggregate=15m&grouped=false&group=forecast&name=db%3A8&title=Battery&format=json&lang=de';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

--------------------------------

### Example response for GET /sessions

Source: https://docs.evcc.io/en/integrations/rest-api/operations/getsessions

Shows an example JSON response array with fields id, loadpoint, and vehicle. The response is an array of objects representing charging sessions.

```json
[
  {
    "id": 1,
    "loadpoint": "Garage",
    "vehicle": "vehicle_1"
  }
]
```

--------------------------------

### Configuration example for evcc.yaml

Source: https://docs.evcc.io/en/chargers/chargeline-business-wallbox

Use this YAML block to configure the ChargeLine Business Wallbox manually in evcc.yaml if not using the UI.

```yaml
chargers:
    - name: my_charger
      type: template
      template: peblar


      # Modbus TCP
      modbus: tcpip
      id: 1
      host:  # Hostname
      port: 502 # Port
```

--------------------------------

### JavaScript fetch example for POST /loadpoints/{id}/mintemp/{temp}

Source: https://docs.evcc.io/en/integrations/rest-api/operations/setloadpointmintemp

Sends a POST request to set the minimum temperature for a loadpoint. Uses the demo URL with id=1 and temp=50. Logs the response JSON or any error.

```JavaScript
const url = 'https://demo.evcc.io/api/loadpoints/1/mintemp/50';
const options = {method: 'POST'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

--------------------------------

### Configuration example for evcc.yaml

Source: https://docs.evcc.io/en/meters/fronius-argeno

Use this YAML block to configure the Fronius Argeno meter manually in evcc.yaml instead of using the UI.

```yaml
meters:
    - name: my_pv
      type: template
      template: fronius-argeno
      usage: pv
      host: 192.0.2.2 # IP address or hostname
      port: 502 # Port, optional
```

--------------------------------

### Example tariff response

Source: https://docs.evcc.io/en/integrations/rest-api/operations/gettariffinfo

Shows a sample JSON response with a rates array containing start, end, and value fields.

```json
{
  "rates": [
    {
      "start": "2026-04-15T12:00:00Z",
      "end": "2026-04-15T12:00:00Z",
      "value": 1
    }
  ]
}
```

--------------------------------

### cURL command example

Source: https://docs.evcc.io/integrations/rest-api/operations/getenergyhistory

cURL command to send a GET request to the energy history endpoint with the specified query parameters.

```shell
curl --request GET \
  --url 'https://demo.evcc.io/api/history/energy?from=2026-07-01T00%3A00%3A00Z&to=2026-07-02T00%3A00%3A00Z&aggregate=15m&grouped=false&group=forecast&name=db%3A8&title=Battery&format=json&lang=de'
```

--------------------------------

### Configure loadpoint phases via MQTT

Source: https://docs.evcc.io/en/integrations/mqtt-api

Example of setting the configured phases for loadpoint 1 to 3 using the mosquitto_pub command.

```bash
mosquitto_pub -t "evcc/loadpoints/1/phasesConfigured/set" -m "3"
```

--------------------------------

### GET /loadpoints/{id}/plan

Source: https://docs.evcc.io/en/integrations/rest-api/operations/getloadpointplan

Returns the current charging plan for the specified loadpoint. The loadpoint is identified by its index, starting at 1.

```APIDOC
## GET /loadpoints/{id}/plan

### Description
Returns the current charging plan for this loadpoint.

### Method
GET

### Endpoint
/loadpoints/{id}/plan

### Parameters
#### Path Parameters
- **id** (integer) - Required - Loadpoint index starting at 1. Must be >= 1.

### Request Example
```
https://demo.evcc.io/api/loadpoints/1/plan
```

### Response
#### Success Response (200)
Media type: application/json

Response body is an object with the following fields:
- **planId** (integer) - Loadpoint index starting at 1. Must be >= 1.
- **duration** (integer) - Duration in seconds.
- **plan** (Array<object>) - A time slot with an associated price or emission value. Each object has:
  - **start** (string, date-time) - Required - Start of the time slot.
  - **end** (string, date-time) - Required - End of the time slot.
  - **value** (number) - Required - Price per kWh in the configured currency or emissions in g/kWh.
- **planTime** (string, date-time) - Timestamp in RFC3339 format.
- **power** (number) - Power in watts.

#### Response Example
```
{
  "planId": 1,
  "power": 2500
}
```
```

--------------------------------

### Enable systemd service at boot

Source: https://docs.evcc.io/en/installation/linux

Configure the evcc service to start automatically when the system boots.

```bash
sudo systemctl enable evcc.service
```

--------------------------------

### Configuration example for evcc.yaml

Source: https://docs.evcc.io/en/meters/esphome-dsmr

Use this YAML block to configure the ESPHome DSMR meter manually in evcc.yaml instead of using the UI.

```yaml
meters:
    - name: my_grid
      type: template
      template: slimmelezer
      usage: grid
      host: 192.0.2.2 # IP address or hostname
      scale: 1000 # Scale factor, Use scale of 1000 for Zuidwijk Slimmelezer. Use scale 1 for ESPHome DSMR and P1 Dongle
```

--------------------------------

### Messaging events with simple placeholder syntax

Source: https://docs.evcc.io/en/reference/configuration/messaging

Complete example of messaging events using simple ${variableName} placeholders for start, stop, connect, and disconnect events.

```yaml
messaging:
  events:
    start:
      title: Charging started
      msg: >-
        ${title} charging ${vehicleTitle} in ${mode} mode
    stop:
      title: Charging finished
      msg: >-
        ${title}: ${vehicleTitle} charged ${chargedEnergy:%.1fk}kWh in ${chargeDuration}.
        Solar share: ${sessionSolarPercentage:%.0f}%
    connect:
      title: Vehicle connected
      msg: >-
        ${vehicleTitle} connected to ${title} at ${pvPower:%.1fk}kW solar
    disconnect:
      title: Vehicle disconnected
      msg: >-
        ${vehicleTitle} disconnected from ${title} after ${connectedDuration}

```

--------------------------------

### Configure DZG DVH4013 for Charger Meter in evcc.yaml

Source: https://docs.evcc.io/en/meters/dzg-dvh4013

Example configuration for using the DZG DVH4013 as a charger meter, showing both serial and TCP/IP Modbus setups.

```yaml
meters:
    - name: my_charger
      type: template
      template: dzg
      usage: charge


      # RS485 via adapter (Modbus RTU)
      modbus: rs485serial
      id: 1
      device: /dev/ttyUSB0 # USB-RS485 Adapter Adresse
      baudrate: 9600 # Prüfe die Geräteeinstellungen, typische Werte sind 9600, 19200, 38400, 57600, 115200
      comset: "8N1" # Kommunikationsparameter für den Adapter


      # RS485 via TCP/IP (Modbus RTU)
      modbus: rs485tcpip
      id: 1
      host:  # Hostname
      port: 502 # Port
```

--------------------------------

### Configure Custom device

Source: https://docs.evcc.io/en/user-defined-devices

Example configuration for a custom control system using HTTP and MQTT plugins to manage power limits.

```yaml
type: custom
maxConsumptionPower:
  source: http
  uri: http://steuerbox.local/api/limit
  jq: .maxPower # Power limit in watts, 0 = no limit
curtailedPercent:
  source: mqtt
  topic: hems/curtail/percent # Allowed feed-in in percent, 100 = no curtailment
productionNominalMax: 10000 # Installed generator power (Wp)
```

--------------------------------

### Configuration example for evcc.yaml

Source: https://docs.evcc.io/en/meters/homewizard-wi-fi-p1-meter

Use this YAML block to configure the HomeWizard Wi-Fi P1 Meter manually if you prefer not to use the UI.

```yaml
meters:
    - name: my_grid
      type: template
      template: homewizard
      usage: grid
      host: 192.0.2.2 # IP address or hostname
```
Tokens:
Raw