### Thermal Load Configuration Example

Source: https://emhass.readthedocs.io/en/latest/_sources/thermal_model.md.txt

Example of defining a thermal load configuration within `def_load_config`. This snippet shows how to set parameters like heating rate, cooling constant, thermal inertia, start temperature, sense, and desired temperatures for a thermal device.

```json
"def_load_config": [
    {},
    {"thermal_config": {
        "heating_rate": 5.0,
        "cooling_constant": 0.1,
        "thermal_inertia": 1.0,
        "overshoot_temperature": 24.0,
        "start_temperature": 20,
        "sense": "heat",
        "desired_temperatures": [20, 21, 20, 19]
    }}
]
```

--------------------------------

### Install Dependencies with uv

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Install project dependencies, including packages for running unit tests, using the uv package manager.

```bash
# With the 'test' packages to run unit tests locally.
uv sync --extra test
# If on ARM, try adding piwheels as an index.
#uv sync --extra test --index=https://www.piwheels.org/simple
```

--------------------------------

### Install Dependencies with pip

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Install project dependencies, including packages for running unit tests, using virtualenv and pip.

```bash
virtualenv .venv

# Then activate the virtualenv, see below...

# With the 'test' packages to run unit tests locally.
python3 -m pip install -e '.[test]'
```

--------------------------------

### Use Solar.Forecast for PV Power

Source: https://emhass.readthedocs.io/en/latest/_sources/forecasts.md.txt

Example of calling the EMHASS API to get a day-ahead optimization using the Solar.Forecast method. Pass the PV peak installed power in kW as a runtime parameter.

```bash
curl -i -H "Content-Type:application/json" -X POST -d '{
	"solar_forecast_kwp":5
}' http://localhost:5000/action/dayahead-optim
```

--------------------------------

### EMHASS Static Configuration Example

Source: https://emhass.readthedocs.io/en/latest/_sources/cookbook/_template.md.txt

This snippet shows an example of static EMHASS configuration keys that should be set before running recipes. It is intended to be directly runnable.

```yaml
# EMHASS config keys, runnable as-is
```

--------------------------------

### Setup Git Repository for Testing Pipeline

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Clones the EMHASS repository from GitHub and checks out a specific branch, setting up the environment for testing.

```bash
#setup environment variables for test
export repo=https://github.com/davidusb-geek/emhass.git
export branch=master
#Ex. HAURL=https://localhost:8123/
export HAURL=HOMEASSISTANTURLHERE
export HAKEY=HOMEASSISTANTKEYHERE

git clone $repo
cd emhass 
git checkout $branch
```

--------------------------------

### Reading Battery SOC from Various Sources

Source: https://emhass.readthedocs.io/en/latest/_sources/cookbook/battery_aware_runtime_params.md.txt

Adapt these examples to read the raw battery SOC from your specific orchestrator or sensor source. Choose the one that best fits your setup.

```javascript
// Pick ONE of these — adapt to your stack:
const soc_raw = flow.get("battery_soc_percent");          // typical HA / Modbus poll
// const soc_raw = msg.payload;                            // if previous node was a sensor read
// const soc_raw = global.get("home_battery").soc;         // global context store
```

--------------------------------

### Configure Multiple Deferrable Loads with Thermal Battery

Source: https://emhass.readthedocs.io/en/latest/_sources/thermal_battery.md.txt

Example configuration demonstrating how to include a thermal battery alongside other deferrable loads like EV chargers or washing machines in the system.

```python
{
  "def_load_config": [
    {},
    {
      "thermal_battery": {
        "supply_temperature": 35.0,
        "volume": 15.0,
        "start_temperature": 22.0,
        "min_temperatures": [20.0] * 48,  # Constant 20°C minimum
        "max_temperatures": [26.0] * 48,  # Constant 26°C maximum
        "u_value": 0.45,
        "envelope_area": 320.0,
        "ventilation_rate": 0.5,
        "heated_volume": 200.0
      }
    },
    {}
  ]
}
```

--------------------------------

### Install Requests-Mock in Docker Container

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Updates package lists and installs the python3-requests-mock package within the running EMHASS Docker container.

```bash
docker exec emhass-test apt-get update 
docker exec emhass-test apt-get install python3-requests-mock -y

```

