Documentation updates: Monitor mode, Battery loss & scaling, new FAQ …

…for impoving the plan, days_previous (#670)

* Review and update configuration guide

* Review & refine 'what does predbat do'

* Expand explanation days_previous with examples

* Added explanation of how set_reserve_min could be used to retain SOC ahead of predicted storms #571

* Add explanation of using car_charging_energy to filter other loads such as Mixergy out #574

* Add details of load_forecast and predheat Not utilising battery #574

* Added 'choose' branching to givtcp activity monitor

* Added givtcp alert if inverter temperature <5 degrees (should never happen, indicates inverter offline)

* Added GivTCP restart to activity monitor

* Move GivTCP 'output raw register values' image into images folder

* Move 'Predbat sample data-out dashboard' into images folder

* Added rounding to rate_min_forward_looking log message

* Reformat 'joined Octopus saving session' log & alert for improved readability

* [pre-commit.ci lite] apply automatic fixes

* Expanded and updated Predbat Plan card documentation

* Line length fix

* Minor changes to predbat-plan-card

* Expanded installation guide for #645, clarify Monitor mode

* Added Arg0t's tip to use metric_future_rate_offset_import for more aggressive charging

* Improve battery loss & scaling and weight documentation sections

* New FAQ for improving the plan

* Move configuration docs from config guide to customisation doc

* Completed new FAQ for understanding losses & battery metric #643

* Expanded explanation of how days_previous works #647

* Move extended days_previous examples to separate section

---------

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>

docs/apps-yaml.md

@@ -46,46 +46,46 @@ 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.<BR>
-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.<BR>
+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:
     - 7
     - 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:
     purge_keep_days: 14
 ```
 
 - **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
@@ -506,3 +506,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!<BR>
+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
+```

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.<BR>
-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.<BR>
 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.<BR>
-_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.