diff --git a/.cspell/custom-dictionary-workspace.txt b/.cspell/custom-dictionary-workspace.txt index 8ca93883..16ac6e43 100644 --- a/.cspell/custom-dictionary-workspace.txt +++ b/.cspell/custom-dictionary-workspace.txt @@ -112,6 +112,7 @@ timestr timezone Trefor treforsiphone +unstaged Wallbox xaxis yaxis diff --git a/apps/predbat/predbat.py b/apps/predbat/predbat.py index f6b65aac..06ee2422 100644 --- a/apps/predbat/predbat.py +++ b/apps/predbat/predbat.py @@ -7959,7 +7959,7 @@ def calculate_plan(self, recompute=True): save="best", end_record=self.end_record, ) - # round charge_limit_best (kWh) to 2 decimal places and discharge_limits_best (percentage) to nearest whole number gc + # round charge_limit_best (kWh) to 2 decimal places and discharge_limits_best (percentage) to nearest whole number self.charge_limit_best = [self.dp2(elem) for elem in self.charge_limit_best] self.discharge_limits_best = [self.dp0(elem) for elem in self.discharge_limits_best] diff --git a/docs/config-yml-settings.md b/docs/config-yml-settings.md index 95ae7ab7..784fb0d0 100644 --- a/docs/config-yml-settings.md +++ b/docs/config-yml-settings.md @@ -1,4 +1,4 @@ -# config.yml settings +# apps.yaml settings ## Basics @@ -21,7 +21,7 @@ is the suggested amount (to match energy rate cycles) The following are entity names in HA for GivTCP, assuming you only have one inverter and the entity names are standard then it will be auto discovered - **num_inverters** - If you increase this above 1 you must provide multiple of each of these entities -- **geserial** - This is a helper regular expression to find your serial number, if it doesn't work edit it manually or change individual entities to match: +- **geserial** - This is a helper regular expression to find your serial number, if it doesn't work edit it manually or change individual entities to match. ## Historical data @@ -34,9 +34,22 @@ The following are entity names in HA for GivTCP, assuming you only have one inve - **export_today** - GivTCP Exported energy today in kWh (incrementing) - **pv_today** - GivTCP PV energy today in kWh (incrementing) +If you have multiple inverters then you may find that the load_today figures from GivTCP are incorrect as the inverters share the house load between them. +In this circumstance one solution is to create a template helper to calculate house load from {pv generation}+{battery discharge}-{battery charge}+{import}-{export}. + +e.g. + +```yaml +{{ states('sensor.givtcp_XXX_pv_energy_today_kwh')|float(0) + ... ++ states('sensor.givtcp_XXX_battery_discharge_energy_today_kwh')|float(0) + ... +- states('sensor.givtcp_XXX_battery_discharge_energy_today_kwh')|float(0) - ... ++ states('sensor.givtcp_XXX_import_energy_today_kwh')|float(0) +- states('sensor.givtcp_XXX_export_energy_today_kwh')|float(0) }} +``` + ### GivEnergy Cloud Data - If you have an issue with the GivTCP data you can get this historical data from the GivEnergy cloud instead. This data is updated every 30 minutes + If you have an issue with the GivTCP data you can get this historical data from the GivEnergy cloud instead. This data is updated every 30 minutes. - **ge_cloud_data** - When True use the GE Cloud for data rather than load_today, import_today and export_today - **ge_cloud_serial** - Set the inverter serial number to use for the Cloud data @@ -71,7 +84,7 @@ to 99 to workaround some gen2 inverters which refuse to be set to 100. ### REST Interface inverter control - **givtcp_rest** - One per Inverter, sets the REST API URL ([http://homeassistant.local:6345](http://homeassistant.local:6345) -is the normal one). When enabled the Control per inverter below isn't used and instead communication is directly via REST and +is the normal one for the first inverter). When enabled the Control per inverter below isn't used and instead communication is directly via REST and thus bypasses some issues with MQTT. If using Docker then change homeassistant.local to the Docker IP address. To check your REST is working open up the readData API point in a Web browser e.g: [http://homeassistant.local:6345/readData](http://homeassistant.local:6345/readData) @@ -124,13 +137,13 @@ They are set to a regular expression and auto-discovered but you can comment out events which are disabled by the plugin by default: ```yaml - event.octopus_energy_electricity_xxxxxxxx_previous_day_rates - event.octopus_energy_electricity_xxxxxxxx_current_day_rates - event.octopus_energy_electricity_xxxxxxxx_next_day_rates + event.octopus_energy_electricity_xxxxxxxx_previous_day_rates + event.octopus_energy_electricity_xxxxxxxx_current_day_rates + event.octopus_energy_electricity_xxxxxxxx_next_day_rates - event.octopus_energy_electricity_xxxxxxxx_export_previous_day_rates - event.octopus_energy_electricity_xxxxxxxx_export_current_day_rates - event.octopus_energy_electricity_xxxxxxxx_export_next_day_rates + event.octopus_energy_electricity_xxxxxxxx_export_previous_day_rates + event.octopus_energy_electricity_xxxxxxxx_export_current_day_rates + event.octopus_energy_electricity_xxxxxxxx_export_next_day_rates ``` - **octopus_intelligent_slot** - If you have Octopus Intelligent GO and the Octopus Energy plugin installed point to the 'slot' sensor. @@ -157,11 +170,13 @@ Or you can override these by manually supplying an octopus pricing URL (expert f ## Standing charge -Predbat also include the daily standing charge in cost predictions (optional) +Predbat also includes the daily standing charge in cost predictions (optional) - **metric_standing_charge** - Set to the standing charge in pounds e.g. 0.50 is 50p. Can be typed in directly or point to a sensor that stores this information (e.g. Octopus Plugin). +Delete this line from apps.yaml or set it to zero if you don't want the standing charge (and only have consumption usage) to be included in Predbat charts and output data. + ## Manual energy rates Or manually set your rates in a 24-hour period using these: @@ -174,32 +189,36 @@ Or manually set your rates in a 24-hour period using these: rates_export: - start : "HH:MM:SS" end : "HH:MM:SS" - rate : p + rate : pence ``` -**start** and **end** are in time format of "HH:MM:SS" e.g. "12:30:00" and should be aligned to 30 minute slots normally. +**start** and **end** are in the time format of "HH:MM:SS" e.g. "12:30:00" and should be aligned to 30 minute slots normally. rate is in pence e.g. 4.2 +## Manually Over-riding energy rates + You can also override the energy rates (regardless of if they are set manually or via Octopus) using the override feature. The override is used to set times where rates are different, e.g. an Octopus Power Up session (zero rate for an hour or two) +```yaml rates_import_override: - start : "HH:MM:SS" end : "HH:MM:SS" - rate : p + rate : pence date : "YYYY-MM-DD" rates_export_override: - start : "HH:MM:SS" end : "HH:MM:SS" - rate : p + rate : pence date : "YYYY-MM-DD" +``` -**date** is in date format of "YYYY-MM-DD" e.g. "2023-09-09" +**date** is in the date format of "YYYY-MM-DD" e.g. "2023-09-09" ## Car charging filtering -You might want to remove your electric car charging data from the historical load as to not bias the calculations, otherwise you will get -high charge levels when the car was charged previously (e.g. last week) +You might want to remove your electric car charging data from the historical load so as to not bias the calculations, otherwise you will get +high charge levels when the car was charged previously (e.g. last week). - **car_charging_hold** - When true car charging data is removed from the simulation (by subtracting car_charging_rate), as you either charge from the grid or you use the Octopus Energy plugin to predict when it will charge correctly (default 6kw, configure with **car_charging_threshold**) @@ -209,7 +228,7 @@ more accurate car charging data to filter out ## Planned car charging -These features allow Predbat to know when you plan to charge your car. If you have Intelligent Octopus set up you won't need to change +These features allow Predbat to know when you plan to charge your car. If you have Intelligent Octopus setup then you won't need to change these as it's done automatically via their app and the Octopus Energy plugin. - **octopus_intelligent_charging** - When enabled Predbat will plan charging around the Intelligent Octopus slots, taking it into account @@ -218,18 +237,18 @@ for battery load and generating the slot information Only needed if you don't use Intelligent Octopus: - **car_charging_planned** - Can be set to a sensor which lets Predbat know the car is plugged in and planned to charge during low rate -slots, or False to disable or True to always enable +slots, or False to disable, or True to always enable - **car_charging_planned_response** - An array of values from the planned sensor which indicate that the car is plugged in and will charge in the next low rate slot -- **car_charging_rate** - Set to the cars charging rate (normally 7.5 for 7.5kw). -- **car_charging_battery_size** - Indicates the cars battery size in kWh, defaults to 100. It will be used to predict car charging stops. +- **car_charging_rate** - Set to the car's charging rate (normally 7.5 for 7.5kw). +- **car_charging_battery_size** - Indicates the car's battery size in kWh, defaults to 100. It will be used to predict car charging stops. - **car_charging_now** - When set links to a sensor that tells you that the car is currently charging. Predbat will then assume this 30 minute slot is used for charging regardless of the plan. If Octopus Intelligent Charging is enabled then it will also assume it's a low rate slot for the car/house, otherwise rates are taken from the normal rate data. - **car_charging_now_response** - Sets the range of positive responses for **car_charging_now**, useful if you have a sensor for your car that isn't binary. -- **car_charging_plan_time** - When using Batpred led planning set this to the time you want the car to be charged by +- **car_charging_plan_time** - When using Predbat-led planning set this to the time you want the car to be charged by - **car_charging_plan_smart** - When true the cheapest slots can be used for charging, when False it will be the next low rate slot Connect to your cars sensors for accurate data: @@ -255,6 +274,8 @@ charging plan, e.g. you are using Intelligent Octopus or you use the car slots i ## Workarounds - **switch.predbat_set_read_only** - When set prevents Predbat from making modifications to the inverter settings (regardless of the configuration). +Predbat will continue making and updating its prediction plan every 5 minutes, but no inverter changes will be made. +This is useful if you want to over-ride what predbat is planning to do, or whilst you are learning how Predbat works prior to turning it on 'in anger'. - **battery_scaling** - Scales the battery reported SOC kWh e.g. if you set 0.8 your battery is only 80% of reported capacity. If you are going to chart this you may want to use **predbat.soc_kw_h0** as your current status rather than the GivTCP entity so everything lines up - **import_export_scaling** - Scaling the import & export data from GivTCP - used for workarounds @@ -266,36 +287,39 @@ reported size. If your battery size is reported wrongly maybe try turning this o - **inverter_battery_rate_min** - Can be set to model the inverter not actually totally stopping discharging or charging the battery (value in watts). - **inverter_reserve_max** - Global, sets the maximum reserve % that maybe set to the inverter, the default is 100. Can be set to 99 to workaround some gen2 inverters which refuse to be set to 100. -- **car_charging_now** - Can be used to workaround Ohme issue with Intelligent where the plan is not published, see Planned car charging +- **car_charging_now** - Can be used to workaround Ohme issue with Intelligent where the plan is not published, see [Planned car charging](#planned-car-charging) ## Balance Inverters When you have two or more inverters it's possible they get out of sync so they are at different charge levels or they start to cross-charge (one discharges into another). -When enabled balance inverters tries to recover this situation by disabling either charging or discharging from one of the batteries until they re-align. +When enabled, balance inverters tries to recover this situation by disabling either charging or discharging from one of the batteries until they re-align. The apps.yaml contains a setting **balance_inverters_seconds** which defines how often to run the balancing, 30 seconds is recommended if your machine is fast enough, but the default is 60 seconds. -Enable **switch.predbat_balance_inverters_enable** switch in Home Assistant to enable this feature. +Enable the **switch.predbat_balance_inverters_enable** switch in Home Assistant to enable this feature. -**switch.predbat_balance_inverters_charge** - Is used to toggle on/off balancing while the batteries are charging -**switch.predbat_balance_inverters_discharge** - Is used to toggle on/off balancing while the batteries are discharging -**switch.predbat_balance_inverters_crosscharge** - Is used to toggle on/off balancing when the batteries are cross charging -**input_number.predbat_balance_inverters_threshold_charge** - Sets the minimum percentage divergence of SOC during charge before balancing, default is 1% -**input_number.predbat_balance_inverters_threshold_discharge** - Sets the minimum percentage divergence of SOC during discharge before balancing, default is 1% +- **switch.predbat_balance_inverters_charge** - Is used to toggle on/off balancing while the batteries are charging +- **switch.predbat_balance_inverters_discharge** - Is used to toggle on/off balancing while the batteries are discharging +- **switch.predbat_balance_inverters_crosscharge** - Is used to toggle on/off balancing when the batteries are cross charging +- **input_number.predbat_balance_inverters_threshold_charge** - Sets the minimum percentage divergence of SOC during charge before balancing, default is 1% +- **input_number.predbat_balance_inverters_threshold_discharge** - Sets the minimum percentage divergence of SOC during discharge before balancing, default is 1% ## Triggers -The trigger figure is useful to help trigger your own automation based on having spare solar energy or battery that you would otherwise export +The trigger feature is useful to help trigger your own automation based on Predbat determining that you have spare solar energy or battery that you would otherwise export The triggers count export energy until the next active charge slot only. -For each trigger give a name, the minutes of export needed and the energy required in that time -Multiple triggers can be set at once so in total you could use too much energy if all run -Each trigger create an entity called 'binary_sensor.predbat_export_trigger_[name]' which will be turned On when the condition is valid -connect this to your automation to start whatever you want to trigger. +For each trigger give a name, the minutes of export needed and the energy required in that time. + +Multiple triggers can be set at once so in total you could use too much energy if all run! + +Each trigger create an entity called 'binary_sensor.predbat_export_trigger_[name]' which will be turned On when the condition is valid. + +Connect your automation to this binary sensor to start whatever you want to trigger. -Set the name for each trigger, the number of minutes of solar export you need and the amount of energy in kwH you will need available during that time period. +Set the name for each trigger, the number of minutes of solar export you need, and the amount of energy in kwH you will need available during that time period in apps.yaml: For example: @@ -311,23 +335,23 @@ For example: If you wish to trigger based on charging or discharging the battery rather than spare solar energy you can instead use the following binary sensors -**binary_sensor.predbat_charging** - Will be True when the home battery is inside a charge slot (either being charged or being held at a level). -This does include charge freeze slots where the discharge rate is set to zero without charging the battery. -**binary_sensor.predbat_discharging** - Will be True when the home battery is inside a force discharge slot. This does not include +- **binary_sensor.predbat_charging** - Will be True when the home battery is inside a charge slot (either being charged or being held at a level). +Note that this does include charge freeze slots where the discharge rate is set to zero without charging the battery. +- **binary_sensor.predbat_discharging** - Will be True when the home battery is inside a force discharge slot. This does not include discharge freeze slots where the charge rate is set to zero to export excess solar only. ## Holiday mode -When you go away you are likely to use less electric and so the previous load data will be quite pessimistic. Using the +When you go away you are likely to use less electricity and so the previous load data will be quite pessimistic. Using the configuration item **input_number.predbat_holiday_days_left** in Home assistant you can set the number of full days that you will be away for (including today). The number will count down by 1 day at midnight until it gets back to zero. When -holiday days left is non-zero holiday mode is active. +holiday days left are non-zero, the holiday mode is active. -When holiday mode is active the historical load data will be taken from yesterdays data (1 day ago) rather than from the **days_previous** +When holiday mode is active the historical load data will be taken from yesterday's data (1 day ago) rather than from the **days_previous** setting in apps.yaml. This means Predbat will adjust more quickly to the new usage pattern. If you have been away for a longer period of time (more than your normal days_previous setting) then obviously it's going -to take longer for the historical data to catch up, you could then enable holiday more for another 7 days after your return. +to take longer for the historical data to catch up, you could then enable holiday mode for another 7 days after your return. In summary: diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md index f3f4a977..f82353a5 100644 --- a/docs/configuration-guide.md +++ b/docs/configuration-guide.md @@ -8,28 +8,28 @@ charging. You might want to also set to the car charging plan so you can predict You should try to tune **inverter_loss**, **battery_loss** and **battery_loss_discharge** to the correct % loss for your system in order to get more accurate predictions. Around 4% for each is good for a hybrid inverter. Also set **inverter_hybrid** to -True or False depending on if you have a Hybrid or AC Coupled battery. +True or False depending on if you have a Hybrid or AC-Coupled battery. The setting **input_number.metric_battery_cycle** (_expert mode_) can be used to put a cost on using your battery for charging and discharging. In theory if you think your battery will last say 6000 complete cycles and cost you £4000 and is 9.5kWh then each cycle is 19kWh and so the cost is £4000 / 19 / 6000 = 3.5p. If you configure this number higher then more expensive plans -will be selected which avoid charging and discharging your battery as much. The default is 2p but can be set to 0 if you want +will be selected which avoids charging and discharging your battery as much. The default is 2p but can be set to 0 if you want to turn this off. Note that the cycle cost will not be included in the cost predictions, just taken into account in the planning -stage. _Note: Setting this to a non-zero zero will increase your daily cost, but will reduce your home battery usage._ +stage. _Note: Setting this to a non-zero value will increase your daily cost, but will reduce your home battery usage._ Cloud coverage is modelled by using difference between PV and PV10 is used to work out a cloud factor, this modulates the PV -output predictions up and down accordingly as if there was passing clouds. This can have an impact on planning, especially for +output predictions up and down accordingly as if there were passing clouds. This can have an impact on planning, especially for things like freeze charging which could assume the PV will cover the house load but it might not due to clouds. Below is a guide to some of the tariff options, in theory most tariffs will work out of the box but still it's worth reviewing your settings. ## Fixed daily rates -- In this case you will just be predicting the battery levels, no charging or discharging is required although it won't hurt if you leave these options enabled. +With a fixed daily rate tariff you will just be predicting the battery levels, no charging or discharging is required although it won't hurt if you leave these options enabled. ## Cheap night rate with bad export rate (e.g. Octopus Go, Economy 7 etc) -- In this scenario you will want to charge overnight based on the next days solar forecast. +In this scenario you will want to charge overnight based on the next day's solar forecast. Recommended settings - these must be changed in Home Assistant once Predbat is running: @@ -50,7 +50,7 @@ metric_min_improvement - 0 # Charge less if it's cost neutral ## Cheap night rate, with a good export rate (e.g. Intelligent Octopus with Octopus Outgoing) -Follow the instructions from Cheap Night rate above, but also you will want to have automatic discharge when the export rates are profitable. +Follow the instructions from the _Cheap Night rate_ above, but also you will also want to have automatic discharge occurring when the export rates are profitable. ```yaml calculate_best_charge - True # You want the tool to calculate charging diff --git a/docs/creating-charts.md b/docs/creating-charts.md index 6c70e87b..69c9c81f 100644 --- a/docs/creating-charts.md +++ b/docs/creating-charts.md @@ -3,9 +3,12 @@ To create the fancy charts: - Install Apex Charts [https://github.com/RomRider/apexcharts-card](https://github.com/RomRider/apexcharts-card) -- There are multiple charts, for each section of the example file create a new apexcharts card and copy the YAML into it +- There are multiple charts, for each section of the [example chart yaml file](https://github.com/springfall2008/batpred/blob/main/example_chart.yml), create a new apexcharts card +and copy the YAML into it - Customise as you like +See the [video guides](video-guides.md) for a walkthrough of what the different charts show. + Example charts: ![image](https://github.com/springfall2008/batpred/assets/48591903/28f29756-2502-4079-9c75-398e8a1a0699) diff --git a/docs/customisation.md b/docs/customisation.md index f9f95083..379f3468 100644 --- a/docs/customisation.md +++ b/docs/customisation.md @@ -110,7 +110,7 @@ if **car_charging_planned** is set correctly in apps.yaml to detect your car bei ## Calculation options **switch.predbat_calculate_best_charge** If set to False then charge windows will not be calculated and the -default inverter settings are used, when True predbat will decide the charge window automatically. +default inverter settings are used, when True Predbat will decide the charge window automatically. **switch.predbat_calculate_best_discharge** If set to False then force discharge windows will not be calculated, when True they will be calculated. Default is True. diff --git a/docs/developing.md b/docs/developing.md index 570040d3..260408f5 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -39,8 +39,8 @@ This includes: can connect to a copy of VS Code installed on your own machine - A terminal where you can run commands against your codebase -e.g. running `mkdocs`, linting files etc. -- Software like `mkdocs` (and other software we may include) +e.g. running `pre-commit` to run the automatic code quality checks, linting files, etc. +- Software like `mkdocs` to re-generate the documentation files (and other software we may include) pre-installed in it The Codespaces environment is entirely separate from your HA @@ -82,7 +82,7 @@ Once you start your Codespaces environment, it'll take a minute to create a VM for you, and to install the software we've asked it to install in there. It will also clone your repository and chosen branch into it for you, and the VM will be authenticated with GitHub -so you can commit and push straight back to GitHub. +so you can commit and push straight back to your fork of Predbat on GitHub. You can choose between running the IDE in the browser, or having your local installation of VS Code connect to the environment that GitHub @@ -168,7 +168,9 @@ as what works on GitHub READMEs, for example, does not necessarily work with the published documentation site (which follows a more strict Markdown standard). -To run the live preview, run `mkdocs serve` - this will cause `mkdocs` to build a +There are a number of terminal commands that you can use in the Codespaces environment. Open a terminal window in Codespaces by choosing menu > Terminal > New Terminal. + +To run the live preview, enter `mkdocs serve` in the terminal window - this will cause `mkdocs` to build a local temporary version of the documentation site, and to temporarily publish it on port 8000 - it will show the link where you can access the documentation. @@ -238,7 +240,7 @@ installed automatically. You can run it manually, or automatically. Running `pre-commit` manually: -- Running `pre-commit` will run all the checks against any files that you +- In a terminal window, running `pre-commit` will run all the checks against any files that you have modified and staged. - Alternatively, running `pre-commit run --all-files` will run all the checks @@ -249,14 +251,14 @@ those changes will not be staged. You will need to stage those changes too before committing. - You may notice `pre-commit` mentioning about stashing changes - this is -because when it runs, any changes that aren't stages are stashed (saved +because when it runs, any changes that aren't staged are stashed (saved away temporarily) so it runs against only the staged changes; after it has run, it pulls back those stashed changes, so they appear again (still unstaged). Running `pre-commit` automatically: -- If you run `pre-commit install` it will install a pre-commit hook - +- If you run `pre-commit install` in a terminal window it will install a pre-commit hook - this is a file which tells `git` to run some code each type you do a particular action (a pre-commit hook runs at the start of processing a commit, but there are other hooks e.g. pre-push). diff --git a/docs/energy-rates.md b/docs/energy-rates.md index 19af6679..d1d46b00 100644 --- a/docs/energy-rates.md +++ b/docs/energy-rates.md @@ -2,17 +2,19 @@ ## Octopus Energy Plugin -- If you want to use real pricing data and have Octopus Energy then ensure you have the Octopus Energy plugin installed and working +If you want to use real pricing data and have Octopus Energy then ensure you have the Octopus Energy plugin installed and working ([https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy](https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy/)) -- The Octopus Energy Plugin also provides support for Intelligent Octopus charging to support car charging -- When **octopus_intelligent_charging** is True and you are on Intelligent Octopus import the car charging plan will be + +The Octopus Energy Plugin also provides support for Intelligent Octopus charging to support car charging. + +When **octopus_intelligent_charging** is True and you are on Intelligent Octopus import the car charging plan will be extracted from Octopus and used for Predbat to plan, and it may charge the home battery using these slots also. ### Octopus Saving sessions For Predbat to automatically manage saving sessions you will need to make sure that **octopus_saving_session** is set in apps.yaml to point to the saving session binary sensor supported by the Octopus Energy plugin (see template apps.yaml -for the default name) +for the default name). When a saving session is available it will be automatically joined by Predbat and then should appear as a joined session within the next 30 minutes. @@ -24,7 +26,7 @@ using the **octopus_saving_session_octopoints_per_penny** configuration item in As the saving session import and export rates are very high compared to normal you would expect Predbat to export during the entire period if the battery is large amount, a pre-charge may happen at some point during the day to maintain the right level for the session. -If you are using expert mode, for best results: **switch.predbat_combine_charge_slots** (_expert mode_) is turned off. +If you are using expert mode, for best results: **switch.predbat_combine_charge_slots** (_expert mode_) should be turned off. Set **input_number.rate_low_threshold** (_expert mode_) and **input_number.rate_high_threshold** (_expert mode_) to 0 for automatic mode. For forced export you need to ensure that **switch.predbat_calculate_best_discharge** is enabled and that **switch.predbat_set_discharge_freeze_only** is disabled. @@ -32,27 +34,25 @@ If you do not have an export tariff then forced export will not apply. ## Rate bands -- you can configure your rate bands (assuming they repeat) using rates_import/rates_export (see below) +You can manually configure your rate bands (assuming they repeat) using rates_import/rates_export (see below). ## Rate offsets -- Note that you can tune future unknown energy rates by adjusting **input_number.predbat_metric_future_rate_offset_import** +Note that you can tune future unknown energy rates by adjusting **input_number.predbat_metric_future_rate_offset_import** (_expert mode_) and **input_number.predbat_metric_future_rate_offset_export** (_expert mode_) inside Home Assistant -to set the predicted offset for future unknown rates +to set the predicted offset for future unknown rates. ## Future Agile energy rates In the energy market it's possible to calculate the Octopus Agile rates from around 10am UK time using public data, you can -enable this in apps.yaml for Import, Export or both. This will approximate next days rates based on the spot prices. -The approximation is only used until the real rates are released around 4pm +enable this in apps.yaml for Import, Export or both. This will approximate next day's rates based on the spot prices. +The approximation is only used until the real Octopus Agile rates are released around 4pm. CAUTION: You may violate the terms and conditions of the Nordpool site if you use this data and as such the authors of Predbat accept no responsibility for any violations: -`` - ## Nordpool market energy rates ```yaml diff --git a/docs/faq.md b/docs/faq.md index 43211a97..dcf0363e 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,6 +1,6 @@ # FAQ -## I've installed Batpred but I don't see the correct entities +## I've installed Predbat but I don't see the correct entities - First look at AppDaemon.log (can be found in the list of log files in the System/Log area of the GUI). See if any errors are warnings are found. If you see an error it's likely something is configured wrongly, @@ -11,11 +11,11 @@ The default solcast sensor names maybe wrong, you might need to update the apps. ## Why is my predicted charge % higher or lower than I might expect? -- Batpred is based on costing, so it will try to save you money. If you have the PV 10% option enabled it will also +- Predbat is based on costing, so it will try to save you money. If you have the PV 10% option enabled it will also take into account the more worse case scenario and how often it might happen, so if the forecast is a bit unreliable it's better to charge more and not risk getting stung importing. - Have you checked your energy rates for import and export are correct, maybe check the rates graph and confirm. -If you do something like have export>import then Batpred will try to export as much as possible. +If you do something like have export>import then Predbat will try to export as much as possible. - Have you tuned Solcast to match your output accurately? - Have you tuned the **metric_min_improvement**, **best_soc_min** and **best_soc_keep settings**? - Do you have predicted car charging during the time period? @@ -37,13 +37,33 @@ a script that changes the reserve %, this will cause problems - please disable o ## It's all running but I'm not getting very good results -- You might want to tune **best_soc_keep** to set a minimum target battery level, e.g. I use 2.0 (for 2kWh, which is just over 20% on a 9.5kWh battery) -- Have a read of the user configuration guide above depending on your tariff different settings maybe required -- Check your solar production is well calibrated (you can compare solcast vs actually in home assistant energy tab or on the GivEnergy portal) +- You might want to tune **best_soc_keep** to set a minimum target battery level, e.g. I use 2.0 (for 2kWh, which is just over 20% on a 9.5kWh battery). +If you set **best_soc_keep** too high then predbat could need to charge the battery in unfavourable import rates, so try to set it to a fairly low value, +especially if you have a small battery. If you set it to zero then predbat may not charge at all, so use 0.1 as a minimum. +- Have a read of the [energy rates configuration guide](energy-rates.md) as depending on your tariff different settings maybe required +- Check your solar production is well calibrated (you can compare solcast vs actually in the Home Assistant energy tab or on the GivEnergy portal) - Make sure your inverter max AC rate has been set correctly - If you have an EV that you charge then you will want some sort of car charging sensor or use the basic car charging hold feature or your load predictions maybe unreliable - Do you have a solar diverter? If so maybe you want to try using the IBoost model settings. - Perhaps set up the calibration chart and let it run for 24 hours to see how things line up - If your export slots are too small compared to expected check your inverter_limit is set correctly (see below) -If you are still having trouble feel free to raise a ticket for support to post on the [GivTCP Facebook group](https://www.facebook.com/groups/615579009972782). +## Predbat is causing warning messages in the Home Assistant Core log + +- If you have a large **input_number.predbat_forecast_plan_hours** then you may see warning +messages in the Home Assistant Core log about the size of the predbat.plan_html entity. +This is just a warning, the entity isn't stored in the database, but you can suppress it by adding the following +to your configuration.yaml: + +```yaml +# Filter out 'message too large' warnings from Predbat +logger: + default: warning + filters: + - "State attributes for predbat.plan_html exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored" +``` + +## My question isn't covered here + +If you are still having trouble feel free to raise a [Github ticket](https://github.com/springfall2008/batpred/issues) for support, +or post on the [GivTCP Facebook group](https://www.facebook.com/groups/615579009972782). diff --git a/docs/images/predbat-status-issue.png b/docs/images/predbat-status-issue.png new file mode 100644 index 00000000..f599cb3c Binary files /dev/null and b/docs/images/predbat-status-issue.png differ diff --git a/docs/install.md b/docs/install.md index 56c5f6fa..32587eeb 100644 --- a/docs/install.md +++ b/docs/install.md @@ -2,23 +2,23 @@ ## GivTCP install -- You must have GivTCP installed and running first ([https://github.com/britkat1980/giv_tcp](https://github.com/britkat1980/giv_tcp)) - - You will need at least 24 hours history in HA for this to work correctly, the default is 7 days (but you configure this back 1 day if you need to) +You must have GivTCP installed and running first ([https://github.com/britkat1980/giv_tcp](https://github.com/britkat1980/giv_tcp)) + +You will need at least 24 hours history in HA for this to work correctly, the default is 7 days (but you can configure this back to 1 day if you need to). ## AppDaemon install -- Install AppDaemon add-on [https://github.com/hassio-addons/addon-appdaemon](https://github.com/hassio-addons/addon-appdaemon) - - You will find the appdaemon.yaml file in addon_configs/a0d7b954_appdaemon - - Add to the appdaemon: section **apps_dir** which should point to /homeassistant/appdaemon/apps - - Set the **time_zone** correctly in appdaemon.yaml (e.g. Europe/London) - - Add **thread_duration_warning_threshold: 120** to the appdaemon.yaml file in the appdaemon section - - It's recommended you set a new logfile location so that you can see the complete logs, I set mine - to /homeassistant/appdaemon/appdaemon.log and increase the maximum size and number of generations to capture a few days worth +- Install the AppDaemon add-on [https://github.com/hassio-addons/addon-appdaemon](https://github.com/hassio-addons/addon-appdaemon) +- You will find the appdaemon.yaml file in addon_configs/a0d7b954_appdaemon +- Add to the appdaemon: section **apps_dir** which should point to /homeassistant/appdaemon/apps +- Set the **time_zone** correctly in appdaemon.yaml (e.g. Europe/London) +- Add **thread_duration_warning_threshold: 120** to the appdaemon.yaml file in the appdaemon section +- It's recommended you set a new logfile location so that you can see the complete logs, I set mine +to /homeassistant/appdaemon/appdaemon.log and increase the maximum size and number of generations to capture a few days worth Example config: ```yaml ---- appdaemon: latitude: 52.379189 longitude: 4.899431 @@ -41,7 +41,7 @@ logs: log_size: 10000000 ``` -CAUTION: Migration from an older Appdaemon to 0.15.2 or above: +CAUTION: Migrating from an older Appdaemon to 0.15.2 or above: - Make sure you have access to the HA filesystem, e.g. I use the Samba add on and connect to the drives on my Mac, but you can use ssh also. Update AppDaemon to 0.15.2 @@ -61,16 +61,22 @@ old location and update your logfile location (if you have set it). You should r [![hacs_badge](https://img.shields.io/badge/HACS-Default-41BDF5.svg?style=for-the-badge)](https://github.com/hacs/integration) -- Once installed you will get automatic updates from each release! +Once installed you will get automatic updates from each release! - Add as a custom repository of type 'AppDaemon' - Click on the Repo and Download the app -*After an update with HACS you may need to reboot AppDaemon as it sometimes reads the config wrongly during the update (If this happens you will get a template configuration error).* +*After an update with HACS you may need to reboot AppDaemon as it sometimes reads the config wrongly during the update +(If this happens you will get a template configuration error in the entity predbat.status).* + +Edit in HomeAssistant config/appdaemon/apps/batpred/config/apps.yaml to configure Predbat - see [Configuring apps.yaml](config-yml-settings.md#Basics). + +You must delete the 'template: True' line in the configuration to enable Predbat once you are happy with your configuration. + +You may initially want to set *switch.predbat_set_read_only* to True whilst you learn how Predbat operates. +Read-only mode prevents Predbat from making any inverter changes but it will continue to predict and plan battery charging and discharging activity. -- Edit in HomeAssistant config/appdaemon/apps/batpred/config/apps.yml to configure - - You must delete the 'template: True' line in the configuration to enable Predbat once you are happy with your configuration - - Note that future updates will not overwrite apps.yml, but you may need to copy settings for new features across manually +Note that future updates to Predbat will not overwrite apps.yaml, but you may need to copy settings for new features across manually ## Predbat manual install @@ -88,13 +94,13 @@ Predbat needs a solar forecast in order to predict battery levels. If you don't have solar then comment out the Solar forecast part of the apps.yml: **pv_forecast_* ** -- Make sure Solcast is installed and working () +Make sure Solcast is installed and working (). -- Note that Predbat does not update Solcast for you, it's recommended that you disable polling (due to the API polling limit) +Note that Predbat does not update Solcast for you, it's recommended that you disable polling (due to the API polling limit) in the Solcast plugin and instead have your own automation that updates the forecast a few times a day (e.g. dawn, dusk and just before your nightly charge slot). -- Example Solcast update script: +Example Solcast update script: ```yaml alias: Solcast update diff --git a/docs/installation-summary.md b/docs/installation-summary.md index 8e4de688..cf24a417 100644 --- a/docs/installation-summary.md +++ b/docs/installation-summary.md @@ -12,8 +12,8 @@ Please see the sections below for how to achieve each step. This is just a check - Also check Solcast is being auto-updated a few times a day and that you see the data in Home Assistant 6. If you use Octopus Energy then install the Octopus Energy plugin (if you haven't already) - [Octopus Energy](install.md#octopus-energy) - CAUTION: You need to enable the events for previous, current and next rates for import and export in HA as the plugin leaves them disabled by default (see the above link for details) -8. Go and edit apps.yml (in config/appdaemon/apps/predbat/config/apps.yml) to match your system - [config.yml settings](config-yml-settings.md) - - Inverter settings match the names in GivTCP - should be automatic but if you have _2 names you will have to edit apps.yml) +8. Go and edit apps.yaml (in config/appdaemon/apps/predbat/config/apps.yaml) to match your system - [apps.yaml settings](config-yml-settings.md) + - Inverter settings match the names in GivTCP - should be automatic (but if you have 2 names you will have to edit apps.yml) - You have set the right number of inverters (**num_inverters**) - Adjust your **inverter_limit** and **export_limit** as required - You have your energy rates set correctly either using Octopus Plugin or entered manually diff --git a/docs/output-data.md b/docs/output-data.md index 2ad2d987..b2e9302a 100644 --- a/docs/output-data.md +++ b/docs/output-data.md @@ -2,24 +2,29 @@ ## Displaying output data -Each config item has an input_number or switch associated with it, you can find an auto generated dashboard for your -configuration in your AppDaeamon configuration area under the filename **predbat_dashboard.yaml** +Each Predbat config item has an input_number or switch associated with it, you can find an auto-generated dashboard for your +configuration in your AppDaemon configuration area under the filename **predbat_dashboard.yaml**. +You will need to open that file in a Home Assistant file editor and copy the contents into a new dashboard page. -You can also create a card using 'dynamic-entities-card.yaml' for a dynamically created list of entities for predbat which -groups the entities by type and is collapsed by default to prevent screen clutter. Requires lovelace-collapsable-cards +You can also create a dashboard page using [dynamic-entities-card.yaml](https://github.com/springfall2008/batpred/blob/main/dynamic-entities-card.yaml) for a +dynamically created list of all Predbat entities which groups the entities by type and is collapsed by default to prevent screen clutter. Requires lovelace-collapsable-cards ([https://github.com/RossMcMillan92/lovelace-collapsable-cards](https://github.com/RossMcMillan92/lovelace-collapsable-cards)) and lovelace-auto-entities ([https://github.com/thomasloven/lovelace-auto-entities](https://github.com/thomasloven/lovelace-auto-entities)) to be installed via HACS as well as the stock vertical stack card. Credit @DJBenson for the code. +The Predbat Plan card is very useful for seeing the plan that Predbat has created - [Create the Predbat Plan card](predbat-plan-card.md). + +A set of Apex Charts can also be created to see graphically what Predbat plans to do - [Creating the charts](creating-charts.md). + ## Basic status -- predbat.status - Gives the current status & errors and logs any adjustments made to your inverter +- predbat.status - Gives the current status & errors and logs any changes that Predbat makes to your inverter ## Baseline data What your battery is expected to do with no changes made by Predbat: -- predbat.battery_hours_left - The number of hours left until your home battery is predicated to run out (stops at the maximum prediction time) +- predbat.battery_hours_left - The number of hours left until your home battery is predicted to run out (stops at the maximum prediction time) - predbat.charge_limit - The current charge limit used for the scenario in % - predbat.charge_limit_kw - The current charge limit used for the scenario in kwH - predbat.duration - The duration of the prediction maximum in hours @@ -28,7 +33,7 @@ What your battery is expected to do with no changes made by Predbat: - predbat.export_energy - Predicted export energy in kWh - predbat.import_energy - Predicted import energy in kWh - predbat.import_energy_battery - Predicted import energy to charge your home battery in kWh -- predbat.import_energy_house - Predicted import energy not provided by your home battery (flat battery or above maximum discharge rate +- predbat.import_energy_house - Predicted import energy not provided by your home battery (flat battery or above maximum discharge rate) - predbat.soc_kw - Predicted state of charge (in kWh) at the end of the prediction, not very useful in itself, but holds all minute by minute prediction data (in attributes) which can be charted with Apex Charts (or similar) - predbat.soc_min_kwh - The minimum battery level during the time period in kWh @@ -64,7 +69,7 @@ When calculate_best is enabled a second set of entities are created for the simu - predbat_soc_kw_best - Predicted best final state of charge (in kWh), holds minute by minute prediction data (in attributes) to be charted - predbat.soc_kw_best_h1 - Single data point for the predicted state of charge in 1 hours time (useful for calibration charts, predicted vs actual) - predbat.soc_kw_best_h8 - Single data point for the predicted state of charge in 8 hours time (useful for calibration charts, predicted vs actual) -- predbat.soc_kw_best_h12 - Single data point for hte predicted state of charge in 12 hours time (useful for calibration charts, predicted vs actual) +- predbat.soc_kw_best_h12 - Single data point for the predicted state of charge in 12 hours time (useful for calibration charts, predicted vs actual) - predbat_best_metric - The predicted cost if the proposed SOC % charge target is selected. Also contains data for charting cost in attributes. - predbat.best_charge_limit - Predicted best battery charge limit in percent - predbat.best_charge_limit_kw - Predicted best battery charge limit in kwH @@ -119,6 +124,137 @@ The calculated best results under PV 10% scenario: - binary_sensor.predbat_car_charging_slot - A binary sensor suggesting when to charge your car (if the car planning is enabled) -Example data out: +## Sample Predbat data out ![image](https://github.com/springfall2008/batpred/assets/48591903/5c73cd6e-3110-4ecd-af42-7e6d156af4b2) + +## Monitoring that Predbat and GivTCP are running OK + +With GivTCP and Predbat performing an important function, managing your battery charging and discharging to best reduce your electricity bills, +you may find these automations useful to monitor that GivTCP and Predbat are running OK, and if not, to raise an alert on your mobile device. + +### GivTCP activity monitor + +This automation will raise an alert if any of the following occur: + +- The inverter goes offline for more than 30 minutes +- No last_updated_time received from the inverter for more than 30 minutes +- The battery goes offline to the inverter for more than 30 minutes + +The script will need to be customised for your inverter id, battery id and mobile details, and can be extended for multiple inverters and batteries. + +```yaml +alias: GivTCP activity monitor +description: Alert when communications to GivTCP have ceased for 30 minutes +trigger: + - platform: state + entity_id: sensor.givtcp__last_updated_time + to: null + for: + minutes: 30 + id: no-givtcp-update + variables: + inv_id: inverter + - platform: state + entity_id: + - sensor.givtcp__status + from: online + for: + minutes: 30 + id: no-givtcp-update + variables: + inv_id: inverter + - platform: state + entity_id: + - sensor.givtcp__battery_cells + to: unknown + for: + minutes: 30 + id: battery-unavailable + variables: + batt_id: +action: + - condition: trigger + id: + - no-givtcp-update + - service: notify.mobile_app_ + data: + title: GivTCP communication issue + message: | + {{ now().timestamp() | timestamp_custom('%-d %b %H:%M') }} ISSUE: + No GivTCP update received from {{ inv_id }} for the past 30 minutes. + data: + visibility: public + persistent: true + push: + sound: + name: default + critical: 1 + volume: 0.8 + sticky: true + color: red + - condition: trigger + id: + - battery-unavailable + - service: notify.mobile_app_ + data: + title: GivTCP communication issue + message: | + {{ now().timestamp() | timestamp_custom('%-d %b %H:%M') }} ISSUE: + Battery {{ batt_id }} offline to GivTCP for the past 30 minutes. + data: + visibility: public + persistent: true + push: + sound: + name: default + critical: 1 + volume: 0.8 + sticky: true + color: red +mode: single +``` + +### Predbat error monitor + +This automation will raise an alert if Predbat's status turns to *ERROR* for more than 10 minutes. + +The script will need to be customised for your mobile details. + +```yaml +alias: predbat error monitor +description: Alert when Predbat has raised an exception +trigger: + - platform: state + entity_id: + - predbat.status + to: "ERROR: Exception raised" + for: + minutes: 10 + - platform: template + value_template: "{{ 'ERROR' in states('predbat.status') }}" + for: + minutes: 10 +action: + - service: notify.mobile_app_ + data: + title: Predbat status issue + message: | + {{ now().timestamp() | timestamp_custom('%-d %b %H:%M') }} ISSUE: + predbat status is {{ states('predbat.status') }} + data: + visibility: public + persistent: true + push: + sound: + name: default + critical: 1 + volume: 0.8 + sticky: true + color: red +mode: single +``` + +An error alert looks like this: + +![image](images/predbat-status-issue.png) diff --git a/docs/todo-list.md b/docs/todo-list.md index 7437a17d..6020d3de 100644 --- a/docs/todo-list.md +++ b/docs/todo-list.md @@ -1,3 +1,3 @@ -# Todo list +# To-do list - See [Github issues](https://github.com/springfall2008/batpred/issues)