messaging
evcc supports the transmission of status information via Telegram, PushOver, ntfy, and many other services using the shoutrrr system. The configuration allows defining custom messages for specific events and systems.
messaging
defines in sub-elements what and how to send. The events for which messages should be sent must be defined under events
and the services through which the messages should be sent must be defined under services
.
For example:
messaging:
events: ...
services: ...
events
events
defines the message content for various predefined events.
The available events are:
start
: Charging has startedstop
: Charging has stoppedconnect
: Vehicle connecteddisconnect
: Vehicle disconnectedsoc
: Vehicle battery state of charge changedguest
: Unknown vehicle detected
For example:
start: # charge start event
title: Charge started
msg: Started charging in "${mode}" mode
title
title
defines the text for the message title.
For example:
title: Charge started
msg
msg
defines the text for the message content. Various variables in the format ${<variable name>}
can be used to display evcc information in the text.
When using variables, make sure to use the correct capitalisation (uppercase/lowercase)!
Useful messages for use in evcc notifications:
msg Variable | Description |
---|---|
${chargedEnergy:%.1fk} | Energy amount charged in kWh |
${chargeDuration} | Charging duration |
${connectedDuration} | Charger connection duration |
${loadpoint} | Number of loadpoints (charging point) 1,2... |
${mode} | Active charging mode (see mode of loadpoints ) |
${pvPower:%.1fk} | Currently measured PV power in kW |
${title} | Charging point: Text from loadpoints title parameter |
${vehicleTitle} | Vehicle: Text from vehicles title parameter |
For example:
# Message examples using evcc variables
# start
msg: Charger ${title} started charging ${vehicleTitle} in ${mode} mode
# stop
msg: Charger ${title} finished charging ${vehicleTitle} with ${chargedEnergy:%.1fk}kWh in ${chargeDuration}
# connect
msg: ${vehicleTitle} connected on Charger ${title} at ${pvPower:%.1fk}kW PV
# disconnect
msg: ${vehicleTitle} disconnected of Charger ${title} after ${connectedDuration}
To render the msg
texts, you can also use the go text/template syntax in combination with sprig functions.
# Message config using evcc go-text-template rendering, evcc variables and sprig-functions
messaging:
events:
start: # charge start event
title: Charge of {{.vehicleTitle}} started
msg: |
Charger {{.title}} started charging {{.vehicleTitle}} in {{ toString .mode | upper }} mode.
--------------------------
evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
Grid power: {{round (divf .gridPower 1000) 3 }} kW
Solar power: {{round (divf .pvPower 1000) 3 }} kW
Home consumption: {{round (divf .homePower 1000) 3 }} kW
{{if .batteryConfigured}}Battery storage status: {{round (divf .batteryPower 1000) 3 }} kW ({{.batterySoc }} %){{end}}
stop: # charge stop event
title: Charge of {{.vehicleTitle}} finished
msg: |
Charger {{.title}} finished charging {{.vehicleTitle}}
with {{round (divf .chargedEnergy 1000) 2 }} kWh in {{.chargeDuration}}.
--------------------------
evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
Grid power: {{round (divf .gridPower 1000) 3 }} kW
Solar power: {{round (divf .pvPower 1000) 3 }} kW
Home consumption: {{round (divf .homePower 1000) 3 }} kW
{{if .batteryConfigured}}Battery storage status: {{round (divf .batteryPower 1000) 3 }} kW ({{.batterySoc }} %){{end}}
connect: # vehicle connect event
title: "{{.vehicleTitle}} connected on Charger {{.title}}"
msg: |
{{.vehicleTitle}} connected on Charger {{.title}} at {{round (divf .pvPower 1000) 2 }} kW PV.
--------------------------
evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
Grid power: {{round (divf .gridPower 1000) 3 }} kW
Solar power: {{round (divf .pvPower 1000) 3 }} kW
Home consumption: {{round (divf .homePower 1000) 3 }} kW
{{if .batteryConfigured}}Battery storage status: {{round (divf .batteryPower 1000) 3 }} kW ({{.batterySoc }} %){{end}}
disconnect: # vehicle connected event
title: "{{.vehicleTitle}} disconnected of Charger {{.title}}"
msg: |
{{.vehicleTitle}} disconnected of Charger {{.title}} after {{.connectedDuration}}.
--------------------------
evcc Status {{printf `(%d-%02d-%02d %02d:%02d:%02d)` now.Year now.Month now.Day now.Hour now.Minute now.Second}}
Grid power: {{round (divf .gridPower 1000) 3 }} kW
Solar power: {{round (divf .pvPower 1000) 3 }} kW
Home consumption: {{round (divf .homePower 1000) 3 }} kW
{{if .batteryConfigured}}Battery storage status: {{round (divf .batteryPower 1000) 3 }} kW ({{.batterySoc }} %){{end}}
List of all evcc-provided variables:
The variables provided by evcc (also see /api/state) must be defined as ${<VariableName>}
or in the go-template format {{<VariableName>}}
in the message text. Multiple variables in the message text are possible.
- Site
- Configuration
siteTitle
- Main headline of the evcc app (string)prioritySoc
- Minimum Powerwall state of charge in percent before PV mode release (integer)
- Information
batteryConfigured
- Indicator, home battery/Powerwall meter configured (bool)gridConfigured
- Indicator, smart/grid meter configured (bool)pvConfigured
- Indicator, solar panels/photovoltaic meter configured (bool)
- Configuration
- Tariff Information
currency
- Tariff currency (string)tariffFeedIn
- PV feed-in remuneration per kWh in tariff currency (float)tariffGrid
- Grid consumption price per kWh in tariff currency (float)
- Meter Information
batteryPower
- Current home battery/Powerwall power in watts (float)batterySoc
- Current state of charge of home battery/Powerwall in percent (integer)gridPower
- Current grid feed-in(-) or consumption(+) in watts (float)homePower
- Current home consumption power (excluding Charger consumption) in watts (float)pvPower
- Current solar panels power in watts (float)
- Charging Point (loadpoint)
- Configuration
loadpoint
- Loadpoint index (integer)maxCurrent
- Maximum charging current in amperes (float)minCurrent
- Minimum charging current in amperes (float)mode
- Initial mode of the charging point after evcc startoff
/now
/min
/pv
(string)phases
- Initial active number of phases of the charging point after evcc start (integer)title
- Label of the charging point in the evcc app (string)
- Information
activePhases
- Currently active number of phases of the charging point (integer)chargeCurrent
- Current total charging current in amperes (float)chargeCurrents
- Current charging current per active phase in amperes (float)chargeDuration
- Charging duration in nanoseconds (integer)chargePower
- Current charging power in watts (float)chargeRemainingDuration
- Charging time in nanoseconds until the target state of charge (integer)chargeRemainingEnergy
- Required energy until the target state of charge in watt-hours (float)chargedEnergy
- Energy charged so far in watt-hours (float)charging
- Indicator, charging process active (bool)enabled
- Indicator, charging enabled (bool)hasVehicle
- Indicator, vehicle definitions assigned to the charging point (bool)targetTime
- Target charging time in nanoseconds since 1970 UTC (integer)pvAction
- Control variable for PV timer controlenable
/disable
(string)pvRemaining
- Required PV remaining charging time with activated timer control in nanoseconds (integer)
- Configuration
- Vehicles (vehicles)
- Configuration
vehicleCapacity
- Capacity of the vehicle battery in watt-hours (float)vehicleTitle
- Label of the vehicle in the evcc app (string)
- Information
climater
- Status of vehicle climatisationon
/off
/heating
/cooling
(string)connected
- Indicator, vehicle connected to the charging point (bool)connectedDuration
- Duration of vehicle connection in nanoseconds (integer)vehicleOdometer
- Current vehicle odometer reading in kilometers (float)vehiclePresent
- Indicator, evcc can access vehicle data (bool)vehicleRange
- Current vehicle range in kilometers (float)vehicleSoc
- Current state of charge of the vehicle battery in percent (integer)
- Configuration
- Savings Efficiency Information
savingsAmount
- Sum of evcc savings (float)savingsEffectivePrice
- Calculated savings price (float)savingsGridCharged
- Consumed grid energy in Wh (float)savingsSelfConsumptionCharged
- Consumed solar energy in Wh (float)savingsSelfConsumptionPercent
- Percentage of consumed solar energy in Wh (float)savingsSince
- Time period of savings calculation in nanoseconds (integer)savingsTotalCharged
- Total energy consumed in Wh (float)
- Charging Session Information
sessionSolarPercentage
- Solar percentage of the sessionsessionPrice
- Price of the charged energy of the sessionsessionPricePerKWh
- Average price of energy per kWh of the sessionsessionCO<sub>2</sub>PerKWh
- Average CO2 emissions per kWh
- Sponsor
- Configuration
auth
- Authentication token of the evcc sponsor (string)
- Information
sponsor
- Name of the evcc sponsor (string)
- Configuration
services
services
defines a list of message services to be used.
For example:
services:
- type: pushover
app: 12345
recipients:
- 234567
The following sections will now explain all the required parameters.
type
type
defines the type of message service to be used.
Possible values:
-
telegram
: Telegram Messenger. Seetelegram
definition -
email
: Email. Seeemail
definition -
script
: Can initiate external scripts to send messages. It's also useful to include any kind of external functionality. Seescript
definition
For example:
services:
- type: pushover
Supported Services
pushover
pushover
uses the Pushover service. Details can be found at Pushover API.
For example:
- type: pushover
app: # API Token/Key of the created application in Pushover
recipients:
- # List of recipients: either User Key or Delivery Group. Groups created in Pushover can be limited to specific devices.
devices:
- Johns phone
- Mias ticker
telegram
telegram
uses the Telegram Messenger service.
For example:
- type: telegram
token: # bot id : each running instance of evcc needs its own bot id
chats:
- # List of chat or group IDs. Each entry requires a - sign in the beginning and must be in a separate line.
- -GroupID #Note: Group IDs in Telegram have a - sign
- ChatID
email
email
uses the shoutrrr service.
Here, the parameter uri
with the value smtp://<user>:<password>@<host>:<port>/?fromAddress=<from>&toAddresses=<to>
is expected. The placeholders are to be replaced as follows:
<host>
: Address (hostname or IP address) of the email server<port>
: Port address of the email server<user>
: Username for the email server<password>
: User password<from>
: Sender's email address<to>
: Recipient's email address
For example:
- type: email
uri: smtp://username:password@emailserver.domain:1234/?fromAddress=sender@mail.com&toAddresses=recipient@mail.com
shout
shout
uses the shoutrrr service and supports all its services.
The configuration is shown in the following example using Gotify, and the same applies to the other options through the same method.
For example:
- type: shout
uri: gotify://gotify.example.com:443/AzyoeNS.D4iJLVa/?priority=1
Further information can be found in the shoutrrr documentation on supported services.
ntfy
ntfy
uses the ntfy service.
Here, the parameter uri
with the value https://<host>/<topics>
is expected. The placeholders are to be replaced as follows:
<host>
: Address (hostname or IP address) of the ntfy server<topics>
: Subscribed topic or topics
Optional parameters are priority
and tags
. All parameters are passed as strings.
For example:
- type: ntfy
uri: https://ntfy.sh/evcctestalerts
priority: default
tags: electric_plug,blue_car
Further information can be found in the ntfy documentation.
script
script
starts shell scripts or other commands to send messages or start any action based on the events.
The path to the script must be specified in cmdline
. Likewise, a timeout
should be set. The timeout
specifies after how much time the script will be aborted.
For example:
- type: script
cmdline: /home/pi/sendSignalMessage.sh
timeout: 50s