--------------------------------

### Run Day-Ahead Optimization with Solcast Secrets

Source: https://emhass.readthedocs.io/en/latest/_sources/forecasts.md.txt

Example of running the day-ahead optimization action, passing Solcast API credentials as runtime parameters via a curl command.

```bash
# Example of running day-ahead, passing Solcast secrets via runtime parameters (i.e. not set in configuration)
curl -i -H "Content-Type:application/json" -X POST -d '{
	"solcast_rooftop_id":"<your_system_id>",
	"solcast_api_key":"<your_secret_api_key>"
}' http://localhost:5000/action/dayahead-optim
```

--------------------------------

### Publish Data with Custom Deferrable Load Forecast Sensors

Source: https://emhass.readthedocs.io/en/latest/_sources/publish_data.md.txt

This example demonstrates publishing data with custom sensor configurations for multiple deferrable loads. It uses a list of dictionaries, where each dictionary defines the entity ID, unit of measurement, and friendly name for a specific deferrable load sensor.

```shell
shell_command:
  publish_data: "curl -i -H \"Content-Type:application/json\" -X POST -d '{\"custom_deferrable_forecast_id\": [{\"entity_id\": \"sensor.p_deferrable0\",\"unit_of_measurement\": \"W\", \"friendly_name\": \"Deferrable Load 0\"},{\"entity_id\": \"sensor.p_deferrable1\",\"unit_of_measurement\": \"W\", \"friendly_name\": \"Deferrable Load 1\"}]}' http://localhost:5000/action/publish-data"
```

--------------------------------

### MPC Optimization with Solcast and Amber Prices

Source: https://emhass.readthedocs.io/en/latest/_sources/forecasts.md.txt

Execute a Model Predictive Control (MPC) optimization using curl. This example integrates Solcast PV forecasts and Amber electricity prices for 4 deferrable loads.

```bash
    post_mpc_optim_solcast: "curl -i -H "Content-Type: application/json" -X POST -d '{"load_cost_forecast":{{(
          ([states('sensor.amber_general_price')|float(0)] +
          state_attr('sensor.amber_general_forecast', 'forecasts') |map(attribute='per_kwh')|list)[:48])
          }}, "prod_price_forecast":{{(
          ([states('sensor.amber_feed_in_price')|float(0)] +
          state_attr('sensor.amber_feed_in_forecast', 'forecasts')|map(attribute='per_kwh')|list)[:48]) 
          }}, "pv_power_forecast":{{states('sensor.solcast_24hrs_forecast')
          }}, "prediction_horizon":48,"soc_init":{{(states('sensor.powerwall_charge')|float(0))/100
          }},"soc_final":0.05,"operating_hours_of_each_deferrable_load":[2,0,0,0]}' http://localhost:5000/action/naive-mpc-optim"
```

--------------------------------

### Docker Mount Folder as Data Path

Source: https://emhass.readthedocs.io/en/latest/_sources/mlregressor.md.txt

Example of mounting a folder to be used as the data_path in a Docker container for EMHASS.

```bash
docker run -it --restart always -p 5000:5000 -e LOCAL_COSTFUN="profit" -v ./data:/data -v ./config_emhass.yaml:/app/config_emhass.yaml -v ./secrets_emhass.yaml:/app/secrets_emhass.yaml --name DockerEMHASS <REPOSITORY:TAG>
```

--------------------------------

### Runtime Parameters for Naive MPC Optimization

Source: https://emhass.readthedocs.io/en/latest/_sources/advanced_math_model.md.txt

Example of setting runtime parameters for the naive MPC optimization using a curl command. This allows dynamic adjustment of optimization settings.

