{"id":51422895,"url":"https://github.com/ara686/ha-energy-planner","last_synced_at":"2026-07-05T01:00:57.200Z","repository":{"id":369078392,"uuid":"1288086040","full_name":"ara686/ha-energy-planner","owner":"ara686","description":"Home Assistant custom integration for PV, battery, tariff and energy planning","archived":false,"fork":false,"pushed_at":"2026-07-03T13:45:20.000Z","size":115,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-03T14:27:29.419Z","etag":null,"topics":["battery","custom-component","energy-planner","hacs","home-assistant","solar","solcast"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ara686.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-07-03T09:04:09.000Z","updated_at":"2026-07-03T13:43:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ara686/ha-energy-planner","commit_stats":null,"previous_names":["ara686/ha-energy-planner"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ara686/ha-energy-planner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ara686%2Fha-energy-planner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ara686%2Fha-energy-planner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ara686%2Fha-energy-planner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ara686%2Fha-energy-planner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ara686","download_url":"https://codeload.github.com/ara686/ha-energy-planner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ara686%2Fha-energy-planner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35140189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["battery","custom-component","energy-planner","hacs","home-assistant","solar","solcast"],"created_at":"2026-07-05T01:00:49.114Z","updated_at":"2026-07-05T01:00:57.192Z","avatar_url":"https://github.com/ara686.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Energy Planner for Home Assistant\n\nEnglish | [Česky](README.cs.md)\n\nEnergy Planner helps Home Assistant users understand what will probably happen\nwith a home battery during the next day. It combines your recent house\nconsumption, optional managed loads and Solcast PV forecast data that already\nexists in Home Assistant.\n\n\u003e [!WARNING]\n\u003e Energy Planner is experimental software under active development. It is not\n\u003e recommended for production use. Install and use it at your own risk, and do\n\u003e not rely on it for safety-critical, life-critical, property protection,\n\u003e emergency, operational, financial, billing, regulatory, or compliance\n\u003e decisions.\n\nEnergy Planner **does not control anything by itself**. It only creates sensors\nand binary sensors that you can use in dashboards or in your own automations.\n\n## What It Helps With\n\n- See a future battery SoC forecast for the next 24 hours or longer.\n- Decide whether the battery should be charged during a low-tariff period.\n- Decide whether battery discharge is currently still safe for the plan.\n- Estimate unused PV surplus that can be used for flexible loads such as hot\n  water, pool technology or EV charging.\n- Keep managed loads out of the normal house consumption profile, so the planner\n  learns the base household load more realistically.\n\nFor example, with a Czech D25d tariff you can use the forecast to run flexible\nloads from summer PV surplus, and in winter use the low-tariff window to bridge\nthe next high-tariff period.\n\n## Installation\n\n### HACS\n\n1. Add `https://github.com/ara686/ha-energy-planner` as an **Integration**\n   custom repository in HACS.\n2. Install **Energy Planner**.\n3. Restart Home Assistant.\n4. Add **Energy Planner** from **Settings \u003e Devices \u0026 services**.\n\n### Manual Installation\n\n1. Copy `custom_components/energy_planner` into your Home Assistant\n   `custom_components` directory.\n2. Restart Home Assistant.\n3. Add the integration from **Settings \u003e Devices \u0026 services**.\n\nYAML setup is not supported.\n\n## What You Need Before Setup\n\nEnergy Planner is configured from the Home Assistant UI. You select existing HA\nentities during setup.\n\nRequired:\n\n- Battery SoC entity in `%`.\n- Battery capacity entity in `kWh`.\n- Battery minimum/reserve SoC entity in `%`.\n- Whole-home cumulative energy entity in `kWh`.\n\nOptional:\n\n- One or more managed-load cumulative energy entities in `kWh`, such as EV\n  charging, water heater, boiler or pool technology.\n- Solcast PV forecast entities for today, tomorrow and additional days.\n\nIf your home consumption is only available as a power sensor, for example\n`sensor.home_power` in `W`, create a Home Assistant **Integral** helper first and\nuse the resulting `kWh` energy sensor.\n\nSee [detailed configuration](docs/configuration.md) for the full input list,\naccepted units and runtime options.\n\n## First Results\n\nEnergy Planner builds an hourly consumption profile from Home Assistant history.\n\n- If Home Assistant already has history for your selected energy sensors, useful\n  values can appear immediately.\n- On a fresh setup without history, expect the first reasonable results after\n  about 24 hours.\n- Results become more accurate after about 48 hours because the planner has seen\n  repeated samples for the same hour of day.\n\nReconfigure keeps the stored history. If you change a source entity, check the\nresults for a while and only remove the integration if you intentionally want to\ndelete the stored planner history.\n\n## Main Entities To Use\n\nThe exact entity IDs can differ if Home Assistant adds a suffix or if you rename\nentities. Check them in **Settings \u003e Devices \u0026 services \u003e Energy Planner \u003e\nEntities**.\n\nMost useful entities:\n\n| Entity | What it means |\n|--------|---------------|\n| `sensor.energy_planner_soc_forecast` | Forecasted SoC at the configured forecast horizon. Its attributes contain the future forecast points for graphs. |\n| `sensor.energy_planner_soc_forecast_24h` | Forecasted SoC exactly 24 hours from the last calculation. |\n| `binary_sensor.energy_planner_charge_now` | On when the plan says charging is currently useful. |\n| `binary_sensor.energy_planner_discharge_allowed` | On when the plan says battery discharge is still allowed. |\n| `sensor.energy_planner_target_soc` | Target SoC used by the planner. |\n| `sensor.energy_planner_charge_to_soc` | SoC level needed for planned grid charging. |\n| `sensor.energy_planner_safe_discharge_soc` | Lowest SoC that should still preserve the plan. |\n| `sensor.energy_planner_unused_surplus_today` | Estimated unused PV surplus for today. |\n\nSee [all created entities](docs/entities.md) for the complete list.\n\n## Dashboards\n\nStart with these dashboard ideas:\n\n- Future SoC chart from `sensor.energy_planner_soc_forecast`.\n- 24 hour SoC gauge from `sensor.energy_planner_soc_forecast_24h`.\n- Unused PV surplus chart.\n- Home vs managed consumption history chart.\n\nLovelace and ApexCharts examples live in [dashboard examples](docs/dashboard.md).\nScreenshots can be added there later without making this README too long.\n\n## Automation Ideas\n\nEnergy Planner does not operate devices directly, but it provides simple signals\nfor automations:\n\n- Use `binary_sensor.energy_planner_charge_now` to allow grid charging.\n- Use `binary_sensor.energy_planner_discharge_allowed` to allow battery\n  discharge.\n- Use `sensor.energy_planner_unused_surplus_today` to start flexible loads when\n  there is enough predicted PV surplus.\n\nExample automations with placeholders are in\n[automation examples](docs/automations.md). Always test automations manually in\nyour own Home Assistant before letting them control real devices.\n\n## Manual Recalculation\n\nEnergy Planner recalculates automatically. It also reacts to battery SoC changes.\n\nYou can force a recalculation from **Developer Tools \u003e Services**:\n\n```text\nenergy_planner.recalculate\n```\n\n## Troubleshooting\n\n- `insufficient_data` usually means a required source entity is missing,\n  unavailable or not numeric.\n- If the home source is in `W`, convert it to `kWh` with an Integral helper.\n- `warning` usually means a configured optional source, such as a selected\n  Solcast entity, is missing or has no usable forecast data.\n- If forecast graphs are empty, check that\n  `sensor.energy_planner_soc_forecast` has a `points` attribute in\n  **Developer Tools \u003e States**.\n- If values look strange after the first setup, wait until the planner has at\n  least 24 to 48 hours of history.\n\nUse diagnostics from the integration page to inspect configured entities, active\noptions, warnings and the last planner output.\n\n## Removal\n\nTo remove Energy Planner:\n\n1. Open **Settings \u003e Devices \u0026 services \u003e Energy Planner**.\n2. Delete the integration entry.\n3. Remove Energy Planner from HACS if it was installed through HACS.\n4. Restart Home Assistant if Home Assistant asks for a restart.\n\nDeleting the integration entry removes Energy Planner's stored internal history.\nIt does not remove your original source entities, helpers, dashboards or\nautomations.\n\n## More Documentation\n\n- [Detailed configuration](docs/configuration.md)\n- [All created entities](docs/entities.md)\n- [Dashboard examples](docs/dashboard.md)\n- [Automation examples](docs/automations.md)\n- [How the history model works](docs/history.md)\n- [Planner details](docs/planner.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fara686%2Fha-energy-planner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fara686%2Fha-energy-planner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fara686%2Fha-energy-planner/lists"}