Documentation updates (#692)

* 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

* Update configuration-guide.md, add missing predbat_ prefixes

predbat_ prefix missing from a number of entities

* Update energy-rates.md, minor typos

* Update install.mdUpdate install.md, extra highlight of what Monitor mode does

* Update configuration-guide.md, more missing predbat_ prefixes

* Update car-charge-planning.md, clarify settings for Octopus Intelligent

* Typo & formatting corrections

* Create charge curve, more info on entities required for history to create the curve #666

* Added missing predbat_ prefixes to HA entity names

* Expanded predbat freeze charge/discharge statii descriptions #689

---------

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

docs/apps-yaml.md

@@ -224,7 +224,8 @@ The **givtcp_rest** line should be commented out/deleted in order for Predbat to
 - **discharge_start_time** - GivTCP scheduled discharge slot_1 start time
 - **discharge_end_time** - GivTCP scheduled discharge slot_1 end time
 
-If you are using REST control the above GivTCP configuration items can be deleted or commented out of apps.yaml.
+If you are using REST control the above GivTCP configuration items can be deleted or commented out of `apps.yaml`
+(but see section below on [creating the battery charge power curve](#workarounds)).
 
 ## Solcast Solar Forecast
 
@@ -248,7 +249,7 @@ If however you have a mixed PV array setup with some PV that does not feed into
 then it's recommended that Solcast is only configured for the PV connected to the GivEnergy inverters.
 
 Solcast produces 3 forecasted PV estimates, the 'central' (50% or most likely to occur) PV forecast, the '10%' (worst case) PV forecast, and the '90%' (best case) PV forecast.<BR>
-By default Predbat will use the central estimate and applies to it the **input_number.pv_metric10_weight** weighting of the 10% (worst case) estimate.
+By default Predbat will use the central estimate and applies to it the **input_number.predbat_pv_metric10_weight** weighting of the 10% (worst case) estimate.
 
 Predbat models cloud coverage by using the difference between the PV and PV10 forecasts to work out a cloud factor,
 this modulates the PV output predictions up and down accordingly as if there were passing clouds.
@@ -258,11 +259,11 @@ This can have an impact on planning, especially for things like freeze charging
 or '90' to always use the 90% PV estimate (not recommended!).<BR>
 Set to blank or delete / comment out the line to use the default central estimate.
 
-If **pv_estimate** is set to 10 then **input_number.pv_metric10_weight** in Home Assistant should be set to 1.0.
+If **pv_estimate** is set to 10 then **input_number.predbat_pv_metric10_weight** in Home Assistant should be set to 1.0.
 
 ## Energy Rates
 
-There are a number of configuration items in apps.yaml for telling Predbat what your import and export rates are.
+There are a number of configuration items in `apps.yaml` for telling Predbat what your import and export rates are.
 
 These are described in detail in [Energy Rates](energy-rates.md) and are listed here just for completeness:
 
@@ -304,20 +305,20 @@ Set to 0 if you don't have an EV (and the remaining car sensors in apps.yaml can
 You might want to remove your electric car charging data from the historical house load data so as to not bias the calculations, otherwise you will get
 high battery charge levels when the car was charged previously (e.g. last week).
 
-- **switch.car_charging_hold** - A Home Assistant switch that when turned on (True) tells Predbat to remove car charging data from Predbat's battery prediction plan.
+- **switch.predbat_car_charging_hold** - A Home Assistant switch that when turned on (True) tells Predbat to remove car charging data from Predbat's battery prediction plan.
 
 - **car_charging_energy** - Set in apps.yaml to point to a Home Assistant entity which is the incrementing kWh data for the car charger.
 This has been pre-defined to a regular expression to auto-detect the appropriate Wallbox and Zappi car charger sensors, or edit as necessary in apps.yaml for your charger sensor.<BR>
 This can be set to a list of car charging energy sensors, one per line if you have multiple EV car chargers.<BR>
 You can also use **car_charging_energy** to remove other house load kWh from the data Predbat uses for the forecast,
 e.g. if you want to remove Mixergy hot water tank heating data from the forecast such as if you sometimes heat on gas, and sometimes electric depending upon import rates.
 
-- **input_number.car_charging_energy_scale** - A Home Assistant entity used to define a scaling factor (in the range 0.1 to 1.0)
+- **input_number.predbat_car_charging_energy_scale** - A Home Assistant entity used to define a scaling factor (in the range 0.1 to 1.0)
 to multiply the car_charging_energy data by if required (e.g. set to 0.001 to convert Watts to kW).
 
 If you do not have a suitable car charging kWh sensor in Home Assistant then comment the car_charging_energy line out of `apps.yaml` and configure the following Home Assistant entity:
 
-- **input_number.car_charging_threshold** - Sets the threshold above which home consumption is assumed to be car charging and will be removed from the home load data (default 6 = 6kW).
+- **input_number.predbat_car_charging_threshold** - Sets the threshold above which home consumption is assumed to be car charging and will be removed from the home load data (default 6 = 6kW).
 
 ### Planned Car Charging
 
@@ -448,18 +449,33 @@ Enter the charging curve as a series of steps of % of max charge rate for each s
 
 The default is 1.0 (full power) charge all the way to 100%.
 
-Modelling the charge curve becomes important if you have limited charging slots (e.g. ony a few hours a night) or you wish to make accurate use of the
+Modelling the charge curve becomes important if you have limited charging slots (e.g. only a few hours a night) or you wish to make accurate use of the
 low power charging mode (**switch.predbat_set_charge_low_power**).
 
-Predbat can now automatically calculate the charging curve for you if you have enough suitable data in your load history. The charging curve will be calculated
+Predbat can now automatically calculate the charging curve for you if you have enough suitable historical data in Home Assistant. The charging curve will be calculated
 when battery_charge_power_curve option is *not* set in apps.yaml and Predbat is started for the first time (due to restarting AppDaemon or an edit to apps.yaml).
-You should look at the AppDaemon/Predbat logfile to find the predicted charging curve and copy/paste it into your apps.yaml. This will also include a recommendation
-for how to set your **battery_rate_max_scaling** setting in HA.
+You should look at the [AppDaemon/Predbat logfile](output-data.md#predbat-logfile) to find the predicted battery charging curve and copy/paste it into your `apps.yaml` file.
+This will also include a recommendation for how to set your **battery_rate_max_scaling** setting in HA.
 
 Setting This option to **auto** will cause the computed curve to be stored and used automatically. This is not recommended if you use low power charging mode as your
 history will eventually not contain any full power charging data to compute the curve, so in this case it's best to manually save the data.
 
-Example from a GivEnergy 9.5kWh battery with latest firmware and Gen 1 inverter:
+NB: In order for Predbat to have calculate your charging curve it needs to have access to historical Home Assistant data for battery_charge_rate, battery_power and soc_kw.
+
+If you are using the recommended default [REST mode to control your inverter](#inverter-control-configurations) then you will need to uncomment out the following entries in apps.yaml:
+
+```yaml
+  charge_rate:
+    - number.givtcp_{geserial}_battery_charge_rate
+  battery_power:
+    - sensor.givtcp_{geserial}_battery_power
+  soc_kw:
+    - sensor.givtcp_{geserial}_soc_kwh
+```
+
+Once the battery charge curve has been created these entries can be commented out again in `apps.yaml`.
+
+Example charging curve from a GivEnergy 9.5kWh battery with latest firmware and Gen 1 inverter:
 
 ```yaml
   battery_charge_power_curve:

docs/car-charge-planning.md

@@ -2,12 +2,17 @@
 
 There are two ways to plan car charging slots:
 
-- If you have Intelligent Octopus import tariff and the Octopus Energy integration - in which case Predbat will use the slots allocated by Octopus Energy in battery prediction
-    - Ensure **octopus_intelligent_slot** in `apps.yaml` points to the Intelligent Slot sensor in the Octopus Energy integration
+- If you have Intelligent Octopus import tariff and the Octopus Energy integration - in which case Predbat will use the slots allocated by Octopus Energy in battery prediction.
+The [Octopus Energy integration supports Octopus Intelligent](https://bottlecapdave.github.io/HomeAssistant-OctopusEnergy/entities/intelligent/),
+and through that Predbat gets most of the information it needs.
+    - **octopus_intelligent_slot** in `apps.yaml` is pre-configured with a regular expression to point to the Intelligent Slot sensor in the Octopus Energy integration.
+You should not need to change this, but its worth checking the [Predbat logfile](output-data.md#predbat-logfile) to confirm that it has found your Octopus account details
     - Set **switch.predbat_octopus_intelligent_charging** to True
-    - Information about the car's battery size will also be extracted from the Octopus Energy integration
-    - You will need to set the cars current soc sensor, **car_charging_soc** in apps.yaml correctly to have accurate results
-    - If you set **car_charging_limit** in `apps.yaml` then Predbat can also know if the car's limit is set lower than in Intelligent Octopus
+    - Information about the car's battery size will be automatically extracted from the Octopus Energy integration
+    - You should set the cars current soc sensor, **car_charging_soc** in `apps.yaml` to point to a sensor that specifies the car's current % charge level to have accurate results.
+This should normally be a sensor provided by your car charger. If you don't have this available for your charger then Predbat will assume the charge level is 0%.
+    - If you set **car_charging_limit** in `apps.yaml` then Predbat can also know if the car's limit is set lower than in Intelligent Octopus.
+    If you don't set this Predbat will default to 100%.
     - You can use **car_charging_now** as a workaround to indicate your car is charging but the Intelligent API hasn't reported it.
     - Let the Octopus app control when your car charges
 

docs/configuration-guide.md

@@ -12,11 +12,11 @@ It is recommended that you [create a dashboard page](output-data.md#displaying-o
 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.
+You should try to tune **input_number.predbat_inverter_loss**, **input_number.predbat_battery_loss** and **input_number.predbat_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.predbat_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 per kWh on using your battery for charging and discharging.<BR>
+The setting **input_number.predbat_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.
 
@@ -47,9 +47,9 @@ If you are using expert mode then these options maybe worth reviewing:
 |---------|---------------|-------------|
 | input_number.predbat_forecast_plan_hours | 24 | If you set this to 24 then you will have quicker updates, the cycle repeats itself anyhow |
 | switch.predbat_combine_charge_slots | True  | As you have just one overnight rate then one slot is fine |
-| input_number.metric_min_improvement | 0  | Charge less if it's cost neutral |
+| input_number.predbat_metric_min_improvement | 0  | Charge less if it's cost neutral |
 
-You should set **select.predbat_mode** to 'Control Charge'
+You should set **select.predbat_mode** to 'Control charge'
 
 ## Cheap night rate, with a good export rate (e.g. Intelligent Octopus with Octopus Outgoing)
 
@@ -67,12 +67,12 @@ If you are using expert mode then these options maybe worth reviewing, otherwise
 |---------|---------------|-------------|
 | input_number.predbat_forecast_plan_hours  | 24 | If you set this to 24 then you will have quicker updates, the cycle repeats itself anyhow |
 | switch.predbat_combine_charge_slots | ? | Setting to False will allow charging at more expensive day rates when it's worth it to export more |
-| input_number.metric_min_improvement  | 0   | Charge less if it's cost neutral |
-| input_number.metric_min_improvement_discharge  | 0.1  | Discharge only if there is a profit |
-| input_number.metric_battery_cycle  | ?  | Higher numbers mean less charging and discharging but higher costs |
+| input_number.predbat_metric_min_improvement  | 0   | Charge less if it's cost neutral |
+| input_number.predbat_metric_min_improvement_discharge  | 0.1  | Discharge only if there is a profit |
+| input_number.predbat_metric_battery_cycle  | ?  | Higher numbers mean less charging and discharging but higher costs |
 | input_number.predbat_best_soc_min |  ?  | Can be set non-zero if you want to force a minimum charge level |
 
-You should set **select.predbat_mode** to 'Control Charge & Discharge'
+You should set **select.predbat_mode** to 'Control charge & discharge'
 
 ## Multiple rates for import and export (e.g. Octopus Flux & Cozy)
 
@@ -92,12 +92,12 @@ If you are using expert mode then these options maybe worth reviewing, otherwise
 |---------|---------------|-------------|
 | input_number.predbat_forecast_plan_hours  | 24 | If you set this to 24 then you will have quicker updates, the cycle repeats itself anyhow |
 | switch.predbat_combine_charge_slots | ? | Setting to False will allow charging at more expensive day rates when it's worth it to export more |
-| input_number.metric_min_improvement  | 0  | Charge less if it's cost neutral |
-| input_number.metric_min_improvement_discharge  | 0.1  | Discharge only if there is a profit |
-| input_number.metric_battery_cycle  | ?  | Higher numbers mean less charging and discharging but higher costs |
+| input_number.predbat_metric_min_improvement  | 0  | Charge less if it's cost neutral |
+| input_number.predbat_metric_min_improvement_discharge  | 0.1  | Discharge only if there is a profit |
+| input_number.predbat_metric_battery_cycle  | ?  | Higher numbers mean less charging and discharging but higher costs |
 | input_number.predbat_best_soc_min |  0  | Don't use non-zero otherwise all slots will be force charging |
 
-You should set **select.predbat_mode** to 'Control Charge & Discharge'
+You should set **select.predbat_mode** to 'Control charge & discharge'
 
 ## Half hourly variable rates (e.g. Octopus Agile)
 
@@ -114,10 +114,10 @@ If you are using expert mode then these options maybe worth reviewing, otherwise
 | Item |  Value  | Comment  |
 |---------|---------------|-------------|
 | input_number.predbat_forecast_plan_hours  | 24-48 | If you set this to 24 then you will have quicker updates, going to 36/48 for a longer plan |
-| input_number.metric_min_improvement  | 0  | Charge less if it's cost neutral |
-| input_number.metric_min_improvement_discharge  | 0.1  | Discharge only if there is a profit |
-| input_number.metric_battery_cycle  | ?  | Higher numbers mean less charging and discharging but higher costs |
+| input_number.predbat_metric_min_improvement  | 0  | Charge less if it's cost neutral |
+| input_number.predbat_metric_min_improvement_discharge  | 0.1  | Discharge only if there is a profit |
+| input_number.predbat_metric_battery_cycle  | ?  | Higher numbers mean less charging and discharging but higher costs |
 | input_number.predbat_best_soc_min |  0  | Don't use non-zero otherwise all slots will be force charging |
-| switch.calculate_fast_plan | False | The fast plan feature reduces accuracy of planning |
+| switch.predbat_calculate_fast_plan | False | The fast plan feature reduces accuracy of planning |
 
-You should set **select.predbat_mode** to 'Control Charge & Discharge'
+You should set **select.predbat_mode** to 'Control charge & discharge'