HAEO - Home Assistant Energy Optimizer¶

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 energy system elements based on electricity prices, forecasts, and system constraints.

Quick Links¶

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 interval tiers.

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¶

HAEO models your energy system as a network of connected elements. Each element—whether it stores energy, generates it, consumes it, or transfers it—participates in a single unified optimization. Learn about available element types in the user guide.

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
• Model Layer Elements - Mathematical building blocks forming the linear programming problem
• Device Layer Elements - How user-configured elements compose models

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

Getting Help¶

• Issues: Report bugs on GitHub Issues
• Discussions: Ask questions in GitHub Discussions
• Contributing: See our contribution guidelines

Next Steps¶