```bash
curl -i -H "Content-Type: application/json" -X POST -d '{
    "inverter_stress_cost": 0.5,
    "prediction_horizon": 24
}' http://localhost:5000/action/naive-mpc-optim
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://emhass.readthedocs.io/en/latest/_sources/installation_methods.md.txt

These commands set up a dedicated Python virtual environment for installing and running EMHASS. This isolates dependencies and ensures a clean installation.

```bash
python3 -m venv ~/emhassenv
cd ~/emhassenv
source bin/activate
```

--------------------------------

### Configure ML Regressor Fit in Home Assistant

Source: https://emhass.readthedocs.io/en/latest/_sources/mlregressor.md.txt

Example of configuring the regressor-model-fit endpoint as a Home Assistant rest_command. Verify the URL and payload for correct integration.

```yaml
fit_heating_hours:
  url: http://127.0.0.1:5000/action/regressor-model-fit
  method: POST
  headers:
    content-type: application/json
  payload: >-
    {
    "csv_file": "heating_prediction.csv",
    "features": ["degreeday", "solar"],
    "target": "hours",
    "regression_model": "RandomForestRegression",
    "model_type": "heating_hours_degreeday",
    "timestamp": "timestamp",
    "date_features": ["month", "day_of_week"]
    }
```

--------------------------------

### Naive MPC Optimization with Deferrable Load Parameters

Source: https://emhass.readthedocs.io/en/latest/_sources/advanced_math_model.md.txt

Perform a naive MPC optimization including parameters for deferrable loads such as operating hours, start, and end timesteps. This is a direct API call.

```bash
curl -i -H 'Content-Type:application/json' -X POST -d '{"pv_power_forecast":[0, 70, 141.22, 246.18, 513.5, 753.27, 1049.89, 1797.93, 1697.3, 3078.93], "prediction_horizon":10, "soc_init":0.5,"soc_final":0.6,"operating_hours_of_each_deferrable_load":[1,3],"start_timesteps_of_each_deferrable_load":[0,3],"end_timesteps_of_each_deferrable_load":[0,6]}' http://localhost:5000/action/naive-mpc-optim
```

--------------------------------

### Home Assistant File Notification Setup

Source: https://emhass.readthedocs.io/en/latest/_sources/mlregressor.md.txt

Configure a Home Assistant file notification platform to write data to a CSV file.

```yaml
notify:
  - platform: file
    name: heating_hours_prediction
    timestamp: false
    filename: /share/heating_prediction.csv
```

--------------------------------

### PV-Only System Configuration (No Battery, Heat Pump, Static Tariff)

Source: https://emhass.readthedocs.io/en/latest/_sources/study_cases/reference_configs.md.txt

Configuration for a simpler setup with PV, a heat pump for water heating, and a static electricity tariff. EMHASS helps schedule deferrable loads against PV surplus.

```yaml
set_use_pv: true
solar_forecast_kwp: 8
optimization_time_step: 30

set_use_battery: false

nominal_power_of_deferrable_loads:
  - 3000        # water heater (heat-pump-driven, treat as regular deferrable)
  - 1500        # dishwasher

operating_hours_of_each_deferrable_load:
  - 4
  - 2           # rounded up from typical 1.5 h cycle

# Static prices (no dynamic tariff)
load_cost_forecast_method: list
prod_price_forecast_method: list
# Pass [0.30] * 48 and [0.08] * 48 at runtime, or set in config if truly static.
```

--------------------------------

### Configure Thermal Battery for Modern Home

Source: https://emhass.readthedocs.io/en/latest/_sources/thermal_battery.md.txt

Example configuration for a modern home with underfloor heating, solar, and internal gains. Models a well-insulated building with specific thermal properties and gain factors.

```python
{
  "def_load_config": [
    {
      "thermal_battery": {
        "supply_temperature": 35.0,
        "volume": 18.0,
        "start_temperature": 22.0,
        "min_temperatures": [20.0] * 48,  # Constant 20°C minimum
        "max_temperatures": [28.0] * 48,  # Constant 28°C maximum
        "carnot_efficiency": 0.45,
        "u_value": 0.35,
        "envelope_area": 380.0,
        "ventilation_rate": 0.4,
        "heated_volume": 240.0,
        "window_area": 28.0,
        "shgc": 0.6,
        "internal_gains_factor": 0.7
      }
    }
  ]
}
```

--------------------------------

### EMHASS Static Configuration Example

Source: https://emhass.readthedocs.io/en/latest/_sources/cookbook/transport_nodered_mpc_orchestration.md.txt

Ensure your EMHASS static configuration includes keys that will be driven by runtime parameters. These keys are essential for runtime overrides to function correctly.

```yaml
optim_conf:
  set_use_battery: true                              # if you have a battery
  number_of_deferrable_loads: 2                      # adjust to your setup
  nominal_power_of_deferrable_loads: [3000, 750]
  operating_hours_of_each_deferrable_load: [4, 0]    # overridden per MPC call
  start_timesteps_of_each_deferrable_load: [0, 0]    # overridden per MPC call
  end_timesteps_of_each_deferrable_load: [0, 0]      # overridden per MPC call
