diff --git a/docs/apps-yaml.md b/docs/apps-yaml.md
index 61729ac2b..1247e4df6 100644
--- a/docs/apps-yaml.md
+++ b/docs/apps-yaml.md
@@ -216,6 +216,10 @@ then it's recommended that Solcast is only configured for the PV connected to th
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.
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.
+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.
+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.
+
- **pv_estimate** in `apps.yaml` can be used to configure Predbat to always use the 10% forecast by setting the configuration item to '10',
or '90' to always use the 90% PV estimate (not recommended!).
Set to blank or delete / comment out the line to use the default central estimate.
diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md
index a0dc4f8c1..e1a1b4ce1 100644
--- a/docs/configuration-guide.md
+++ b/docs/configuration-guide.md
@@ -1,59 +1,60 @@
# Configuration guide
-First get the basics set up, ensure you have the inverter controls configured, the historical load data and the solar forecast
-in place. Make sure your energy rates are configured correctly for import and export.
+First get the basics set up, ensure you have the [inverter controls configured](install.md#inverter-control-integration-install-givtcpsolax-modbus),
+you have [configured apps.yaml](apps-yaml.md) to your setup, and the [solar forecast](install.md#solcast-install) is in place.
+Make sure your [energy rates](energy-rates.md) are configured correctly for import and export.
-If you have an EV try to set up the car charging sensor correctly so the tool can tell what part of your historical load is EV
-charging. You might want to also set to the car charging plan so you can predict when your car is plugged in and how much it will charge.
+If you have an EV try to set up the [car charging sensor](apps-yaml.md#car-charging-integration) correctly so Predbat can tell what part of your historical load is EV charging.
+You might want to also set to the [car charging plan](apps-yaml.md#planned-car-charging) so you can predict when your car is plugged in and how much it will charge.
-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.
+It is recommended that you [create a dashboard page](output-data.md#displaying-output-data) with all the required entities to control Predbat.
-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 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 value will increase your daily cost, but will reduce your home battery usage._
+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.
-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 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.
+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.
+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 2p 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)
+- **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)
-- **set_discharge_during_charge** - If turned off disables inverter discharge during charge slots, useful for multi-inverter
+- **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 tariff options, in theory most tariffs will work out of the box but still it's worth reviewing your settings.
+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.
## Fixed daily rates
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.
+You should set **select.predbat_mode** to 'Monitor'.
+
## 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 day's solar forecast.
+In this scenario you will want to charge overnight based on the next day's solar forecast and don't want Predbat to force discharge your battery.
Recommended settings - these must be changed in Home Assistant once Predbat is running:
| Item | Value | Comment |
|---------|---------------|-------------|
-| select.predbat_mode | Control Charge | You want the tool to calculate and control charging |
+| select.predbat_mode | Control Charge | You want Predbat to calculate and control charging |
| input_number.predbat_best_soc_keep | 2.0 | Tweak this to control what battery level you want to keep as a backup in case you use more energy |
-| switch.predbat_combine_charge_slots | True | Use one big charge slot |
+| switch.predbat_combine_charge_slots | True | Use one big charge slot |
If you are using expert mode then these options maybe worth reviewing:
| Item | Value | Comment |
|---------|---------------|-------------|
-| input_number.predbat_forecast_plan_hours | 24 | If you set this to 24 then you will have quicker updates, the cycle repeats itself anyhow |
+| 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.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)
@@ -61,47 +62,47 @@ Follow the instructions from the _Cheap Night rate_ above, but also you will als
| Item | Value | Comment |
|---------|---------------|-------------|
-| select.predbat_mode | Control Charge & Discharge | You want the tool to calculate and control charging and discharging |
+| select.predbat_mode | Control Charge & Discharge | You want Predbat to calculate and control charging and discharging |
| input_number.predbat_best_soc_keep | 2.0 | Tweak this to control what battery level you want to keep as a backup in case you use more energy |
-| switch.predbat_combine_charge_slots | True | Use one big charge slot |
+| switch.predbat_combine_charge_slots | True | Use one big charge slot |
If you are using expert mode then these options maybe worth reviewing, otherwise ignore this:
| Item | Value | Comment |
|---------|---------------|-------------|
-| 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 | ? | Going to False will allow charging at more expensive day rates when it's worth it to export mode |
+| 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_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)
-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 _Cheap Night_ rate above, but also you will want to have automatic discharge when the export rates are profitable.
Recommended settings - these must be changed in Home Assistant once Predbat is running:
| Item | Value | Comment |
|---------|---------------|-------------|
-| select.predbat_mode | Control Charge & Discharge | You want the tool to calculate and control charging and discharging |
+| select.predbat_mode | Control Charge & Discharge | You want Predbat to calculate and control charging and discharging |
| input_number.predbat_best_soc_keep | 0.5 | Use the full battery without going empty |
-| switch.predbat_combine_charge_slots | True | Use one big charge slot |
+| switch.predbat_combine_charge_slots | True | Use one big charge slot |
If you are using expert mode then these options maybe worth reviewing, otherwise ignore this:
| Item | Value | Comment |
|---------|---------------|-------------|
-| 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 | ? | Going to False will allow charging at more expensive day rates when it's worth it to export mode |
-| input_number.metric_min_improvement | 0 | Charge less if it's cost neutral |
+| 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_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)
@@ -109,19 +110,19 @@ Recommended settings - these must be changed in Home Assistant once Predbat is r
| Item | Value | Comment |
|---------|---------------|-------------|
-| select.predbat_mode | Control Charge & Discharge | You want the tool to calculate and control charging and discharging |
+| select.predbat_mode | Control Charge & Discharge | You want Predbat to calculate and control charging and discharging |
| input_number.predbat_best_soc_keep | 0.5 | Use the full battery without going empty |
-| switch.predbat_combine_charge_slots | True | Use one big charge slot |
+| switch.predbat_combine_charge_slots | True | Use one big charge slot |
If you are using expert mode then these options maybe worth reviewing, otherwise ignore this:
| 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.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_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 |
-You should set **select.predbat_mode** to Control Charge & Discharge
+You should set **select.predbat_mode** to 'Control Charge & Discharge'
diff --git a/docs/customisation.md b/docs/customisation.md
index 1c4b1ce79..917132f3b 100644
--- a/docs/customisation.md
+++ b/docs/customisation.md
@@ -1,7 +1,6 @@
# Customisation
-These are configuration items that you can modify to fit your needs, you can configure these in Home Assistant directly.
-Changing the items in apps.yaml will have no effect.
+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.
See [Displaying output data](output-data.md#displayng-output-data)
for information on how to view and edit these entities within
@@ -81,9 +80,9 @@ legacy reasons but please adjust.
**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.
-**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 expensive of higher energy costs.
-Figures of around 1p-5p are recommended, the default is 0.
+**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 2p.
**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
@@ -114,7 +113,7 @@ A value of 0.15 is recommended.
## Historical load data
-The historical load data is taken from the load sensor as configured in apps.yaml and the days are selected
+The historical load data is taken from the load sensor as configured in `apps.yaml` and the days are selected
using **days_previous** and weighted using ***days_previous_weight** in the same configuration file
**switch.predbat_load_filter_modal** (_expert mode_) when enabled will automatically discard the lowest daily consumption
@@ -208,49 +207,50 @@ you want to discharge late.
## Battery margins and metrics options
-**best_soc_keep** is minimum battery level to try to keep above during the whole period of the simulation time,
-soft constraint only (use min for hard constraint). It's usually good to have this above 0 to allow some margin
+**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.
+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.
-**best_soc_min** (_expert mode_) sets the minimum charge level (in kWh) for charging during each slot and the
-minimum discharge level also (set to 0 if you want to skip some slots). If you set this non-zero you will need
+**input_number.best_soc_min** (_expert mode_) sets the minimum charge level (in kWh) for charging during each slot and the
+minimum discharge level also (set to 0 if you want to skip some slots). If you set this to a non-zero value you will need
to use the low rate threshold to control which slots you charge from or you may charge all the time.
-**best_soc_max** (_expert mode_) sets the maximum charge level (in kWh) for charging during each slot.
+**input_number.best_soc_max** (_expert mode_) sets the maximum charge level (in kWh) for charging during each slot.
A value of 0 disables this feature.
-**combine_charge_slots** Controls if charge slots of > 30 minutes can be combined. When disabled they will be split up,
+**switch.combine_charge_slots** Controls if charge slots of > 30 minutes can be combined. When disabled they will be split up,
increasing run times but potentially more accurate for planning. Turn this off if you want to enable ad-hoc import
during long periods of higher rates but you wouldn't charge normally in that period (e.g. pre-charge at day rate before
a saving session). The default is enable (True)
-**combine_discharge_slots** (_expert mode_) Controls if discharge slots of > 30 minute can be combined. When disabled
+**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)
-**metric_min_improvement** (_expert mode_) sets the minimum cost improvement that it's worth lowering the battery SOC % for.
+**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.
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)
-**metric_min_improvement_discharge** (_expert mode_) Sets the minimum pence cost improvement it's worth doing a forced discharge (and export) for.
+**input_number.metric_min_improvement_discharge** (_expert mode_) Sets the minimum pence cost improvement it's worth doing a forced discharge (and export) for.
A value of 0.1 is the default which prevents any marginal discharges. If you increase this value (e.g. you only want to discharge/forced export if definitely very profitable),
then discharges will become less common and shorter.
-**rate_low_threshold** (_expert mode_) When 0 (default) this is automatic but can be overridden. When non zero it sets
+**input_number.rate_low_threshold** (_expert mode_) When 0 (default) this is automatic but can be overridden. When non zero it sets
the threshold below average rates as the minimum to consider for a charge window, 0.8 = 80% of average rate
If you set this too low you might not get enough charge slots. If it's too high you might get too many in the
24-hour period which makes optimisation harder.
-**rate_high_threshold** (_expert mode_) When 0 (default) this is automatic but can be overridden. When non zero it sets
+**input_number.rate_high_threshold** (_expert mode_) When 0 (default) this is automatic but can be overridden. When non zero it sets
the threshold above average rates as to the minimum export rate to consider exporting for - 1.2 = 20% above average rate
If you set this too high you might not get any export slots. If it's too low you might get too many in the 24-hour period.
-**metric_future_rate_offset_import** (_expert mode_) Sets an offset to apply to future import energy rates that are
+**input_number.metric_future_rate_offset_import** (_expert mode_) Sets an offset to apply to future import energy rates that are
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.
-**metric_future_rate_offset_export** (_expert mode_) Sets an offset to apply to future export energy rates that are
+**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.
@@ -263,32 +263,32 @@ in the charts template in Github).
## Inverter control options
-**set_status_notify** Enables mobile notification about changes to the Predbat state (e.g. Charge, Discharge etc). On by default.
+**switch.set_status_notify** Enables mobile notification about changes to the Predbat state (e.g. Charge, Discharge etc). On by default.
-**set_inverter_notify** Enables mobile notification about all changes to inverter registers (e.g. setting window, turning discharge on/off).
+**switch.set_inverter_notify** Enables mobile notification about all changes to inverter registers (e.g. setting window, turning discharge on/off).
Off by default.
**switch.predbat_set_charge_low_power** Enables low power charging mode where the max charge rate will be limited to the
lowest possible to meet the charge target. Only really effective for charge windows >30 minutes.
Off by default.
-**set_reserve_enable** (_expert_mode_) When enabled the reserve setting is used to hold the battery charge level
+**switch.set_reserve_enable** (_expert_mode_) When enabled the reserve setting is used to hold the battery charge level
once it has been reached or to protect against discharging beyond the set limit. Enabled by default.
-**set_charge_freeze** (_expert mode_) When enabled will allow Predbat to hold the current battery level while drawing
+**switch.set_charge_freeze** (_expert mode_) When enabled will allow Predbat to hold the current battery level while drawing
from the grid/solar as an alternative to charging. Enabled by default.
-**set_discharge_freeze_only** (_expert mode_) When enabled forced discharge is prevented, but discharge freeze can be used
+**switch.set_discharge_freeze_only** (_expert mode_) When enabled forced discharge is prevented, but discharge freeze can be used
(if enabled) to export excess solar rather than charging the battery. This is useful with tariffs that pay you for
solar exports but don't allow forced export (brown energy).
-If you have **inverter_hybrid** set to False then if **inverter_soc_reset** (_expert mode_) is set to True then the
+If you have **switch.inverter_hybrid** set to False then if **switch.inverter_soc_reset** (_expert mode_) is set to True then the
target SOC % will be reset to 100% outside a charge window. This may be required for AIO inverter to ensure it charges from solar.
-**set_reserve_min** Defines the reserve percentage to reset the reserve to when not in use, a value of 4 is the
+**input_number.set_reserve_min** Defines the reserve percentage to reset the reserve to when not in use, a value of 4 is the
minimum and recommended to make use of the full battery
-**inverter_soc_reset** (_expert mode_) When enabled the target SOC for the inverter(s) will be reset to 100%
+**switch.inverter_soc_reset** (_expert mode_) When enabled the target SOC for the inverter(s) will be reset to 100%
when a charge slot is not active, this can be used to workaround some firmware issues where the SOC target is
used for solar charging as well as grid charging. When disabled the SOC % will not be changed after a charge slot.
This is disabled by default.
@@ -311,7 +311,7 @@ Enable the **switch.predbat_balance_inverters_enable** switch in Home Assistant
## iBoost model options
-iBoost model, when enabled with **iboost_enable** tries to model excess solar energy being used to heat
+iBoost model, when enabled with **switch.iboost_enable** tries to model excess solar energy being used to heat
hot water (or similar). The predicted output from the iBoost model is returned in **iboost_best**.
The following entities are only available when you turn on iboost enable:
diff --git a/docs/install.md b/docs/install.md
index a5776474c..3fe6fa16b 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -239,18 +239,26 @@ As described above, the basic configuration of Predbat is held in the `apps.yaml
When Predbat first runs it will create a number of output and configuration control entities in Home Assistant which are used to fine-tune how Predbat operates.
The entities are all prefixed *predbat* and can be seen (and changed) from the Settings / Devices & Services / Entities list in Home Assistant.
+It is recommended that you create a dashboard page with all the required entities to control Predbat
+and another page to display Predbat's charging and discharging plan for your battery.
+
+The [Output Data](output-data.md) section describes these points in more detail.
+
The Home Assistant entity **predbat.status** contains details of what status Predbat is currently in (e.g. Idle, Charging, Error).
Detailed progress messages and error logging is written to the Predbat logfile which you can view within Home Assistant using a file editor.
-It is recommended that you create a dashboard page with all the required entities to control Predbat
-and another page to display Predbat's charging and discharging plan for your battery.
+The [Predbat Configuration Guide](configuration-guide.md) gives an overview of the main Predbat configuration items and
+detail of 'standard Predbat configuration' settings for different electricity tariff types - e.g. a cheap overnight rate,
+multiple import rates during the day, and variable tariffs such as Agile, etc.
-The [Output Data](output-data.md) section describes all these points in more detail.
+The detailed [Predbat Customisation Guide](customisation.md) details all the Predbat configuration items (switches, input numbers, etc) in Home Assistant, and what each of them does.
## Ready to light the touch-paper
By now you should have successfully installed and configured Predbat in AppDaemon and the other components it is dependent upon (e.g. GivTCP, Solcast, Octopus Integration).
-You have checked the logfile doesn't have any errors (there is a lot of output in the logfile, this is normal).
+
+You have checked the [Predbat AppDaemon log file](output-data.md#predbat-logfile) doesn't have any errors (there is a lot of output in the logfile, this is normal).
+
You have configured predbat's control entities, created a couple of dashboard pages to control and monitor Predbat, and are ready to start Predbat running.
In order to enable Predbat you must delete the 'template: True' line in `apps.yaml` once you are happy with your configuration.
diff --git a/docs/installation-summary.md b/docs/installation-summary.md
index 689cea695..3e08ac2bb 100644
--- a/docs/installation-summary.md
+++ b/docs/installation-summary.md
@@ -16,8 +16,9 @@ see the [video guides](video-guides.md) section for those and other videos
Create an automation to update Solcast a times a day, and check that you see the Solcast data in Home Assistant
6. Follow the [Energy Rates](energy-rates.md) instructions to tell Predbat what your import and export energy rates are.
If you use Octopus Energy then this includes installing the Octopus Energy integration (if you haven't already) - [Octopus Energy](energy-rates.md#octopus-energy-integration)
-7. Edit Predbat's `apps.yaml` configuration file (which will be in either the directory `/addon_configs/46f69597_appdaemon-predbat/apps`
-or `/config/appdaemon/apps/predbat/config/` depending on which Predbat install method you used) to match your system - [apps.yaml settings](apps-yaml.md)
+7. Edit Predbat's `apps.yaml` configuration file to to match your system - [apps.yaml settings](apps-yaml.md)
+The apps.yaml file will be in either the directory `/addon_configs/46f69597_appdaemon-predbat/apps`
+or `/config/appdaemon/apps/predbat/config/` depending on which Predbat install method you used.
- Inverter settings match the names in GivTCP - should be automatic (but if you have 2 names you will have to edit apps.yaml)
- You have set the right number of inverters (**num_inverters**)
- Adjust your **inverter_limit** and **export_limit** as required
@@ -25,15 +26,16 @@ or `/config/appdaemon/apps/predbat/config/` depending on which Predbat install m
- That the Solcast plugin is matching the configuration correctly - should be automatic
- If you have a car charging sensor you might want to add that also to help make predictions more accurate
8. Add the Predbat entities to your dashboard - [Output data](output-data.md)
-9. Follow the configuration guide to tune things for your system - [Configuration guide](configuration-guide.md)
-10. Set up the Predbat Plan card so you can check what Predbat is planning to do - [Create the Predbat Plan card](predbat-plan-card.md)
-11. Set up the Apex Charts for other views on what Predbat is doing - [Creating the charts](creating-charts.md)
-12. Then check Predbat is working correctly:
- - Look at the Predbat AppDaemon log file and make sure you have no errors or warnings that are unexpected
+9. Follow the [Configuration Guide](configuration-guide.md) to set 'standard' Predbat configuration settings depending on your import and export tariffs
+10. The detailed [Customisation Guide](customisation.md) lists all Predbat's controls and settings in Home Assistant that can be tuned for your system
+11. Set up the Predbat Plan card so you can check what Predbat is planning to do - [Create the Predbat Plan card](predbat-plan-card.md)
+12. Set up the Apex Charts for other views on what Predbat is doing - [Creating the charts](creating-charts.md)
+13. Then check Predbat is working correctly:
+ - Look at the [Predbat AppDaemon log file](output-data.md#predbat-logfile) and make sure you have no errors or warnings that are unexpected
- Comment out or delete the [template: True line in apps.yaml](apps-yaml.md#basics) when you are ready to start Predbat
- The **predbat.status** in Home Assistant should be 'Idle' (if there are any errors then they are reported here too)
- Start with **select.predbat_mode** set to 'Monitor' but remember to change it later to enable Predbat to control your inverter
-13. Look at the [FAQ](faq.md) for help
+14. Look at the [FAQ](faq.md) for help
Overview of the key configuration elements:
diff --git a/docs/output-data.md b/docs/output-data.md
index eba56bc4a..bb11f1dbc 100644
--- a/docs/output-data.md
+++ b/docs/output-data.md
@@ -124,11 +124,30 @@ 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)
-## Sample Predbat data out
+## Sample Predbat data out dashboard
-## Monitoring that Predbat and GivTCP are running OK
+## Predbat Logfile
+
+Predbat writes detailed logging, status and progress activity information to a logfile as it runs and so this file should be checked if **predbat.status** reports an error,
+or if you want to verify that Predbat is running OK.
+
+There is a lot of output in the logfile, this is normal!
+
+Depending upon whether you have used the [combined AppDaemon/Predbat add-on installation method](install.md#appdaemon-predbat-combined-install) or the
+[HACS, Appdaemon add-on then Predbat installation method](install.md#predbat-installation-into-appdaemon), the logfile will be held in one of two directories in Home Assistant:
+
+- `/addon_configs/46f69597_appdaemon-predbat/predbat.log` if you used the combined AppDaemon/Predbat add-on installation method
+
+or
+
+- `/homeassistant/appdaemon/appdaemon.log` if you used the HACS, AppDaemon add-on then Predbat installation method
+
+You will need to use a file editor within Home Assistant (e.g. either the File editor or Studio Code Server add-on's)
+to view Predbat's logfile - see [editing configuration files within Home Assistant](install.md#editing-configuration-files-in-home-assistant) if you need to install an editor.
+
+## Automated 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.
diff --git a/docs/what-does-predbat-do.md b/docs/what-does-predbat-do.md
index 948a0275f..87e92d47c 100644
--- a/docs/what-does-predbat-do.md
+++ b/docs/what-does-predbat-do.md
@@ -1,21 +1,22 @@
# What does Predbat do?
-Predbat runs every 5 minutes and will automatically update its prediction for the home battery levels for the next period,
-up to a maximum of 48 hours. It will automatically decide when to charge and discharge your battery to achieve the best cost
-metric within the parameters you have set. It uses the solar production forecast from Solcast combined with your historical
-energy use to make this prediction.
+Predbat is a home battery automation program.
+
+It automatically runs every 5 minutes and will update its prediction for the home battery levels for the next period, up to a maximum of 48 hours ahead.
+Predbat will automatically decide when to charge and discharge your battery to achieve the best (lowest) cost spend within the parameters you have set.
+It uses the solar production forecast from Solcast combined with your historical
+energy usage to make this prediction.
- The output is a prediction of the battery levels, charging slots, discharging slots, costs and import and export amounts.
-- Costs are based on energy pricing data, either manually configured (e.g. 7p from 11pm-4pm and 35p otherwise) or by using the Octopus Plugin
+- Costs are based on energy pricing data, either manually configured (e.g. 7p from 11pm-4pm and 35p otherwise) or by using the Octopus Energy integration
- Both import and export rates are supported.
- Intelligent Octopus is also supported and takes into account allocated charging slots.
-- The solar forecast used is the central scenario from Solcast (50%) with a weighting towards the more pessimistic (10%) scenario.
+- The solar forecast used is the central scenario from Solcast (50%) with a configurable weighting towards the more pessimistic (10%) scenario.
- The charging and discharging controls are automatically programmed into the inverter.
-- Automatic planning of export slots is also supported, when enabled Batpred can start a forced discharge of the battery if
-the export rates are high and you have spare capacity.
+- Automatic planning of export slots is also supported, when enabled Predbat can start a forced discharge of the battery if the export rates are high and you have spare capacity.
- Historical load data is used to predict your consumption, optionally car charging load can be filtered out of this data.
- Predbat can be configured to manage the charging of your EV and take into account its load on the house during these periods.
-- Multiple inverter support depends on running all inverters in lockstep.
+- Multiple inverter support is included but depends on all inverters running in lockstep.
## Terminology
@@ -28,36 +29,36 @@ the export rates are high and you have spare capacity.
- **Import** - Electricity drawn from the grid to be used in the home or to charge the battery
- **Export** - Electricity from your home from the battery or solar which is sent to the grid.
- **PV** - Solar power that is generated in your home
-- **Inverter** - The box that converts DC energy from solar or from your battery into AC power for your home and the grid. It also
-converts AC power from the grid into DC to charge a battery.
+- **Inverter** - The box that converts DC energy from solar or from your battery into AC power for your home and the grid.
+The inverter also converts AC power from the grid into DC to charge a battery.
- **Hybrid inverter** - An inverter that can charge a battery from solar directly using DC power as well as charging it from AC power from the grid.
-- **AC Coupled** - A battery that comes with it's own inverter and is always charge or discharged with AC (using an internal inverter)
+- **AC Coupled** - A battery that comes with it's own inverter and is always charged or discharged with AC (using an internal inverter)
- **Slot** - A period of time where Predbat performs an action e.g. charging. In Predbat everything is a multiple of 5 minutes.
- - Charge slots are always multiples of 30 minutes and align to a 30-minute boundary to match the way energy rates are allocated.
+ - Charge slots are always in multiples of 30 minutes and align to a 30-minute boundary to match the way energy rates are allocated.
- Discharge slots can be any multiple of 5 minutes and always finish on a 30-minute boundary.
### Predbat modes
-When you first install Predbat it will be in Monitor Only mode.
+When you first install Predbat it will be in 'Monitor' mode.
-Can you configure the mode of operation using the drop down menu in **select.predbat_mode**.
-You will find a full description of the modes under: [Predbat Monitor Mode](customisation.md#predbat-monitor-mode)
+You can configure Predbat's mode of operation using the drop down menu in **select.predbat_mode**.
+You will find a full description of [Predbat Modes](customisation.md#predbat-mode) in the Customisation Guide.
Once you are ready for Predbat to take control move this setting to one of the active control modes.
### Predbat status
-The current Predbat status is reported in **predbat.status**
+The current Predbat status is reported in the Home Assistant entity **predbat.status**:
- **Idle** - This is the default, the load will be covered by solar and/or battery. Excess solar will charge the battery or be
-exported if the battery is full. This will be described as ECO Mode for Givenergy inverters but other inverters use different terminology.
+exported if the battery is full. This is described as 'ECO' Mode for GivEnergy inverters but other inverters use different terminology.
-- **Charge** - The battery charges from the grid and the grid also covers any load. Solar power will also be used to charge the battery.
-- **Charge Freeze** - The current battery level is held and the grid/solar covers any load. Solar power will also be used to charge the battery.
-- **Hold Charge** - A type of charge where the target % is the same as the current %, effectively the same as a charge freeze (but without being explicitly selected)
-- **No Charge** - A charge where the target % is lower than the current battery level so there will be no charging unless the usage is unexpectedly high.
+- **Charging** - The battery charges from the grid and the grid also covers any load. Solar power will also be used to charge the battery.
+- **Freeze charging** - The current battery level is held and the grid/solar covers any load. Solar power will also be used to charge the battery.
+- **Hold charging** - A type of charge where the target SOC % is the same as the current SOC %, effectively the same as a charge freeze (but without being explicitly selected).
+- **No Charge** - A charge where the target SOC % is lower than the current battery SOC level so there will be no charging unless the usage is unexpectedly high.
-- **Discharge** - A force discharge slot where the battery is exported to the grid. The battery covers the load. Any solar generated will be exported.
-- **Discharge Freeze** - A slot where the battery covers the load but charging is disabled, thus any solar generated will be exported.
+- **Discharging** - The battery is being force-discharged. The house load will be covered by the battery and any excess is exported to the grid. Any solar generated will be exported.
+- **Freeze discharging** - The battery is covering the load but charging is disabled, thus any solar generated will be exported.
-- **Error** - There is a configuration error or other problem, you should check the AppDaemon log in home assistant for more details (Settings, System, Logs, AppDaemon)
+- **Error** - There is a configuration error or other problem, you should check the [Predbat AppDaemon log file](output-data.md#predbat-logfile) for more details.