HAEO - Home Assistant Energy Optimization¶
Welcome to the HAEO documentation! HAEO is a Home Assistant 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.
Quick Links¶
-
Installation
Get started with HAEO installation via HACS or manual setup.
-
Configuration
Learn how to configure your energy system elements and connections.
-
Mathematical Modeling
Understand how HAEO models your energy system using linear programming.
-
Developer Guide
Contribute to HAEO development or build custom extensions.
What is HAEO?¶
HAEO continuously evaluates forecasts, device limits, and prices to produce an optimal plan for your configured elements. It works alongside other Home Assistant integrations that provide sensor data, and exposes its results as sensors you can reference in automations or dashboards.
Key Features¶
Optimization that follows your data¶
HAEO watches the sensors you configure and re-optimizes whenever inputs change. You choose the horizon and resolution through the UI to balance responsiveness with complexity. See the configuration guide for advice on selecting a horizon window.
Built for the Home Assistant ecosystem¶
Configuration uses the standard Home Assistant integration flow and all results appear as sensors, so there is no separate management interface.
Works with diverse energy setups¶
Whether you have storage, on-site generation, flexible loads, or only the grid, HAEO treats each component as an element in the same optimization network.
Extensible modeling¶
The modeling documentation explains how HAEO formulates the linear program, and the developer guide shows how to extend it when new element types are needed.
Documentation Structure¶
User Guide¶
Perfect for end users who want to install and configure HAEO:
- Installation - HACS and manual installation
- Configuration - Setting up your first network
- Element Guides - Detailed configuration for each device type
- Examples - Complete system walkthroughs
- Troubleshooting - Common issues and solutions
Mathematical Modeling¶
For those interested in how the optimization works:
- Mathematical Modeling Overview - Linear programming formulation and network structure
- Battery Model - Storage dynamics and constraints
- Grid Model - Import and export cost modeling
- Component Models - Element-by-element formulations
Developer Guide¶
For contributors and developers:
- Architecture - System design overview
- Setup - Development environment with
uv - Units - Unit system and numerical stability
- Testing - Running and writing tests
- Contributing - Contribution guidelines
Reference¶
Quick reference tables and schemas:
- Element Types - Complete element reference
- Sensor Types - All sensor types and meanings
- Configuration Schema - Full config options
Getting Help¶
- Issues: Report bugs on GitHub Issues
- Discussions: Ask questions in GitHub Discussions
- Contributing: See our contribution guidelines
Next Steps¶
-
New to HAEO?
Start with the installation guide to get HAEO up and running.
-
Want to understand the math?
Explore the mathematical modeling documentation.
-
Want to contribute?
Check out the developer guide and contribution workflow.