```

--------------------------------

### Apartment with Dynamic Tariff Configuration

Source: https://emhass.readthedocs.io/en/latest/_sources/study_cases/reference_configs.md.txt

Configuration for a renter setup with a dynamic tariff, no PV, and no battery. Specifies nominal power and operating hours for deferrable loads like washing machines and dishwashers.

```yaml
set_use_pv: false
set_use_battery: false

nominal_power_of_deferrable_loads:
  - 2200        # washing machine
  - 2000        # dishwasher
  - 1800        # heat-pump tumble dryer

operating_hours_of_each_deferrable_load:
  - 2           # washing machine (rounded up from typical 1.5 h cycle)
  - 2           # dishwasher (rounded up from typical 1.5 h cycle)
  - 1           # tumble dryer
```

--------------------------------

### Configure Thermal Battery for Older Home

Source: https://emhass.readthedocs.io/en/latest/_sources/thermal_battery.md.txt

Example configuration for an older home with radiator heating using a simpler HDD-based approach. Specifies parameters for a less efficient building and heat pump.

```python
{
  "def_load_config": [
    {
      "thermal_battery": {
        "supply_temperature": 50.0,
        "volume": 12.0,
        "start_temperature": 45.0,
        "min_temperatures": [40.0] * 48,  # Constant 40°C minimum
        "max_temperatures": [65.0] * 48,  # Constant 65°C maximum
        "carnot_efficiency": 0.38,
        "specific_heating_demand": 95.0,
        "area": 120.0,
        "base_temperature": 18.0,
        "annual_reference_hdd": 2800.0
      }
    }
  ]
}
```

--------------------------------

### Naive MPC Optimization with Basic Parameters

Source: https://emhass.readthedocs.io/en/latest/_sources/advanced_math_model.md.txt

Perform a naive MPC optimization using basic runtime parameters like PV power forecast, prediction horizon, and SOC limits. This is a direct API call.

```bash
curl -i -H 'Content-Type:application/json' -X POST -d '{"pv_power_forecast":[0, 70, 141.22, 246.18, 513.5, 753.27, 1049.89, 1797.93, 1697.3, 3078.93], "prediction_horizon":10, "soc_init":0.5,"soc_final":0.6}' http://192.168.3.159:5000/action/naive-mpc-optim
```

--------------------------------

### EMHASS Runtime Banner Log Example

Source: https://emhass.readthedocs.io/en/latest/_sources/study_cases/good_practices.md.txt

This log message is emitted at the start of every EMHASS optimization run. It provides essential information about the EMHASS version, Python version, CVXPY version, solver, and operating system, which is useful for bug reporting.

```log
2026-04-26 17:00:00 INFO     EMHASS 0.17.2 | Python 3.11.9 | CVXPY 1.5.3 | Linux-x86_64
```

--------------------------------

### Perfect Optimization (7-day backtest) using Legacy CLI

Source: https://emhass.readthedocs.io/en/latest/_sources/study_cases/legacy_cli.md.txt

Execute a 7-day historical backtest for perfect optimization using the legacy EMHASS CLI. Requires a configuration file and a cost function.

```bash
emhass --action 'perfect-optim' \
       --config '/home/user/emhass/config_emhass.json' \
       --costfun 'profit'
