From e246a8710c200084b3263f41bc5717ba115b0b57 Mon Sep 17 00:00:00 2001 From: James McMahon Date: Tue, 30 Jul 2024 16:16:40 +0100 Subject: [PATCH] Update README.md --- README.md | 114 +++++++++++++++++++++++++++--------------------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index ee3bb114..d5a1a830 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ Home Assistant provides a platform for the automation of household devices based One of the main benefits of integrating EMHASS and Home Assistant is the ability to customize and tailor the energy management solution to the specific needs and preferences of each household. With EMHASS, households can define their energy management objectives and constraints, such as maximizing self-consumption or minimizing energy costs, and the system will generate an optimization plan accordingly. Home Assistant provides a platform for the automation of devices based on the optimization plan, allowing households to create a fully customized and optimized energy management solution. -Overall, the integration of EMHASS and Home Assistant offers a comprehensive energy management solution that provides significant cost savings, increased energy efficiency, and greater sustainability for households. By leveraging advanced energy management features and automation capabilities, households can achieve their energy management objectives while enjoying the benefits of a more efficient and sustainable energy usage, including optimized EV charging schedules. +Overall, the integration of EMHASS and Home Assistant offers a comprehensive energy management solution that provides significant cost savings, increased energy efficiency, and greater sustainability for households. By leveraging advanced energy management features and automation capabilities, households can achieve their energy management objectives while enjoying the benefits of more efficient and sustainable energy usage, including optimized EV charging schedules. The package flow can be graphically represented as follows: @@ -81,21 +81,21 @@ The package flow can be graphically represented as follows: ## Configuration and Installation -The package is meant to be highly configurable with an object oriented modular approach and a main configuration file defined by the user. -EMHASS was designed to be integrated with Home Assistant, hence it's name. +The package is meant to be highly configurable with an object-oriented modular approach and a main configuration file defined by the user. +EMHASS was designed to be integrated with Home Assistant, hence its name. Installation instructions and example Home Assistant automation configurations are given below. You must follow these steps to make EMHASS work properly: -1) Define all the parameters in the configuration file according to your installation method. For the add-on method you need to use the configuration pane directly on the add-on page. For other installation methods it should be needed to set the variables using the `config_emhass.yaml` file. See below for details on the installation methods. See the description for each parameter in the **configuration** section. If you have a PV installation then this dedicated webapp can be useful to find your inverter and solar panel models: [https://emhass-pvlib-database.streamlit.app/](https://emhass-pvlib-database.streamlit.app/) +1) Define all the parameters in the configuration file according to your installation method. For the add-on method, you need to use the configuration pane directly on the add-on page. For other installation methods, it should be needed to set the variables using the `config_emhass.yaml` file. See below for details on the installation methods. See the description for each parameter in the **configuration** section. If you have a PV installation then this dedicated web app can be useful for finding your inverter and solar panel models: [https://emhass-pvlib-database.streamlit.app/](https://emhass-pvlib-database.streamlit.app/) -2) You most notably will need to define the main data entering EMHASS. This will be the `sensor.power_photovoltaics` for the name of the your hass variable containing the PV produced power and the variable `sensor.power_load_no_var_loads` for the load power of your household excluding the power of the deferrable loads that you want to optimize. +2) You most notably will need to define the main data entering EMHASS. This will be the `sensor.power_photovoltaics` for the name of your hass variable containing the PV produced power and the variable `sensor.power_load_no_var_loads` for the load power of your household excluding the power of the deferrable loads that you want to optimize. -3) Launch the actual optimization and check the results. This can be done manually using the buttons in the web ui or with a `curl` command like this: `curl -i -H 'Content-Type:application/json' -X POST -d '{}' http://localhost:5000/action/dayahead-optim`. +3) Launch the actual optimization and check the results. This can be done manually using the buttons in the web UI or with a `curl` command like this: `curl -i -H 'Content-Type:application/json' -X POST -d '{}' http://localhost:5000/action/dayahead-optim`. -4) If you’re satisfied with the optimization results then you can set the optimization and data publish task commands in an automation. You can read more about this on the **usage** section below. +4) If you’re satisfied with the optimization results then you can set the optimization and data publish task commands in an automation. You can read more about this in the **usage** section below. -5) The final step is to link the deferrable loads variables to real switchs on your installation. An example code for this using automations and the shell command integration is presented below in the **usage** section. +5) The final step is to link the deferrable loads variables to real switches on your installation. An example code for this using automations and the shell command integration is presented below in the **usage** section. A more detailed workflow is given below: @@ -103,7 +103,7 @@ A more detailed workflow is given below: ### Method 1) The EMHASS add-on for Home Assistant OS and supervised users -For Home Assistant OS and HA Supervised users, I've developed an add-on that will help you use EMHASS. The add-on is more user friendly as the configuration can be modified directly in the add-on options pane and as with the standalone docker it exposes a web ui that can be used to inspect the optimization results and manually trigger a new optimization. +For Home Assistant OS and HA Supervised users, I've developed an add-on that will help you use EMHASS. The add-on is more user-friendly as the configuration can be modified directly in the add-on options pane and as with the standalone docker it exposes a web UI that can be used to inspect the optimization results and manually trigger a new optimization. You can find the add-on with the installation instructions here: [https://github.com/davidusb-geek/emhass-add-on](https://github.com/davidusb-geek/emhass-add-on) @@ -126,11 +126,11 @@ Then load the image in the .tar file: ```bash docker load -i .tar ``` -Finally check your image tag with `docker images` and launch the docker itself: +Finally, check your image tag with `docker images` and launch the docker itself: ```bash docker run -it --restart always -p 5000:5000 -e LOCAL_COSTFUN="profit" -v $(pwd)/config_emhass.yaml:/app/config_emhass.yaml -v $(pwd)/secrets_emhass.yaml:/app/secrets_emhass.yaml --name DockerEMHASS ``` - - If you wish to keep a local, persistent copy of the EMHASS generated data, create a local folder on your device, then mount said folder inside the container. + - If you wish to keep a local, persistent copy of the EMHASS-generated data, create a local folder on your device, then mount said folder inside the container. ```bash mkdir -p $(pwd)/data #linux: create data folder on local device @@ -170,9 +170,9 @@ python3 -m pip install --upgrade emhass ### Method 1) Add-on and docker standalone -If using the add-on or the standalone docker installation, it exposes a simple webserver on port 5000. You can access it directly using your brower, ex: http://localhost:5000. +If using the add-on or the standalone docker installation, it exposes a simple webserver on port 5000. You can access it directly using your browser, ex: http://localhost:5000. -With this web server you can perform RESTful POST commands on multiple ENDPOINTS with prefix `action/*`: +With this web server, you can perform RESTful POST commands on multiple ENDPOINTS with the prefix `action/*`: - A POST call to `action/perfect-optim` to perform a perfect optimization task on the historical data. - A POST call to `action/dayahead-optim` to perform a day-ahead optimization task of your home energy. @@ -180,7 +180,7 @@ With this web server you can perform RESTful POST commands on multiple ENDPOINTS - A POST call to `action/publish-data` to publish the optimization results data for the current timestamp. - A POST call to `action/forecast-model-fit` to train a machine learning forecaster model with the passed data (see the [dedicated section](https://emhass.readthedocs.io/en/latest/mlforecaster.html) for more help). - A POST call to `action/forecast-model-predict` to obtain a forecast from a pre-trained machine learning forecaster model (see the [dedicated section](https://emhass.readthedocs.io/en/latest/mlforecaster.html) for more help). -- A POST call to `action/forecast-model-tune` to optimize the machine learning forecaster models hyperparameters using bayesian optimization (see the [dedicated section](https://emhass.readthedocs.io/en/latest/mlforecaster.html) for more help). +- A POST call to `action/forecast-model-tune` to optimize the machine learning forecaster models hyperparameters using Bayesian optimization (see the [dedicated section](https://emhass.readthedocs.io/en/latest/mlforecaster.html) for more help). A `curl` command can then be used to launch an optimization task like this: `curl -i -H 'Content-Type:application/json' -X POST -d '{}' http://localhost:5000/action/dayahead-optim`. @@ -188,8 +188,8 @@ A `curl` command can then be used to launch an optimization task like this: `cur To run a command simply use the `emhass` CLI command followed by the needed arguments. The available arguments are: -- `--action`: That is used to set the desired action, options are: `perfect-optim`, `dayahead-optim`, `naive-mpc-optim`, `publish-data`, `forecast-model-fit`, `forecast-model-predict` and `forecast-model-tune`. -- `--config`: Define path to the config.yaml file (including the yaml file itself) +- `--action`: This is used to set the desired action, options are: `perfect-optim`, `dayahead-optim`, `naive-mpc-optim`, `publish-data`, `forecast-model-fit`, `forecast-model-predict` and `forecast-model-tune`. +- `--config`: Define the path to the config.yaml file (including the yaml file itself) - `--costfun`: Define the type of cost function, this is optional and the options are: `profit` (default), `cost`, `self-consumption` - `--log2file`: Define if we should log to a file or not, this is optional and the options are: `True` or `False` (default) - `--params`: Configuration as JSON. @@ -205,9 +205,9 @@ Before running any valuable command you need to modify the `config_emhass.yaml` ## Home Assistant integration -To integrate with home assistant we will need to define some shell commands in the `configuration.yaml` file and some basic automations in the `automations.yaml` file. -In the next few paragraphs we are going to consider the `dayahead-optim` optimization strategy, which is also the first that was implemented, and we will also cover how to publish the results. -Then additional optimization strategies were developed, that can be used in combination with/replace the `dayahead-optim` strategy, such as MPC, or to expland the funcitonalities such as the Machine Learning method to predict your hosehold consumption. Each of them has some specificities and features and will be considered in dedicated sections. +To integrate with Home Assistant we will need to define some shell commands in the `configuration.yaml` file and some basic automations in the `automations.yaml` file. +In the next few paragraphs, we are going to consider the `dayahead-optim` optimization strategy, which is also the first that was implemented, and we will also cover how to publish the results. +Then additional optimization strategies were developed, that can be used in combination with/replace the `dayahead-optim` strategy, such as MPC, or to expand the funcitonalities such as the Machine Learning method to predict your household consumption. Each of them has some specificities and features and will be considered in dedicated sections. ### Dayahead Optimization - Method 1) Add-on and docker standalone @@ -263,9 +263,9 @@ In `automations.yaml`: action: - service: shell_command.publish_data ``` -In these automation's the day-ahead optimization is performed once a day, everyday at 5:30am, and the data *(output of automation)* is published every 5 minutes. +In these automations the day-ahead optimization is performed once a day, every day at 5:30am, and the data *(output of automation)* is published every 5 minutes. -#### Option 2, EMHASS automate publish +#### Option 2, EMHASS automated publish In `automations.yaml`: ```yaml @@ -282,15 +282,15 @@ in configuration page/`config_emhass.yaml` "method_ts_round": "first" "continual_publish": true ``` -In this automation the day-ahead optimization is performed once a day, everyday at 5:30am. -If the `freq` parameter is set to `30` *(default)* in the configuration, the results of the day-ahead optimization will generate 48 values *(for each entity)*, a value for each 30 minutes in a day *(i.e. 24 hrs x 2)*. +In this automation, the day-ahead optimization is performed once a day, every day at 5:30am. +If the `freq` parameter is set to `30` *(default)* in the configuration, the results of the day-ahead optimization will generate 48 values *(for each entity)*, a value for every 30 minutes in a day *(i.e. 24 hrs x 2)*. -Setting the parameter `continual_publish` to `true` in the configuration page, will allow EMHASS to store the optimization results as entities/sensors into seperate json files. `continual_publish` will periodically (every `freq` amount of minutes) run a publish, and publish the optimization results of each generated entities/sensors to Home Assistant. The current state of the sensor/entity being updated every time publish runs, selecting one of the 48 stored values, by comparing the stored values timestamps, the current timestamp and [`"method_ts_round": "first"`](#the-publish-data-specificities) to select the optimal stored value for the current state. +Setting the parameter `continual_publish` to `true` in the configuration page will allow EMHASS to store the optimization results as entities/sensors into separate json files. `continual_publish` will periodically (every `freq` amount of minutes) run a publish, and publish the optimization results of each generated entities/sensors to Home Assistant. The current state of the sensor/entity being updated every time publish runs, selecting one of the 48 stored values, by comparing the stored values' timestamps, the current timestamp and [`"method_ts_round": "first"`](#the-publish-data-specificities) to select the optimal stored value for the current state. -option 1 and 2 are very similar, however option 2 (`continual_publish`) will require a cpu thread to constantly be run inside of EMHASS, lowering efficiency. The reason why you may pick one over the other is explained in more detail bellow in [continual_publish](#continual_publish-emhass-automation). +option 1 and 2 are very similar, however, option 2 (`continual_publish`) will require a CPU thread to constantly be run inside of EMHASS, lowering efficiency. The reason why you may pick one over the other is explained in more detail below in [continual_publish](#continual_publish-emhass-automation). -Lastly, we can link a EMHASS published entities/sensor's current state to a Home Assistant entity on/off switch, controlling a desired controllable load. -For example, imagine that I want to control my water heater. I can use a published `deferrable` EMHASS entity to control my water heaters desired behavior. In this case, we could use an automation like below, to control the desired water heater on and off: +Lastly, we can link an EMHASS published entity/sensor's current state to a Home Assistant entity on/off switch, controlling a desired controllable load. +For example, imagine that I want to control my water heater. I can use a published `deferrable` EMHASS entity to control my water heater's desired behavior. In this case, we could use an automation like the below, to control the desired water heater on and off: on: ```yaml @@ -322,13 +322,13 @@ automation: - service: homeassistant.turn_off entity_id: switch.water_heater_switch ``` -The result of these automation's will turn on and off the Home Assistant entity `switch.water_heater_switch` using the current state from the EMHASS entity `sensor.p_deferrable0`. `sensor.p_deferrable0` being the entity generated from the EMHASS day-ahead optimization and published by examples above. The `sensor.p_deferrable0` entity current state being updated every 30 minutes (or `freq` minutes) via a automated publish option 1 or 2. *(selecting one of the 48 stored data values)* +These automations will turn on and off the Home Assistant entity `switch.water_heater_switch` using the current state from the EMHASS entity `sensor.p_deferrable0`. `sensor.p_deferrable0` being the entity generated from the EMHASS day-ahead optimization and published by examples above. The `sensor.p_deferrable0` entity's current state is updated every 30 minutes (or `freq` minutes) via an automated publish option 1 or 2. *(selecting one of the 48 stored data values)* ## The publish-data specificities -`publish-data` (which is either run manually, or automatically via `continual_publish` or Home Assistant automation), will push the optimization results to Home Assistant for each deferrable load defined in the configuration. For example if you have defined two deferrable loads, then the command will publish `sensor.p_deferrable0` and `sensor.p_deferrable1` to Home Assistant. When the `dayahead-optim` is launched, after the optimization, either entity json files or a csv file will be saved on disk. The `publish-data` command will load the latest csv/json files to look for the closest timestamp that match the current time using the `datetime.now()` method in Python. This means that if EMHASS is configured for 30min time step optimizations, the csv/json will be saved with timestamps 00:00, 00:30, 01:00, 01:30, ... and so on. If the current time is 00:05, and parameter `method_ts_round` is set to `nearest` in the configuration, then the closest timestamp of the optimization results that will be published is 00:00. If the current time is 00:25, then the closest timestamp of the optimization results that will be published is 00:30. +`publish-data` (which is either run manually or automatically via `continual_publish` or Home Assistant automation), will push the optimization results to Home Assistant for each deferrable load defined in the configuration. For example, if you have defined two deferrable loads, then the command will publish `sensor.p_deferrable0` and `sensor.p_deferrable1` to Home Assistant. When the `dayahead-optim` is launched, after the optimization, either entity json files or a csv file will be saved on disk. The `publish-data` command will load the latest csv/json files to look for the closest timestamp that matches the current time using the `datetime.now()` method in Python. This means that if EMHASS is configured for 30-minute time step optimizations, the csv/json will be saved with timestamps 00:00, 00:30, 01:00, 01:30, ... and so on. If the current time is 00:05, and parameter `method_ts_round` is set to `nearest` in the configuration, then the closest timestamp of the optimization results that will be published is 00:00. If the current time is 00:25, then the closest timestamp of the optimization results that will be published is 00:30. -The `publish-data` command will also publish PV and load forecast data on sensors `p_pv_forecast` and `p_load_forecast`. If using a battery, then the battery optimized power and the SOC will be published on sensors `p_batt_forecast` and `soc_batt_forecast`. On these sensors the future values are passed as nested attributes. +The `publish-data` command will also publish PV and load forecast data on sensors `p_pv_forecast` and `p_load_forecast`. If using a battery, then the battery-optimized power and the SOC will be published on sensors `p_batt_forecast` and `soc_batt_forecast`. On these sensors, the future values are passed as nested attributes. If you run publish manually *(or via a Home Assistant Automation)*, it is possible to provide custom sensor names for all the data exported by the `publish-data` command. For this, when using the `publish-data` endpoint we can just add some runtime parameters as dictionaries like this: ```yaml @@ -343,7 +343,7 @@ If you provide the `custom_deferrable_forecast_id` then the passed data should b 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" ``` -And you should be careful that the list of dictionaries has the correct length, which is the number of defined deferrable loads. +You should be careful that the list of dictionaries has the correct length, which is the number of defined deferrable loads. ### Computed variables and published data @@ -354,7 +354,7 @@ Below you can find a list of the variables resulting from EMHASS computation, sh | P_PV | Forecasted power generation from your solar panels (Watts). This helps you predict how much solar energy you will produce during the forecast period. | sensor.p_pv_forecast | | P_Load | Forecasted household power consumption (Watts). This gives you an idea of how much energy your appliances are expected to use. | sensor.p_load_forecast | | P_deferrableX
[X = 0, 1, 2, ...] | Forecasted power consumption of deferrable loads (Watts). Deferable loads are appliances that can be managed by EMHASS. EMHASS helps you optimise energy usage by prioritising solar self-consumption and minimizing reliance on the grid or by taking advantage or supply and feed-in tariff volatility. You can have multiple deferable loads and you use this sensor in HA to control these loads via smart switch or other IoT means at your disposal. | sensor.p_deferrableX | -| P_grid_pos | Forecasted power imported from the grid (Watts). This indicates the amount of energy you are expected to draw from the grid when your solar production is insufficient to meet your needs or it is advantagous to consume from the grid. | - | +| P_grid_pos | Forecasted power imported from the grid (Watts). This indicates the amount of energy you are expected to draw from the grid when your solar production is insufficient to meet your needs or it is advantageous to consume from the grid. | - | | P_grid_neg | Forecasted power exported to the grid (Watts). This indicates the amount of excess solar energy you are expected to send back to the grid during the forecast period. | - | | P_batt | Forecasted (dis)charge power load (Watts) for the battery (if installed). If negative it indicates the battery is charging, if positive that the battery is discharging. | sensor.p_batt_forecast | | P_grid | Forecasted net power flow between your home and the grid (Watts). This is calculated as P_grid_pos - P_grid_neg. A positive value indicates net export, while a negative value indicates net import. | sensor.p_grid_forecast | @@ -368,34 +368,34 @@ Below you can find a list of the variables resulting from EMHASS computation, sh ## Passing your own data -In EMHASS we have basically 4 forecasts to deal with: +In EMHASS we have 4 forecasts to deal with: - PV power production forecast (internally based on the weather forecast and the characteristics of your PV plant). This is given in Watts. -- Load power forecast: how much power your house will demand on the next 24h. This is given in Watts. +- Load power forecast: how much power your house will demand in the next 24 hours. This is given in Watts. -- Load cost forecast: the price of the energy from the grid on the next 24h. This is given in EUR/kWh. +- Load cost forecast: the price of the energy from the grid in the next 24 hours. This is given in EUR/kWh. -- PV production selling price forecast: at what price are you selling your excess PV production on the next 24h. This is given in EUR/kWh. +- PV production selling price forecast: at what price are you selling your excess PV production in the next 24 hours. This is given in EUR/kWh. -The sensor containing the load data should be specified in parameter `var_load` in the configuration file. As we want to optimize the household energies, when need to forecast the load power consumption. The default method for this is a naive approach using 1-day persistence. The load data variable should not contain the data from the deferrable loads themselves. For example, lets say that you set your deferrable load to be the washing machine. The variable that you should enter in EMHASS will be: `var_load: 'sensor.power_load_no_var_loads'` and `sensor.power_load_no_var_loads = sensor.power_load - sensor.power_washing_machine`. This is supposing that the overall load of your house is contained in variable: `sensor.power_load`. The sensor `sensor.power_load_no_var_loads` can be easily created with a new template sensor in Home Assistant. +The sensor containing the load data should be specified in the parameter `var_load` in the configuration file. As we want to optimize household energy, we need to forecast the load power consumption. The default method for this is a naive approach using 1-day persistence. The load data variable should not contain the data from the deferrable loads themselves. For example, let's say that you set your deferrable load to be the washing machine. The variables that you should enter in EMHASS will be: `var_load: 'sensor.power_load_no_var_loads'` and `sensor.power_load_no_var_loads = sensor.power_load - sensor.power_washing_machine`. This is supposing that the overall load of your house is contained in the variable: `sensor.power_load`. The sensor `sensor.power_load_no_var_loads` can be easily created with a new template sensor in Home Assistant. -If you are implementing a MPC controller, then you should also need to provide some data at the optimization runtime using the key `runtimeparams`. +If you are implementing an MPC controller, then you should also need to provide some data at the optimization runtime using the key `runtimeparams`. -The valid values to pass for both forecast data and MPC related data are explained below. +The valid values to pass for both forecast data and MPC-related data are explained below. ### Alternative publish methods -Due to the flexibility of EMHASS, multiple different approaches to publishing the optimization results have been created. Select a option that best meets your use case: +Due to the flexibility of EMHASS, multiple different approaches to publishing the optimization results have been created. Select an option that best meets your use case: #### publish last optimization *(manual)* -By default, running an optimization in EMHASS will output the results into the csv file: `data_path/opt_res_latest.csv` *(overriding the existing data on that file)*. We run the publish command to publish the last optimization saved in the `opt_res_latest.csv`: +By default, running an optimization in EMHASS will output the results into the CSV file: `data_path/opt_res_latest.csv` *(overriding the existing data on that file)*. We run the publish command to publish the last optimization saved in the `opt_res_latest.csv`: ```bash # RUN dayahead curl -i -H 'Content-Type:application/json' -X POST -d {} http://localhost:5000/action/dayahead-optim # Then publish teh results of dayahead curl -i -H 'Content-Type:application/json' -X POST -d {} http://localhost:5000/action/publish-data ``` -*Note, the published entities from the publish-data action will not automatically update the entities current state (current state being used to check when to turn on and off appliances via Home Assistant automatons). To update the EMHASS entities state, another publish would have to be re-run later when the current time matches the next values timestamp (E.g every 30 minutes). See examples bellow for methods to automate the publish-action.* +*Note, the published entities from the publish-data action will not automatically update the entities' current state (current state being used to check when to turn on and off appliances via Home Assistant automatons). To update the EMHASS entities state, another publish would have to be re-run later when the current time matches the next value's timestamp (e.g. every 30 minutes). See examples below for methods to automate the publish-action.* #### continual_publish *(EMHASS Automation)* As discussed in [Common for any installation method - option 2](#option-2-emhass-automate-publish), setting `continual_publish` to `true` in the configuration saves the output of the optimization into the `data_path/entities` folder *(a .json file for each sensor/entity)*. A constant loop (in `freq` minutes) will run, observe the .json files in that folder, and publish the saved files periodically (updating the current state of the entity by comparing date.now with the saved data value timestamps). @@ -412,7 +412,7 @@ This will tell continual_publish to loop every 5 minutes based on the freq passe
-*It is recommended to use the 2 other options bellow once you have a more advance understanding of EMHASS and/or Home Assistant.* +*It is recommended to use the 2 other options below once you have a more advanced understanding of EMHASS and/or Home Assistant.* #### Mixture of continual_publish and manual *(Home Assistant Automation for Publish)* @@ -430,7 +430,7 @@ This example saves the dayahead optimization into `data_path/entities` as .json #### Manual *(Home Assistant Automation for Publish)* -For users who wish to have full control of exactly when they will like to run a publish and have the ability to save multiple different optimizations. The `entity_save` runtime parameter has been created to save the optimization output entities to .json files whilst `continual_publish` is set to `false` in the configuration. Allowing the user to reference the saved .json files manually via a publish: +For users who wish to have full control of exactly when they would like to run a publish and have the ability to save multiple different optimizations. The `entity_save` runtime parameter has been created to save the optimization output entities to .json files whilst `continual_publish` is set to `false` in the configuration. Allowing the user to reference the saved .json files manually via a publish: in configuration page/`config_emhass.yaml` : ```json @@ -459,9 +459,9 @@ This action will publish the dayahead (_dh) and MPC (_mpc) optimization results ### Forecast data at runtime -It is possible to provide EMHASS with your own forecast data. For this just add the data as list of values to a data dictionary during the call to `emhass` using the `runtimeparams` option. +It is possible to provide EMHASS with your own forecast data. For this just add the data as a list of values to a data dictionary during the call to `emhass` using the `runtimeparams` option. -For example if using the add-on or the standalone docker installation you can pass this data as list of values to the data dictionary during the `curl` POST: +For example, if using the add-on or the standalone docker installation you can pass this data as a list of values to the data dictionary during the `curl` POST: ```bash curl -i -H 'Content-Type:application/json' -X POST -d '{"pv_power_forecast":[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 70, 141.22, 246.18, 513.5, 753.27, 1049.89, 1797.93, 1697.3, 3078.93, 1164.33, 1046.68, 1559.1, 2091.26, 1556.76, 1166.73, 1516.63, 1391.13, 1720.13, 820.75, 804.41, 251.63, 79.25, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]}' http://localhost:5000/action/dayahead-optim ``` @@ -482,7 +482,7 @@ The possible dictionary keys to pass data are: ### Passing other data at runtime -It is possible to also pass other data during runtime in order to automate the energy management. For example, it could be useful to dynamically update the total number of hours for each deferrable load (`def_total_hours`) using for instance a correlation with the outdoor temperature (useful for water heater for example). +It is possible to also pass other data during runtime to automate energy management. For example, it could be useful to dynamically update the total number of hours for each deferrable load (`def_total_hours`) using for instance a correlation with the outdoor temperature (useful for water heater for example). Here is the list of the other additional dictionary keys that can be passed at runtime: @@ -492,7 +492,7 @@ Here is the list of the other additional dictionary keys that can be passed at r - `def_total_hours` for the total number of hours that each deferrable load should operate. -- `def_start_timestep` for the timestep as from which each deferrable load is allowed to operate (if you don't want the deferrable load to use the whole optimization timewindow). +- `def_start_timestep` for the timestep from which each deferrable load is allowed to operate (if you don't want the deferrable load to use the whole optimization timewindow). - `def_end_timestep` for the timestep before which each deferrable load should operate (if you don't want the deferrable load to use the whole optimization timewindow). @@ -512,19 +512,19 @@ Here is the list of the other additional dictionary keys that can be passed at r - `SOCmax` the maximum possible SOC. -- `SOCtarget` for the desired target value of initial and final SOC. +- `SOCtarget` for the desired target value of the initial and final SOC. - `Pd_max` for the maximum battery discharge power. - `Pc_max` for the maximum battery charge power. -- `publish_prefix` use this key to pass a common prefix to all published data. This will add a prefix to the sensor name but also to the forecasts attributes keys within the sensor. +- `publish_prefix` use this key to pass a common prefix to all published data. This will add a prefix to the sensor name but also the forecast attribute keys within the sensor. ## A naive Model Predictive Controller -A MPC controller was introduced in v0.3.0. This is an informal/naive representation of a MPC controller. This can be used in combination with/as a replacement of the Dayahead Optimization. +An MPC controller was introduced in v0.3.0. This is an informal/naive representation of an MPC controller. This can be used in combination with/as a replacement for the Dayahead Optimization. -A MPC controller performs the following actions: +An MPC controller performs the following actions: - Set the prediction horizon and receding horizon parameters. - Perform an optimization on the prediction horizon. @@ -535,7 +535,7 @@ This is the receding horizon principle. When applying this controller, the following `runtimeparams` should be defined: -- `prediction_horizon` for the MPC prediction horizon. Fix this at at least 5 times the optimization time step. +- `prediction_horizon` for the MPC prediction horizon. Fix this at least 5 times the optimization time step. - `soc_init` for the initial value of the battery SOC for the current iteration of the MPC. @@ -543,11 +543,11 @@ When applying this controller, the following `runtimeparams` should be defined: - `def_total_hours` for the list of deferrable loads functioning hours. These values can decrease as the day advances to take into account receding horizon daily energy objectives for each deferrable load. -- `def_start_timestep` for the timestep as from which each deferrable load is allowed to operate (if you don't want the deferrable load to use the whole optimization timewindow). If you specify a value of 0 (or negative), the deferrable load will be optimized as from the beginning of the complete prediction horizon window. +- `def_start_timestep` for the timestep from which each deferrable load is allowed to operate (if you don't want the deferrable load to use the whole optimization timewindow). If you specify a value of 0 (or negative), the deferrable load will be optimized as from the beginning of the complete prediction horizon window. - `def_end_timestep` for the timestep before which each deferrable load should operate (if you don't want the deferrable load to use the whole optimization timewindow). If you specify a value of 0 (or negative), the deferrable load optimization window will extend up to the end of the prediction horizon window. -A correct call for a MPC optimization should look like: +A correct call for an MPC optimization should look like this: ```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 @@ -565,11 +565,11 @@ Check the dedicated section in the documentation here: [https://emhass.readthedo ## Development -Pull request are very much accepted on this project. For development you can find some instructions here [Development](https://emhass.readthedocs.io/en/latest/develop.html). +Pull requests are very much accepted on this project. For development, you can find some instructions here [Development](https://emhass.readthedocs.io/en/latest/develop.html). ## Troubleshooting -Some problems may arise from solver related issues in the Pulp package. It was found that for arm64 architectures (ie. Raspberry Pi4, 64 bits) the default solver is not avaliable. A workaround is to use another solver. The `glpk` solver is an option. +Some problems may arise from solver-related issues in the Pulp package. It was found that for arm64 architectures (ie. Raspberry Pi4, 64 bits) the default solver is not available. A workaround is to use another solver. The `glpk` solver is an option. This can be controlled in the configuration file with parameters `lp_solver` and `lp_solver_path`. The options for `lp_solver` are: 'PULP_CBC_CMD', 'GLPK_CMD' and 'COIN_CMD'. If using 'COIN_CMD' as the solver you will need to provide the correct path to this solver in parameter `lp_solver_path`, ex: '/usr/bin/cbc'.