Set up documentation site (#277)

* Add mkdocs to install list
* Add initial mkdocs config
* Add README symlink
* Add workflow to publish docs
* Break docs into separate pages
* Renaming, reordering, tidying up
* Run on releases
* Whitespace, spelling fixes

.github/workflows/main.yml

@@ -0,0 +1,19 @@
+name: build
+on:
+  push:
+    branches:
+      - documentation
+  release:
+    types: [published]
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs
+      - run: mkdocs gh-deploy --force --clean --verbose

docs/car-charge-planning.md

@@ -0,0 +1,20 @@
+# Car charging planning
+
+There are two ways to plan car charging slots:
+
+- If you have Intelligent Octopus import tariff and the Octopus Energy Plugin - in which case Predbat will use the slots allocated by the plugin in battery prediction
+    - Ensure **octopus_intelligent_slot** in `apps.yaml` points to the Intelligent Slot sensor in the Octopus Energy Plugin
+    - Set **octopus_intelligent_charging** to True
+    - Information about the car's battery size will also be extracted from the plugin
+    - You will need to set the cars current soc sensor, **car_charging_soc** correctly to have accurate results
+    - If you set **car_charging_limit** then Batpred can also know if the car's limit is set lower than in Intelligent Octopus
+    - Let the Octopus app control when your car charges
+- Predbat led charging - Here Predbat plans the charging based on the upcoming low rate slots
+    - Ensure **car_charging_limit**, **car_charging_soc** and **car_charging_planned** are set correctly
+    - Set **car_charging_plan_time** in the config or in HA to the time you want the car ready by
+    - Enable **car_charging_plan_smart** if you want to use the cheapest slots only
+    - Use an automation based on **binary_sensor.predbat_car_charging_slot** to control when your car charges
+
+NOTE: Multiple cars can be planned with Predbat.
+
+See [Car charging filtering](config-yml-settings.md#car-charging-filtering) and [Planned car charging](config-yml-settings.md#planned-car-charging) in the [config.yml settings](config-yml-settings.md) section of the documentation.

docs/configuration-guide.md

@@ -0,0 +1,100 @@
+# 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.
+
+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.
+
+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.
+
+The setting **input_number.metric_battery_cycle** can be used to put a cost on using your battery for charging and discharging. In theory if you think your battery will last say 6000 complete cycles and cost you £4000 and is 9.5kWh then each cycle is 19kWh and so the cost is £4000 / 19 / 6000 = 3.5p. If you configure this number higher then more expensive plans will be selected which avoid charging and discharging your battery as much. The default is 3p 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.
+
+A new experimental feature that tries to model cloud coverage by modulating the PV output can be enabled with **switch.predbat_metric_cloud_enable**. When enabled the difference between PV and PV10 is used to work out a cloud factor, this modulates the PV output predictions up and down accordingly as if there was passing clouds. This can have an impact on planning, especially for things like freeze charging which could assume the PV will cover the house load but it might not due to clouds.
+
+## Fixed daily rates
+
+- In this case you will just be predicting the battery levels, no charging or discharging is required although it won't hurt if you leave these options enabled.
+
+## Cheap night rate with bad export rate (e.g. Octopus Go, Economy 7 etc)
+
+- In this scenario you will want to charge overnight based on the next days solar forecast.
+
+Recommended settings - these must be changed in Home Assistant once Predbat is running:
+
+```yaml
+set_soc_enable - True              # Allow the tool to configure the charge %
+set_reserve_enable - True          # Use the reserve to stop fluctuations in the charge % when charging
+set_reserve_hold - True            # Means if you don't need to charge then charging won't be enabled
+calculate_best_charge - True       # You want the tool to calculate charging
+combine_charge_slots - True        # As you have just one overnight rate then one slot is fine
+metric_min_improvement - 0         # Charge less if it's cost neutral 
+set_charge_window - True           # You want to have Predbat control the charge window
+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
+best_soc_min - 0.0                 # You can also set this to best_soc_keep if you don't want charging to be turned off overnight when it's not required
+rate_low_threshold - 0.8           # Consider a 20% reduction in rates or more as a low rate
+forecast_plan_hours - 24           # In apps.yml set this to 24 hours to match the repeating rates
+calculate_discharge_first - False  # You probably only want to discharge any excess as export rates are poor
+```
+
+## Cheap night rate, with a good export rate (e.g. Intelligent Octopus with Octopus Outgoing)
+
+Follow the instructions from Cheap Night rate above, but also you will want to have automatic discharge when the export rates are profitable.
+
+```yaml
+calculate_best_discharge - True        # Enable discharge calculation
+calculate_discharge_first - True       # Give priority to discharge when it's profitable
+combine_charge_slots - True            # Keep one big charge slot
+combine_discharge_slots - False        # For fixed export rate you have to break up the discharge slots
+set_discharge_window - True            # Allow the tool to control the discharge slots
+metric_min_improvement - 0             # Charge less if it's cost neutral 
+metric_min_improvement_discharge - 0   # Discharge even if cost neutral, as you often need many slots to see the improvement
+rate_high_threshold: 0                 # Automatic high rate selection
+set_discharge_freeze - True            # Allow Predbat to hold the current battery level rather than just discharge
+set_charge_freeze - False              # Allow Predbat to hold the current battery level rather than just charge
+calculate_max_windows - 96             # Set to 96 for best results, but if you have host performance issues you can reduce this to 48 or 32
+predbat_metric_battery_cycle - ?       # You can set this to maybe 2-5p if you want to avoid cycling the battery too much
+```
+
+predbat_set_discharge_freeze_only - ?? # If you set Freeze only to True then excess solar will be exported, set to False if you want forced export as well
+
+## 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.
+
+Recommended settings - these must be changed in Home Assistant once Predbat is running:
+
+```yaml
+calculate_best_discharge - True        # Enable discharge calculation
+calculate_discharge_first - True       # Give priority to discharge when it's profitable
+combine_charge_slots - True            # Keep one big charge slot
+combine_discharge_slots - True         # As these rates have fixed longer periods then a single slot is fine
+set_discharge_window - True            # Allow the tool to control the discharge slots
+metric_min_improvement - 0             # Charge less if it's cost neutral 
+metric_min_improvement_discharge - 0.1 # Make sure discharge only happens if it makes a profit
+rate_low_threshold: 0.8                # Select rates 20 % below average only
+rate_high_threshold: 1.2               # Export rates 20 % above average only
+metric_battery_cycle - ?               # You can set this to maybe 2-5p if you want to avoid cycling the battery too much
+set_discharge_freeze - True            # Allow Predbat to hold the current battery level rather than just discharge
+set_charge_freeze - True               # Allow Predbat to hold the current battery level rather than just charge
+```
+
+## Half hourly variable rates (e.g. Octopus Agile)
+
+Recommended settings - these must be changed in Home Assistant once Predbat is running:
+
+```yaml
+calculate_best_discharge - True        # Enable discharge calculation
+calculate_discharge_first - True       # Give priority to discharge when it's profitable
+set_discharge_window - True            # Allow the tool to control the discharge slots
+combine_discharge_slots - False        # Split into 30 minute chunks for best optimisation
+metric_min_improvement - 0             # Charge less if it's cost neutral 
+metric_min_improvement_discharge - 0.1 # Make sure discharge only happens if it makes a profit
+rate_low_match_export - False          # Start with this at False but you can try it as True if you want to charge at higher rates to export even more
+rate_low_threshold: 0                  # Automatic rate selection (can also be tuned manually to find the rates you want)
+rate_high_threshold: 0                 # Automatic rate selection (can also be tuned manually to find the rates you want)
+calculate_max_windows - 32             # Normally 32 is enough, but you can try more or less to optimise runtime vs results
+set_discharge_freeze - True            # Allow Predbat to hold the current battery level rather than just discharge
+set_charge_freeze - True               # Allow Predbat to hold the current battery level rather than just charge
+forecast_plan_hours - 48               # In apps.yml set this to 48 hours to consider a full cycle plan
+```
+
+If you have a fixed export rate then follow the above guidance.

docs/creating-charts.md

@@ -0,0 +1,19 @@
+# Creating the charts
+
+To create the fancy charts:
+
+- Install Apex Charts [https://github.com/RomRider/apexcharts-card](https://github.com/RomRider/apexcharts-card)
+- There are multiple charts, for each section of the example file create a new apexcharts card and copy the YAML into it
+- Customise as you like
+
+Example charts:
+
+![image](https://github.com/springfall2008/batpred/assets/48591903/28f29756-2502-4079-9c75-398e8a1a0699)
+
+![image](https://github.com/springfall2008/batpred/assets/48591903/4c3df49c-52e5-443f-b9c5-7a673c96b205)
+
+![image](https://github.com/springfall2008/batpred/assets/48591903/5f1f504d-9251-4610-9403-2a5f4d0bf332)
+
+![image](https://github.com/springfall2008/batpred/assets/48591903/c02d65cf-e502-4484-a58d-cff8fb93d0f3)
+
+![image](https://github.com/springfall2008/batpred/assets/48591903/a96934d3-753a-49da-800b-925896f87cb6)