evcc Integration¶

Batcontrol can integrate with evcc (Electric Vehicle Charging Controller) to intelligently manage battery usage during electric vehicle charging. This integration helps prevent unnecessary battery discharge while your EV is charging, optimizing your overall energy management.

How It Works¶

When evcc is charging your electric vehicle, batcontrol can automatically:

Block battery discharge to prevent the home battery from being used while the EV charges
Temporarily adjust discharge limits based on evcc's buffer SOC settings
Monitor multiple charging loadpoints for comprehensive EV charging detection
Restore original settings when charging stops

Basic Configuration¶

evcc:
  enabled: true
  broker: localhost
  port: 1883
  status_topic: evcc/status
  loadpoint_topic:
    - evcc/loadpoints/1/charging
    - evcc/loadpoints/2/charging
  block_battery_while_charging: true

Required Parameters¶

Parameter	Type	Description
`enabled`	boolean	Enable or disable evcc integration
`broker`	string	MQTT broker hostname or IP address (same as evcc uses)
`port`	integer	MQTT broker port (typically 1883 or 8883 for TLS)
`status_topic`	string	MQTT topic for evcc online/offline status
`loadpoint_topic`	list/string	MQTT topic(s) for loadpoint charging status

Basic Parameters Explained¶

status_topic: Usually evcc/status - monitors if evcc is online/offline
loadpoint_topic: Can be a single string or list of topics like:
evcc/loadpoints/1/charging (for loadpoint 1)
evcc/loadpoints/2/charging (for loadpoint 2)
Add more loadpoints as needed for your setup

Advanced Configuration¶

Authentication¶

evcc:
  username: mqtt_user
  password: mqtt_password

TLS/SSL Support¶

⚠️ Note: TLS/SSL support is currently untested and known to be non-functional (same limitation as in the MQTT API). Keep MQTT traffic on a trusted local network.

Battery Management Options¶

evcc:
  block_battery_while_charging: true
  battery_halt_topic: evcc/site/bufferSoc

Parameter	Type	Default	Description
`block_battery_while_charging`	boolean	`true`	If `true`: Block battery discharge while EV is charging. If `false`: Battery discharge follows normal batcontrol algorithm regardless of EV charging status
`battery_halt_topic`	string	unset (disabled)	Topic for dynamic discharge limit control, e.g. `evcc/site/bufferSoc`

Battery Halt Topic (Advanced)¶

The battery_halt_topic enables dynamic battery discharge limit management based on evcc's buffer SOC setting.

How It Works¶

Normal Operation: Batcontrol uses your configured always_allow_discharge_limit
EV Charging Starts:
Batcontrol saves current discharge limit
Sets new limit based on evcc's bufferSoc value
EV Charging Stops:
Restores original discharge limit
Returns to normal battery management

Example Scenario¶

Your normal always_allow_discharge_limit: 0.20 (20%)
evcc bufferSoc setting: 50 (50%)
Result: While EV charges, battery discharge is blocked above 50% SOC instead of 20%

MQTT Topics Monitored¶

Batcontrol subscribes to the following evcc MQTT topics:

Status Monitoring¶

evcc/status - evcc online/offline status (online/offline)

Charging Detection¶

evcc/loadpoints/1/charging - Loadpoint 1 charging status (true/false)
evcc/loadpoints/2/charging - Loadpoint 2 charging status (true/false)
Additional loadpoints as configured

Loadpoint Mode and Connection State (derived automatically)¶

For every configured .../charging topic, batcontrol additionally subscribes to the sibling topics:

evcc/loadpoints/1/mode - Loadpoint charging mode (pv, now, minpv, off)
evcc/loadpoints/1/connected - Whether an EV is connected (true/false)

These are used by peak shaving: peak shaving is automatically disabled while evcc is actively charging or while an EV is connected in PV mode, and re-enabled when the EV disconnects or the mode changes.

Buffer SOC (Optional)¶

evcc/site/bufferSoc - Dynamic discharge threshold (integer 0-100)

