diff --git a/docs/apps-yaml.md b/docs/apps-yaml.md
index 920721b16..ad779518b 100644
--- a/docs/apps-yaml.md
+++ b/docs/apps-yaml.md
@@ -46,30 +46,19 @@ Once you have made all other required changes to apps.yaml this line should be d
- **notify_devices** - A list of device names to notify when Predbat sends a notification. The default is just 'notify' which contacts all mobile devices
-- **days_previous** - A list (which has to be entered as one entry per line) of the number of days of historical house load to be used to predict your future daily load.
-It's recommended that you set days_previous so Predbat uses sufficient days' history so that 'unusual' load activity (e.g. saving sessions, "big washing day", etc) get averaged out.
+- **days_previous** - Predbat needs to know what your likely future house load will be to set and manage the battery level to support it.
+days_previous defines a list (which has to be entered as one entry per line) of the previous days of historical house load that are to be used to predict your future daily load.
+It's recommended that you set days_previous so Predbat calculates an average house load using sufficient days' history so that 'unusual' load activity
+(e.g. saving sessions, "big washing day", etc) get averaged out.
-For example, to take an average house load over all the days of the last week:
-
-```yaml
- days_previous:
- - 2
- - 3
- - 4
- - 5
- - 6
- - 7
- - 8
-```
-
-Or if you just want same day last week's consumption:
+For example, if you just want Predbat to assume the house load on a particular day is the same as the same day of last week:
```yaml
days_previous:
- 7
```
-Or if you want the average of the same day for the last 2 weeks:
+Or if you want Predbat to take the average of the same day for the last two weeks:
```yaml
days_previous:
@@ -77,8 +66,10 @@ Or if you want the average of the same day for the last 2 weeks:
- 14
```
-Do keep in mind that Home Assistant only keeps 10 days history by default, so you might need to increase the number of days history kept in HA before it is purged
-by editing and adding the following to the `/homeassistant/configuration.yaml` configuration file and restarting Home Assistant afterwards:
+Further details and worked examples of [how days_previous works](#understanding-how-days_previous-works) are covered at the end of this document.
+
+Do keep in mind that Home Assistant only keeps 10 days history by default, so if you want to access more than this for Predbat you might need to increase the number of days history
+kept in HA before it is purged by editing and adding the following to the `/homeassistant/configuration.yaml` configuration file and restarting Home Assistant afterwards:
```yaml
recorder:
@@ -86,6 +77,15 @@ by editing and adding the following to the `/homeassistant/configuration.yaml` c
```
- **days_previous_weight** - A list (again with one entry per line) of weightings to be applied to each of the days in days_previous.
+
+For example, to apply a 100% weighting for the first day entry in days_previous, but only a 50% weighting to the second day in days_previous:
+
+```yaml
+ days_previous_weight:
+ - 1
+ - 0.5
+```
+
The default value is 1, that all history days are equally weighted, so if you don't want to weight individual days you can simply use:
```yaml
@@ -497,3 +497,78 @@ Note that this does include charge freeze slots where the discharge rate is set
- **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.
+
+## Understanding how days_previous works
+
+As described earlier, **days_previous** is a list of the previous days of historical house load that are averaged together to predict your future daily load.
+
+e.g., if you want the average of the same day for the last 2 weeks:
+
+```yaml
+ days_previous:
+ - 7
+ - 14
+```
+
+This section describes in more detail how days_previous is used by Predbat in creating the future battery plan, and gives some worked examples and a 'gotcha' to be aware of.
+
+When Predbat forecasts future home demand it counts backwards the days_previous number of days to find the appropriate historical home consumption.
+This is best explained through a worked example:
+
+In this example, days_previous is set to use history from 2 days ago:
+
+```yaml
+ days_previous:
+ - 2
+```
+
+If right now today it's Monday 3:15pm and Predbat is predicting the forward plan for the next 48 hours:
+
+- For tomorrow (Tuesday) 9am slot, Predbat will look backwards 2 days from Tuesday so will use the historical home consumption from Sunday 9am
+as being the predicted load for Tuesday 9am.
+- For the day after (Wednesday) 9am slot, Predbat again looks backwards 2 days from that day, so will use historical home consumption from Monday 9am as being the Wednesday 9am prediction.
+
+This pattern of counting backwards days_previous days to find the appropriate time slot to load historical home consumption from
+requires Predbat to operate some additional special processing if days_previous is set to a low value or forecast_hours to a high value.
+
+Extending the previous example but this time days_previous is set to use history from just the previous day:
+
+```yaml
+ days_previous:
+ - 1
+```
+
+Today its still Monday 3:15pm and Predbat is predicting the forward plan for the next 48 hours:
+
+- For tomorrow (Tuesday) 9am slot, Predbat will look backwards 1 day from Tuesday so will use the historical home consumption from today (Monday) 9am
+as being the predicted load for Tuesday 9am.
+- For the day after (Wednesday) 9am slot, Predbat again looks backwards 1 days from that day,
+so looks for historical home consumption from Tuesday 9am as being the Wednesday 9am prediction,
+but of course it's still Monday and Tuesday hasn't happened yet so we can't know what that historial consumption was!
+What Predbat does in this circumstance is to subtract a further day from days_previous and for Wednesday 9am's prediction it will therefore use the historical load from Monday 9am.
+
+This issue of finding future historical load only occurs when days_previous is set to 1 and Predbat is forecasting more than 24 hours ahead from 'now'.
+So to highlight this with some edge cases, today is still Monday 3:15pm, days_previous is still set to '1' and in the forward plan:
+
+- For tomorrow (Tuesday) 2:30pm slot, Predbat looks backwards 1 day from Tuesday and takes the historical home consumption from today (Monday) 2:30pm slot.
+- For tomorrow (Tuesday) 3:00pm slot, Predbat looks backwards 1 day and takes the historical load from today (Monday) 3:00pm slot - which we are only part way through
+so only 15 minutes of load will be predicted for tomorrow 3pm.
+- For tomorrow (Tuesday) 3:30pm slot, Predbat looks backwards 1 day but the 3:30pm slot today hasn't yet occurred so Predbat will take the historical load from the prior day
+and has to use Sunday's 3:30pm load for tomorrow's prediction.
+- Ditto the predicted load for tomorrow (Tuesday) 4:00pm slot comes from Sunday 4pm.
+
+Of course as today rolls forward and Predbat keeps on updating the forward plan every 5 minutes the prediction will be updated with the correct previous_day history as and when it exists.
+
+Its recommended therefore that days_previous isn't set to 1, or if it is, that you understand the way this has to work and the consequences.
+If you want to set days_previous to take an average of the house load over all the days of the last week its suggested that it be set as:
+
+```yaml
+ days_previous:
+ - 2
+ - 3
+ - 4
+ - 5
+ - 6
+ - 7
+ - 8
+```
diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md
index d7e818a3a..d6ce5187b 100644
--- a/docs/configuration-guide.md
+++ b/docs/configuration-guide.md
@@ -9,21 +9,16 @@ You might want to also set to the [car charging plan](apps-yaml.md#planned-car-c
It is recommended that you [create a dashboard page](output-data.md#displaying-output-data) with all the required entities to control Predbat.
+This page gives a summary of some of the key configuration settings you should consider in Predbat for different energy tariffs;
+the [Predbat customisation guide](customisation.md) details all the Predbat customisation options.
+
You should try to tune **input_number.inverter_loss**, **input_number.battery_loss** and **input_number.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 **switch.inverter_hybrid** to True or False depending upon if you have a Hybrid or AC-Coupled battery.
-The setting **input_number.metric_battery_cycle** (_expert mode_) can be used to put a 'virtual cost' in pence 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 per cycle is £4000 / 19 / 6000 = 3.5p.
+The setting **input_number.metric_battery_cycle** (_expert mode_) can be used to put a 'virtual cost' in pence per kWh on using your battery for charging and discharging.
If you configure this number higher then more expensive plans will be selected which avoids charging and discharging your battery as much.
The default is 1p but can be set to 0 if you want to turn this feature off.
-Note that the cycle cost will not be included in the cost predictions that Predbat produces, its just taken into account in the planning stage.
-_NB: Setting this to a non-zero value will increase your daily cost, but will reduce your home battery usage._
-
-- **input_number.forecast_plan_hours** - the number of hours after the next charge slot to include in the plan, default 24 hours is the suggested amount (to match energy rate cycles)
-
-- **switch.set_discharge_during_charge** - If turned off disables inverter discharge during charge slots, useful for multi-inverter setups
-to avoid cross charging when batteries are out of balance.
Below is a guide to some of the electricity tariff options and a set of recommended Predbat settings for each tariff type.
In theory most tariffs will work out of the box but still it's worth reviewing your settings.
diff --git a/docs/customisation.md b/docs/customisation.md
index e3822ecf9..186a1a9ac 100644
--- a/docs/customisation.md
+++ b/docs/customisation.md
@@ -1,24 +1,26 @@
# Customisation
-These are the Predbat configuration items in Home Assistant that you can modify to fit your needs, you can configure these in Home Assistant directly.
+This document describes the Predbat configuration items in Home Assistant that you can modify to customise Predbat to fit your needs.
-See [Displaying output data](output-data.md#displayng-output-data)
+All of these settings are entities that can be configured directly in Home Assistant (unlike the '[apps.yaml](apps-yaml.md)' configuration items that have to be edited with a file editor).
+
+See [Displaying output data](output-data.md)
for information on how to view and edit these entities within
Home Assistant.
## Saving and restoring Predbat settings
-The selector **select.predbat_saverestore** can be used to save you current settings to a yaml file (kept in /config/predbat_save/) and to
+The selector **select.predbat_saverestore** can be used to save your current Predbat settings to a yaml file (kept in the directory `/config/predbat_save/`) and to
restore the settings from one of these files.
-Selecting **save current** will cause the settings to be save to a date/time stamped file. You can rename this file yourself in the HA filesystem
-to give it a more human readable name or delete it if you no longer want it. This is normally best done in the SSH window or via a Samba mount.
+Selecting the selector option **save current** will cause the settings to be saved to a date/time stamped file.
+You can rename this file yourself in the Home Assistant filesystem to give it a more human readable name, or delete it if you no longer want to keep it.
+This is normally best done in an SSH window or via a Samba mount.
-Selecting **restore default** will put all your settings back to the Predbat defaults.
-Before the the restore the current settings will be saved as **previous.yaml** should you have made a mistake you can restore them quickly again.
+Selecting the option **restore default** will put all your settings back to the Predbat defaults.
+Before the restore the current Predbat settings will be saved to the file **previous.yaml** - should you have made a mistake you can restore them quickly again.
Selecting any of the .yaml files you have created will restore your settings from this file.
-Before the the restore the current settings will be saved as **previous.yaml** should you have made a mistake you can restore them quickly again.
@@ -42,35 +44,39 @@ both charge and discharge, reset charge and discharge rates to full power and re
### Predbat Monitor mode
-In **monitor** mode Predbat will not control charging or discharging, inverter balancing will take place if enabled, the plan will show
-just what is expected based on the current inverter configuration alone.
+In **monitor** mode Predbat will not control or Plan any charging or discharging, inverter balancing will take place if enabled,
+and the plan will show just what is expected based on the current inverter configuration alone.
### Predbat Control SOC Only mode
In **Control SOC Only** mode Predbat will adjust the target charge percentage (SOC target) according to the Best plan, but the charge
-window will not be modified. This can be useful if you just have one fixed
-charge slot per day and you only want Predbat to control the percentage.
+window will not be modified.
+
+This mode can be useful if you just have one fixed charge slot per day and you only want Predbat to control the percentage the battery is charged based on solar generation
+and predicted house load.
-_CAUTION: If the charge window is disabled then no charging will take place._
+_CAUTION: You must manually set any charging required on the inverter and if the charge window is disabled then no charging will take place._
### Predbat Control Charge mode
In **Control Charge** mode Predbat will set the charge times and charge percentages according to the Best plan, charging can be enabled and
disabled by Predbat.
+Predbat will set the inverter into Eco mode when required to enable the battery to support house load, but it will not plan any forced discharging of the battery for export purposes.
+
+This mode can be useful if you don't have an export rate, or if you want to preserve the battery for home demand.
### Predbat Control Charge & Discharge mode
In **Control Charge and Discharge** mode Predbat will set both charge and discharge times and control charge and discharge percentages.
-If you have set the **switch.predbat_set_discharge_freeze_only** to True then forced export won't occur but Predbat can force the export
+If you have set the **switch.predbat_set_discharge_freeze_only** set to True then forced export won't occur but Predbat can force the export
of solar power to the grid when desired.
## Expert mode
-Predbat has a toggle switch called **switch.predbat_expert_mode** which is off by default for new installs (on
-by default for upgraded installs). A lot of configuration items will not be available unless expert mode is enabled.
-It's recommended for new users to start without expert mode and then maybe enable it later once you become more
-confident with the tool.
+Predbat has a toggle switch called **switch.predbat_expert_mode** which is set to Off by default for new installs (On by default for upgraded installs).
+A lot of Predbat's more advanced configuration options will not be available unless expert mode is enabled.
+It's recommended for new users to start without expert mode and then maybe enable it later once you become more confident with the tool.
## Performance related
@@ -88,48 +94,66 @@ reduce your CPU load.
## Battery loss options
-**input_number.battery_loss** accounts for energy lost charging the battery, default 0.05 is 5%
+**input_number.battery_loss** is an assumed percentage figure for energy lost when charging the battery, the default 0.05 is 5%.
+
+**input_number.battery_loss_discharge** is an assumed percentage figure for energy lost whilst discharging the battery, the default 0.05 is 5%.
+
+**input_number.inverter_loss** is an assumed percentage figure for energy lost during the conversion within the inverter from DC to AC or AC to DC,
+the default is 0% for legacy reasons but please adjust.
+
+**switch.inverter_hybrid** Set to True if you have a hybrid inverter so no inverter losses will be applied for DC charging from Solar generation.
+Set to False if you have an AC coupled battery and inverter losses will be applied when charging from solar.
+NB: This switch only applies when Predbat is modelling solar charging.
+All grid charging (regardless of inverter type) has to undergo an AC to DC conversion and so the inverter_loss % will be included in Predbat's model when charging from the grid.
-**input_number.battery_loss_discharge** accounts for energy lost discharging the battery, default 0.05 is 5%
+**input_number.metric_battery_cycle** (_expert mode_) This sets a 'virtual cost' in pence per kWh on using your battery for charging and discharging.
+Higher numbers will reduce battery cycles at the expense of using higher energy costs.
+In theory if you think your battery will last say 6000 complete cycles and cost you £4000 and is 9.5kWh then each full charge and discharge cycle is 19kWh
+and so the cost per cycle is £4000 / 19 / 6000 = 3.5p.
-**input_number.inverter_loss** accounts for energy loss during going from DC to AC or AC to DC, default is 0% for
-legacy reasons but please adjust.
+Taking the 3.5p example, Predbat will apply a "virtual cost" of 3.5p to every kWh of charge and of discharge of the battery.
+This cost will be included in Predbat's cost optimisation plan when it decides whether to charge, discharge the battery or let the house run on grid import.
+_NB: For clarity and to re-emphasise, the "virtual cost" will be applied to BOTH the cost calculation for charging AND for discharging the battery._
-**switch.inverter_hybrid** When True you have a hybrid inverter so no inverter losses for DC charging. When false
-you have inverter losses as it's AC coupled battery.
+If you configure this number higher then more expensive plans will be selected which avoids charging and discharging your battery as much.
+The default is 1p but can be set to 0 if you want to turn this feature off.
+Note that the cycle cost will not be included in the cost predictions that Predbat produces such as the Predbat HTML plan or Apex charts,
+its just a cost taken into account by Predbat at the planning stage when the plan is calculated.
+_NB: Setting this to a non-zero value will increase your daily cost, but will reduce your home battery usage._
-**input_number.metric_battery_cycle** (_expert mode_) Sets the cost in pence per kWh of using your battery for charging and discharging.
-Higher numbers will reduce battery cycles at the expense of using higher energy costs.
Figures of around 1p-5p are recommended, the default is 1p per kWh.
-**input_number.predbat_metric_battery_value_scaling** (_expert mode_) Can be used to scale the value of the energy
-in the battery at the end of the plan. The battery value is accounted for in the optimisations at the lowest future
-import rate including charging and inverter losses. A value of 1.0 means no change to this, while lower than 1.0
-means to value future battery levels less, greater than 1.0 will value it more (and hence hold more charge at the end of the plan).
+**input_number.predbat_metric_battery_value_scaling** (_expert mode_) A percentage value that can be used to scale the value of the energy in the battery at the end of the plan.
+The battery value is accounted for in the optimisations at the lowest future import rate including charging and inverter losses.
+A value of 1.0 means no change to this, while lower than 1.0 means to value future battery levels less,
+greater than 1.0 will value it more (and hence hold more charge at the end of the plan).
## Scaling and weight options
-**input_number.battery_rate_max_scaling** adjusts your maximum charge/discharge rate from that reported by GivTCP
-e.g. a value of 1.1 would simulate a 10% faster charge/discharge than reported by the inverter
+**input_number.battery_rate_max_scaling** is a percentage factor to adjust your maximum charge/discharge rate from that reported by GivTCP
+e.g. a value of 1.1 would simulate a 10% faster charge/discharge rate than reported by the inverter.
-**switch.predbat_battery_capacity_nominal** - When enabled Predbat uses the reported battery size from the Nominal field rather than from the normal GivTCP
-reported size. If your battery size is reported wrongly maybe try turning this on and see if it helps.
+**switch.predbat_battery_capacity_nominal** - When enabled Predbat uses the reported battery size from the GivTCP 'Battery Nominal Capacity' field
+rather than from the normal GivTCP reported 'Battery Capacity kWh' size.
+If your battery size is reported wrongly maybe try turning this on and see if it helps.
-**input_number.load_scaling** is a Scaling factor applied to historical load, tune up if you want to be more pessimistic on future consumption
-Use 1.0 to use exactly previous load data (1.1 would add 10% to load)
+**input_number.load_scaling** is a percentage Scaling factor applied to historical load, increase this if you want to be more pessimistic on future consumption.
+Use 1.0 to use exactly previous load data. A value of 1.1 for example would add 10% to historical load.
-**input_number.load_scaling10** is a Scaling factor applied to historical load only for the PV10% scenario (this is in addition to load_scaling).
-This can be used to make the 10% scenario take into account extra load usage and hence be more pessimistic while leaving the central
+**input_number.load_scaling10** is a percentage Scaling factor applied to historical load only for the PV10% scenario (this is in addition to load_scaling above).
+This can be used to make the PV10% scenario take into account extra load usage and hence be more pessimistic while leaving the central
scenario unchanged. The default is 1.1 meaning an extra 10% load is added. This will only have an impact if the PV 10% weighting is non-zero.
-**input_number.load_scaling_saving** is a Scaling factor applied to historical load only during Octopus Saving sessions. This can be used to model
-your household cutting down on energy use only inside a session (e.g. turning off a heat pump).
+**input_number.load_scaling_saving** is a percentage Scaling factor applied to historical load only during Octopus Saving sessions.
+This can be used to model your household cutting down on energy use inside a saving session (e.g. turning off a heat pump, deferring cooking until after the session, etc).
-**input_number.pv_scaling** is a scaling factor applied to PV data, tune down if you want to be more pessimistic on PV production vs Solcast
-Use 1.0 to use exactly the Solcast data (0.9 would remove 10% from forecast)
+**input_number.pv_scaling** is a percentage scaling factor applied to PV data, decrease this if you want to be more pessimistic on PV production vs Solcast.
+Use 1.0 to use exactly use the Solcast forecast generation data. A value of 0.9 for example would remove 10% from the Solcast generation forecast.
-**input_number.pv_metric10_weight** is the weighting given to the 10% PV scenario. Use 0.0 to disable this.
-A value of 0.1 assumes that 1:10 times we get the 10% scenario and hence to count this in the metric benefit/cost.
+**input_number.pv_metric10_weight** is the percentage weighting given to the Solcast 10% PV scenario in calculating solar generation.
+Use 0.0 to disable using the PV 10% in Predbat's forecast of solar generation.
+A value of 0.1 assumes that 1 in every 10 times we will get the Solcast 10% scenario, and 9 in every 10 times we will get the 'median' Solcast forecast.
+Predbat estimates solar generation for each half hour slot to be a pv_metric10_weight weighting of the Solcast 10% PV forecast to the Solcast Median forecast.
A value of 0.15 is recommended.
## Historical load data
@@ -199,6 +223,8 @@ charging sessions but will not reset it automatically.
See the Predbat mode setting as above for basic calculation options
+**input_number.forecast_plan_hours** is the number of hours after the next charge slot to include in the plan, default 24 hours is the suggested amount (to match energy rate cycles).
+
**switch.predbat_calculate_regions** (_expert mode_) When True the a second pass of the initial thresholds is
calculated in 4 hour regions before forming the detailed plan. Is True by default but can be turned off in expert
mode.
@@ -212,6 +238,9 @@ longer term plan will be less accurate.
**switch.predbat_calculate_discharge_oncharge** (_expert mode_) When True calculated discharge slots will
disable or move charge slots, allowing them to intermix. When False discharge slots will never be placed into charge slots.
+**switch.set_discharge_during_charge** - If turned off disables inverter discharge during charge slots, useful for multi-inverter setups
+to avoid cross charging when batteries are out of balance.
+
**switch.predbat_calculate_tweak_plan** (_expert mode_) When True causes Predbat to perform a second pass optimisation
across the next 8 charge and discharge windows in time order.
@@ -221,15 +250,14 @@ you want to discharge late.
**switch.predbat_calculate_second_pass** (_expert mode_) When True causes Predbat to perform a second pass optimisation
across all the charge and discharge windows in time order.
-NOTE: This feature is quite slow and so may need a higher performance machine
+NOTE: This feature is quite slow and so may need a higher performance machine.
-This can help to slightly improve the plan for tariffs like Agile but can make it worse in some fixed rate tariffs which
-you want to discharge late.
+This can help to slightly improve the plan for tariffs like Agile but can make it worse in some fixed rate tariffs which you want to discharge late.
## Battery margins and metrics options
**input_number.best_soc_keep** is the minimum battery level in kWh that Predbat will to try to keep above during the whole period of the simulation time.
-This is a soft constraint only so it is possible for your SoC to drop below this - use **input_number.best_soc_min** for hard SoC constraint that will always be maintained.
+This is a soft constraint only so it is possible for your SoC to drop below this - use **input_number.best_soc_min** for a hard SoC constraint that will always be maintained.
It's usually good to have best_soc_keep set to a value above 0 to allow some margin
in case you use more energy than planned between charge slots.
@@ -248,8 +276,8 @@ a saving session). The default is enable (True)
**switch.combine_discharge_slots** (_expert mode_) Controls if discharge slots of > 30 minute can be combined. When disabled
they will be split up, increasing run times but potentially more accurate for planning. The default is disabled (False)
-**input_number.metric_min_improvement** (_expert mode_) sets the minimum cost improvement that it's worth lowering the battery SOC % for.
-If it's 0 then this is disabled and the battery will be charged less if it's cost neutral.
+**input_number.metric_min_improvement** (_expert mode_) sets the minimum cost improvement in pence that it's worth lowering the battery SOC % for.
+The default value is 0 which means this feature is disabled and the battery will be charged less if it's cost neutral.
If you use **pv_metric10_weight** then you probably don't need to enable this as the 10% forecast does the same thing better
Do not use if you have multiple charge windows in a given period as it won't lead to good results (e.g. Agile)
You could even go to something like -0.1 to say you would charge less even if it cost up to 0.1p more (best used with metric10)
@@ -275,6 +303,10 @@ If you set this too high you might not get any export slots. If it's too low you
not yet published, best used for variable rate tariffs such as Agile import where the rates are not published until 4pm.
If you set this to a positive value then Predbat will assume unpublished import rates are higher by the given amount.
+Setting this to 1 to 1.5p for example results in Predbat being a little more aggressive in the charging calculation for today -
+Predbat will charge the battery to a higher percentage than it would otherwise as it expects a cost benefit of using today's lower rates.
+NB: this can lead to higher costs and to some export if solar generation is better than forecast.
+
**input_number.metric_future_rate_offset_export** (_expert mode_) Sets an offset to apply to future export energy rates that are
not yet published, best used for variable rate tariffs such as Agile export where the rates are not published until 4pm.
If you set this to a negative value then Predbat will assume unpublished export rates are lower by the given amount.
@@ -388,22 +420,24 @@ In summary:
## Manual control
-In some cases you may want to override Predbat behaviour and make a decision yourself. One way to achieve this is to put Predbat into
+In some cases you may want to override Predbat's planned behaviour and make a decision yourself. One way to achieve this is to put Predbat into
read-only mode using **switch.predbat_set_read_only**. When going to read only mode the inverter will be put back to the default settings and then you should
control it yourself using GivTCP or the App.
A better alternative in some cases is to tell Predbat what you want it to do using the manual force features:
-Can you force a charge within a 30 minute slot by using the **select.predbat_manual_charge** selector. Pick the 30 minute slot you wish
-to charge in and this will be actioned. You can select multiple slots by using the drop down menu more than once, when Predbat updates
-you will see the slots picked in the current value of this selector and in the HTML plan (upside down F symbol).
+You can force the battery to be charged within a 30 minute slot by using the **select.predbat_manual_charge** selector.
+Pick the 30 minute slot you wish to charge in and Predbat will change the plan to charge in the selected slot.
+You can select multiple slots by using the drop down menu more than once.
+When Predbat updates the plan you will see the slots picked to be charging slots in the current value of this selector,
+and annotated in the [Predbat HTML plan](predbat-plan-card.md#displaying-the-predbat-plan) with an upside down 'F' symbol.
-You can cancel a force slot by selecting the time again (it will be shown in square brackets to indicate its already selected).
+You can cancel a force slot by selecting the slot time again (it will be shown in square brackets to indicate its already selected).
-The **select.predbat_manual_discharge** selector can be used to manually force a discharge within a 30 minute slot in the same way as the
-manual force charge feature. The force discharge takes priority over force charging.
+The **select.predbat_manual_discharge** selector can be used to manually force a discharge within a 30 minute slot in the same way as the manual force charge feature.
+The force discharge takes priority over force charging.
The **select.predbat_manual_idle** selector is used to force Predbat to be idle during a 30 minute slot, this implies no charging or discharging and thus the
battery will cover the house load (if there is enough charge).
diff --git a/docs/faq.md b/docs/faq.md
index b4a870027..07a07ca64 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -50,6 +50,44 @@ especially if you have a small battery. If you set it to zero then predbat may n
- 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)
+## The plan doesn't charge or discharge when I expect it to
+
+It is very important to correctly set Predbat's [Battery Loss Options](customisation.md#battery-loss-options)
+and [Battery Margins](customisation.md#battery-margins-and-metrics-options) as these can have a huge and critical impact on the plan that Predbat generates.
+
+Predbat's default configuration values are the recommended starting values for most users but there is no single right set of configuration values for every user of Predbat,
+it depends on many factors and your personal preferences. Many users will need to customise and tweak their [Predbat configuration](customisation.md) to suit their needs.
+
+The SOC level that Predbat aims to keep in the battery **input_number.best_soc_keep** and the absolute minimum SoC level **input_number.best_soc_min** are the first thing to check.
+If these are set too high then Predbat will charge at unfavourable rates to maintain the battery SoC.
+
+Predbat performs a lowest cost battery optimisation so a key part of deciding whether to charge, discharge or feed the house from the battery are the loss rates
+**input_number.battery_loss**, **input_number.battery_loss_discharge** and **input_number.inverter_loss**.
+Typical values could be 4, 4, 4 or 5, 5, 5. It is tempting to set these inverter loss figures lower to encourage Predbat to use the battery more,
+but this should be resisted as experience from the GivEnergy community forum suggests total energy conversion losses are in the range of 10-20%.
+
+Putting these losses into context and assuming you have an AC-coupled battery and have set the losses to 4, 4 and 4;
+then for every kWh charged from the grid you will only get 0.92kWh stored in the battery (4% charge + 4% inverter conversion loss)
+and similarly when that 0.92kWh is discharged to the home you will only receive 0.85kWh (0.92 x 0.92).
+
+These loss percentages also impact the Predbat plan. Consider an import rate of 20p/kWh; after conversion losses are considered,
+each 1kWh of stored battery charge will in effect have cost 21.7p (20 / 0.92) to import.
+
+Then for discharging, the same applies. Each kWh of stored battery charge (that cost 21.7p to charge) will in effect have cost 23.6p (21.7 / 0.92) to discharge.
+Predbat makes cost optimisation decisions so unless the current import rate is more than 23.6p, it will be cheaper to let the home run off grid import rather than to discharge the battery.
+
+If you turn [debug mode on for the Predbat plan](predbat-plan-card.md#debug-mode-for-predbat-plan) then you can see the
+effective import and export rates after losses that Predbat calculates in the Predbat plan.
+
+Predbat also uses **input_number.metric_battery_cycle** (_expert mode_ setting) to apply a 'virtual cost' in pence per kWh for charging and discharging the battery.
+The default value is 1p but this this can be changed to a different value to recognise the 'cost of using the battery', or set to zero to disable this feature.
+
+So if metric battery cycle is set to 1p, and continuing the example above, each kWh of battery charge will be costed at 22.7p (21.7p + 1p battery metric to charge),
+and the battery will not be discharged to support the home unless the current import rate is more than 25.6p (23.6p + 1p cost of charging + 1p cost to discharge).
+
+**input_number.metric_min_improvement** and **input_number.metric_min_improvement_discharge** (both _expert mode_ settings) also affect Predbat's cost optimisation decisions
+as to whether to charge or discharge the battery so could be tweaked. The defaults (0p and 0.1p respectively) should however give good results for most users.
+
## 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
diff --git a/docs/install.md b/docs/install.md
index f07a7ea11..43f1a321e 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -266,10 +266,19 @@ You have configured predbat's control entities, created a couple of dashboard pa
In order to enable Predbat you must delete the 'template: True' line in `apps.yaml` once you are happy with your configuration.
-You may initially want to set **select.predbat_mode** to *Monitor* to see how Predbat operates, e.g. by studying the Predbat Plan.
+You may initially want to set **select.predbat_mode** to *Monitor* to see how Predbat operates, e.g. by studying the [Predbat Plan](predbat-plan-card.md).
+In *Monitor* mode Predbat will monitor (but not change) the current inverter settings and predict the battery SoC based on predicted Solar Generation and House Load.
-Once you are happy with the plan Predbat is producing, and are ready to let Predbat start controlling your inverter, set **select.predbat_mode**
-to the correct mode of operation for your system.
+The recommended next step is to start Predbat planning your inverter charging and discharging activity but not (yet) make any changes to the inverter.
+This enables you to get a feel for the Predbat plan and [customise Predbat's settings](customisation.md) to meet your needs.
+
+Set **select.predbat_mode** to the correct [mode of operation](customisation.md#predbat-mode) for your system
+and also set **switch.predbat_set_read_only** to True to stop Predbat making any changes to your inverter.
+
+Once you are happy with the plan Predbat is producing, and are ready to let Predbat start controlling your inverter charging and discharging,
+set the switch **switch.predbat_set_read_only** to False and Predbat will start controlling your inverter.
+
+You can see the planned charging and discharging activity in the [Predbat Plan](predbat-plan-card.md).
## Updating Predbat
diff --git a/docs/predbat-plan-card.md b/docs/predbat-plan-card.md
index 0391d07ea..45dcce03c 100644
--- a/docs/predbat-plan-card.md
+++ b/docs/predbat-plan-card.md
@@ -66,6 +66,8 @@ So in essence, Yellow and Red coloured export rates will be considered as priori
discharging and force exported, or being held at the current level.
Alongside the state is an arrow which points upwards if the battery SoC is increasing (i.e. charging), to the right if the battery SoC is remaining constant,
or downwards if the battery SoC is decreasing (i.e. discharging).
+If Predbat's plan has been over-ridden and the [slot has been manually controlled](customisation.md#manual-control) to be a Charging slot, Discharging or Idle,
+then alongside the State and battery SoC arrow will be an upside down 'F' indicating it is a 'Forced' activity.
The slot will be coloured Green for Charging, Yellow for Discharging, Silver Grey for Freeze Charging, Pale Blue for Hold Charging or White for Idle.
NB: The Predbat plan is shown in 30 minute time slots but Predbat actually plans battery activity in 5 minute segments within the 30 minute slot.
If the Home Assistant control *switch.predbat_calculate_discharge_oncharge* is set to True,