```

--------------------------------

### Build Docker Image with Add-on Local Build Argument

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Builds the Docker image, passing the 'build_version=addon-local' build argument.

```bash
docker build -t emhass/test --build-arg build_version=addon-local .
```

--------------------------------

### Install EMHASS using pip

Source: https://emhass.readthedocs.io/en/latest/_sources/installation_methods.md.txt

Installs the EMHASS Python package within an activated virtual environment. This is the command to use after setting up the environment.

```bash
python3 -m pip install emhass
```

--------------------------------

### VS-Code Dev Container Tasks

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Tasks for installing and running EMHASS within a VS-Code Dev Container environment.

```json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "EMHASS Install",
            "type": "shell",
            "command": "pip install -e .[test]",
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "presentation": {
                "reveal": "always",
                "panel": "new"
            }
        }
    ]
}
```

--------------------------------

### Run Dayahead and MPC Optimizations with Prefixes

Source: https://emhass.readthedocs.io/en/latest/_sources/publish_data.md.txt

Execute dayahead and MPC optimizations with specific prefixes and optimization time steps. Continual publish will use the lowest optimization_time_step.

```bash
# RUN dayahead, with optimization_time_step=30 (default), prefix=dh_ 
curl -i -H 'Content-Type:application/json' -X POST -d '{"publish_prefix":"dh_"}' http://localhost:5000/action/dayahead-optim
# RUN MPC, with optimization_time_step=5, 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
```

--------------------------------

### Docker Mount Single CSV File

Source: https://emhass.readthedocs.io/en/latest/_sources/mlregressor.md.txt

Example of mounting a single CSV file to be used as the data_path in a Docker container for EMHASS.

```bash
docker run -it --restart always -p 5000:5000 -e LOCAL_COSTFUN="profit" -v ./data/heating_prediction.csv:/app/heating_prediction.csv -v ./config_emhass.yaml:/app/config_emhass.yaml -v ./secrets_emhass.yaml:/app/secrets_emhass.yaml --name DockerEMHASS <REPOSITORY:TAG>
```

--------------------------------

### Execute Naive MPC Optimization via API

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Sends a POST request to the /action/naive-mpc-optim endpoint to perform naive MPC optimization. Requires specific JSON payload with PV forecast and prediction horizon.

```bash
curl -i -H 'Content-Type:application/json' -X POST -d '{"pv_power_forecast":[0, 70, 141.22, 246.18, 513.5, 753.27, 1049.89, 1797.93, 1697.3, 3078.93], "prediction_horizon":10, "soc_init":0.5,"soc_final":0.6}' http://localhost:5000/action/naive-mpc-optim

```

--------------------------------

### Integration Code Snippet Example

Source: https://emhass.readthedocs.io/en/latest/_sources/cookbook/_template.md.txt

This snippet represents integration code for a specific transport stack, such as Node-RED. It is intended to be runnable and source-verified.

```javascript
// integration code, runnable, source-verified
```

--------------------------------

### Create EMHASS Directory and Secrets File

Source: https://emhass.readthedocs.io/en/latest/_sources/installation_methods.md.txt

Demonstrates creating a local directory for EMHASS configuration and appending a sample secrets_emhass.yaml file with essential Home Assistant connection details and location information. This is a prerequisite before running the Docker container.

```bash
# cli example of creating an emhass directory and appending a secrets_emhass.yaml file inside
mkdir ~/emhass
cd ~/emhass 
cat <<EOT >> ~/emhass/secrets_emhass.yaml
hass_url: https://myhass.duckdns.org/
long_lived_token: thatverylongtokenhere
time_zone: Europe/Paris
lat: 45.83
lon: 6.86
alt: 4807.8
EOT
docker run --rm -it --restart always  -p 5000:5000 --name emhass-container -v /emhass/share:/share -v /emhass/secrets_emhass.yaml:/app/secrets_emhass.yaml ghcr.io/davidusb-geek/emhass:latest
```

--------------------------------

### Volume Mount Local Data Folder

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Demonstrates how to sync the local 'data' folder with the container's data folder using a volume mount.

```bash
docker run ... -v ./data/:/data/ ...
```

--------------------------------

### CSV Format for Forecast Data

Source: https://emhass.readthedocs.io/en/latest/_sources/forecasts.md.txt

Example of the required CSV file format for passing forecast data. The file should not have a header, and data should be timestamped.

```text
2021-04-29 00:00:00+00:00,287.07
2021-04-29 00:30:00+00:00,274.27
2021-04-29 01:00:00+00:00,243.38
...
```

--------------------------------

### Configure Thermal Battery Deferrable Load

Source: https://emhass.readthedocs.io/en/latest/_sources/study_cases/heat_pump_walkthrough.md.txt

Add the thermal_battery configuration to the deferrable load settings. This example uses underfloor heating parameters.

```yaml
{
  "def_load_config": [
    {},
    {
      "thermal_battery": {
        "supply_temperature": 35.0,
        "volume": 20.0,
        "start_temperature": 22.0,
        "min_temperatures": [20.0] * 48,
        "max_temperatures": [26.0] * 48,
        "carnot_efficiency": 0.45,
        "u_value": 0.35,
        "envelope_area": 280.0,
        "ventilation_rate": 0.4,
        "heated_volume": 320.0,
        "thermal_inertia_time_constant": 2.0
      }
    }
  ]
}
```

--------------------------------

### Make a Prediction with MLForecaster

Source: https://emhass.readthedocs.io/en/latest/_sources/mlforecaster.md.txt

Use the `forecast-model-predict` endpoint to get a prediction from a trained model. An empty JSON body is used for default parameters.

```bash
curl -i -H "Content-Type:application/json" -X POST -d '{}' http://localhost:5000/action/forecast-model-predict
```

--------------------------------

### EMHASS CLI Commands

Source: https://emhass.readthedocs.io/en/latest/_sources/usage_guide.md.txt

The EMHASS CLI provides a way to run various tasks using command-line arguments when installed in a Python virtual environment.

```APIDOC
## emhass CLI Arguments