Behavior During EV Charging¶

When Charging Starts¶

Battery Blocking: If block_battery_while_charging: true, battery discharge is blocked. If false, battery discharge continues according to normal batcontrol algorithm
Limit Adjustment: If battery_halt_topic configured, discharge limit is temporarily set to buffer SOC
Logging: Batcontrol logs: "evcc is charging, set block" (only if blocking enabled)

When Charging Stops¶

Battery Unblocking: Battery discharge blocking is removed
Limit Restoration: Original discharge limit is restored
Logging: Batcontrol logs: "evcc is not charging, remove block"

When evcc Goes Offline¶

Safety Mechanism: If evcc goes offline while charging, blocks are automatically removed
Limit Restoration: Original settings are restored
Logging: Batcontrol logs: "evcc went offline" and "evcc was charging, remove block"

Example Configurations¶

Single Loadpoint Setup¶

evcc:
  enabled: true
  broker: 192.168.1.100
  port: 1883
  status_topic: evcc/status
  loadpoint_topic: evcc/loadpoints/1/charging
  block_battery_while_charging: true

Multiple Loadpoints with Authentication¶

evcc:
  enabled: true
  broker: evcc.local
  port: 1883
  status_topic: evcc/status
  loadpoint_topic:
    - evcc/loadpoints/1/charging
    - evcc/loadpoints/2/charging
  block_battery_while_charging: true
  username: batcontrol
  password: secure_password

Advanced Setup with Buffer SOC¶

evcc:
  enabled: true
  broker: mqtt.home.local
  port: 1883
  status_topic: evcc/status
  loadpoint_topic:
    - evcc/loadpoints/1/charging
  block_battery_while_charging: true
  battery_halt_topic: evcc/site/bufferSoc
  username: mqtt_user
  password: mqtt_pass

Monitoring Only (No Battery Blocking)¶

evcc:
  enabled: true
  broker: localhost
  port: 1883
  status_topic: evcc/status
  loadpoint_topic:
    - evcc/loadpoints/1/charging
  block_battery_while_charging: false  # Battery discharge follows normal batcontrol algorithm

Use Case: This configuration allows you to monitor EV charging status without affecting battery discharge behavior. The battery will charge/discharge according to batcontrol's normal price-based algorithm, regardless of whether the EV is charging.

Troubleshooting¶

Common Issues¶

Connection Failed
Verify evcc MQTT broker settings match batcontrol configuration
Check network connectivity between batcontrol and MQTT broker
Ensure MQTT credentials are correct
Charging Not Detected
Verify loadpoint topic names match your evcc configuration
Check evcc MQTT API is enabled and publishing messages
Use MQTT client to monitor topics: mosquitto_sub -h localhost -t evcc/+/+
Buffer SOC Not Working
Ensure battery_halt_topic matches evcc's bufferSoc topic
Verify evcc is publishing bufferSoc values
Check logs for: "Enabling battery threshold management"

Debug Logging¶

Enable detailed logging for troubleshooting:

evcc:
  enabled: true
  # ... other config ...
  logger: true  # Enable MQTT debug logging

Log Messages to Watch For¶

"evcc is online" - evcc status detection working
"Loadpoint evcc/loadpoints/1/charging is charging" - charging detection
"evcc is charging, set block" - battery blocking activated
"Enabling battery threshold management" - buffer SOC feature active
"New battery_halt value: 50" - buffer SOC updated

Integration with Home Assistant¶

When using both batcontrol and evcc with Home Assistant:

Use the same MQTT broker for all three systems
Configure evcc auto-discovery: homeassistant topic
Configure batcontrol MQTT auto-discovery for the same topic
Both systems will create entities in Home Assistant automatically

Security Considerations¶

Use authentication for production MQTT brokers
TLS encryption is currently not functional (see above) — keep MQTT traffic on a trusted local network
Ensure MQTT user has appropriate topic permissions
Keep MQTT credentials secure and unique