# batcontrol

> batcontrol is open-source (MIT), price-aware battery control for PV home batteries. It combines a dynamic electricity tariff, a solar forecast and a consumption forecast, and every 3 minutes sets the inverter to one of four modes: charge from grid (-1), avoid discharge (0), limit PV charge rate / peak shaving (8), or allow discharge (10). It runs locally (Docker, Home Assistant add-on, Python) and sends no data to a cloud.

Key facts:

- Grid charging only happens when the price spread exceeds `max(min_price_difference, price * min_price_difference_rel)` (defaults 0.05 EUR / 10 %), only for the energy missing for upcoming more expensive hours, and by default only up to 80 % state of charge.
- The battery only supplies the household; batcontrol does not export battery energy to the grid.
- Inverters: Fronius GEN24 (Solar API HTTP, Modbus TCP), any system via MQTT bridge.
- Tariffs: Tibber, aWATTar, evcc, energyforecast.de, static zone tariffs (e.g. Octopus), German §14a EnWG network fees.
- Solar forecast: Forecast.Solar, Solcast, evcc, Home Assistant Solar Forecast ML.
- Integrations: MQTT (Home Assistant auto-discovery), evcc, read-only REST API, dashboard, MCP server.

## Documentation

- [llms.txt of the user documentation](https://mastr.github.io/batcontrol/llms.txt): index of all documentation pages
- [llms-full.txt](https://mastr.github.io/batcontrol/llms-full.txt): complete user documentation in one file
- [How batcontrol works](https://mastr.github.io/batcontrol/getting-started/how-batcontrol-works/): control loop, forecasts, modes, price logic
- [Installation](https://mastr.github.io/batcontrol/getting-started/installation/): Docker, Home Assistant add-on, Python

## Project

- [Source code (GitHub)](https://github.com/MaStr/batcontrol)
- [Releases](https://github.com/MaStr/batcontrol/releases)
- [Home Assistant add-on](https://github.com/MaStr/batcontrol_ha_addon)
- [Docker image](https://hub.docker.com/r/mastr950/batcontrol)

## Optional

- [Homepage (English)](https://batcontrol.software/)
- [Homepage (Deutsch)](https://batcontrol.software/de/)
- [Imprint](https://batcontrol.software/imprint.html)
