Local AI-powered home battery optimization for solar homes

Warning

PUBLIC BETA: Darkstar is currently in Public Beta. This software controls high-power electrical equipment. Always maintain human supervision and ensure your Home Assistant safety cut-offs are configured. Use at your own risk!

Caution

If you're using a Raspberry Pi, ensure you have at least a Raspberry Pi 4 (RPi 5 recommended).

Darkstar is a local, privacy-first energy management system that optimizes your home battery, solar production, and electricity costs using machine learning (LightGBM) and mathematical optimization (MILP).

Features

• Smart Optimization — Minimizes electricity costs over a 48-hour rolling horizon
• ML Forecasting — Learns your home's load and PV production patterns
• Real-time Execution — Automatic inverter control via Home Assistant
• Beautiful Dashboard — React-based UI with live schedule visualization
• Self-Learning — Parameters auto-tune to your home over time. New: Automatic ML model retraining.
• Smart EV Charging — Intelligent charging optimization that respects your house battery and prioritizes cheap grid hours.
• Load Disaggregation — Separates base load from controllable appliances (Water Heater, EV, etc.) for better ML accuracy
• Vacation Mode — Safe anti-legionella water heating while away

Installation

Option 1: Home Assistant Add-on (Recommended)

1. Go to Settings → Add-ons → Add-on store, click ⋮ → Repositories, fill in
   https://github.com/ergetie/darkstar and click Add → Close or click the Add repository button below.
2. Click on Darkstar Energy Manager and press Install.
3. Start the add-on - Darkstar will automatically detect your Home Assistant connection. No manual token required!
4. Click OPEN WEB UI and navigate to Settings in the sidebar to map your sensors.

[DEV] Development Version (Optional)

For testers and developers who want the latest features (and bugs!) from the dev branch:

1. Follow the installation steps above to add the repository.
2. In the Add-on Store, look for [DEV] Darkstar Energy Manager.
3. Note: The Dev version is optimized for amd64 architecture and updates frequently. It can be installed alongside the stable version for testing.

Option 2: Docker Compose

1. Copy config.default.yaml to config.yaml and secrets.example.yaml to secrets.yaml.
2. Edit secrets.yaml with your Home Assistant credentials.
3. Start with docker-compose up -d.
4. Access the UI at http://localhost:5000.

---

Getting Started

Once you have installed Darkstar, follow the comprehensive guide to tune the system for your home:

👉 Read the Configuration Guide

Already configured? Learn how to operate the system daily:

📘 Read the User Manual

---

Configuration

config.yaml

Main configuration for your system:

# Solar arrays (Up to 6 supported)
system:
  solar_arrays:
    - name: "Roof South"
      azimuth: 180
      tilt: 35
      kwp: 6.5
    - name: "Garage West"
      azimuth: 270
      tilt: 20
      kwp: 4.0

# Your Home Assistant sensor mappings
input_sensors:
  battery_soc: sensor.inverter_battery_soc
  pv_power: sensor.inverter_pv_power
  load_power: sensor.inverter_load_power
  # Darkstar automatically aggregates all production sensors
  # if you use sensor.pv_total or similar integration.

# Nordpool price area
nordpool:
  price_area: "SE4"

secrets.yaml

Credentials (never committed to git):

home_assistant:
  url: "http://your-homeassistant:8123"
  token: "your-long-lived-access-token"

openrouter_api_key: "sk-or-v1-..."

notifications:
  discord_webhook_url: ""  # Optional fallback alerts

Water Heater (Optional)

If you have a smart water heater, Darkstar can optimize its heating schedule. It controls the water heater thermostat temperature with set levels:

# In config.yaml - Entity-Centric Configuration (ARC15)
water_heaters:
  - id: main_tank
    name: "Main Water Heater"
    enabled: true
    power_kw: 3.0
    min_kwh_per_day: 6.0
    max_hours_between_heating: 8
    water_min_spacing_hours: 4
    sensor: sensor.vvb_power
    type: binary
    nominal_power_kw: 3.0

# Control entity for the water heater
executor:
  water_heater:
    target_entity: input_number.your_water_heater_temp
    temp_off: 40       # Idle (legionella-safe minimum)
    temp_normal: 60    # Normal scheduled heating
    temp_boost: 70     # Manual boost via Dashboard
    temp_max: 85       # Max temp for PV surplus dumping

Setting	Default	When Used
temp_off	40°C	Idle mode, no active heating
temp_normal	60°C	Planner schedules heating
temp_boost	70°C	You press "Water Boost" button
temp_max	85°C	Excess PV with full battery

EV Charger (Optional)

Darkstar can optimize EV charging as a deferrable load:

# Entity-Centric Configuration (ARC15)
ev_chargers:
  - id: tesla_model_3
    name: "Tesla Model 3"
    enabled: true
    max_power_kw: 11.0
    battery_capacity_kwh: 82.0
    min_soc_percent: 20.0
    target_soc_percent: 80.0
    sensor: sensor.tesla_power
    type: variable
    nominal_power_kw: 11.0

Multiple Devices

You can add multiple water heaters and EV chargers:

water_heaters:
  - id: main_tank
    name: "Main Water Heater"
    enabled: true
    # ... settings
  - id: upstairs_tank
    name: "Upstairs Water Heater"
    enabled: true
    # ... settings

ev_chargers:
  - id: tesla
    name: "Tesla Model 3"
    enabled: true
    # ... settings
  - id: fiat
    name: "Fiat 500e"
    enabled: false  # Disabled, won't be used
    # ... settings

Home Assistant Integration

Darkstar reads sensors and controls your inverter through Home Assistant:

Required Sensors:

• Battery SoC (%)
• Total PV production (kWh)
• Total load consumption (kWh)

Controlled Entities:

• Inverter work mode (export/zero-export)
• Battery charging current limits
• Grid charging switch
• Water heater temperature (optional)

Supported Inverter Profiles:

Brand	OEM / Resold As	Profile Name	Control Unit
Deye	SunSynk, Sol-Ark, Turbo Energy	deye	A
Fronius	GEN24 hybrid series	fronius	W
Sungrow	Sungrow hybrid series	sungrow	W
Solinteg	Reco, Solinteg MHT series	solinteg	W
Generic	Any inverter	generic	A (configurable)

Solinteg / Reco note: This inverter uses a single bidirectional power register instead of separate charge/discharge entities. Set the working mode to Charge-Discharge once before use — Darkstar never changes it (EEPROM protection). See profiles/solinteg.yaml for full setup instructions.

Dashboard

The web UI provides:

• Live Schedule — 48-hour visualization with charge/discharge/export slots
• Forecasting — Compare ML predictions vs. actuals
• Manual Planning — Override or extend the automated schedule
• Settings — Tune parameters without editing YAML files

How It Works

1. Forecasting — Aurora ML predicts your home's energy patterns
2. Strategy — Context-aware adjustments (vacation mode, weather, etc.)
3. Optimization — Kepler solver generates optimal battery schedules
4. Execution — Native executor controls your inverter in real-time

The system re-optimizes every hour to adapt to changing prices and conditions.

---

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).