### Description
Use the `emhass` CLI command followed by arguments to perform tasks.

### Arguments
- `--action` (string) - Required - The desired action. Options: `perfect-optim`, `dayahead-optim`, `naive-mpc-optim`, `publish-data`, `forecast-model-fit`, `forecast-model-predict`, `forecast-model-tune`.
- `--config` (string) - Required - Path to the `config.json` file (including the yaml file itself).
- `--secrets` (string) - Optional - Path to the `secrets_emhass.yaml` file.
- `--costfun` (string) - Optional - Type of cost function. Options: `profit` (default), `cost`, `self-consumption`.
- `--log2file` (boolean) - Optional - Whether to log to a file. Options: `True` or `False` (default).
- `--params` (JSON string) - Optional - Configuration as JSON.
- `--runtimeparams` (JSON string) - Optional - Data passed at runtime.
- `--debug` (boolean) - Optional - Set to `True` for testing purposes.
- `--version` (flag) - Show the current version of EMHASS.
- `--root` (string) - Optional - Path to the EMHASS root directory.
- `--data` (string) - Optional - Path to the data files (.csv & .pkl).

### Example
```bash
emhass --action 'dayahead-optim' --config ~/emhass/config.json --costfun 'profit'
```

### Note
Before running commands, ensure `config.json` and `secrets_emhass.yaml` are correctly configured for your system.
```

--------------------------------

### Upgrade EMHASS Installation

Source: https://emhass.readthedocs.io/en/latest/_sources/installation_methods.md.txt

Updates the EMHASS Python package to the latest version within an activated virtual environment. Use this command for future upgrades.

```bash
python3 -m pip install --upgrade emhass
```

--------------------------------

### API Call with Mixed Forecast Formats

Source: https://emhass.readthedocs.io/en/latest/_sources/forecasts.md.txt

Demonstrates an API call to the naive-MPC-optim action using both list format for pv_power_forecast and dictionary format for load_cost_forecast.

```bash
curl -i -H "Content-Type: application/json" -X POST -d '{
	"pv_power_forecast": [0, 0, 50, 150, 300, ...],
	"load_cost_forecast": {
		"2025-10-16 10:00:00+00:00": 0.25,
		"2025-10-16 11:00:00+00:00": 0.28
	}
}' http://localhost:5000/action/naive-mpc-optim
```

--------------------------------

### Carnot Efficiency Calculation Example

Source: https://emhass.readthedocs.io/en/latest/_sources/thermal_battery.md.txt

Calculates the Carnot efficiency of a heat pump based on its rated COP and operating temperatures. Ensure temperatures are in Kelvin.

```python
carnot_eff = COP_rated × (T_supply_K - T_outdoor_K) / T_supply_K
```

--------------------------------

### Set Environment Variables for Docker Build and Run

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Sets environment variables for Home Assistant URL, key, timezone, and location, then builds and runs the EMHASS Docker container using these variables.

```bash
export EMHASS_URL="YOURHAURLHERE"
export EMHASS_KEY="YOURHAKEYHERE"
export TIME_ZONE="Europe/Paris"
export LAT="45.83"
export LON="6.86"
export ALT="4807.8"

