index

HSEM Documentation

Home Assistant Solar Energy Management (HSEM) — version 5.1.0

---

Quick reference

Document	Description
Home	User-facing overview: features, FAQ, working modes, battery schedules, excess export, consumption sensors
Battery Charging Economics	How to calculate the minimum charging price for a battery schedule
Architecture Overview	System context, layered architecture, module map, planning pipeline
Planner Specification	Normative — all planner invariants, rules, and constraints
Planner Technical Guide	How the planner works with worked examples
Cost Function Math	Complete mathematical formulation of the 8-term cost function
Energy Accounting	Physical energy flow model, SoC simulation, efficiency math
Candidate Generation	How candidates are generated, assumptions, partial-SoC
MILP Optimization	Full LP formulation, variable layout, constraints, and solver pipeline
Consumption Prediction	Weighted-average model, IQR outlier detection, spike suppression
Safety Modes	Degraded mode, read-only gate, write-verify applier, runtime resolver
Price Scaling	EDS price scaling, eds_share conversion factor
Services Reference	All 4 HSEM services with examples
Sensors Reference	Complete entity reference: all sensor, select, switch, number, and time entities
Dashboard Setup	Step-by-step ApexCharts dashboard with full YAML, layout reference, and troubleshooting
Config Flow Reference	Every config/options flow step and field
EV Charge Plan Setup	EV planned load configuration guide
EV Optimal Charging Template	Legacy Home Assistant template sensor for cost-optimal EV charging
Forecast Accuracy Tracking	Forecast vs actual tracking system
Huawei Entities	Canonical HA entity ID reference
Troubleshooting Guide	Diagnose and fix common problems: missing data, wrong prices, write failures, battery behaviour
Quality Checks	Static quality tools and CI configuration

---

Key files

File	Purpose
planner-spec.md	Read this first before touching any planner code
planner-guide.md	Worked examples for 6 common scenarios
huawei_entities.md	Verified HA entity IDs — never guess
architecture-overview.md	Module responsibility map and dependency graph

---

For developers

1. Always read planner-spec.md before modifying planner code
2. Always check huawei_entities.md before using a battery/inverter value
3. Use Mermaid for architecture and flow diagrams; do not use ASCII/Markdown box diagrams
4. Use math equations ($$ ... $$) for formulas rather than plain text/code-block formulas
5. Run tox -e lint before every commit
6. Run tox -e quality after lint
7. Run pytest tests/ before every PR
8. See AGENTS.md and CLAUDE.md for full development rules