HAEO (Home Assistant Energy Optimizer) is a custom integration that optimizes your home's energy usage in real-time using linear programming. It helps you minimize energy costs by intelligently managing battery storage, solar generation, grid import/export, and loads based on electricity prices, forecasts, and system constraints.
HAEO follows the Unix philosophy: do one thing and do it well.
- ✅ Energy optimization using linear programming
- ✅ Network modeling with flexible topology
- ✅ Integration with Home Assistant's sensor ecosystem
HAEO focuses exclusively on optimization and will not add features outside this scope:
- ❌ Solar forecasting - Use existing integrations like Open-Meteo Solar Forecast or Solcast
- ❌ Price fetching - Use integrations like Amber Electric, Nordpool, or Tibber
- ❌ Device control - Use Home Assistant automations
- ❌ Load forecasting - Use HAFO or other integrations
This focused approach means:
- Better integration with the HA ecosystem
- Simpler, more maintainable codebase
- Users can choose best-in-class solutions for each component
- HAEO does optimization exceptionally well
- Installation Guide - Get started with HAEO
- Configuration Guide - Set up your energy system
- Element Configuration - Configure batteries, solar, grids, and loads
- Mathematical Modeling - Understand the optimization
- Developer Guide - Contribute to HAEO
- API Reference - Auto-generated API docs
- Real-time Optimization: Continuously optimizes energy flow across all connected devices
- Multi-device Support: Batteries, solar panels, grid connection, loads, and energy flows
- Price-based Optimization: Minimizes costs using real-time and forecast electricity prices
- Solar Integration: Optimizes solar generation with curtailment support
- Battery Management: Smart charging/discharging based on prices and SOC constraints
- Flexible Configuration: Easy-to-use UI configuration via Home Assistant
- Multiple Solver Support: Choose from HiGHS, GLPK, CBC, and other linear programming solvers
- Rich Sensors: Power, energy, cost, and state of charge sensors for all devices
HAEO builds an energy network model from your configured devices. It uses linear programming to find the optimal power flow. This minimizes your total energy cost over a configurable time horizon (default 48 hours).
- Data Collection: Gathers current state (battery SOC, prices) and forecasts (solar production, loads, price forecasts)
- Network Modeling: Builds a mathematical model representing your energy system with power flow constraints
- Constraint Application: Applies limits (battery capacity, charge rates, grid limits, etc.)
- Cost Optimization: Uses a linear programming solver to minimize total cost
- Result Publishing: Updates Home Assistant sensors with optimal power schedules
- Battery: Energy storage with configurable capacity, charge/discharge rates, and efficiency
- Grid: Bi-directional grid with import/export limits and pricing
- Solar: Solar generation with optional curtailment
- Constant Load: Fixed power loads
- Forecast Load: Variable loads with forecast data
- Node: Virtual metering points for grouping energy flows
- Connection: Power flow paths between devices with optional constraints
- Open HACS in your Home Assistant instance
- Click on "Integrations"
- Click the three dots in the top right corner
- Select "Custom repositories"
- Add this repository URL:
https://github.com/hass-energy/haeo - Select "Integration" as the category
- Click "Add"
- Search for "HAEO" and click "Download"
- Restart Home Assistant
- Download the latest release from the releases page
- Extract the
haeofolder to yourcustom_componentsdirectory - Restart Home Assistant
- Go to Settings → Devices & Services
- Click Add Integration
- Search for HAEO
- Configure your network:
- Name: A unique name for your energy network
- Horizon Hours: Optimization time horizon (1-168 hours, default 48)
- Period Minutes: Time step for optimization (1-60 minutes, default 5)
- Optimizer: Choose your solver (HiGHS recommended)
After creating your network, you can add devices through the integration's options:
- Name: Unique identifier for the battery
- Capacity: Total energy capacity in kWh
- Current Charge Sensor: Entity ID of sensor providing current SOC (%)
- Min/Max Charge Level: Operating range (%)
- Max Charge/Discharge Power: Power limits in kW
- Efficiency: Round-trip efficiency (0-1, e.g., 0.95 for 95%)
- Charge/Discharge Costs: Optional additional costs per kWh
- Name: Identifier for grid
- Import/Export Limits: Maximum power in kW (optional)
- Import/Export Prices: Fixed prices OR forecast sensor entities
- Use live sensors for real-time pricing
- Use forecast sensors for time-of-use optimization
- Name: Identifier for solar system
- Forecast Sensors: Entity IDs providing power forecast
- Curtailment: Enable if you can curtail (reduce) solar output
- Production Price: Value of generated electricity
- Constant Load: Fixed power consumption in kW
- Forecast Load: Variable load with forecast sensor entities
Define how energy flows between devices:
- Source/Target: Connect two devices
- Min/Max Power: Optional flow limits
- Bidirectional flows use negative values
HAEO creates sensors for each device and the network:
- Optimization Cost: Total optimized cost for the time horizon
- Optimization Status: Success, failed, or pending
- Optimization Duration: Time taken to solve (seconds)
- Power: Current optimal power for each device (kW)
- Energy: Current energy level (batteries, kWh)
- State of Charge: Battery SOC (%)
Each sensor includes forecast attributes with timestamped future values.
HAEO uses the HiGHS linear programming solver directly via the highspy Python bindings:
- Fast: High-performance open-source solver
- Reliable: Industry-standard optimization engine
- Integrated: Direct Python bindings with no external dependencies
- Efficient: Optimized for large-scale linear and mixed-integer programming
- Shorter horizons (12-24h): Faster optimization, less lookahead
- Longer horizons (48-168h): Better long-term decisions, slower solve
- Smaller periods (5min): Higher resolution, more variables
- Larger periods (15-60min): Faster solve, coarser control
Balance these based on your hardware and use case.
Optimize when to charge your battery from solar vs. grid based on electricity prices. This determines when to discharge to maximize savings.
Automatically shift battery charging to off-peak hours and discharging to peak hours to minimize electricity costs.
Reduce solar output when grid export prices are negative or very low, preventing paying to export energy.
Plan energy-intensive activities during periods of low prices or high solar production.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
# Clone the repository
git clone https://github.com/hass-energy/haeo.git
cd haeo
# Install dependencies with uv
uv sync
# Run tests
uv run pytest
# Run linters
uv run ruff check
uv run pyright- Issues: GitHub Issues
- Discussions: GitHub Discussions
When reporting issues, please include:
- Home Assistant version
- HAEO version
- Integration configuration (sanitized)
- Relevant logs from Home Assistant
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with HiGHS for linear programming via the
highspyPython bindings - Special mention to EMHASS for bringing out my competitive nature and proving that healthy competition drives innovation
- Uses the Home Assistant integration framework
Note: This integration performs optimization calculations that may be computationally intensive for large networks or long time horizons. Monitor your Home Assistant instance's performance. Adjust configuration as needed.