docker build -t emhass/test --build-arg build_version=addon-local .

docker run -it -p 5000:5000 --name emhass-test -e EMHASS_KEY -e EMHASS_URL -e TIME_ZONE -e LAT -e LON -e ALT emhass/test
```

--------------------------------

### Build and Run Docker Add-on Method

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Builds the Docker image for EMHASS and runs a container, passing secrets via options.json. This is used for testing the Add-on method.

```bash
docker build -t emhass/test .

# pass secrets via options.json (similar to what Home Assistant automatically creates from the addon configuration page)
docker run -it -p 5000:5000 --name emhass-test -v ./options.json:/data/options.json emhass/test
```

--------------------------------

### Call ML Regressor Fit Endpoint with cURL

Source: https://emhass.readthedocs.io/en/latest/_sources/mlregressor.md.txt

Example of how to call the regressor-model-fit endpoint using cURL. Ensure the payload matches the desired model configuration.

```bash
curl -i -H "Content-Type:application/json" -X POST -d  '{"csv_file": "heating_prediction.csv", "features": ["degreeday", "solar"], "target": "hour", "regression_model": "RandomForestRegression", "model_type": "heating_hours_degreeday", "timestamp": "timestamp", "date_features": ["month", "day_of_week"], "new_values": [12.79, 4.766, 1, 2] }' http://localhost:5000/action/regressor-model-fit
```

--------------------------------

### Dictionary Format Forecast Data with Curl

Source: https://emhass.readthedocs.io/en/latest/_sources/forecasts.md.txt

Example curl command using the dictionary format for forecast data, including prediction horizon and optimization time step.

```bash
curl -i -H "Content-Type: application/json" -X POST -d '{
	"load_cost_forecast": {
		"2025-10-16 10:00:00+00:00": 0.25,
		"2025-10-16 11:00:00+00:00": 0.28,
		"2025-10-16 12:00:00+00:00": 0.23
	},
	"prediction_horizon": 48,
	"optimization_time_step": 15
}' http://localhost:5000/action/naive-mpc-optim
```

--------------------------------

### Naive MPC Optimization using Rest Command Integration

Source: https://emhass.readthedocs.io/en/latest/_sources/advanced_math_model.md.txt

Configure and execute a naive MPC optimization using the Home Assistant rest_command integration. This allows for more structured payload definition.

```yaml
rest_command:
  url: http://127.0.0.1:5000/action/naive-mpc-optim
  method: POST
  headers:
    content-type: application/json
  payload: >-
    {
      "pv_power_forecast": [0, 70, 141.22, 246.18, 513.5, 753.27, 1049.89, 1797.93, 1697.3, 3078.93],
      "prediction_horizon":10,
      "soc_init":0.5,
      "soc_final":0.6,
      "operating_hours_of_each_deferrable_load":[1,3],
      "start_timesteps_of_each_deferrable_load":[0,3],
      "end_timesteps_of_each_deferrable_load":[0,6]
    }
```

--------------------------------

### Build Docker Image with Architecture and OS Version

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Builds the Docker image, manually specifying the architecture (e.g., armhf) and OS version (e.g., raspbian) to resolve TARGETARCH build issues.

```bash
docker build ... --build-arg TARGETARCH=armhf --build-arg os_version=raspbian ...
```

--------------------------------

### Home Assistant Shell Command: Dyahead Optim with Nordpool List Format

Source: https://emhass.readthedocs.io/en/latest/_sources/forecasts.md.txt

Integrates EMHASS with Nordpool using the list format for forecast data. Requires manual data extraction, slicing, and formatting.

```yaml
shell_command:
	emhass_dayahead_nordpool_list: >
		curl -i -H "Content-Type: application/json" -X POST -d '{
			"load_cost_forecast": {{( (states("sensor.nordpool_kwh_be_eur_3_10_025")|float(0)) + state_attr("sensor.nordpool_kwh_be_eur_3_10_025", "raw_today") | map(attribute="value") | list + state_attr("sensor.nordpool_kwh_be_eur_3_10_025", "raw_tomorrow") | map(attribute="value") | list) [now().hour:][:24]
		}}' http://localhost:5000/action/dayahead-optim
