mastr950/batcontrol repository overview

⁠batcontrol

Optimize your electricity costs by charging your PV battery when grid electricity is cheap and there is not enough solar power available.

batcontrol makes your battery inverter price-aware: it combines a dynamic electricity tariff (Tibber, aWATTar, evcc), a solar forecast and a consumption profile to decide every few minutes whether the battery should discharge, hold, or charge from the grid.

• Source: https://github.com/MaStr/batcontrol⁠
• Documenation / configuration reference: https://mastr.github.io/batcontrol⁠
• Supported inverters: Fronius GEN24 (Solar API), Fronius Modbus TCP, and any system via the generic MQTT inverter driver.

⁠Tags

Pin a version in production so an unattended update can't change battery behaviour unexpectedly:

<registry>/batcontrol:0.8.0

⁠Quick start

⁠1. Prepare folders and configuration

mkdir -p ./config ./logs

Download the sample config, then edit it (tariff, PV system, battery limits):

curl -fsSL \
  https://raw.githubusercontent.com/MaStr/batcontrol/refs/heads/main/config/batcontrol_config_dummy.yaml \
  -o ./config/batcontrol_config.yaml

A default load profile is used automatically; supply your own ./config/load_profile.csv only if you want to.

⁠2a. Run with plain Docker

docker run -d \
  --name batcontrol \
  -v "$(pwd)/config:/app/config" \
  -v "$(pwd)/logs:/app/logs" \
  -e TZ=Europe/Berlin \
  --restart unless-stopped \
  <registry>/batcontrol:latest

⁠2b. Run with Docker Compose

docker-compose.yml:

services:
  batcontrol:
    image: <registry>/batcontrol:latest
    container_name: batcontrol
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

Start it:

docker compose up -d

Follow the logs:

docker compose logs -f

⁠Home Assistant add-on

If you run Home Assistant OS / Supervised, you do not need this image directly — use the dedicated add-on instead, which wraps batcontrol and integrates it into the HA add-on store:

• Add-on repository: https://github.com/MaStr/batcontrol_ha_addon⁠

Add the repository URL under Settings → Add-ons → Add-on Store → ⋮ → Repositories, then install batcontrol from the list. Configuration is done through the add-on options / the mounted config share, so the volume and timezone notes below also apply there.

batcontrol also publishes its state over MQTT with Home Assistant auto-discovery, so a battery-SoC sensor, current price and mode entities appear automatically once MQTT is enabled in your config. See the MQTT API wiki page⁠.

⁠Volumes

The container is configured entirely through the YAML file in /app/config — there are no functional settings exposed as environment variables (see below). Keep a backup of a known-good batcontrol_config.yaml.

⁠Environment variables

All other configuration (inverter type, tariff provider, solar forecast, battery limits, MQTT, etc.) lives in batcontrol_config.yaml, not in environment variables.

⁠Updating

docker compose pull
docker compose up -d

On shutdown batcontrol restores the inverter settings it saved on startup. When pinning a version tag, bump it deliberately and re-pull; review the release notes at https://github.com/MaStr/batcontrol/releases⁠ before updating in production.

⁠Notes & safety

• Do not run another tool that controls the same inverter/battery (Solar API or Modbus) at the same time — this causes conflicts. Stop the other tool and restart the inverter before starting batcontrol.
• For Fronius Modbus setups with backup/emergency power, run batcontrol from a UPS-backed power source so it stays alive to reset restrictive battery flags if the grid fails.
• This software is provided without warranty and controls real hardware — start with conservative limits and watch the logs during initial setup.

Full documentation and configuration reference: - https://mastr.github.io/batcontrol⁠