DOCSEARCHbyAlgolia
Submit Docs

emhass Documentation

repository·master·Indexed 20 days ago

https://github.com/davidusb-geek/emhass

An Energy Management System for Home Assistant that uses Linear Programming (LP) and Mixed Integer Linear Programming (MILP) to optimize residential energy consumption. It manages solar generation, battery storage, and controllable loads using weather and consumption forecasts. Features include Day-ahead and Model Predictive Control (MPC) optimization, support for open-source (HiGHS) and commercial solvers (Gurobi, CPLEX), and configurable cost functions for profit, cost minimization, or self-consumption.

Tokens
84.2K
Snippets
170
Records
289
Agent score
67%

What's inside emhass

  1. Overview of EMHASS

    master

    EMHASS (Energy Management for Home Assistant) is a Python-based module designed to optimize household energy usage by interfacing with Home Assistant. It uses Linear Programming to schedule energy loads (like batteries or appliances) to minimize costs or maximize solar self-consumption.

    Core Capabilities:

    • Cost Optimization: Uses Linear Programming to schedule loads during low-cost tariff periods or high PV production.
    • Solar Forecasting: Integrates PV forecasts to optimize battery charging and appliance usage.
    • Machine Learning Forecasting: Uses scikit-learn (via skforecast) to predict household consumption behavior.
    • Thermal Modeling: Manages thermal inertia for water heaters and heat pumps, treating them as thermal energy storage.
    • Home Assistant Integration: Automatically retrieves sensor data from Home Assistant and publishes optimized schedules back to it.

    Technical Foundation:

    • Optimization Engine: Powered by CVXPY using a vectorized backend for high performance.
    • Solver: Uses HiGHS as the default high-performance linear solver.
    • Deployment: Available as a Home Assistant Add-on or a standalone Docker container.

  2. What is Energy Management for Home Assistant (EMHASS)?

    master

    EMHASS is an optimization tool for residential energy management that uses a Linear Programming approach. It generates optimized daily schedules to manage energy usage by considering variables like electricity prices, solar power generation, and battery storage.

    Key capabilities include:

    • Optimization Objectives: Users can define goals such as maximizing solar self-consumption or minimizing total energy costs.
    • Flexible Use Cases: While ideal for households with solar panels and batteries, it can also be used for simple scenarios like optimizing controllable or deferrable loads (e.g., pool pumps, water heaters, or EV chargers).
    • Home Assistant Integration: EMHASS generates the optimization plan, and Home Assistant acts as the execution layer, automating devices based on that plan.

  3. What is EMHASS and its core principles

    master

    EMHASS (Energy Management for Home Assistant) is a Python module designed to optimize home energy usage. It generates an optimization plan by analyzing variables such as solar power production, energy usage, and energy costs.

    Key Features:

    • Real optimization algorithms for energy management.
    • Integration with Home Assistant (though it can be used standalone).
    • Integrated forecasting methods and built-in machine learning.
    • Support for Solar PV, batteries, thermal loads, and more.

    Core Use Cases:

    • Optimizing households with full equipment (Solar, Batteries).
    • Optimizing households with only controllable/deferrable loads (even without solar or batteries).

  4. Overview of the Machine Learning Forecaster

    master

    The Machine Learning (ML) Forecaster is a framework introduced in EMHASS v0.4.0 designed for efficient power load consumption forecasting. It utilizes the skforecast module, which employs scikit-learn regression models using auto-regression lags as features. For hyperparameter optimization, it uses Bayesian optimization via the optuna module.

    The API provides three primary endpoints:

    • forecast-model-fit: Trains a model with provided data.
    • forecast-model-predict: Generates a forecast using a pre-trained model.
    • forecast-model-tune: Optimizes model hyperparameters using Bayesian optimization.

  5. Understand SOC convention and bounds

    master

    EMHASS treats State of Charge (SOC) as a fraction [0.0, 1.0] of the nominal battery capacity (battery_nominal_energy_capacity or Enom).

    • Operational Limits: battery_minimum_state_of_charge (default 0.3) and battery_maximum_state_of_charge (default 0.9) are constraints for the optimizer; they do not rescale the SOC value.
    • Reporting: A value like sensor.soc_optim = 0.45 means 45% of nominal capacity.

    If your downstream automations require a different convention (like percentage of usable range), you must apply that transformation manually in a Home Assistant template.

  6. Use arithmetic expressions with InfluxDB sensors

    master

    When using InfluxDB, you can pass arithmetic expressions instead of single entity IDs for sensor list parameters (like sensor_power_photovoltaics). This allows you to combine multiple time series into a single value (e.g., for unit conversion or calculating net power).

    Syntax: Wrap the expression in {{ ... }} and quote each entity ID with single quotes.

    Supported Operators: +, -, *, /, **, %, unary +/-, and numeric constants.

    Example: To calculate the difference between two sensors with a multiplier: {{'sensor.power_a' - 'sensor.power_b' * 1000}}

    Caveats:

    • Alignment: EMHASS uses GROUP BY time() FILL(previous) to ensure series are aligned on the same time grid.
    • Gaps: If a sensor updates less than once per day, the expression might start with NaN due to the one-day lookback used for forward-filling. Use sensor_replace_zero or sensor_linear_interp to handle these gaps.
    • Failure: If any entity in the expression returns no data, the entire InfluxDB retrieval fails.
    {{'sensor.power_a' - 'sensor.power_b' * 1000}}

  7. Model heat pump efficiency with Carnot or Constant modes

    master

    EMHASS supports two modes for calculating how much heat is produced from electrical input:

    1. Carnot Efficiency (Heat Pumps)

    By default, EMHASS uses a Carnot-based COP that varies with outdoor temperature. Use the carnot_efficiency parameter to set the fraction of the ideal Carnot cycle (typical range: 0.35-0.50).

    2. Constant Efficiency (Boilers/District Heating)

    For non-electric sources like gas boilers or oil burners, set the efficiency parameter. This is a constant energy-conversion factor (output thermal kW / input kW). When efficiency is present, it takes precedence over carnot_efficiency.

    Typical Efficiency Values:

    • Condensing gas boiler: 0.90-0.95
    • Standard gas boiler: 0.85-0.90
    • Oil burner: 0.80-0.90
    • District heating: 0.95-0.98
    • Direct electric heater: 1.0

  8. Understand State of Charge (SOC) conventions

    master

    In emhass, the State of Charge (SOC_opt) is represented as a fraction of the nominal battery capacity.

    • 0.0 = Empty
    • 1.0 = Full

    Note that the configured operational bounds (minimum and maximum SOC) do not rescale this value; they are applied directly to the fraction. For example, if battery_minimum_state_of_charge is set to 0.3, the optimizer will treat 0.3 as the lower limit of the capacity fraction.

  9. Required forecasts for EMHASS optimization

    master

    To function properly, EMHASS requires four specific forecasts:

    • PV power production forecast: Generated using detailed weather forecasts (via open-meteo at 15 min/1 km resolution) and PV modeling using the NREL PVLib module.
    • Load power forecast: Generated using custom machine learning autoregressive models.
    • Load cost forecast: Forecast of energy prices.
    • PV production selling price forecast: Forecast of the price at which excess solar energy can be sold.

  10. How the ML Forecaster works (Recursive Autoregressive Model)

    master

    The machine learning forecaster is based on the skforecast module and uses a recursive autoregressive forecaster with added features.

    Core Mechanism

    The model uses timestamps from Home Assistant to create features such as:

    • Day of the year
    • Hour of the day
    • Day of the week
    • Month of the year

    Future Known Covariates

    Because these timestamp-based features are known in advance, they act as future known covariates. You can extend the model by adding other known future signals, such as:

    • Weather forecasts: (e.g., forecasted outside temperature).
    • Scheduled events: (e.g., a scheduled presence sensor).

    This flexibility allows the forecaster to be used for any sensor variable in Home Assistant, not just load power consumption.

  11. Use Continual Publish for automated updates

    master

    When continual_publish is set to true in your configuration, EMHASS saves optimization outputs as individual .json files in the data_path/entities folder. A background loop runs every optimization_time_step minutes, observing these files and publishing them to Home Assistant. This method automatically updates entity states by comparing the current time with the data timestamps.

    To manage multiple optimization types (e.g., Day-Ahead and MPC) simultaneously, use the publish_prefix runtime parameter. This creates unique entity_id names. The background loop frequency will automatically adapt to the lowest optimization_time_step provided among all active optimizations.

    # Run dayahead with 30m step and prefix 'dh_'
curl -i -H 'Content-Type:application/json' -X POST -d '{"publish_prefix":"dh_"}' http://localhost:5000/action/dayahead-optim

# Run MPC with 5m step and prefix 'mpc_'
curl -i -H 'Content-Type:application/json' -X POST -d '{"optimization_time_step":5,"publish_prefix":"mpc_"}' http://localhost:5000/action/naive-mpc-optim

  12. Configure battery self-identification trust tiers

    master

    The battery_identification_trust_tier setting determines how the calculated estimates are shared with you:

    • observe (default): The estimate is written to a JSON file (battery_identification.json) under your data path and recorded in the logs. No sensors are created in Home Assistant.
    • suggest: In addition to the file and logs, EMHASS publishes two read-only sensors to Home Assistant and logs a recommendation. This allows you to monitor the estimates directly in your dashboard.