```

--------------------------------

### Configure Solcast Forecast Sensor

Source: https://emhass.readthedocs.io/en/latest/_sources/forecasts.md.txt

Set up a REST sensor in Home Assistant to fetch daily PV production forecasts from Solcast. Ensure the API key and site ID are correctly configured.

```yaml
sensors:

  - platform: rest
    name: "Solcast Forecast Data"
    json_attributes:
      - forecasts
    resource: https://api.solcast.com.au/rooftop_sites/yyyy/forecasts?format=json&api_key=xxx&hours=24
    method: GET
    value_template: "{{ (value_json.forecasts[0].pv_estimate)|round(2) }}"
    unit_of_measurement: "kW"
    device_class: power
    scan_interval: 8000
    force_update: true
```

--------------------------------

### Run EMHASS Docker Container for Unit Testing

Source: https://emhass.readthedocs.io/en/latest/_sources/develop.md.txt

Runs the EMHASS Docker container, mapping volumes for tests, data, and configuration files. This setup is for executing unit tests.

```bash
docker run --rm -it -p 5000:5000 --name emhass-test -v $(pwd)/tests/:/app/tests/ -v $(pwd)/data/:/data/ -v $(pwd)/"secrets_emhass(example).yaml":/app/"secrets_emhass(example).yaml" -v $(pwd)/options.json:/app/options.json -v $(pwd)/config_emhass.yaml:/app/config_emhass.yaml -v $(pwd)/secrets_emhass.yaml:/app/secrets_emhass.yaml emhass/test

```

--------------------------------

### Test and Lint with Aider

Source: https://emhass.readthedocs.io/en/latest/_sources/develop_ai_coders.md.txt

If configured in `.aider.conf.yml`, use '/test' and '/lint' commands within Aider to run tests and checks.

```bash
/test
```

```bash
/lint
```

--------------------------------

### Home Assistant Shell Command: Dyahead Optim with Nordpool Dictionary Format

Source: https://emhass.readthedocs.io/en/latest/_sources/forecasts.md.txt

Integrates EMHASS with Nordpool using the dictionary format for forecast data. Leverages Home Assistant's `tojson` filter for direct data passing.

```yaml
shell_command:
	emhass_dayahead_nordpool: >
		curl -i -H "Content-Type: application/json" -X POST -d '{
			"load_cost_forecast": {{ state_attr("sensor.nordpool_kwh_be_eur_3_10_025", "raw_today") | tojson }},
			"prod_price_forecast": {{ state_attr("sensor.nordpool_kwh_be_eur_3_10_025", "raw_today") | tojson }}
		}' http://localhost:5000/action/dayahead-optim
```

--------------------------------

### EMHASS Optimization Summary Log Example

Source: https://emhass.readthedocs.io/en/latest/_sources/study_cases/good_practices.md.txt

This log message summarizes the total runtime of an EMHASS optimization run and identifies the stage that consumed the most time. This helps in pinpointing performance bottlenecks.

```log
2026-04-26 17:00:01 INFO     Optimization completed in 0.96s (top: optim_solve=0.52s, 54%)
```

--------------------------------

### Configure Thermal Battery with Thermal Inertia

Source: https://emhass.readthedocs.io/en/latest/_sources/thermal_battery.md.txt

Example configuration for a thermal battery that includes a thermal inertia filter to model delays in heat transfer. Useful for systems like concrete slabs.

```python
{
  "def_load_config": [
    {
      "thermal_battery": {
        "supply_temperature": 35.0,
        "volume": 18.0,
        "start_temperature": 22.0,
        "min_temperatures": [20.0] * 48,
        "max_temperatures": [28.0] * 48,
        "carnot_efficiency": 0.45,
        "u_value": 0.35,
        "envelope_area": 380.0,
        "ventilation_rate": 0.4,
        "heated_volume": 240.0,
        "thermal_inertia_time_constant": 2.0
      }
    }
  ]
}
```