{"id":42887583,"url":"https://github.com/hass-energy/haeo","last_synced_at":"2026-04-25T08:05:51.278Z","repository":{"id":317467634,"uuid":"1066130732","full_name":"hass-energy/haeo","owner":"hass-energy","description":"Home Assistant Energy Optimiser","archived":false,"fork":false,"pushed_at":"2026-02-13T07:04:55.000Z","size":12878,"stargazers_count":25,"open_issues_count":39,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-13T08:43:41.993Z","etag":null,"topics":["custom-component","energy-management","energy-optimization","home-assistant","homeassistant","integration","python"],"latest_commit_sha":null,"homepage":"https://haeo.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hass-energy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"hass-energy","buy_me_a_coffee":"haeo.io"}},"created_at":"2025-09-29T04:17:42.000Z","updated_at":"2026-02-13T07:00:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"5f4793f8-deb4-4d2b-a91b-5b58061ec96e","html_url":"https://github.com/hass-energy/haeo","commit_stats":null,"previous_names":["ha-energy-optimiser/haeo","hass-energy/haeo"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/hass-energy/haeo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hass-energy%2Fhaeo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hass-energy%2Fhaeo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hass-energy%2Fhaeo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hass-energy%2Fhaeo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hass-energy","download_url":"https://codeload.github.com/hass-energy/haeo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hass-energy%2Fhaeo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29569856,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T04:18:28.490Z","status":"ssl_error","status_checked_at":"2026-02-18T04:13:49.018Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-component","energy-management","energy-optimization","home-assistant","homeassistant","integration","python"],"created_at":"2026-01-30T14:51:47.950Z","updated_at":"2026-04-19T06:11:00.278Z","avatar_url":"https://github.com/hass-energy.png","language":"Python","funding_links":["https://github.com/sponsors/hass-energy","https://buymeacoffee.com/haeo.io"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"docs/assets/logo.svg\" alt=\"HAEO Logo\" width=\"512\"\u003e\n\u003c/p\u003e\n\n# HAEO - Home Assistant Energy Optimizer\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/integration) [![GitHub Release](https://img.shields.io/github/release/hass-energy/haeo.svg)](https://github.com/hass-energy/haeo/releases) [![License](https://img.shields.io/github/license/hass-energy/haeo.svg)](LICENSE) [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://hass-energy.github.io/haeo/) [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow.svg)](https://buymeacoffee.com/haeo.io)\n\nHAEO (Home Assistant Energy Optimizer) is a custom integration that optimizes your home's energy usage in real-time using linear programming.\nIt 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.\n\n## 🎯 Project Philosophy\n\nHAEO follows the Unix philosophy: **do one thing and do it well**.\n\n### What HAEO Does\n\n- ✅ **Energy optimization** using linear programming\n- ✅ **Network modeling** with flexible topology\n- ✅ **Integration** with Home Assistant's sensor ecosystem\n\n### What HAEO Doesn't Do\n\nHAEO focuses exclusively on optimization and **will not** add features outside this scope:\n\n- ❌ **Solar forecasting** - Use existing integrations like [Open-Meteo Solar Forecast](https://github.com/rany2/ha-open-meteo-solar-forecast) or [Solcast](https://github.com/BJReplay/ha-solcast-solar)\n- ❌ **Price fetching** - Use integrations like Amber Electric, Nordpool, or Tibber\n- ❌ **Device control** - Use Home Assistant automations\n- ❌ **Load forecasting** - Use [HAFO](https://hafo.haeo.io) or other integrations\n\nThis focused approach means:\n\n- Better integration with the HA ecosystem\n- Simpler, more maintainable codebase\n- Users can choose best-in-class solutions for each component\n- HAEO does optimization exceptionally well\n\n## 📚 Documentation\n\n**[Read the full documentation →](https://hass-energy.github.io/haeo/)**\n\n- **[Installation Guide](https://hass-energy.github.io/haeo/user-guide/installation/)** - Get started with HAEO\n- **[Configuration Guide](https://hass-energy.github.io/haeo/user-guide/configuration/)** - Set up your energy system\n- **[Element Configuration](https://hass-energy.github.io/haeo/user-guide/elements/)** - Configure batteries, solar, grids, and loads\n- **[Mathematical Modeling](https://hass-energy.github.io/haeo/modeling/)** - Understand the optimization\n- **[Developer Guide](https://hass-energy.github.io/haeo/developer-guide/)** - Contribute to HAEO\n- **[API Reference](https://hass-energy.github.io/haeo/api/)** - Auto-generated API docs\n\n## ✨ Features\n\n- **Real-time Optimization**: Continuously optimizes energy flow across all connected devices\n- **Multi-device Support**: Batteries, solar panels, grid connection, loads, and energy flows\n- **Price-based Optimization**: Minimizes costs using real-time and forecast electricity prices\n- **Solar Integration**: Optimizes solar generation with curtailment support\n- **Battery Management**: Smart charging/discharging based on prices and SOC constraints\n- **Flexible Configuration**: Easy-to-use UI configuration via Home Assistant\n- **Multiple Solver Support**: Choose from HiGHS, GLPK, CBC, and other linear programming solvers\n- **Rich Sensors**: Power, energy, cost, and state of charge sensors for all devices\n\n## 🎯 How It Works\n\nHAEO builds an energy network model from your configured devices.\nIt uses linear programming to find the optimal power flow.\nThis minimizes your total energy cost over a configurable time horizon (default 48 hours).\n\n### The Optimization Process\n\n1. **Data Collection**: Gathers current state (battery SOC, prices) and forecasts (solar production, loads, price forecasts)\n2. **Network Modeling**: Builds a mathematical model representing your energy system with power flow constraints\n3. **Constraint Application**: Applies limits (battery capacity, charge rates, grid limits, etc.)\n4. **Cost Optimization**: Uses a linear programming solver to minimize total cost\n5. **Result Publishing**: Updates Home Assistant sensors with optimal power schedules\n\n### Supported Devices\n\n- **Battery**: Energy storage with configurable capacity, charge/discharge rates, and efficiency\n- **Grid**: Bi-directional grid with import/export limits and pricing\n- **Solar**: Solar generation with optional curtailment\n- **Constant Load**: Fixed power loads\n- **Forecast Load**: Variable loads with forecast data\n- **Node**: Virtual metering points for grouping energy flows\n- **Connection**: Power flow paths between devices with optional constraints\n\n## 📦 Installation\n\n### HACS Installation (Recommended)\n\n[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=hass-energy\u0026repository=haeo\u0026category=integration)\n\n1. Open HACS in your Home Assistant instance\n2. Click on \"Integrations\"\n3. Click the three dots in the top right corner\n4. Select \"Custom repositories\"\n5. Add this repository URL: `https://github.com/hass-energy/haeo`\n6. Select \"Integration\" as the category\n7. Click \"Add\"\n8. Search for \"HAEO\" and click \"Download\"\n9. Restart Home Assistant\n\n### Manual Installation\n\n1. Download the latest release from the [releases page](https://github.com/hass-energy/haeo/releases)\n2. Extract the `haeo` folder to your `custom_components` directory\n3. Restart Home Assistant\n\n## ⚙️ Configuration\n\n### Initial Setup\n\n1. Go to **Settings** → **Devices \u0026 Services**\n2. Click **Add Integration**\n3. Search for **HAEO**\n4. Configure your network:\n    - **Name**: A unique name for your energy network\n    - **Horizon Hours**: Optimization time horizon (1-168 hours, default 48)\n    - **Period Minutes**: Time step for optimization (1-60 minutes, default 5)\n    - **Optimizer**: Choose your solver (HiGHS recommended)\n\n### Adding Devices\n\nAfter creating your network, you can add devices through the integration's options:\n\n#### Battery Configuration\n\n- **Name**: Unique identifier for the battery\n- **Capacity**: Total energy capacity in kWh\n- **Current Charge Sensor**: Entity ID of sensor providing current SOC (%)\n- **Min/Max Charge Level**: Operating range (%)\n- **Max Charge/Discharge Power**: Power limits in kW\n- **Efficiency**: Round-trip efficiency (0-1, e.g., 0.95 for 95%)\n- **Charge/Discharge Costs**: Optional additional costs per kWh\n\n#### Grid Configuration\n\n- **Name**: Identifier for grid\n- **Import/Export Limits**: Maximum power in kW (optional)\n- **Import/Export Prices**: Fixed prices OR forecast sensor entities\n    - Use live sensors for real-time pricing\n    - Use forecast sensors for time-of-use optimization\n\n#### Solar Configuration\n\n- **Name**: Identifier for solar system\n- **Forecast Sensors**: Entity IDs providing power forecast\n- **Curtailment**: Enable if you can curtail (reduce) solar output\n- **Production Price**: Value of generated electricity\n\n#### Load Configuration\n\n- **Constant Load**: Fixed power consumption in kW\n- **Forecast Load**: Variable load with forecast sensor entities\n\n#### Connections\n\nDefine how energy flows between devices:\n\n- **Source/Target**: Connect two devices\n- **Min/Max Power**: Optional flow limits\n- Bidirectional flows use negative values\n\n## 📊 Sensors\n\nHAEO creates sensors for each device and the network:\n\n### Network Sensors\n\n- **Optimization Cost**: Total optimized cost for the time horizon\n- **Optimization Status**: Success, failed, or pending\n- **Optimization Duration**: Time taken to solve (seconds)\n\n### Device Sensors\n\n- **Power**: Current optimal power for each device (kW)\n- **Energy**: Current energy level (batteries, kWh)\n- **State of Charge**: Battery SOC (%)\n\nEach sensor includes forecast attributes with timestamped future values.\n\n## 🔧 Advanced Configuration\n\n### Optimization Solver\n\nHAEO uses the **HiGHS** linear programming solver directly via the `highspy` Python bindings:\n\n- **Fast**: High-performance open-source solver\n- **Reliable**: Industry-standard optimization engine\n- **Integrated**: Direct Python bindings with no external dependencies\n- **Efficient**: Optimized for large-scale linear and mixed-integer programming\n\n### Time Horizon and Resolution\n\n- **Shorter horizons** (12-24h): Faster optimization, less lookahead\n- **Longer horizons** (48-168h): Better long-term decisions, slower solve\n- **Smaller periods** (5min): Higher resolution, more variables\n- **Larger periods** (15-60min): Faster solve, coarser control\n\nBalance these based on your hardware and use case.\n\n## 📈 Example Use Cases\n\n### Solar + Battery + Grid\n\nOptimize when to charge your battery from solar vs. grid based on electricity prices.\nThis determines when to discharge to maximize savings.\n\n### Time-of-Use Pricing\n\nAutomatically shift battery charging to off-peak hours and discharging to peak hours to minimize electricity costs.\n\n### Solar Curtailment\n\nReduce solar output when grid export prices are negative or very low, preventing paying to export energy.\n\n### Load Shifting\n\nPlan energy-intensive activities during periods of low prices or high solar production.\n\n## 🤝 Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/hass-energy/haeo.git\ncd haeo\n\n# Install dependencies with uv\nuv sync\n\n# Run tests\nuv run pytest\n\n# Run linters\nuv run ruff check\nuv run pyright\n```\n\n## 🐛 Support\n\n- **Issues**: [GitHub Issues](https://github.com/hass-energy/haeo/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/hass-energy/haeo/discussions)\n\nWhen reporting issues, please include:\n\n- Home Assistant version\n- HAEO version\n- Integration configuration (sanitized)\n- Relevant logs from Home Assistant\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [HiGHS](https://highs.dev/) for linear programming via the `highspy` Python bindings\n- Special mention to [EMHASS](https://github.com/davidusb-geek/emhass) for bringing out my competitive nature and proving that healthy competition drives innovation\n- Uses the Home Assistant integration framework\n\n---\n\n**Note**: This integration performs optimization calculations that may be computationally intensive for large networks or long time horizons.\nMonitor your Home Assistant instance's performance.\nAdjust configuration as needed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhass-energy%2Fhaeo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhass-energy%2Fhaeo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhass-energy%2Fhaeo/lists"}