diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 000000000..e69de29bb diff --git a/404.html b/404.html new file mode 100644 index 000000000..646e73502 --- /dev/null +++ b/404.html @@ -0,0 +1,161 @@ + + + + + + + + Predbat Documentation + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • +
    • +
+
+
+
+
+ + +

404

+ +

Page not found

+ + +
+
+ +
+
+ +
+ +
+ +
+ + + + + +
+ + + + + + + + + diff --git a/apps-yaml/index.html b/apps-yaml/index.html new file mode 100644 index 000000000..b0027433c --- /dev/null +++ b/apps-yaml/index.html @@ -0,0 +1,1109 @@ + + + + + + + + apps.yaml settings - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • apps.yaml settings
    • +
  • +
    • +
+
+
+
+
+ +

apps.yaml settings

+

The basic Predbat configuration is defined in the apps.yaml file.

+

Depending on how you installed Predbat the apps.yaml file will be held in one of three different directories in Home Assistant:

+ +

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 edit the apps.yaml file - see editing configuration files within Home Assistant if you need to install an editor.

+

This section of the documentation describes what the different configuration items in apps.yaml do.

+

When you edit apps.yaml, the change will automatically be detected and Predbat will be reloaded with the updated file. +You don't need to restart the Predbat or AppDaemon add-on for your edits to take effect.

+

Warning! apps.yaml file format

+

When editing the apps.yaml file you must ensure that the file remains correctly formatted. YAML files are especially finicky about how the file contents are indented +and its very easy to end up with an incorrectly formatted file that will cause problems for Predbat.

+

The YAML Basics from This Smart Home is a good introduction video to how YAML should be correctly structured, but as a brief introduction, +YAML files consist of an entity name, colon then the entity value, for example:

+
timezone: Europe/London
+
+

Or the entity can be set to a list of values with each value being on a new line, two spaces, a dash, then the value. For example:

+
car_charging_now_response:
+  - 'yes'
+  - 'on'
+
+

The two spaces before the dash are especially critical. Its easy to mis-edit and have one or three spaces which isn't valid YAML.

+

NB: the sequence of entries in apps.yaml doesn't matter, as long as the YAML itself is structured correctly you can move things and edit things anywhere in the file.

+

Templates

+

You can find template configurations in the following location: https://github.com/springfall2008/batpred/tree/main/templates

+

The GivEnergy GivTCP template will be installed by default but if you are using another inverter please copy the correct template into the directory +where your apps.yaml is stored, replacing the existing apps.yaml file, and modify it from there.

+

Please read Inverter Setup for inverter control software and details of setting apps.yaml for non-GivEnergy inverters

+

Checking your apps.yaml

+

Syntax errors will be highlighted by the Home Assistant editor or via other YAML aware editors such as VSCode.

+

Once you have completed your apps.yaml and started Predbat you may want to open the Predbat Web Interface and click on 'apps.yaml'. Review any items shown +in a red background as those do not match (its okay for a 2nd inverter not to match if you only have one configured). Regular expressions that do not +match can be ignored if you are not supporting that feature (e.g. Car SOC if you don't have a car).

+

As an example these do not match and are shown in the web interface in red, I'm ignoring them as I only have one inverter and I'm using +the Predbat internal Solcast rather than the external integration:

+

image

+

Basics

+

Basic configuration items

+

prefix

+

Set to the prefix name to be used for all entities that Predbat creates in Home Assistant. Default 'predbat'. Unlikely that you will need to change this.

+
prefix: predbat
+
+

timezone

+

Set to your local timezone, default is Europe/London. It must be set to a +valid Python time zone for your location

+
timezone: Europe/London
+
+

currency_symbols

+

Sets your symbol to use for your main currency e.g. £ or $ and for 1/100th unit e.g. p or c

+
currency_symbols:
+  - '£'
+  - 'p'
+
+

template

+

Initially set to True, this is used to stop Predbat from operating until you have finished configuring your apps.yaml. +Once you have made all other required changes to apps.yaml this line should be deleted or commented out:

+
template: True
+
+

Home assistant connection

+

Predbat can speak directly to Home Assistant rather than going via AppDaemon.

+

If you are using a standard add-on then this will be automatic and you do not need to set this.

+

If you run AppDaemon/Predbat in a Docker then you will need to set the URL or IP address of Home Assistant and the access key which is the long +lived access token you can create inside Home Assistant.

+

Currently if this communication is not established Predbat will fallback to AppDaemon, however some users have experienced failures due to a 10-second timeout set by AppDaemon.

+

In future versions of Predbat, AppDaemon will be removed.

+
ha_url: 'http://homeassistant.local:8123'
+ha_key: 'xxxxxxxxxxx'
+
+

image

+

TIP: You can replace homeassistant.local with the IP address of your Home Assistant server if you have it set to a fixed IP address. +This will remove the need for a DNS lookup of the IP address every time Predbat talks to Home Assistant and may improve reliability as a result.

+

threads

+

If defined sets the number of threads to use during plan calculation, the default is 'auto' which will use the same number of threads as you have CPUs in your system.

+

Valid values are:

+
    +
  • 'auto' - Use the same number of threads as your CPU count
    • +
  • '0' - Don't use threads - disabled
    • +
  • 'N' - Use N threads, recommended values are between 2 and 8
    • +
+
threads: auto
+
+

notify_devices

+

A list of device names to notify when Predbat sends a notification. The default is just 'notify' which contacts all mobile devices

+
notify_devices:
+  - mobile_app_treforsiphone12_2
+
+

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, if you just want Predbat to assume the house load on a particular day is the same as the same day of last week:

+
days_previous:
+  - 7
+
+

Or if you want Predbat to take the average of the same day for the last two weeks:

+
days_previous:
+  - 7
+  - 14
+
+

Further details and worked examples of 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:

+
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:

+
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:

+
days_previous_weight:
+  - 1
+
+

forecast_hours

+

the number of hours that Predbat will forecast ahead, 48 is the suggested amount, although other values can be used +such as 30 or 36 if you have a small battery and thus don't need to forecast 2 days ahead.

+
forecast_hours: 48
+
+

Inverter information

+

The template apps.yaml comes pre-configured with regular expressions that should auto-discover the GivTCP Home Assistant entity names. +If you have more than one inverter or entity names are non-standard then you will need to edit apps.yaml for your inverter entities

+

num_inverters

+

The number of inverters you have. If you increase this above 1 you must provide multiple of each of the inverter entities

+
num_inverters: 1
+
+

geserial

+

Only for GE inverters, this is a helper regular expression to find your inverter serial number, if it doesn't work edit it manually or change individual entities to match. +If you have more than one inverter you will need one per inverter to be used in the later configuration lines

+
geserial: 're:sensor.givtcp_(.+)_soc_kwh'
+geserial2: 're:sensor.givtcp2_(.+)_soc_kwh'
+
+

If you are running GivTCP v3 and have an AIO or a 3 phase inverter then the helper regular expression will not correctly work +and you will need to manually set geserial in apps.yaml to your inverter serial number, e.g.:

+
geserial: 'chNNNNgZZZ'
+
+

TIP: If you have a single GivEnergy AIO, all control is directly to the AIO and the gateway is not required.
+Check the GivTCP configuration to determine whether inverter 1 (the givtcp sensors) is the AIO or the gateway, or inverter 2 (the givtcp2 sensors) is the AIO or gateway.
+Then in apps.yaml comment out the lines corresponding to the gateway, leaving just the givtcp or givtcp2 lines for the AIO. +Also delete the appropriate givtcp_rest inverter control line corresponding to the gateway so that Predbat controls the AIO directly.

+

TIP2: If you have multiple GivEnergy AIO's, all the AIO's are controlled by the AIO gateway and not controlled individually.
+geserial should be manually configured to be your AIO gateway serial number 'gwNNNNgZZZ' and all the geserial2 lines should be commented out in apps.yaml. +You should also delete the second givtcp_rest inverter control line so that Predbat controls the AIO's via the gateway.

+

GivTCP version 3 is required for multiple AIO's or a 3 phase inverter.

+

Historical data

+

Predbat can either get historical data (house load, import, export and PV generation) directly from GivTCP or it can obtain it from the GivEnergy cloud. +Unless you have a specific reason to not use the GivTCP data (e.g. you've lost your GivTCP data), its recommended to use GivTCP.

+

Data from Home Assistant

+

The following configuration entries in apps.yaml are pre-configured to automatically use the appropriate sensors.

+

If you have a 3-phase electricity supply and one inverter (and battery) on each phase then you will need to add one line for the load, import, export and PV sensors +for each of the 3 phases.

+

If you have a single phase electricity supply and multiple inverters on the phase then you will need to add one line for each of the load and PV sensors. +You don't need multiple lines for the import or export sensors as each inverter will give the total import or export information.

+

Edit if necessary if you have non-standard sensor names:

+
    +
  • load_today - Entity name for the house load in kWh today (must be incrementing)
    • +
  • import_today - Imported energy today in kWh (incrementing)
    • +
  • export_today - Exported energy today in kWh (incrementing)
    • +
  • pv_today - PV energy today in kWh (incrementing). If you have multiple inverters, enter each inverter PV sensor on a separate line.
    +If you have an AC-coupled inverter then enter the Home Assistant sensor for your PV inverter.
    +If you don't have any PV panels, comment or delete this line out of apps.yaml.
    • +
+

See the Workarounds section below for configuration settings for scaling these if required.

+

If you have multiple inverters then you may find that the load_today figures are incorrect as the inverters share the house load between them. +In this circumstance one solution is to create a Home Assistant template helper to calculate house load from {pv generation}+{battery discharge}-{battery charge}+{import}-{export}.

+

e.g.

+
{{ ( states('sensor.givtcp_XXX_pv_energy_today_kwh')|float(0) + <inverter 2>...
+  + states('sensor.givtcp_XXX_battery_discharge_energy_today_kwh')|float(0) + <inverter 2>...
+  - states('sensor.givtcp_XXX_battery_charge_energy_today_kwh')|float(0) - <inverter 2>...
+  + states('sensor.givtcp_XXX_import_energy_today_kwh')|float(0)
+  - states('sensor.givtcp_XXX_export_energy_today_kwh')|float(0) ) | round(1) }}
+
+

GivEnergy Cloud Data

+

If you have an issue with the GivTCP data, Predbat can get the required historical data from the GivEnergy cloud instead. This data is updated every 30 minutes. +Obviously connecting to the cloud is less efficient and means that Predbat will be dependent upon your internet connection and the GivEnergy cloud to operate.

+
    +
  • ge_cloud_data - When True Predbat will use the GE Cloud integration +for inverter data rather than GivTCP sensors for load_today, import_today and export_today
    • +
  • ge_cloud_serial - Set the inverter serial number to use for the cloud data
    • +
  • ge_cloud_key - Set to your API Key for the GE Cloud (long string)
    • +
+

Load filtering

+

By default if Predbat sees a gap in the historical load data it will fill it with average data. This is to help in the cases of small amounts of lost data. +For entire lost days you should change days_previous to point to different days(s) or include 3 or more days and if you set switch.predbat_load_filter_modal to true, +the lowest day's historical load will be discarded.

+
    +
  • load_filter_threshold - Sets the number of minutes of zero load data to be considered a gap (that's filled with average data), the default is 30. +To disable, set it to 1440.
    • +
+

iBoost energy

+
    +
  • iboost_energy_today - Set to a sensor which tracks the amount of energy sent to your solar diverter, can also be used to subtract from your historical load +for more accurate predictions.
    • +
+

Inverter control configurations

+
    +
  • inverter_limit - One per inverter. When set defines the maximum AC output power in watts for your inverter or micro-inverters (e.g. 3600). +This is used by Predbat in calculating the plan to emulate clipping that occurs in the inverter when your solar produces more than the inverter can handle, +but it won't be that accurate as the source of the data isn't minute by minute. +If you have a separate Solar inverter as well then add the solar inverter limit to the battery inverter limit to give one total amount.
    +For example, if you have a GivEnergy hybrid inverter you should set export_limit to 3600 or 5000 depending on which size inverter you have. +If though you have a GivEnergy All-in-one (6kW AC limit) and a 5kW Solis solar inverter, you should set inverter_limit to 11000 (6000+5000). +For multiple All-in-one's, add each of their limits together, plus any separate solar inverter limits.
    • +
+

NB: inverter_limit is ONLY used by Predbat to improve the quality of the plan, any solar clipping is done by the inverter and is not controlled by Predbat.

+
    +
  • export_limit - One per inverter (optional). When set defines the maximum watts of AC power your inverter can export to the grid at (e.g. 2500). +This is used by Predbat in calculating the plan to emulate your inverter's software export limit setting that you will have if your G98/G99 +approval was lower than your maximum inverter power (check your install information for details). +If you do not set an export limit then it's the same as the inverter limit.
    • +
+

NB: export_limit is ONLY used by Predbat to improve the quality of the plan, any export limit is done by the inverter and is not controlled by Predbat.

+
    +
  • inverter_limit_charge and inverter_limit_discharge - One per inverter (optional). When set in Watts, overrides the maximum +charge/discharge rate settings used when controlling the inverter. +This can be used if you need Predbat to cap your inverter battery rate (e.g. charge overnight at a slower rate to reduce inverter/battery heating) as Predbat +will normally configure all timed charges or discharges to be at the inverter's maximum rate.
    • +
+

Controlling the Inverter

+

There are a few different ways to control your inverter:

+
    +
  • Home Assistant entity controls (standard)
    • +
  • GivTCP REST Interface (GivEnergy Inverters only)
    • +
  • Service API
    • +
  • MQTT API
    • +
+

Home Assistant entity inverter control

+

Predbat can control inverters by updating Home Assistant entities.

+

The template apps.yaml for is pre-configured with regular expressions for many configuration items, but some of them may need updating to match your system.

+

If you only have a single inverter then the second inverter lines can be commented out if so desired or left in place (as they are ignored).

+

The givtcp_rest line should be commented out/deleted on anything but GivTCP REST mode.

+
    +
  • charge_rate - Battery charge rate entity in watts
    • +
  • discharge_rate - Battery discharge max rate entity in watts
    • +
  • battery_power - Current battery power in watts
    • +
  • battery_voltage - Current battery voltage (only needed for inverters controlled via amps)
    • +
  • battery_rate_max - Sets the maximum battery charge/discharge rate in watts (e.g. 2500)
    • +
  • pv_power - Current PV power in watts
    • +
  • load_power - Current load power in watts
    • +
  • soc_kw - Entity name of the battery SOC in kWh, should be the inverter one not an individual battery
    • +
  • soc_max - Entity name for the maximum charge level for the battery
    • +
  • battery_min_soc - When set limits the target SOC% setting for charge and discharge to a minimum percentage value
    • +
  • reserve - sensor name for the reserve setting in %
    • +
  • inverter_reserve_max - When set defines the maximum reserve setting in % (default is 100)
    • +
  • inverter_mode - Givenergy inverter mode control
    • +
  • inverter_time - Inverter timestamp, used to track the last update of the inverter data
    • +
  • charge_start_time - Battery charge start time entity
    • +
  • charge_end_time - Battery charge end time entity
    • +
  • charge_limit - Entity name for used to set the SOC target for the battery in percentage (AC charge target)
    • +
  • scheduled_charge_enable - Scheduled charge enable config
    • +
  • scheduled_discharge_enable - Scheduled discharge enable config
    • +
  • discharge_start_time - scheduled discharge slot_1 start time
    • +
  • discharge_end_time - scheduled discharge slot_1 end time
    • +
  • pause_mode - Givenergy pause mode register (if present)
    • +
  • pause_start_time - scheduled pause start time (only if supported by your inverter)
    • +
  • pause_end_time - scheduled pause start time (only if supported by your inverter)
    • +
  • inverter_battery_rate_min - Defines the minimum discharge/charge rate of the battery in watts (default is 0)
    • +
+

If you are using REST control the configuration items should still be kept as not all controls work with REST.

+

See section below on creating the battery charge power curve.

+

REST Interface inverter control

+

For GivEnergy inverters Predbat can control the inverter directly via REST instead of via the Home Assistant GivTCP inverter controls detailed above.

+

When configured in apps.yaml, control communication from Predbat to GivTCP is via REST which bypasses some issues with MQTT.

+
    +
  • givtcp_rest - One entry per Inverter, sets the GivTCP REST API URL (http://homeassistant.local:6345 +is the normal address and port for the first inverter, and the same address but ending :6346 if you have a second inverter - if you don't have a second inverter +(or if you have multiple AIO's that are controlled through the gateway), delete the second line.
    +If you are using Docker then change 'homeassistant.local' to the Docker IP address.
    • +
+

TIP: You can replace homeassistant.local with the IP address of your Home Assistant server if you have it set to a fixed IP address. +This may improve reliability of the REST connection as it doesn't need to lookup the HA server IP address each time.

+

To check your REST is working open up the readData API point in a Web browser e.g: http://homeassistant.local:6345/readData

+

If you get a bunch of inverter information back then it's working!

+

Note that Predbat will still retrieve inverter information via REST, this configuration only applies to how Predbat controls the inverter.

+

Service API

+

Some inverters have the Service API enabled, this allows the configuration to call an arbitrary Home Assistant service to start/stop charging and discharging

+
    +
  • charge_start_service - Should be set to a service that is called when charging starts
    • +
  • charge_freeze_service - If your inverter supports charge freeze set to a service that starts this mode
    • +
  • +

    charge_stop_service - Should be set to a service that is called when charging/charge freeze stops

    +
    • +
  • +

    discharge_start_service - Should be set to a service that is called when force export (discharge) starts

    +
    • +
  • discharge_freeze_service - If your inverter supports export freeze set to a service that starts this mode
    • +
  • discharge_stop_service - Should be set to a service that is called when export/export freeze stops
    • +
+

Services that are not configuration will not be called.

+

Example service is below:

+
  charge_start_service:
+    service: switch.turn_off
+    entity_id: "switch.sunsynk_inverter_use_timer"
+
+

See Service API for details.

+

Note that device_id will be passed to the service automatically, it can be set in apps.yaml.

+

MQTT API

+

Some Inverters are enabled with an MQTT API, in this case certain MQTT messages are send via the HA MQTT service.

+

The mqtt_topic in apps.yaml set in the root of the MQTT topic (shown as topic below).

+

Set reserve

+

Called when the reserve is changed

+

topic: topic/set/reserve +payload: reserve

+

Set target soc

+

Called when the target (charge %) SOC is set.

+

topic: topic/set/target_soc +payload: soc

+

Set charge rate

+

Called to change the charge rate in Watts

+

topic: topic/set/charge_rate +payload: charge_rate

+

Set discharge rate

+

Called to change the discharge rate in Watts

+

topic: topic/set/discharge_rate +payload: discharge_rate

+

Set charge

+

Called when a charge is started

+

topic: topic/set/charge +payload: charge_rate

+

Set discharge

+

Called when a forced export (discharge) is started

+

topic: topic/set/discharge +payload: discharge_rate

+

Set auto

+

Called when a charge/discharge is cancelled and the inverter goes back to home demand mode.

+

topic: topic/set/auto +payload: true

+

Solcast Solar Forecast

+

As described in the Predbat installation instructions, Predbat needs a solar forecast +in order to predict solar generation and battery charging which can be provided by the Solcast integration.

+

By default the template apps.yaml is pre-configured to use the Solcast forecast integration for Home Assistant. +The apps.yaml contains regular expressions for the following configuration items that should auto-discover the Solcast forecast entity names. +They are unlikely to need changing although a few people have reported their entity names don't contain 'solcast' so worth checking, or edit if you have non-standard names:

+
    +
  • pv_forecast_today - Entity name for today's Solcast forecast
    • +
  • pv_forecast_tomorrow - Entity name for tomorrow's Solcast's forecast
    • +
  • pv_forecast_d3 - Entity name for Solcast's forecast for day 3
    • +
  • pv_forecast_d4 - Entity name for Solcast's forecast for day 4 (also d5, d6 & d7 are supported, but not that useful)
    • +
+

If you do not have a PV array then comment out or delete these Solcast lines from apps.yaml.

+

Alternatively, Predbat can obtain the solar forecast directly from Solcast and the Solcast integration is thus not required. +Uncomment the following Solcast cloud interface settings in apps.yaml and set the API key correctly:

+
solcast_host: 'https://api.solcast.com.au/'
+solcast_api_key: 'xxxx'
+solcast_poll_hours: 8
+
+

Note that by default the solcast API will be used to download all sites (up to 2 for hobby accounts), if you want to override this set your sites manually using +solcast_sites as an array of site IDs:

+
solcast_sites:
+   - 'xxxx'
+
+

If you have more than 2 array orientations and thus more than one Solcast API key, enter each key in a list, i.e.:

+
api_key:
+  - xxxx_API_key_1
+  - yyyy_API_key_2
+
+

Keep in mind hobbyist accounts only have 10 polls per day so you need to ensure that the solcast_poll_hours refresh period is set so that you do not exceed the 10 poll limit. +If you have two arrays then each Solcast refresh will consume 2 polls. +If you use the same Solcast account for other automations the total polls needs to be kept under the limit or you will experience failures.

+

If you have multiple PV arrays connected to hybrid inverters or you have AC-coupled inverters, then ensure your PV configuration in Solcast covers all arrays.

+

If however you have a mixed PV array setup with some PV that does not feed into the inverters that Predbat is managing +(e.g. hybrid GE inverters with an older firmware but a separate older FIT array that directly feeds AC into the house), +then it's recommended that Solcast is only configured for the PV connected to the inverters that Predbat is managing.
+NB: Gen2, Gen3 and Gen1 hybrid inverters with the 'fast performance' firmware are able to charge their batteries from excess AC that would be exported, +so for these inverters you should configure Solcast with your total solar generation capability.

+

Solcast produces 3 forecasted PV estimates, the 'central' (50% or most likely to occur) PV forecast, the '10%' (1 in 10 more cloud coverage 'worst case') PV forecast, +and the '90%' (1 in 10 less cloud coverage 'best case') PV forecast.
+By default Predbat will use the central (PV50) estimate and applies to it the input_number.predbat_pv_metric10_weight weighting of the 10% (worst case) estimate. +You can thus adjust the metric10_weight to be more pessimistic about the solar forecast.

+

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 over the 30 minute slot 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.
    • +
+

If pv_estimate is set to 10 then input_number.predbat_pv_metric10_weight in Home Assistant should be set to 1.0.

+

See also PV configuration options in Home Assistant.

+

Energy Rates

+

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 and are listed here just for completeness:

+
    +
  • metric_octopus_import - Import rates from the Octopus Energy integration
    • +
  • metric_octopus_export - Export rates from the Octopus Energy integration
    • +
  • metric_octopus_gas - Gas rates from the Octopus Energy integration
    • +
  • octopus_intelligent_slot - Octopus Intelligent GO slot sensor from the Octopus Energy integration
    • +
  • octopus_saving_session - Energy saving sessions sensor from the Octopus Energy integration
    • +
  • octopus_saving_session_octopoints_per_penny - Sets the Octopoints per pence
    • +
  • rates_import_octopus_url - Octopus pricing URL (over-rides metric_octopus_import)
    • +
  • rates_export_octopus_url - Octopus export pricing URL (over-rides metric_octopus_export)
    • +
  • metric_standing_charge - Standing charge in pounds
    • +
  • rates_import - Import rates over a 24-hour period with start and end times
    • +
  • rates_export - Export rates over a 24-hour period with start and end times
    • +
  • rates_gas - Gas rates over a 24-hour period with start and end times
    • +
  • rates_import_override - Over-ride import rate for specific date and time range, e.g. Octopus Power-up events
    • +
  • rates_export_override - Over-ride export rate for specific date and time range
    • +
  • futurerate_url - URL of future energy market prices for Agile users
    • +
  • futurerate_adjust_import and futurerate_adjust_export - Whether tomorrow's predicted import or export prices should be adjusted based on market prices or not
    • +
  • futurerate_peak_start and futurerate_peak_end - start/end times for peak-rate adjustment
    • +
  • carbon_intensity - Carbon intensity of the grid in half hour slots from an integration.
    • +
+

Car Charging Integration

+

Predbat is able to include electric vehicle charging in its plan and manage the battery activity so that the battery isn't discharged into your car when the car is charging +(although you can over-ride this if you wish by setting the switch.predbat_car_charging_from_battery to True in Home Assistant).

+

There are two different ways of planning car charging into cheap slots with Predbat, either by the Octopus Energy integration or by Predbat identifying the cheapest slots. +These approaches and the set of settings that need to be configured together are described in Car Charging.

+

The full list of car charging configuration items in apps.yaml that are used to plan car charging activity within Predbat are described below. +The Home Assistant controls (switches, input numbers, selectors, etc) related to car charging are described in Car Charging configuration within Home Assistant, +with brief mention of pertinent controls included here alongside the apps.yaml configuration items where relevant for context.

+
    +
  • +

    num_cars should be set in apps.yaml to the number of cars you want Predbat to plan for. +Set to 0 if you don't have an EV (and the remaining car sensors in apps.yaml can safely be commented out or deleted as they won't be required).
    +NB: num_cars must be set correctly regardless of whether you are using Octopus Intelligent Go to control your EV charging or Predbat to control the charging; +or else Predbat could start discharging your battery when the EV is charging.

    +
    • +
  • +

    car_charging_exclusive should be set to True for each car in apps.yaml if you have multiple cars configured in Predbat, but only one car charger. +This indicates that only one car may charge at once (the first car reporting as plugged in will be considered as charging). +If you set this to False for each car then it is assumed that the car can charge independently, and hence two or more cars could charge at once. +One entry per car.

    +
    • +
+
car_charging_exclusive:
+  - True
+  - True
+
+

Car Charging Filtering

+

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.predbat_car_charging_hold - A Home Assistant switch that when turned on (True) tells Predbat to remove car charging data from your historical house load +so that Predbat's battery prediction plan is not distorted by previous car charging.

    +
    • +
  • +

    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 that should auto-detect the appropriate Wallbox and Zappi car charger sensors, +or edit as necessary in apps.yaml for your charger sensor.
    +This can be set to a list of car charging energy sensors, one per line if you have multiple EV car chargers.
    +TIP: 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.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 sensor data by if required (e.g. set to 0.001 to convert Watts to kW).

    +
    • +
+

If you do not have a suitable car charging energy 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.predbat_car_charging_threshold (default 6 = 6kW)- Sets the kW power threshold above which home consumption is assumed to be car charging +and input_number.predbat_car_charging_rate will be subtracted from the historical load data.
    • +
+

Planned Car Charging

+

These features allow Predbat to know when you plan to charge your car.

+

If you have Intelligent Octopus tariff then planning of charging is done via the Octopus app and Predbat obtains this information through the Octopus Energy integration in Home Assistant.

+
    +
  • switch.predbat_octopus_intelligent_charging - When this Home Assistant switch is enabled, Predbat will plan charging around the Intelligent Octopus slots, taking +it into account for battery load and generating the slot information
    • +
+

The following apps.yaml configuration items are pre-defined with regular expressions to point to appropriate sensors in the Octopus Energy integration. +You should not normally need to change these if you have the Octopus Intelligent tariff:

+
    +
  • +

    octopus_intelligent_slot - Points to the Octopus Energy integration 'intelligent dispatching' sensor that indicates +whether you are within an Octopus Energy "smart charge" slot, and provides the list of future planned charging activity.

    +
    • +
  • +

    octopus_ready_time - Points to the Octopus Energy integration sensor that details when the car charging will be completed by.

    +
    • +
  • +

    octopus_charge_limit - Points to the Octopus Energy integration sensor that provides the car charging limit.

    +
    • +
  • +

    octopus_slot_low_rate - Default is True, meaning any Octopus Intelligent Slot reported will be at the lowest rate if at home. If False the existing rates only will be used +which is only suitable for tariff's other than IOG.

    +
    • +
+

If you don't use Intelligent Octopus then the above 3 Octopus Intelligent configuration lines in apps.yaml can be commented out or deleted, +and there are a number of other apps.yaml configuration items that should be set:

+
    +
  • +

    car_charging_planned - Optional, can be set to a Home Assistant sensor (e.g. from your car charger integration) +which lets Predbat know the car is plugged in and planned to charge during low rate slots. +Or manually set it to 'False' to disable this feature, or 'True' to always enable.
    +The apps.yaml template supplied with Predbat comes pre-configured with a regular expression that should automatically match Zappi or Wallbox car chargers. +If you have a different type of charger you will need to configure it manually.

    +
    • +
  • +

    car_charging_planned_response - An array of values for the above car_charging_planned sensor which indicate that the car is plugged in and will charge in the next low rate slot. +The template apps.yaml comes with a set of pre-defined sensor values that should match most EV chargers. +Customise for your car charger sensor if it sets sensor values that are not in the list.

    +
    • +
  • +

    car_charging_now - For some cases finding details of planned car charging is difficult to obtain.
    +The car_charging_now configuration item can be set to point to a Home Assistant sensor that tells you that the car is currently charging. +Predbat will then assume this 30 minute slot is used for charging regardless of the plan.
    +If Octopus Intelligent Charging is enabled and car_charging_now indicates the car is charging then Predbat will also assume that this is a +low rate slot for the car/house (and might therefore start charging the battery), otherwise electricity import rates are taken from the normal rate data.

    +
    • +
+

CAUTION: Do not use car_charging_now with Predbat led charging or you will create an infinite loop. Do you use car_charging_now with Octopus intelligent +unless you can't make it work any other way as it will assume all car charging is at low rate.

+
    +
  • car_charging_now_response - Set to the range of positive responses for car_charging_now to indicate that the car is charging. +Useful if you have a sensor for your car charger that isn't binary.
    • +
+

To make planned car charging more accurate, configure the following items in apps.yaml:

+
    +
  • +

    car_charging_battery_size - Set this value in apps.yaml to the car's battery size in kWh. If not set, Predbat defaults to 100kWh. +It will be used to predict when to stop car charging.

    +
    • +
  • +

    car_charging_limit - You should configure this to point to a sensor that specifies the % limit the car is set to charge to. +This could be a sensor on the EV charger integration or a Home Assistant helper entity you can set as you wish. +If you don't specify a sensor Predbat will default to 100% - i.e. fill the car to full.

    +
    • +
  • +

    car_charging_soc - You should configure this to point to a sensor (on the HA integration for your EV charger) that specifies the car's current charge level +expressed as a percentage - it must NOT be set to a sensor that gives the car's current kWh value as this will cause Predbat to charge the car to an incorrect level. +If you don't specify a sensor, Predbat will default to 0%.

    +
    • +
+

Multiple Electric Cars

+

Multiple cars can be planned with Predbat, in which case you should set num_cars in apps.yaml to the number of cars you want to plan

+
    +
  • +

    car_charging_limit, car_charging_planned, car_charging_battery_size and car_charging_soc must then be a list of values (i.e. 2 entries for 2 cars)

    +
    • +
  • +

    If you have Intelligent Octopus then Car 0 will be managed by the Octopus Energy integration, if its enabled

    +
    • +
  • +

    Each car will have it's own Home Assistant slot sensor created e.g. binary_sensor.predbat_car_charging_slot_1, +SoC planning sensor e.g predbat.car_soc_1 and predbat.car_soc_best_1 for car 1

    +
    • +
+

Load Forecast

+

In addition to the historical house load data that Predbat uses by default, you can optionally provide a forecast of future load +such as is produced by Predheat for Hot water and Heat Pump heating systems or via Predai

+
    +
  • load_forecast - this should be configured to point to a sensor and attribute. The attribute must in either
      +
    • The format of 'last_updated' timestamp and 'energy' in incrementing kWh.
      • +
    • The format of a dictionary of timestamps and energy data in incremental KWh.
      • +
    +
    • +
+

For example:
+IMAGE

+

Or

+

image

+

apps.yaml should be configured to point to the forecast sensor and attribute (in the above formats) like this:

+
load_forecast:
+  - sensor_name$attribute_name
+
+

So if using Predheat it would be configured as:

+
load_forecast:
+  - predheat.heat_energy$external
+
+

Set load_forecast_only to True if you do not wish to use the Predbat forecast but instead want to use this as your only forecast data e.g using PredAi:

+
load_forecast_only: True
+load_forecast:
+   - sensor.givtcp_{geserial}_load_energy_today_kwh_prediction$results
+
+

Balance Inverters

+

When you have two or more inverters it's possible they get out of sync so they are at different charge levels or they start to cross-charge (one discharges into another). +When enabled, balance inverters tries to recover this situation by disabling either charging or discharging from one of the batteries until they re-align.

+

Most of the Predbat configuration for balancing inverters is through a number of Home Assistant controls for Balancing Inverters, +but there is one configuration item in apps.yaml:

+
balance_inverters_seconds: seconds
+
+

Defines how often to run the inverter balancing, 30 seconds is recommended if your machine is fast enough, but the default is 60 seconds.

+

Workarounds

+

There are a number of different configuration items in apps.yaml that can be used to tweak the way Predbat operates and workaround +weirdness you may have from your inverter and battery setup.

+

Clock skew

+
clock_skew: minutes
+
+

Skews the local (computer) time that Predbat uses (from the computer that Predbat is running on).
+Set to 1 means add a minute to the Predbat computer time, set to -1 means take a minute off the Predbat computer time. +This clock adjustment will be used by Predbat when real-time actions happen e.g. triggering a charge or discharge.

+

If your inverter's time is different to the time on the computer running Home Assistant, you may need to skew the time settings made on the inverter when you trigger charging or discharging. +Again 1 means the inverter is 1 minute fast and -1 means the inverter is 1 minute slow.

+

Separate start and end options are applied to the start and end time windows, mostly as you want to start battery activity late (not early) and finish early (not late).

+

You can adjust the charge and discharge times written to the inverter by setting the following in apps.yaml:

+
inverter_clock_skew_start: minutes
+inverter_clock_skew_end: minutes
+
+

Skews the setting of the charge slot registers vs the predicted start time

+
inverter_clock_skew_discharge_start: minutes
+inverter_clock_skew_discharge_end: minutes
+
+

Skews the setting of the discharge slot registers vs the predicted start time

+

Battery size scaling

+
battery_scaling:
+  - scale
+
+

Default value 1.0. Multiple battery size scales can be entered, one per inverter on separate lines.

+

This setting is used to scale the battery reported SoC kWh to make it appear bigger or larger than it is. +As the GivEnergy inverters treat all batteries attached to an inverter as in effect one giant battery, +if you have multiple batteries on an inverter that need scaling you should enter a composite scaling value for all batteries attached to the inverter.

+

TIP: If you have a GivEnergy 2.6 or 5.2kWh battery then it will have an 80% depth of discharge but it will falsely report its capacity as being the 100% size, +so set battery_scaling to 0.8 to report the correct usable capacity figure to Predbat.

+

TIP: Likewise, if you have one or multiple GivEnergy All in One (AIO)'s, +it will incorrectly report the 13.5kWh usable capacity of each AIO as 15.9kWh, so set battery_scaling to 0.85 to correct this.

+

If you are going chart your battery SoC in Home Assistant then you may want to use predbat.soc_kw_h0 as your current SoC +rather than the usual givtcp_SERIAL_NUMBER_soc GivTCP entity so everything lines up.

+

Import export scaling

+
import_export_scaling: scale
+
+

Default value 1.0. Used to scale the import & export kWh data from GivTCP if the inverter information is incorrect.

+

Inverter rate minimum

+
inverter_battery_rate_min: watts
+
+

One per inverter (optional), set in Watts, when set models a "bug" in the inverter firmware +in some models where if charge or discharge rates are set to 0 you actually get a small amount of charge or discharge. +Recommended setting is 200 for Gen 1 hybrids with this issue.

+

Inverter reserve maximum

+
inverter_reserve_max: percent
+
+

Global, sets the maximum reserve % that may be set to the inverter, the default is 98, as some Gen 2 & Gen 3 inverters and +AIO firmware versions refuse to be set to 100. Comment the line out or set to 100 if your inverter allows setting to 100%.

+

Automatic restarts

+

If the add-on that is providing the inverter control stops functioning it can prevent Predbat from functioning correctly. +In this case you can tell Predbat how to restart the add-on using a service.

+

Right now only communication loss with GE inverters is detectable but in future other systems will be supported.

+

When enabled if communication is lost then the service configured will be triggered and can cause a restart which may restart the connection. +This maybe useful with GivTCP if you have time sync errors or lose the REST service every now and again.

+

The auto_restart itself is a list of commands to run to trigger a restart.

+
    +
  • The shell command will call a 'sh' shell and can be used to delete files and suchlike.
    • +
  • The service command is used to call a service, and can contain arguments of addon and/or entity_id. The configuration below is for GivTCP v3.
    • +
+
auto_restart:
+  - shell: 'rm -rf /homeassistant/GivTCP/*.pkl'
+  - service: hassio/addon_restart
+    addon: 533ea71a_givtcp
+
+

NB: If you are running GivTCP v2 then the line '533ea71a_givtcp' must be replaced with 'a6a2857d_givtcp' +as the slug-id (Home Assistant add-on identifier) is different between GivTCP v2 and v3.

+

Battery charge/discharge curves

+

Some batteries tail off their charge rate at high SoC% or their discharge rate at low SoC%, and these optional configuration items enables you to model this tail-off in Predbat. +Note that the charge/discharge curves only affect the accuracy of the charging/discharging model Predbat applies in the forward battery plan, +Predbat will still instruct the inverter to charge/discharge at full rate regardless of the charging curve.

+

If you know the battery charge or discharge curves (e.g. manufacturer info or your own testing) then you can manually configure this in apps.yaml, +or Predbat can calculate the curves based upon historical inverter charging/discharging data in Home Assistant.

+

If the battery has not recently been fully charged or fully discharged then Predbat will not be able to calculate the curves and you'll get a warning in the logfile.

+
    +
  • battery_charge_power_curve - This optional configuration item enables you to model in Predbat a tail off in charging at high SoC%.
    • +
+

Enter the charging curve as a series of steps of % of max charge rate for each SoC percentage.

+

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. 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).

+

If the battery_charge_power_curve option is not set in apps.yaml and Predbat performs an initial run (e.g. due to restarting the Predbat/AppDaemon add-on, +or an edit being made to apps.yaml), then Predbat will automatically calculate the charging curve for you from historical battery charging information.

+

You should look at the Predbat logfile to find the predicted battery charging curve and copy/paste it into your apps.yaml file. +The logfile will also include a recommendation for how to set your battery_rate_max_scaling setting in HA.

+

The YouTube video charging curve and low power charging +explains how the curve works and shows how Predbat automatically creates it.

+

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 configure the charge curve in apps.yaml.

+

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. +These must be configured in apps.yaml to point to Home Assistant entities that have appropriate history data for your inverter/battery.

+

If you have a GivEnergy inverter and are using the recommended default REST mode to control your inverter +then you will need to uncomment out the following entries in apps.yaml:

+
charge_rate:
+  - number.givtcp_{geserial}_battery_charge_rate
+battery_power:
+  - sensor.givtcp_{geserial}_battery_power
+soc_kw:
+  - sensor.givtcp_{geserial}_soc_kwh
+
+

Example charging curve from a GivEnergy 9.5kWh battery with latest firmware and Gen 1 inverter:

+
battery_charge_power_curve:
+  91 : 0.91
+  92 : 0.81
+  93 : 0.71
+  94 : 0.62
+  95 : 0.52
+  96 : 0.43
+  97 : 0.33
+  98 : 0.24
+  99 : 0.24
+  100 : 0.24
+
+
    +
  • battery_discharge_power_curve - This optional configuration item enables you to model in Predbat a tail off in discharging at low SoC%.
    • +
+

Enter the discharging curve as a series of steps of % of max discharge rate for each SoC percentage.

+

The default is 1.0 (full power) discharge all the way to 0%.

+

If the battery_discharge_power_curve option is not set in apps.yaml and Predbat performs an initial run (e.g. due to restarting the Predbat/AppDaemon add-on, +or an edit being made to apps.yaml), then Predbat will automatically calculate the discharging curve for you from historical battery discharging information.

+

You should look at the Predbat logfile to find the predicted battery discharging curve and copy/paste it into your apps.yaml file.

+

Setting This option to auto will cause the computed curve to be stored and used automatically. This may not work very well if you don't do regular discharges to empty the battery.

+

In the same way as for the battery charge curve above, Predbat needs to have access to historical Home Assistant data for battery_discharge_rate, battery_power and soc_kw. +These must be configured in apps.yaml to point to Home Assistant entities that have appropriate history data for your inverter/battery.

+

If you are using REST mode to control your GivEnergy inverter then the following entries in apps.yaml will need to be uncommented :

+
discharge_rate:
+  - number.givtcp_{geserial}_battery_discharge_rate
+battery_power:
+  - sensor.givtcp_{geserial}_battery_power
+soc_kw:
+  - sensor.givtcp_{geserial}_soc_kwh
+
+

Triggers

+
    +
  • export_triggers - The export trigger feature is useful to help trigger your own automations based on Predbat predicting in the plan +that you will have spare solar energy that would be exported - this could happen if the battery is full or there is more predicted solar generation than can be charged into the battery. +You can use the trigger in an automation, for example you could turn on an immersion heater or the washing machine to consume the excess solar power.
    • +
+

The triggers count export energy until the next active charge slot only.

+

For each trigger give a name, the minutes of export needed, and the energy required in that time.

+

Multiple triggers can be enabled by Predbat at once so in total you could use too much energy if multiple triggered automations all run.

+

Each trigger specified in apps.yaml will create a Home Assistant entity called 'binary_sensor.predbat_export_trigger_name' +which will be turned on when the predicted trigger conditions are valid. +Connect this binary sensor to your automation to start whatever you want to trigger.

+

Set the name for each trigger, the number of minutes of solar export you need, and the amount of energy in kWh you will need available during that time period in apps.yaml:

+

For example:

+
export_triggers:
+  - name: "large"
+    minutes: 60
+    energy: 1.0
+  - name: "small"
+    minutes: 15
+    energy: 0.25
+
+

Note: Predbat will set an export trigger to True if in the plan it predicts +that there will be more than the specified amount of excess solar energy over the specified time period.
+In the example above, the 'large' trigger will be set to True for the 1 hour period where Predbat predicts +that there will be a total of 1kWh of excess solar generation over that time period. +For clarity the trigger is not set based on actual excess solar generation or export.
+It should also be recognised that this prediction could be wrong; there could be less solar generation or more house load than was predicted in the plan.

+

If you wish to trigger activities based on Predbat charging or discharging the battery rather than spare solar energy you can instead use the following binary sensors in Home Assistant:

+
    +
  • +

    binary_sensor.predbat_charging - Will be True when the home battery is inside a charge slot (either being charged or being held at a level). +Note that this does include charge freeze slots where the discharge rate is set to zero without charging the battery.

    +
    • +
  • +

    binary_sensor.predbat_exporting - 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:

+
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:

+
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:

+
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:

+
days_previous:
+  - 2
+  - 3
+  - 4
+  - 5
+  - 6
+  - 7
+  - 8
+
+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/car-charging/index.html b/car-charging/index.html new file mode 100644 index 000000000..758ffce02 --- /dev/null +++ b/car-charging/index.html @@ -0,0 +1,403 @@ + + + + + + + + Car charging - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Car charging
    • +
  • +
    • +
+
+
+
+
+ +

Car charging

+

As a bare minimum a HA-controllable smart plug with a granny charger could be used, +but do consider there could be an electrical spike to the car if the smart plug is turned off when the car is charging. A proper car charger and HA integration is preferable.

+

You will firstly need to have installed the appropriate Home Assistant integration for your car charger.

+

Configure apps.yaml for your car charging

+

Start by configuring the Car charging settings in apps.yaml.

+

Car Charging Planning

+

There are two ways that Predbat can plan the slots for charging your car:

+
    +
  • +

    If you have the Intelligent Octopus import tariff, have completed enrollment of your car/charger to Intelligent Octopus (requires a compatible charger or car), +and you have installed the Octopus Energy integration - in which case Predbat will use the car charging slots allocated by Octopus Energy in battery prediction. +The Octopus Energy integration supports Octopus 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 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 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 Home Assistant 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 car's current 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
      • +
    • The switch switch.predbat_octopus_intelligent_ignore_unplugged (expert mode) +can be used to prevent Predbat from assuming the car will be charging or that future extra low rate slots apply when the car is unplugged. +This will only work correctly if car_charging_planned is set correctly in apps.yaml to detect your car being plugged in
      • +
    • Let the Octopus app control when your car charges.
      • +
    +
    • +
  • +

    Predbat-led charging - Here Predbat plans and can initiate the car charging based on the upcoming low import rate slots

    +
      +
    • Ensure car_charging_limit, car_charging_soc and car_charging_planned are set correctly in apps.yaml to point to the appropriate sensors from your EV (see Car charging config in apps.yaml)
      • +
    • Check (and if necessary add) the sensor response value from the sensor configured in car_charging_planned that is returned +when the car is 'plugged in and ready to charge' is in the list of car_charging_planned_response values configured in apps.yaml
      • +
    • If your car does not have a state of charge (SoC) sensor you can set switch.predbat_car_charging_manual_soc to True +to have Predbat create input_number.predbat_car_charging_manual_soc_kwh which will hold the cars SoC in kWh.
      +You will need to manually set this to the cars current charge level before charging, Predbat will increment it during +charging sessions but will not reset it automatically.
      +NB: input_number.predbat_car_charging_manual_soc_kwh must be set to the current kWh value of your car battery NOT a percentage SoC figure +otherwise Predbat won't know how much energy there currently is in the battery.
      +NB2: If you have car_charging_soc set and working for your car SoC sensor in apps.yaml, switch.predbat_car_charging_manual_soc must be set to Off +as otherwise the car SoC sensor will be ignored
      • +
    • Ensure switch.predbat_octopus_intelligent_charging in Home Assistant is set to Off
      • +
    • Set input_number.predbat_car_charging_rate to the car's charging rate in kW per hour (e.g. 7.5 for 7.5kWh)
      • +
    • Set select.predbat_car_charging_plan_time to the time you want the car charging to be completed by
      • +
    • Turn on switch.predbat_car_charging_plan_smart if you want to use the cheapest slots only. When disabled (turned off) all low rate slots will be used in time order
      • +
    • You can set input_number.predbat_car_charging_plan_max_price if you want to set a maximum price in pence per kWh to charge your car (e.g. 10p). +If you set this to zero, this feature is disabled, and all low rate slots will be used. This may mean you need to use expert mode and change your low rate +threshold to configure which slots should be considered if you have a tariff with more than 2 import rates (e.g. Flux)
      • +
    • WARNING: Do not set car_charging_now or you will create a circular dependency.
      • +
    • Predbat will set binary_sensor.predbat_car_charging_slot when it determines the car can be charged; +you will need to write a Home Assistant automation based on this sensor to control when your car charges.
      +A sample automation to start/stop car charging using a Zappi car charger and the MyEnergi Zappi integration is as follows, +this should be adapted for your own charger type and how it controls starting/stopping car charging:
      • +
    +
    • +
+
alias: Car charging
+description: "Start/stop car charging based on Predbat determined slots"
+triggers:
+  - trigger: state
+    entity_id:
+      - binary_sensor.predbat_car_charging_slot
+actions:
+  - choose:
+      - conditions:
+          - condition: state
+            entity_id: binary_sensor.predbat_car_charging_slot
+            state: "on"
+        sequence:
+          <commands to turn on your car charger, e.g.>
+          - service: select.select_option
+            data:
+              option: Eco+
+            target:
+              entity_id: select.myenergi_zappi_charge_mode
+      - conditions:
+          - condition: state
+            entity_id: binary_sensor.predbat_car_charging_slot
+            state: "off"
+        sequence:
+          <commands to turn off your car charger, e.g.>
+          - service: select.select_option
+            data:
+              option: Stopped
+            target:
+              entity_id: select.myenergi_zappi_charge_mode
+mode: single
+
+

NOTE: Multiple cars can be planned with Predbat.

+

Additional Car charging configurations

+

If you have one charger and multiple cars configured in Predbat then set car_charging_exclusive in apps.yaml to True to indicate that only one +car may charge at once (the first car reporting as plugged in will be considered as charging). If you set this to False then it is assumed each car +can charge independently and hence two or more could charge at once

+
car_charging_exclusive:
+  - True
+  - True
+
+

See Car charging filtering and Planned car charging +in the apps.yaml settings section of the documentation.

+
    +
  • +

    switch.predbat_car_charging_from_battery - When set to True the car can drain the home battery, Predbat will manage the correct level of battery accordingly. +When set to False home battery discharge will be prevented when your car charges, all load from the car and home will be from the grid. +This is achieved by setting the battery discharge rate to 0 during car charging and to the maximum otherwise. +The home battery can still charge from the grid/solar in either case. Only use this if Predbat knows your car charging plan, +e.g. you are using Intelligent Octopus or you use the car slots in Predbat to control your car charging.

    +
    • +
  • +

    input_number.predbat_car_charging_loss gives the percentage amount of energy lost when charging the car (load in the home vs energy added to the battery). +A good setting is 0.08 which is 8%.

    +
    • +
+

Example EV and charger setup

+

Sample setup and Predbat automation to use the cheapest charging slots with no/limited Home Assistant Integration.

+

MG4 EV Vehicle with a Hypervolt Car Charger. There is no 3rd party integration with the MG, and the Hypervolt car charger doesn't understand when an EV is plugged in.

+

Yet it can be stopped and started with a 3rd party integration.

+

In Home Assistant, create two helper entities (Settings / Devices & Services / Helpers) of type 'Number', and for each set 'Unit of Measurement' to 'kWh':

+
    +
  • Car Max Charge - input_number.car_max_charge
    • +
  • Car Manual SoC - input_number.car_manual_soc
    • +
+

Create a 'Dropdown' helper entity that has two options 'true' and 'false' (in lower case):

+
    +
  • Car Charger Plugged in - input_select.car_charger_plugged_in
    • +
+

Within the apps.yaml configuration file specify the following configuration settings:

+

Find the line for car_charger_battery_size and enter the Car Battery Size in kWh:

+

Example

+
  car_charging_battery_size:
+    - 61.7
+
+

Specify the Car Charging Limit to use the Car Max Charge helper entity created earlier:

+
  car_charging_limit:
+    - 'input_number.car_max_charge'
+
+

Find car_charging_planned and replace the template Wallbox and Zappi regular expression with your new dropdown helper entity:

+
  car_charging_planned:
+    - 'input_select.car_charger_plugged_in'
+
+

Find car_charging_planned_response and add 'true' to the list:

+
  car_charging_planned_response:
+    - 'yes'
+    - 'on'
+    - 'true'
+
+

If possible, add an entity keeping track of the kWh used for car charging to car_charging_energy.

+

If your charging device doesn't keep track of kWh but you can measure the power sent to the car charger +(e.g. from the EV charger integration or an energy monitor/smart plug for the EV charger) then you can create another helper entity to convert kW power into kWh:

+

Create a helper entity (Settings / Devices & Services / Helpers) of type 'Integration - Riemann Sum integral':

+
    +
  • Name : car_energy_used
    • +
  • Input sensor : sensor that measures power consumed by the car charger
    • +
  • Integration method : Right Riemann sum
    • +
  • Metric prefix : k (kilo)
    • +
+

Please look into Integration - Riemann sum integral to convert kW into kWh.

+

And add your custom car charging energy sensor in apps.yaml in place of the template Wallbox and Zappi regular expression:

+

Example

+
car_charging_energy: 'sensor.car_energy_used'
+
+

car_charging_now must be commented out (hashed out) in apps.yaml:

+
  #car_charging_now:
+  #  - off
+
+

Save the apps.yaml file and exit.

+

In Home Assistant, turn on the following Predbat control switches:

+
    +
  • switch.predbat_car_charging_hold
    • +
  • switch.predbat_car_charging_manual_soc
    • +
  • switch.predbat_car_charging_plan_smart
    • +
+

And turn off the Predbat control switch:

+
    +
  • switch.predbat_octopus_intelligent_charging
    • +
+

HA Charging Slot Automation

+

In Home Assistant (Settings / Automation & Scenes), create an automation to monitor the Predbat car charging slot sensor and turn the charger on and off according to the Predbat plan +(the numeric entity id's below would need replacing with the appropriate sensor name for your car charger):

+
alias: Car Charging Slot
+description: ""
+triggers:
+  - trigger: state
+    entity_id:
+      - binary_sensor.predbat_car_charging_slot
+actions:
+  - if:
+      - condition: state
+        entity_id: binary_sensor.predbat_car_charging_slot
+        state: "off"
+    then:
+      - type: turn_off
+        entity_id: f6de2df0758744aba60f6b5f
+        domain: switch
+  - if:
+      - condition: state
+        entity_id: binary_sensor.predbat_car_charging_slot
+        state: "on"
+    then:
+      - type: turn_on
+        entity_id: f6de2df0758744aba60f6b5f
+        domain: switch
+mode: single
+
+

Finally, for simplicity, add the below entities to your HA Dashboard so you can set them when needed:

+
    +
  • Car Max Charge - input_number.car_max_charge
    • +
  • Car Manual SoC - input_number.car_manual_soc
    • +
  • Car Charger Plugged in - input_select.car_charger_plugged_in
    • +
+

Annoyingly, you have to calculate the kWh your vehicle has in total by taking the Percentage left in the car / 100 * Total Car Battery capacity.
+For example:

+
65/100*61.7=40.1
+
+

Enter '40.1' into 'Car Manual SoC' and '80%' into 'Car Max charge'.

+

Once the charger is switched to true and your Car Max charge (target SoC) % is higher than the kWh currently in the car, +Predbat will plan and charge the car with the kW that are needed to reach the target SoC.

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/caution/index.html b/caution/index.html new file mode 100644 index 000000000..7cff4d707 --- /dev/null +++ b/caution/index.html @@ -0,0 +1,206 @@ + + + + + + + + Words of caution - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Words of caution
    • +
  • +
    • +
+
+
+
+
+ +

Some words of caution

+

Predbat is a powerful hobbyist system that can control many home battery and solar systems. While every attempt has been made to make it as easy to use as possible it does require +a certain amount of technical skills.

+

Increased energy costs

+

While Predbat normally will save you money an incorrectly configured Predbat can cause your battery to be badly managed and thus increase your electricity bills, I'd recommend carefully changing what you install is doing +once you have enabled it for the first time.

+

Flash memory

+

Some inverters have a flash memory which has a limited lifespan and so depending on the way register writes are managed controller your inverter can act to reduce this lifespan. +In normal operation this should not be an issue but if you have a setup that performs large number of register writes all the time its possible you could eventually run into +this issue.

+
    +
  • For example on a current GivEnergy inverters its assumed around 1 million register writes could be the current usable limit (although firmware changes may increase this limit)
    • +
  • This would give you around 270 writes per day or around 1 every 5 minutes.
    • +
  • Each change of mode requires more than one register write, e.g. start time, end time, scheduled charge enable, pause mode etc - this could be around 6 registers.
    • +
  • This means one change of mode every 30 minutes on average would be okay.
    • +
  • However given most plans will have larger gaps (often hours) where the battery is either in Demand mode, charging or exporting where registers are not changing it is unlikely to hit this limit.
    • +
+

Given different inverter designs may have different limits it is a wise precaution to avoid your plan being too busy if it doesn't gain you very much. +Things you can do to have a less complex plan include:

+
    +
  • Keep calculate export during charge off
    • +
  • Set metric battery cycle to a small non-zero value e.g. 0.5
    • +
  • Ensure inverter losses are set to a representative value
    • +
  • Turn off charge_low_power mode
    • +
+

Avoid using balance inverters which can make register changes one or twice a minute unless you are sure this is not an issue

+

Predbat creates an entity called predbat.inverter_register_writes which can be used to check the total number of writes across all inverters, if you divide this by the time period of use +and by the number of inverters you will be able to figure out the actual rate of register writes.

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/configuration-guide/index.html b/configuration-guide/index.html new file mode 100644 index 000000000..f63e56b11 --- /dev/null +++ b/configuration-guide/index.html @@ -0,0 +1,445 @@ + + + + + + + + Configuration guide - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Configuration guide
    • +
  • +
    • +
+
+
+
+
+ +

Configuration guide

+

First get the basics set up, ensure you have the inverter controls configured, +you have configured apps.yaml to your setup, and the solar forecast is 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 Predbat can tell what part of your historical load is EV charging. +You might want to also set the car charging plan so you can predict when your car is plugged in and how much it will charge.

+

It is recommended that you create a dashboard page 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 details all the Predbat customisation options.

+

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.

+

For a Hybrid inverter the inverter loss includes the loss on inverting PV as well going AC to DC when importing. Battery loss charge and discharge are factors to account for the loss +in charging and discharging the battery as DC.

+

For a AC coupled inverter the inverter loss is just the loss of the battery inverter, if you need to model the loss of your PV inverter then use input_number.predbat_pv_scaling +or adjust your Solcast output. Battery loss charge and discharge are factors to account for the loss in charging and discharging the battery as DC.

+

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.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.
+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 0.5p (meaning charging and discharging the battery would effectively cost an extra 1p per kWh) but can be set to 0 if you want to turn this feature off.

+

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 and don't want Predbat to force export (discharge) your battery.

+

Recommended settings - these must be changed in Home Assistant once Predbat is running:

+ + + + + + + + + + + + + + + + + + + + +
ItemValueComment
select.predbat_modeControl ChargeYou want Predbat to calculate and control charging
input_number.predbat_best_soc_keep2.0Tweak this to control what battery level you want to keep as a backup in case you use more energy
+

If you are using expert mode then these options maybe worth reviewing:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ItemValueComment
input_number.predbat_forecast_plan_hours24If you set this to 24 then you will have quicker updates, the cycle repeats itself anyhow
input_number.predbat_metric_min_improvement0Charge less if it's cost neutral
input_number.predbat_metric_min_improvement_export5Export only if there is a profit
+

You should set select.predbat_mode to 'Control charge'

+

Cheap night rate, with a good export rate (e.g. Intelligent Octopus with Octopus Outgoing)

+

Follow the instructions from the Cheap Night rate above, but also you will also want to have automatic export occurring when the export rates are profitable.

+ + + + + + + + + + + + + + + + + + + + +
ItemValueComment
select.predbat_modeControl Charge & DischargeYou want Predbat to calculate and control charging and discharging
input_number.predbat_best_soc_keep2.0Tweak this to control what battery level you want to keep as a backup in case you use more energy
+

If you are using expert mode then these options maybe worth reviewing, otherwise ignore this:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemValueComment
input_number.predbat_forecast_plan_hours24If you set this to 24 then you will have quicker updates, the cycle repeats itself anyhow
input_number.predbat_metric_min_improvement0Charge less if it's cost neutral
input_number.predbat_metric_min_improvement_export5Export only if there is a profit
input_number.predbat_metric_battery_cycle0-2Higher numbers mean less charging and discharging but higher costs
input_number.predbat_best_soc_min0Can be set non-zero if you want to force a minimum charge level
+

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 export when the export rates are profitable.

+

Recommended settings - these must be changed in Home Assistant once Predbat is running:

+ + + + + + + + + + + + + + + + + + + + +
ItemValueComment
select.predbat_modeControl Charge & DischargeYou want Predbat to calculate and control charging and discharging
input_number.predbat_best_soc_keep0.5Use the full battery without going empty
+

If you are using expert mode then these options maybe worth reviewing, otherwise ignore this:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemValueComment
input_number.predbat_forecast_plan_hours24If you set this to 24 then you will have quicker updates, the cycle repeats itself anyhow
input_number.predbat_metric_min_improvement0Charge less if it's cost neutral
input_number.predbat_metric_min_improvement_export5Export only if there is a profit
input_number.predbat_metric_battery_cycle0-2Higher numbers mean less charging and discharging but higher costs
input_number.predbat_best_soc_min0Don't use non-zero otherwise all slots will be force charging
+

You should set select.predbat_mode to 'Control charge & discharge'

+

Half hourly variable rates (e.g. Octopus Agile)

+

Recommended settings - these must be changed in Home Assistant once Predbat is running:

+ + + + + + + + + + + + + + + + + + + + +
ItemValueComment
select.predbat_modeControl Charge & DischargeYou want Predbat to calculate and control charging and discharging
input_number.predbat_best_soc_keep0.5Use the full battery without going empty
+

If you are using expert mode then these options maybe worth reviewing, otherwise ignore this:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ItemValueComment
input_number.predbat_forecast_plan_hours24-48If you set this to 24 then you will have quicker updates, going to 36/48 for a longer plan
input_number.predbat_metric_min_improvement0Charge less if it's cost neutral
input_number.predbat_metric_min_improvement_export5Export only if there is a profit
input_number.predbat_metric_battery_cycle0-2Higher numbers mean less charging and discharging but higher costs
input_number.predbat_best_soc_min0Don't use non-zero otherwise all slots will be force charging
+

You should set select.predbat_mode to 'Control charge & discharge'

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/creating-charts/index.html b/creating-charts/index.html new file mode 100644 index 000000000..023ebe613 --- /dev/null +++ b/creating-charts/index.html @@ -0,0 +1,215 @@ + + + + + + + + Creating the charts - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Viewing Predbat data
    • +
  • Creating the charts
    • +
  • +
    • +
+
+
+
+
+ +

Creating the charts

+

There are a number of fancy Apex charts that can be produced from Predbat data - things like Home Battery SoC prediction, Cost prediction, Energy Rates, etc.

+

There's a Video Guide to the different charts available on YouTube.

+

To install the charts:

+
    +
  • +

    Install Apex Charts https://github.com/RomRider/apexcharts-card:

    +
      +
    • In HACS, click on Frontend
      • +
    • Click the blue Explore and download repositories button and type 'apex'
      • +
    • Click on 'apexcharts-card', then click the blue 'Download', then 'Download' again to install it
      • +
    • When prompted to 'reload your browser', click 'Reload'
      • +
    +
    • +
  • +

    Next, on a Home Assistant dashboard you create the charts you want.

    +
    • +
  • There are multiple charts, for each section of the +example chart yaml file, +create a new apexcharts card and copy the YAML into it:
      +
    • Click the blue 'Add card', scroll down the list of cards to the bottom and click 'Custom: ApexCharts card'
      • +
    • Delete the template card configuration and copy/paste ONE Apex chart from the example file
      • +
    • Click 'Save'
      • +
    • Repeat (adding Apex chart card, copy paste card config) for all of the charts you want to see
      • +
    +
    • +
  • Customise as you like
    • +
+

If you get an error 'Custom element doesn't exist: apexcharts-card' then you've not installed the Apex Charts card correctly from HACS.

+

See the video guides for a walkthrough of what the different charts show.

+

Example charts:

+

image

+

image

+

image

+

image

+

image

+

image

+

image

+

image

+

image

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/css/fonts/Roboto-Slab-Bold.woff b/css/fonts/Roboto-Slab-Bold.woff new file mode 100644 index 000000000..6cb600001 Binary files /dev/null and b/css/fonts/Roboto-Slab-Bold.woff differ diff --git a/css/fonts/Roboto-Slab-Bold.woff2 b/css/fonts/Roboto-Slab-Bold.woff2 new file mode 100644 index 000000000..7059e2314 Binary files /dev/null and b/css/fonts/Roboto-Slab-Bold.woff2 differ diff --git a/css/fonts/Roboto-Slab-Regular.woff b/css/fonts/Roboto-Slab-Regular.woff new file mode 100644 index 000000000..f815f63f9 Binary files /dev/null and b/css/fonts/Roboto-Slab-Regular.woff differ diff --git a/css/fonts/Roboto-Slab-Regular.woff2 b/css/fonts/Roboto-Slab-Regular.woff2 new file mode 100644 index 000000000..f2c76e5bd Binary files /dev/null and b/css/fonts/Roboto-Slab-Regular.woff2 differ diff --git a/css/fonts/fontawesome-webfont.eot b/css/fonts/fontawesome-webfont.eot new file mode 100644 index 000000000..e9f60ca95 Binary files /dev/null and b/css/fonts/fontawesome-webfont.eot differ diff --git a/css/fonts/fontawesome-webfont.svg b/css/fonts/fontawesome-webfont.svg new file mode 100644 index 000000000..855c845e5 --- /dev/null +++ b/css/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/css/fonts/fontawesome-webfont.ttf b/css/fonts/fontawesome-webfont.ttf new file mode 100644 index 000000000..35acda2fa Binary files /dev/null and b/css/fonts/fontawesome-webfont.ttf differ diff --git a/css/fonts/fontawesome-webfont.woff b/css/fonts/fontawesome-webfont.woff new file mode 100644 index 000000000..400014a4b Binary files /dev/null and b/css/fonts/fontawesome-webfont.woff differ diff --git a/css/fonts/fontawesome-webfont.woff2 b/css/fonts/fontawesome-webfont.woff2 new file mode 100644 index 000000000..4d13fc604 Binary files /dev/null and b/css/fonts/fontawesome-webfont.woff2 differ diff --git a/css/fonts/lato-bold-italic.woff b/css/fonts/lato-bold-italic.woff new file mode 100644 index 000000000..88ad05b9f Binary files /dev/null and b/css/fonts/lato-bold-italic.woff differ diff --git a/css/fonts/lato-bold-italic.woff2 b/css/fonts/lato-bold-italic.woff2 new file mode 100644 index 000000000..c4e3d804b Binary files /dev/null and b/css/fonts/lato-bold-italic.woff2 differ diff --git a/css/fonts/lato-bold.woff b/css/fonts/lato-bold.woff new file mode 100644 index 000000000..c6dff51f0 Binary files /dev/null and b/css/fonts/lato-bold.woff differ diff --git a/css/fonts/lato-bold.woff2 b/css/fonts/lato-bold.woff2 new file mode 100644 index 000000000..bb195043c Binary files /dev/null and b/css/fonts/lato-bold.woff2 differ diff --git a/css/fonts/lato-normal-italic.woff b/css/fonts/lato-normal-italic.woff new file mode 100644 index 000000000..76114bc03 Binary files /dev/null and b/css/fonts/lato-normal-italic.woff differ diff --git a/css/fonts/lato-normal-italic.woff2 b/css/fonts/lato-normal-italic.woff2 new file mode 100644 index 000000000..3404f37e2 Binary files /dev/null and b/css/fonts/lato-normal-italic.woff2 differ diff --git a/css/fonts/lato-normal.woff b/css/fonts/lato-normal.woff new file mode 100644 index 000000000..ae1307ff5 Binary files /dev/null and b/css/fonts/lato-normal.woff differ diff --git a/css/fonts/lato-normal.woff2 b/css/fonts/lato-normal.woff2 new file mode 100644 index 000000000..3bf984332 Binary files /dev/null and b/css/fonts/lato-normal.woff2 differ diff --git a/css/theme.css b/css/theme.css new file mode 100644 index 000000000..ad773009b --- /dev/null +++ b/css/theme.css @@ -0,0 +1,13 @@ +/* + * This file is copied from the upstream ReadTheDocs Sphinx + * theme. To aid upgradability this file should *not* be edited. + * modifications we need should be included in theme_extra.css. + * + * https://github.com/readthedocs/sphinx_rtd_theme + */ + + /* sphinx_rtd_theme version 1.2.0 | MIT license */ +html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li button.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content .eqno a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content p a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content .eqno .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content p .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li button.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content .eqno .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.btn .wy-menu-vertical li button.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content .eqno .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.nav .wy-menu-vertical li button.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .eqno .btn .headerlink,.rst-content .eqno .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p .btn .headerlink,.rst-content p .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li button.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.rst-content section ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.rst-content section ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.rst-content section ul li p:last-child,.rst-content section ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.rst-content section ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.rst-content section ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.rst-content section ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content .section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol.arabic li,.rst-content .section ol li,.rst-content .toctree-wrapper ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content section ol.arabic li,.rst-content section ol li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol.arabic li ul,.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,.rst-content .toctree-wrapper ol li p:last-child,.rst-content .toctree-wrapper ol li ul,.rst-content section ol.arabic li ul,.rst-content section ol li p:last-child,.rst-content section ol li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol.arabic li ul li,.rst-content .section ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content section ol.arabic li ul li,.rst-content section ol li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs>li{display:inline-block;padding-top:5px}.wy-breadcrumbs>li.wy-breadcrumbs-aside{float:right}.rst-content .wy-breadcrumbs>li code,.rst-content .wy-breadcrumbs>li tt,.wy-breadcrumbs>li .rst-content tt,.wy-breadcrumbs>li code{all:inherit;color:inherit}.breadcrumb-item:before{content:"/";color:#bbb;font-size:13px;padding:0 6px 0 3px}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover button.toctree-expand,.wy-menu-vertical li.on a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search>a:hover{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.version{margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}.rst-content .toctree-wrapper>p.caption,.rst-content h1,.rst-content h2,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img,.rst-content section>a>img,.rst-content section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp,.rst-content div.highlight span.linenos{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*,.rst-content section ol li>*,.rst-content section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child,.rst-content .toctree-wrapper ol li>:first-child,.rst-content .toctree-wrapper ul li>:first-child,.rst-content section ol li>:first-child,.rst-content section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ul li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content section ol li>ol,.rst-content section ol li>ul,.rst-content section ul li>ol,.rst-content section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ul.simple li>*,.rst-content .toctree-wrapper ul.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content section ol.simple li>*,.rst-content section ol.simple li ol,.rst-content section ol.simple li ul,.rst-content section ul.simple li>*,.rst-content section ul.simple li ol,.rst-content section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content .code-block-caption .headerlink:focus,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno .headerlink:focus,.rst-content .eqno:hover .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content dl dt .headerlink:focus,.rst-content dl dt:hover .headerlink,.rst-content h1 .headerlink:focus,.rst-content h1:hover .headerlink,.rst-content h2 .headerlink:focus,.rst-content h2:hover .headerlink,.rst-content h3 .headerlink:focus,.rst-content h3:hover .headerlink,.rst-content h4 .headerlink:focus,.rst-content h4:hover .headerlink,.rst-content h5 .headerlink:focus,.rst-content h5:hover .headerlink,.rst-content h6 .headerlink:focus,.rst-content h6:hover .headerlink,.rst-content p.caption .headerlink:focus,.rst-content p.caption:hover .headerlink,.rst-content p .headerlink:focus,.rst-content p:hover .headerlink,.rst-content table>caption .headerlink:focus,.rst-content table>caption:hover .headerlink{opacity:1}.rst-content p a{overflow-wrap:anywhere}.rst-content .wy-table td p,.rst-content .wy-table td ul,.rst-content .wy-table th p,.rst-content .wy-table th ul,.rst-content table.docutils td p,.rst-content table.docutils td ul,.rst-content table.docutils th p,.rst-content table.docutils th ul,.rst-content table.field-list td p,.rst-content table.field-list td ul,.rst-content table.field-list th p,.rst-content table.field-list th ul{font-size:inherit}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .citation-reference>span.fn-bracket,.rst-content .footnote-reference>span.fn-bracket{display:none}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none!important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:auto minmax(80%,95%)}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{display:inline-grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{display:grid;grid-template-columns:auto auto minmax(.65rem,auto) minmax(40%,95%)}html.writer-html5 .rst-content aside.citation>span.label,html.writer-html5 .rst-content aside.footnote>span.label,html.writer-html5 .rst-content div.citation>span.label{grid-column-start:1;grid-column-end:2}html.writer-html5 .rst-content aside.citation>span.backrefs,html.writer-html5 .rst-content aside.footnote>span.backrefs,html.writer-html5 .rst-content div.citation>span.backrefs{grid-column-start:2;grid-column-end:3;grid-row-start:1;grid-row-end:3}html.writer-html5 .rst-content aside.citation>p,html.writer-html5 .rst-content aside.footnote>p,html.writer-html5 .rst-content div.citation>p{grid-column-start:4;grid-column-end:5}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{margin-bottom:24px}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.citation>dt>span.brackets:before,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.citation>dt>span.brackets:after,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a{word-break:keep-all}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a:not(:first-child):before,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.citation>dd p,html.writer-html5 .rst-content dl.footnote>dd p{font-size:.9rem}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{padding-left:1rem;padding-right:1rem;font-size:.9rem;line-height:1.2rem}html.writer-html5 .rst-content aside.citation p,html.writer-html5 .rst-content aside.footnote p,html.writer-html5 .rst-content div.citation p{font-size:.9rem;line-height:1.2rem;margin-bottom:12px}html.writer-html5 .rst-content aside.citation span.backrefs,html.writer-html5 .rst-content aside.footnote span.backrefs,html.writer-html5 .rst-content div.citation span.backrefs{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content aside.citation span.backrefs>a,html.writer-html5 .rst-content aside.footnote span.backrefs>a,html.writer-html5 .rst-content div.citation span.backrefs>a{word-break:keep-all}html.writer-html5 .rst-content aside.citation span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content aside.footnote span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content div.citation span.backrefs>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content aside.citation span.label,html.writer-html5 .rst-content aside.footnote span.label,html.writer-html5 .rst-content div.citation span.label{line-height:1.2rem}html.writer-html5 .rst-content aside.citation-list,html.writer-html5 .rst-content aside.footnote-list,html.writer-html5 .rst-content div.citation-list{margin-bottom:24px}html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content aside.footnote-list aside.footnote,html.writer-html5 .rst-content div.citation-list>div.citation,html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content aside.footnote-list aside.footnote code,html.writer-html5 .rst-content aside.footnote-list aside.footnote tt,html.writer-html5 .rst-content aside.footnote code,html.writer-html5 .rst-content aside.footnote tt,html.writer-html5 .rst-content div.citation-list>div.citation code,html.writer-html5 .rst-content div.citation-list>div.citation tt,html.writer-html5 .rst-content dl.citation code,html.writer-html5 .rst-content dl.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040;overflow-wrap:normal}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}.rst-content dl dd>ol:last-child,.rst-content dl dd>p:last-child,.rst-content dl dd>table:last-child,.rst-content dl dd>ul:last-child{margin-bottom:0}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .sig-name{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#000}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel{border:1px solid #7fbbe3;background:#e7f2fa;font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>.kbd,.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>kbd{color:inherit;font-size:80%;background-color:#fff;border:1px solid #a6a6a6;border-radius:4px;box-shadow:0 2px grey;padding:2.4px 6px;margin:auto 0}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block} diff --git a/css/theme_extra.css b/css/theme_extra.css new file mode 100644 index 000000000..ab0631a18 --- /dev/null +++ b/css/theme_extra.css @@ -0,0 +1,197 @@ +/* + * Wrap inline code samples otherwise they shoot of the side and + * can't be read at all. + * + * https://github.com/mkdocs/mkdocs/issues/313 + * https://github.com/mkdocs/mkdocs/issues/233 + * https://github.com/mkdocs/mkdocs/issues/834 + */ +.rst-content code { + white-space: pre-wrap; + word-wrap: break-word; + padding: 2px 5px; +} + +/** + * Make code blocks display as blocks and give them the appropriate + * font size and padding. + * + * https://github.com/mkdocs/mkdocs/issues/855 + * https://github.com/mkdocs/mkdocs/issues/834 + * https://github.com/mkdocs/mkdocs/issues/233 + */ +.rst-content pre code { + white-space: pre; + word-wrap: normal; + display: block; + padding: 12px; + font-size: 12px; +} + +/** + * Fix code colors + * + * https://github.com/mkdocs/mkdocs/issues/2027 + */ +.rst-content code { + color: #E74C3C; +} + +.rst-content pre code { + color: #000; + background: #f8f8f8; +} + +/* + * Fix link colors when the link text is inline code. + * + * https://github.com/mkdocs/mkdocs/issues/718 + */ +a code { + color: #2980B9; +} +a:hover code { + color: #3091d1; +} +a:visited code { + color: #9B59B6; +} + +/* + * The CSS classes from highlight.js seem to clash with the + * ReadTheDocs theme causing some code to be incorrectly made + * bold and italic. + * + * https://github.com/mkdocs/mkdocs/issues/411 + */ +pre .cs, pre .c { + font-weight: inherit; + font-style: inherit; +} + +/* + * Fix some issues with the theme and non-highlighted code + * samples. Without and highlighting styles attached the + * formatting is broken. + * + * https://github.com/mkdocs/mkdocs/issues/319 + */ +.rst-content .no-highlight { + display: block; + padding: 0.5em; + color: #333; +} + + +/* + * Additions specific to the search functionality provided by MkDocs + */ + +.search-results { + margin-top: 23px; +} + +.search-results article { + border-top: 1px solid #E1E4E5; + padding-top: 24px; +} + +.search-results article:first-child { + border-top: none; +} + +form .search-query { + width: 100%; + border-radius: 50px; + padding: 6px 12px; + border-color: #D1D4D5; +} + +/* + * Improve inline code blocks within admonitions. + * + * https://github.com/mkdocs/mkdocs/issues/656 + */ + .rst-content .admonition code { + color: #404040; + border: 1px solid #c7c9cb; + border: 1px solid rgba(0, 0, 0, 0.2); + background: #f8fbfd; + background: rgba(255, 255, 255, 0.7); +} + +/* + * Account for wide tables which go off the side. + * Override borders to avoid weirdness on narrow tables. + * + * https://github.com/mkdocs/mkdocs/issues/834 + * https://github.com/mkdocs/mkdocs/pull/1034 + */ +.rst-content .section .docutils { + width: 100%; + overflow: auto; + display: block; + border: none; +} + +td, th { + border: 1px solid #e1e4e5 !important; + border-collapse: collapse; +} + +/* + * Without the following amendments, the navigation in the theme will be + * slightly cut off. This is due to the fact that the .wy-nav-side has a + * padding-bottom of 2em, which must not necessarily align with the font-size of + * 90 % on the .rst-current-version container, combined with the padding of 12px + * above and below. These amendments fix this in two steps: First, make sure the + * .rst-current-version container has a fixed height of 40px, achieved using + * line-height, and then applying a padding-bottom of 40px to this container. In + * a second step, the items within that container are re-aligned using flexbox. + * + * https://github.com/mkdocs/mkdocs/issues/2012 + */ + .wy-nav-side { + padding-bottom: 40px; +} + +/* For section-index only */ +.wy-menu-vertical .current-section p { + background-color: #e3e3e3; + color: #404040; +} + +/* + * The second step of above amendment: Here we make sure the items are aligned + * correctly within the .rst-current-version container. Using flexbox, we + * achieve it in such a way that it will look like the following: + * + * [No repo_name] + * Next >> // On the first page + * << Previous Next >> // On all subsequent pages + * + * [With repo_name] + * Next >> // On the first page + * << Previous Next >> // On all subsequent pages + * + * https://github.com/mkdocs/mkdocs/issues/2012 + */ +.rst-versions .rst-current-version { + padding: 0 12px; + display: flex; + font-size: initial; + justify-content: space-between; + align-items: center; + line-height: 40px; +} + +/* + * Please note that this amendment also involves removing certain inline-styles + * from the file ./mkdocs/themes/readthedocs/versions.html. + * + * https://github.com/mkdocs/mkdocs/issues/2012 + */ +.rst-current-version span { + flex: 1; + text-align: center; +} diff --git a/customisation/index.html b/customisation/index.html new file mode 100644 index 000000000..e739d4ee7 --- /dev/null +++ b/customisation/index.html @@ -0,0 +1,695 @@ + + + + + + + + Customisation - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Customisation
    • +
  • +
    • +
+
+
+
+
+ +

Customisation

+

This document describes the Predbat configuration items in Home Assistant that you can modify to customise Predbat to fit your needs.

+

All of these settings are entities that can be configured directly in Home Assistant (unlike the 'apps.yaml' configuration items that have to be edited with a file editor).

+

See Displaying output data +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 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 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 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.

+

image

+

Predbat mode

+

The mode that Predbat operates in will change the operation, this can be configured with select.predbat_mode drop down menu as follows:

+
    +
  • Monitor
    • +
  • Control SOC Only
    • +
  • Control charge
    • +
  • Control charge & discharge
    • +
+

If the switch.predbat_set_read_only is set to True then this prevents Predbat from making modifications to the inverter settings (regardless of the configuration). +Predbat will continue making and updating its prediction plan every 5 minutes, but no inverter changes will be made. +This is useful if you want to over-ride what Predbat is planning to do (e.g. your own automation), or whilst you are learning how Predbat works prior to turning it on 'in anger'.

+

NOTE: Changing the Predbat mode or the read only switch will cause Predbat to reset the inverter settings to default, this will disable +both charge and discharge, reset charge and discharge rates to full power and reset the reserve to the default setting

+

image

+

Predbat Monitor mode

+

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 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: 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, you have a 'no export' limitation from your electricity supplier, or if you want to preserve the battery for home demand.

+

Predbat Control charge & discharge mode

+

In Control charge & discharge mode Predbat will set both charge and force export (discharge) times and control charge and force export percentages.

+

If you have set the switch.predbat_set_export_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 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.

+ +

By default Predbat controls the inverter and updates the plan every 5 minutes, this can however use a lot of CPU power +especially on more complex tariffs like Agile when run on lower power machines such as Raspberry PIs and some thin clients.

+

You can tweak input_number.predbat_calculate_plan_every (expert mode) to reduce the frequency of replanning while +keeping the inverter control in the 5 minute slots. E.g. a value of 10 or 15 minutes should also give good results.

+

If you have performance problems leave switch.predbat_calculate_second_pass (expert mode) turned Off as it's +quite CPU intensive and provides very little improvement for most systems.

+

You can can enable combine_charge_slots and combine_export_slots in order to speed up planning. +Note: Combining export slots may prevent optimal forced export. Combining charge slots is usually fine for tariffs with +longer periods of fixed rates but can limit the planning ability in some cases.

+

The number of threads you use can change your performance, you can set threads in apps.yaml to 0 to disable threading +if you don't have multiple CPUs available or set it to 'auto' (the default) to use one thread per CPU. Its recommended you don't set this to an odd number of threads.

+

Battery loss options

+

input_number.predbat_battery_loss is an assumed percentage figure for energy lost when charging the battery, the default 0.05 is 5%.

+

input_number.predbat_battery_loss_discharge is an assumed percentage figure for energy lost whilst discharging the battery, the default 0.05 is 5%.

+

input_number.predbat_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.

+

TIP: Make sure you set the losses correctly, they are decimal percentages, don't set to '4' thinking it'll be 4%, Predbat will take this as being 400% and your plan will be very strange!

+

switch.predbat_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.predbat_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 have a 9.5kWh battery and think it will last say 6000 complete cycles and it cost you £4000, then each full charge and discharge cycle is 19kWh +and so the cost per complete cycle is £4000 / 19 / 6000 = 3.5p.

+

Taking the 3.5p per cycle example, if you set predbat_metric_battery_cycle to 1.75 (half of 3.5) then Predbat will apply the "virtual cost" of 1.75p +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.

+

If you configure this number higher then more expensive plans will be selected which avoids charging and discharging your battery as much.

+

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.

+

Figures of around 0p-2p are recommended, the default is 0p per kWh.

+

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).

+

input_number.metric_self_sufficiency (expert mode) A price in pence per kWh used to skew the calculations towards self sufficiency. Effectively saying to Predbat to +account for imports at a higher price than reality in the calculation and thus selecting plans with less import. If you want to be as self sufficient as possible then set +this to the difference between your lowest import rate and the highest export rate to take exports that require additional import appear unprofitable. This setting will not +impact the real calculated costs and is only used for plan selection. Values of 5-10p maybe worth trying if you prefer to avoid importing even if it saves you money.

+

Scaling and weight options

+

input_number.predbat_battery_rate_max_scaling is a percentage factor to adjust your maximum charge rate from that reported by the inverter. +For example a value of 0.95 would be 95% and indicate charging at 5% slower than reported. For GE inverters the charge rate reports the max +AC rate and thus needs to be reduced by inverter losses. +You can try computing your discharge curve and check recommendations for changing this figure in the logfile.

+

input_number.predbat_battery_rate_max_scaling_discharge is a percentage factor to adjust your maximum discharge rate from that reported by the inverter. +For GE inverters the discharge rate is reported as the max AC rate and thus is fairly accurate. +You can try computing your discharge curve and check recommendations for changing this figure in the logfile.

+

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.predbat_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.predbat_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.predbat_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).

+

Solar PV adjustment options

+

See also PV configuration options in apps.yaml including explanation of PV10, PV50 and PV90 terminology.

+

input_number.predbat_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.predbat_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

+

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 +day from the list of days to use (provided you have more than 1 day selected in days_previous). This can be used to ignore +a single low usage day in your average calculation. By default is feature is enabled but can be disabled only in expert mode.

+

Car Charging

+

There are a number of configuration items in Home Assistant for Predbat to control your car charging.

+

These are described in detail in Car Charging and are listed here just for completeness:

+
    +
  • switch.predbat_car_charging_hold - remove historical car charging load from the house load
    • +
  • input_number.predbat_car_charging_threshold - power threshold above which Predbat assumes the car is being charged
    • +
  • input_number.predbat_car_charging_energy_scale - used to scale the car_charging_energy sensor in apps.yaml
    • +
  • input_number.predbat_car_charging_rate - car's charging rate in kW per hour
    • +
  • input_number.predbat_car_charging_loss - percentage energy lost when charging the car
    • +
  • switch.predbat_octopus_intelligent_charging - controls whether Octopus Intelligent (via the Octopus Energy integration) controls the car charging or Predbat plans the car charging
    • +
  • switch.predbat_octopus_intelligent_ignore_unplugged (expert mode) - used with Octopus Intelligent to prevent Predbat from assuming the car will be charging when the car is unplugged
    • +
  • binary_sensor.predbat_car_charging_slot - set to True by Predbat when the car should be charged (Predbat-led charging)
    • +
  • select.predbat_car_charging_plan_time - the time you want the car to be charged by
    • +
  • switch.predbat_car_charging_plan_smart - allows Predbat to allocate car charging slots to the cheapest times rather than all low rate slots
    • +
  • input_number.predbat_car_charging_plan_max_price - maximum price per kWh to pay when charging your car
    • +
  • switch.predbat_car_charging_from_battery - prevent the car draining the home battery when charging
    • +
  • switch.predbat_car_charging_manual_soc - ignore the car_charging_soc car SoC sensor set in apps.yaml
    • +
  • input_number.predbat_car_charging_manual_soc_kwh - manually maintained car SoC (used if car SoC sensor is not available)
    • +
+

Calculation options

+

See the Predbat mode setting as above for basic calculation options

+

input_number.predbat_forecast_plan_hours is the minimum length of the Predbat charge plan, and is the number of hours after the first charge slot to include in the plan. +The default of 24 hours is the recommended value (to match energy rate cycles). Note that the actual length of the Predbat plan will vary depending upon when the first charge slot is.

+

switch.predbat_calculate_export_oncharge (expert mode) When True calculated export slots will +disable or move charge slots, allowing them to intermix. When False export slots will never be placed into charge slots.

+

switch.predbat_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_inverter_set_charge_before - (expert_mode) When True charge slots will be programmed before their start time, when False they will only be +configured when the charging time starts.

+

switch.predbat_calculate_tweak_plan (expert mode) When True causes Predbat to perform a second pass optimisation +across the next 8 charge and export windows in time order.

+

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 force export late.

+

switch.predbat_calculate_second_pass (expert mode) When True causes Predbat to perform a second pass optimisation +across all the charge and export windows in time order.

+

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 force export late.

+

switch.calculate_import_low_export (expert_mode) When True import slots of the same value are sorted by export price. +When False they are sorted just by price and then time. The default is True.

+

By default with this option enabled if there are multiple charge slots of the same price Predbat will try to charge when the export rates are lowest +thus leaving the higher export slots available.

+

switch.calculate_export_high_import (expert_mode) When True export slots of the same value are sorted by import price (to avoid the low import slots for export). +When False they are sorted just by price and then time. The default is False.

+

By default with this option disabled the latest export slot of the same value will be picked, this is useful for fixed price export tariffs where +you want to export as late in the day as you can.

+

Battery margins and metrics options

+

input_number.predbat_best_soc_keep is the minimum battery level in kWh that Predbat will to try to keep the battery above for the Predbat plan. +This is a soft constraint only that's used for longer term planning and is ignored for the forthcoming first 4 hours of the plan. +As this is not used for short-term planning it's possible for your SoC to drop below this - use input_number.predbat_best_soc_min +if you want to force all charges to be above a set level. +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.

+

input_number.predbat_best_soc_keep_weight (expert_mode) Is used to tune how strongly you want the keep metric to apply. +A value of 0 would essentially ignore keep while higher values will make it more important to always stay above your keep threshold even if it costs +more money to do so.

+

The default is 0.5 - this is the recommended setting.

+

input_number.predbat_best_soc_min (expert mode) sets the minimum charge level (in kWh) for charging during each slot and the +minimum force export 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.

+

input_number.predbat_best_soc_max (expert mode) sets the maximum charge level (in kWh) for charging during each slot. +A value of 0 disables this feature.

+

input_number.combine_rate_threshold (expert mode) sets a threshold (in pence) to combine charge or export slots together into a single larger average rate slot. +The default is 0p which disables this feature and all rate changes result in a new slot.

+

switch.predbat_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 disabled (False)

+

switch.predbat_combine_export_slots (expert mode) Controls if export 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.predbat_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 input_number.predbat_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).

+

input_number.predbat_metric_min_improvement_export (expert mode) Sets the minimum pence cost improvement it's worth doing a forced export for. +A value of 5 is the default which prevents any marginal exports as they must be worth at least 5 pence for a 30 minute slot (less for shorter slots. +If you increase this value (e.g. you only want to force export if definitely very profitable), then exports will become less common. +The value is in pence per 30 minutes of export time.

+

input_number.predbat_rate_low_threshold (expert mode) When set to 0 (the default) Predbat will automatically look at the future import rates in the plan +and determine the import rate threshold below which a slot will be considered to be a potential charging slot.
+If rate_low_threshold is set to a non zero value this will set the threshold below future average import rates as the minimum to consider for a charge window, +e.g. setting to 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.

+

input_number.predbat_rate_high_threshold (expert mode) When set to 0 (the default) Predbat will automatically look at the future export rates in the plan +and determine the threshold above which a slot can be considered a potential exporting slot.
+If rate_high_threshold is set to a non zero value this will set the threshold above future average export rates as the minimum export rate to consider exporting for, +e.g. setting to 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.

+

input_number.predbat_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.

+

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.predbat_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.

+

switch.predbat_calculate_inday_adjustment (expert mode) Enabled by default with damping of 0.95. When enabled will +calculate the difference between today's actual load and today's predicated load and adjust the rest of the days usage +prediction accordingly. A scale factor can be set with input_number.predbat_metric_inday_adjust_damping (expert mode) +to either scale up or down the impact of the in-day adjustment (lower numbers scale down its impact). The in-day adjustment +factor can be seen in predbat.load_inday_adjustment and charted with the In Day Adjustment chart (template can be found +in the charts template in Github).

+

input_number.predbat_carbon_metric (carbon enable) When Carbon footprint tracking is enabled (switch.predbat_carbon_enable) +you can specify a cost per Kg of CO2 used to weight the selection of plans. Values of around 10-200 will give varying outcomes to trade off +cost vs carbon footprint of your system.

+

Note: Carbon footprint tracking can only be enabled if apps.yaml is configured to point to the correct CO2 cost sensor

+

Inverter control options

+

switch.predbat_set_status_notify Enables mobile notification about changes to the Predbat state (e.g. Charge, Export etc). On by default.

+

switch.predbat_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 automatically determined by Predbat to be the +lowest possible rate to meet the charge target. This is only really effective for charge windows >30 minutes. +If this setting is turned on, its strongly recommended that you create a battery_power_charge_curve in apps.yaml +as otherwise the low power charge may not reach the charge target in time. +This setting is off by default.

+

The YouTube video low power charging and charging curve +explains how the low power charging works and shows how Predbat automatically creates it.

+

input_number.predbat_charge_low_power_margin (set_charge_low_power) Controls how many minutes before the completion time to target finishing charging, this defaults to 10 +but can be changed between 0 and 30.

+

switch.predbat_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.

+

switch.predbat_set_export_freeze When enabled will allow Predbat to export Solar to the grid rather than charging the battery. +Enabled by default on those inverters that have this support.

+

switch.predbat_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.

+

switch.predbat_set_export_freeze_only (expert mode) When enabled forced export is prevented, but export 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 switch.predbat_inverter_hybrid set to False then if switch.predbat_inverter_soc_reset (expert mode) is set to True then the +target SOC % will be reset to 100% outside of a charge window. This may be required for the AIO inverter to ensure it charges from solar. The default for +this switch is True but it can be disabled in expert mode if need be.

+

input_number.predbat_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.
+If you want to pre-prepare the battery to retain extra charge in the event of a high likelihood of a grid power outage such as storms predicted, +you can increase set_reserve_min to 100%, and then change it back afterwards.
+(Obviously this is only any use if your inverter is wired to act as an Emergency Power Supply or whole-home backup 'island mode' on the GivEnergy AIO).

+

switch.predbat_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.

+

Balance Inverters

+

When you have two or more inverters it's possible they get out of sync so they are at different charge levels or they start to cross-charge (one discharges into another). +When enabled, balance inverters tries to recover this situation by disabling either charging or discharging from one of the batteries until they re-align.

+

The apps.yaml contains a setting balance_inverters_seconds which defines how often to run the balancing, 30 seconds is recommended if your +machine is fast enough, but the default is 60 seconds.

+

Enable the switch.predbat_balance_inverters_enable switch in Home Assistant to enable this feature.

+
    +
  • switch.predbat_balance_inverters_charge - Is used to toggle on/off balancing while the batteries are charging
    • +
  • switch.predbat_balance_inverters_discharge - Is used to toggle on/off balancing while the batteries are discharging
    • +
  • switch.predbat_balance_inverters_crosscharge - Is used to toggle on/off balancing when the batteries are cross charging
    • +
  • input_number.predbat_balance_inverters_threshold_charge - Sets the minimum percentage divergence of SoC during charge before balancing, default is 1%
    • +
  • input_number.predbat_balance_inverters_threshold_discharge - Sets the minimum percentage divergence of SoC during discharge before balancing, default is 1%
    • +
+

Cloud coverage and load variance

+

Predbat tries to model passing clouds by modulating the PV forecast data on a 5 minute interval up and down while retaining the same predicted total. +The amount of modulation depends on the difference between the PV50% (default) and PV10% scenario produced by Solcast.

+

You can disable this feature (expert mode only) using switch.predbat_metric_cloud_enable

+

Predbat tries to model changes in your household load by modulating the historical data on a 5 minute interval up and down while retaining the same predicted total. +The amount of modulation depends on the standard deviation of your load predictions over the coming period (currently 4 hours).

+

You can disable this feature (expert mode only) using switch.metric_load_divergence_enable

+

iBoost model options

+

Predbat has an 'iBoost model' that can be used to model using excess solar energy to heat hot water (or similar) instead of it being exported to the grid.

+

This model can be used to control any solar diverter device, for example an iBoost (e.g. using a Fingerbot or similar device to physically press the 'boost' button on the iBoost), +a MyEnergy Eddi (using the MyEnergy integration), or it can be used with a high power smart switch to turn on the hot water cylinder immersion heater when there is excess solar.

+

So although Predbat refers to controlling an iBoost, you are not limited to just an iBoost device when using this model within Predbat.

+

To turn the model on, switch.predbat_iboost_enable needs to be enabled.

+

The predicted output from the iBoost solar diverter model is returned in predbat.iboost_best and is populated in the 'iBoost' column of the Predbat plan.

+

iBoost basic configuration

+

When you turn on predbat_iBoost_enable the following additional Home Assistant entities are created by Predbat:

+
    +
  • +

    input_number.predbat_iboost_max_energy Sets the maximum energy in kWh that the solar diverter can consume during a day before turning off - default 3kWh.

    +
    • +
  • +

    input_number.predbat_iboost_max_power Sets the maximum power in watts that the solar diverter will consume - default 2400.

    +
    • +
  • +

    input_number.predbat_iboost_min_power Sets the minimum power in watts that the solar diverter will consume - default 500.

    +
    • +
  • +

    input_number.predbat_iboost_value_scaling Sets how to account for the value of iBoost units of energy. +The default value of 0.75 means that each kWh of energy diverted is accounted for a 0.75 x The lowest future import rate.

    +
    • +
+

Higher values will generate plans with more solar diversion while lower values will generate less. +A value of 0 means all diverted energy should be ignored in planning (assumed to be zero value).

+
    +
  • switch.predbat_iboost_energy_subtract When enabled (default) energy reported by the iboost_energy_today sensor configured in apps.yaml will be subtracted +from your historical load data to improve the accuracy of predictions. +If you are using PredAI you will also need to subtract this data inside PredAI configuration.
    • +
+

Different boost modes can be selected:

+

iBoost modes

+

Solar

+
    +
  • +

    switch.predbat_iboost_solar When enabled assumes the diverter will use solar power to boost the hot water heating. +Only excess solar will be used, this is solar that will be otherwise exported and not stored in your battery.

    +
    • +
  • +

    input_number.predbat_iboost_min_soc sets the minimum home battery SoC percentage that must be in the battery before the solar diverter is turned on. +The default is 0 meaning hot water heating can occur regardless of what SoC level the battery is at.

    +
    • +
+

Battery

+
    +
  • switch.predbat_iboost_charging If set to on, the diverter will operate when the battery is charging (can be combined with solar)
    • +
+

Energy rates only

+

If both of the above are off, but iBoost is enabled then boost will happen solely based on energy rates (see below).

+
    +
  • switch.predbat_iboost_smart Will pick the lowest import rate slots within a 24-hour period to achieve the desired energy as specified by input_number.predbat_iboost_max_energy.
    • +
+

Only slots of at or below the rate threshold will be selected.

+

Note this option only applies when iboost_solar and iboost battery are both off.

+
    +
  • +

    input_number.predbat_iboost_smart_min_length Sets the minimum slot length in minutes to iBoost for (only applies for energy rate only modes). +The default is 30 minutes but can be set in multiples of 30. Increasing this slot size could increase costs depending on your tariff.

    +
    • +
  • +

    switch.predbat_iboost_on_export If set to on allows iBoost to run even if the battery is force exporting to the grid, otherwise it won't run in these circumstances.

    +
    • +
  • +

    switch.iboost_prevent_discharge When set will stop your battery from discharging when iBoost is active and thus prevent your battery from draining to the diverter. +This switch will it will work in all modes is not recommended to be used when iBoost Solar is enabled as it will prevent your battery from discharging during excess solar periods +which could cause additional imports due to passing clouds.

    +
    • +
+

iBoost energy rate filtering

+
    +
  • input_number.predbat_iboost_rate_threshold Sets the maximum import rate (in pence) that the diverter will trigger on, defaults to 100.
    • +
  • +

    input_number.predbat_iboost_rate_threshold_export Sets the maximum export rate (in pence) that the diverter will trigger on, defaults to 100.

    +
    • +
  • +

    switch.predbat_iboost_gas When enabled will control the diverter to only operate when import electric rates are lower than gas rates.

    +
    • +
  • switch.predbat_iboost_gas_export When enabled will control the diverter to only operate when export electric rates are lower than gas rates.
    • +
+

These can be useful if you have the choice to heat your hot water by immersion heater or by gas boiler.

+

Note: Gas rates have to be configured in apps.yaml using metric_octopus_gas.

+
    +
  • input_number.predbat_iboost_gas_scale Sets the scaling of the gas rates (set in apps.yaml)used before comparing with electric rates, to account for gas boiler losses and efficiency.
    • +
+

It should be set to the reciprocal of the boiler efficiency, i.e. for an 80% efficient gas boiler, set to 1.25.

+

iBoost control

+

iBoost output data

+

You will see input_number.predbat_iboost_today entity which tracks the estimated kWh consumed by the solar diverter during the day, and resets at midnight every night.

+

The binary_sensor.predbat_iboost_active entity will be enabled when the solar diverter should be active, can be used for automations to trigger the immersion heater boost.

+

The attributes within this sensor include 'solar' which includes Solar diversion should be active and 'full' which indicates iboost should run at maximum rate (could be +during a charge cycle or grid import).

+

Example template automation for controlling the solar diverter:

+
alias: Solar Diverter
+description: "Start/stop solar diverter based on Predbat determined slots"
+trigger:
+  - platform: state
+    entity_id:
+     - binary_sensor.predbat_iboost_active
+action:
+  - choose:
+      - conditions:
+          - condition: state
+            entity_id: binary_sensor.predbat_iboost_active
+            state: "True"
+        sequence:
+          <commands to turn on your solar diverter>
+      - conditions:
+          - condition: state
+            entity_id: binary_sensor.predbat_iboost_active
+            state: "False"
+        sequence:
+          <commands to turn off your solar diverter>
+mode: single
+
+

If you have an incrementing sensor that tracks the solar diverter energy usage then to make your predictions more accurate you should set the iboost_energy_today sensor in +apps.yaml to point to it, and optionally set iboost_energy_scaling if the sensor isn't in kWh (e.g. set to 0.001 if the sensor is in Watts). +The sensor should be an incrementing sensor which can reset at midnight or not.

+

Holiday mode

+

When you go away you are likely to use less electricity and so the previous load data will be quite pessimistic.

+

Using the Home Assistant entity input_number.predbat_holiday_days_left you can set the number of full days that +you will be away for (including today). The number will count down by 1 day at midnight until it gets back to zero. +Whilst holiday days left is non-zero, Predbat's 'holiday mode' is active.

+

When Predbat's 'holiday mode' is active the historical load data will be taken from yesterday's data (1 day ago) rather than from the days_previous setting in apps.yaml. +This means Predbat will adjust more quickly to the new usage pattern.

+

If you have been away for a longer period of time (more than your normal days_previous setting) then obviously it's going +to take longer for the historical data to catch up, you could then enable holiday mode for another 7 days after your return.

+

In summary:

+
    +
  • For short holidays set holiday_days_left to the number of full days you are away, including today but excluding the return day
    • +
  • For longer holidays set holiday_days_left to the number of days you are away plus another 7 days until the data catches back up
    • +
+

Manual control

+

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 you should then +control it yourself using GivTCP or the App appropriate to your inverter.

+

A better alternative in some cases is to tell Predbat what you want it to do using the manual force features:

+

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 with an upside down 'F' symbol.

+

You can cancel a force slot by selecting the slot time again (it will be shown in square brackets to indicate its already selected).

+

image

+

The select.predbat_manual_export selector can be used to manually force an export within a 30 minute slot in the same way as the manual force charge feature. +The force export takes priority over force charging.

+

The select.predbat_manual_demand selector is used to force Predbat to demand mode during a 30 minute slot, this implies no forced grid charging or exporting of the battery. +House load will be supplied from solar, or from the battery if there is insufficient solar, or grid import if there is insufficient battery charge. +This is described as 'ECO' Mode for GivEnergy inverters but other inverters use different terminology.

+

The select.predbat_manual_freeze_charge selector is used to force Predbat to freeze charge during a 30 minute slot, this implies the battery will not discharge and +hold at the current level. The grid maybe used if solar is not enough to cover the load.

+

The select.predbat_manual_freeze_export selector is used to force Predbat to freeze export during a 30 minute slot, this implies the battery will not charge but will +still discharge for the house load. Any solar will be exported to the grid.

+

When you use the manual override features you can only select times in the next 18 hours, the overrides will be removed once their time +slot expires (they do not repeat).

+

_NOTE: once you select a time slot from any of the select.predbat_manual_ selectors the selected time slot is immediately marked on the drop-down and you can then make another change. +Predbat still has to update the plan which it will be doing so in the background, +and this can take a few minutes to run (depending on the speed and power of the PC you are running Home Assistant on) so don't be surprised why the +Predbat plan doesn't change immediately - remember you can see the date/time the plan was last updated on the first row of the plan.

+

CAUTION: If you leave Predbat turned off for a long period of time then the override timeslots could end up repeating when you restart

+

image

+

Debug

+

switch.predbat_debug_enable when on prints lots of debug, leave off by default

+

switch.predbat_plan_debug (expert mode) when enabled adds some extra debug to the Predbat HTML plan - see Predbat Plan debug mode +for more details.

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/developing/index.html b/developing/index.html new file mode 100644 index 000000000..3ca76f270 --- /dev/null +++ b/developing/index.html @@ -0,0 +1,487 @@ + + + + + + + + Developing on Predbat - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Predbat development
    • +
  • Developing on Predbat
    • +
  • +
    • +
+
+
+
+
+ +

Developing on Predbat

+

Creating a fork

+

Using GitHub, take a fork of Predbat - effectively, this creates +a copy of the main repository, but in your personal space. +There, you can create branches to develop on.

+

Pull requests

+

Once you've completed your work on your branch, you can create a +pull request (PR) to merge your work back in to the main branch +of Predbat.

+

This PR should describe the work you've done in a way that +makes it easy for someone to review your work, and either +add comments or approve it.

+

Unit level testing

+

Note you will need to install python_matplotlib (e.g. brew install python_matplotlib or pip install matplotlib)

+

Predbat now has some unit level tests, to run them on your local machine:

+
    +
  1. Create a test directory somewhere
    2. +
  2. Copy apps.yaml to your test area
    3. +
  3. Run python3 /path/6adb4f0d_predbat/unit_test.py
    4. +
+

If the tests fail then debug them.

+

For coverage analysis installed the 'coverage' library with Python

+
    +
  1. python3 -m coverage run /path/6adb4f0d_predbat/unit_test.py
    2. +
  2. python3 -m coverage html
    3. +
  3. Open htmlcov/index.html in your web browser
    4. +
+

Editing the code

+

There are at least a couple of ways of working on the code, outlined here.

+

Using GitHub Codespaces

+

What is GitHub Codespaces?

+

Especially if you don't need to have a running Home Assistant system +to make the changes you're interested in (e.g. for documentation, +quick fixes etc.) a really easy way to work on the code is using +GitHub Codespaces.

+

GitHub Codespaces gives you a full featured development environment. +This includes:

+
    +
  • A full IDE (a code editor), Visual Studio Code, which can be:
      +
    • Run in the browser, requiring no additional software to +be installed
      • +
    • Run in a virtual machine (VM) running in the cloud which +can connect to a copy of VS Code installed on your own +machine
      • +
    +
    • +
  • A terminal where you can run commands against your codebase +e.g. running pre-commit to run the automatic code quality checks, linting files, etc.
    • +
  • Software like mkdocs to re-generate the documentation files (and other software we may include) +pre-installed in it
    • +
+

The Codespaces environment is entirely separate from your HA +installation, so does not require any modification to your HA +setup to work with it.

+

However, you are modifying code in an environment where you +can't see HA running, so it's great for things like +updating documentation, or writing automated tests, but not +if you need to see your changes live within HA.

+

Running GitHub Codespaces

+

You may with to first install VS Code +on your machine, which does offer some benefits compared to running +Codespaces in the cloud, but this is certainly not essential, and +you'll see the same code editor and terminal, and you'll have the +same commands and Python packages available in the terminal. +The local installation is better in a small number of +scenarios e.g. if you need to connect from your browser to a specific port +on the VM, such as if you're working on the documentation.

+

Importantly, even if you do a local install of VS Code and use that +to edit your code within GitHub, the terminal, the code you're editing +any commands that you run, and any processes like mkdocs that you +may browse to are all running in the Codespaces VM. Your local +VS Code is connected to the VM through SSH. It will appear as if +the code, the terminal etc. are local, but they are not. Running +a local VS Code install connected to Codespaces will not install +Python, Python packages or anything else on your local machine.

+

Now, from your fork or branch, click on the Code button, and select the Codespaces tab. +You can create multiple environments, or use a single environment and swap +between branches in it.

+

codespaces-selection

+

Once you start your Codespaces environment, it'll take a minute to +create a VM for you, and to install the software we've asked it to +install in there. It will also clone your repository and chosen +branch into it for you, and the VM will be authenticated with GitHub +so you can commit and push straight back to your fork of Predbat on GitHub.

+

You can choose between running the IDE in the browser, or having +your local installation of VS Code connect to the environment that GitHub +Codespaces has created for you.

+

The Codespaces will be already set up with Python, along with various +Python packages (as defined in requirements.txt). The environment +is configured through the config in .devcontainer/devcontainer.json.

+

Developing locally within Home Assistant

+

To be documented later.

+

Working on the documentation

+

Overview of the Predbat documentation

+

The documentation site at https://springfall2008.github.io/batpred/ +is built from Markdown files in this repo.

+

The Markdown files used to build the documentation are in the docs/ folder, +with additional config for building the documentation site in mkdocs.yml.

+

If you're making minor changes to the documentation e.g. fixing a spelling, +you can just edit the Markdown files directly, and it will be pushed to the +main documentation site as outlined in the documentation build process +section below, once your changes are merged into main and released.

+

However, if you're doing more than that, e.g. adding new sections, working +with lists etc. we recommend you follow the instructions in +working locally on the documentation +below, as this will give you a live preview of what the documentation +will look like once it's build and published. This will avoid any +unexpected results appearing in the main documentation site.

+

If you are adding a new file, please ensure you add that file to +mkdocs.yml, so it will be linked from the menu in the sidebar.

+

The documentation build process

+

The documentation for the site is built using mkdocs, which will +already be installed if you're using a GitHub Codespaces environment.

+

For a detailed explanation of mkdocs features, please read the +mkdocs documentation.

+

As briefly covered above, mkdocs.yml contains the config for defining the documentation site, +and the documentation is built by mkdocs reading the Markdown files in the docs/ folder, +and creating HTML files from those files. mkdocs can be used locally for previewing, +but is also used as part of the documentation build process that publishes +the official documentation site.

+

The publishing of the documentation is triggered by a GitHub action, +as defined in .github/workflows/main.yml.

+

In short, after configuring the build environment, mkdocs builds the +site, then pushes the HTML produced to the gh-pages branch, +overwriting whatever was there previously.

+

GitHub will then detect a new commit on the gh-pages branch, +and that will trigger another action to run (as defined by GitHub). +This action will take the HTML files on the gh-pages branch, +and will make it available at https://springfall2008.github.io/batpred/.

+

The documentation will be published as it is, with no further +review process, so please ensure you check the documentation +that will be built before merging it in.

+

Working locally on the documentation

+

If you are making changes to the documentation, you can see +a live preview version of the documentation as it will be +built and deployed.

+

This preview version is local to your environment, is +temporary, and does not impact the published version in any way.

+

It's recommended for anything other than simple changes +like fixing spellings, adding a sentence or two. Things like +new sections, lists, new pages etc. are best previewed +due to the complications of various Markdown standards, +as what works on GitHub READMEs, for example, does not +necessarily work with the published documentation site +(which follows a more strict Markdown standard).

+

There are a number of terminal commands that you can use in the Codespaces environment. Open a terminal window in Codespaces by choosing menu > Terminal > New Terminal.

+

To run the live preview, enter mkdocs serve in the terminal window - this will cause mkdocs to build a +local temporary version of the documentation site, +and to temporarily publish it on port 8000 - it will +show the link where you can access the documentation.

+

Also, it will watch the docs/ folder, and any time you change the +files, it will rebuild the site, allowing you to see changes to +the Markdown files in your browser within a few seconds.

+

The site will continue being served until you press CTRL-C to +end the mkdocs serve command.

+

Note, accessing the site published by mkdocs serve is not +possible if you are using Codespaces to run VS Code in the browser, +but it is possible if you're using it via VS Code running locally, +due to the way in which ports on your environment are shared.

+

Coding standards

+

Expected standards

+

This section will be enhanced following discussions as we go.

+

However, here's a starting point:

+
    +
  • Variable names should be lower_case_with_underscores - this fits +with most existing variables, is a common standard for Python code, +and also allows the spell checking to check individual words within +the variable name.
    • +
+

Enforced standards

+

Certain coding standards are enforced within the repository. +Some of them can be auto-fixed, if you do a commit that +fails one of those standards; other issues will need fixing +first, as your pull request won't merge in GitHub until it passes.

+

These standards are enforced by pre-commit, +a tool which is able to run other tools to check, and potentially fix +(for certain types of issues) any mistakes you've made.

+

The .pre-commit-config.yaml file lists all checks that are +currently carried out within the repository. Bear in mind that +these checks are done according to the config within that file +in the branch that you are working in, +so if someone adds a new check, or changes some of the related settings, +it won't apply on your branch until you've merged in their changes.

+

Some of the tools have their own related config files:

+
    +
  • CSpell - .cspell.json and .cspell/custom-dictionary-workspace.txt
    • +
  • Black - pyproject.toml
    • +
  • Markdown Lint - .markdownlint.jsonc
    • +
+

Additional notes on some of the standards:

+
    +
  • CSpell - if you have the spelling check failing due to a word which is valid +but is not in the in-built dictionary, please add that word to the end +of .cspell/custom-dictionary-workspace.txt and stage those changes. +The spell-check should then pass. Note, the dictionary file will get +re-sorted alphabetically when you run pre-commit, so you'll need to +re-stage the file after it's been sorted.
    • +
+

Running the checks locally

+

If you are using a Codespaces environment, you'll already have pre-commit +installed automatically. You can run it manually, or automatically.

+

Running pre-commit manually:

+
    +
  • +

    In a terminal window, running pre-commit will run all the checks against any files that you +have modified and staged.

    +
    • +
  • +

    Alternatively, running pre-commit run --all-files will run all the checks +against all files within the repository.

    +
    • +
  • +

    Note that if pre-commit makes any changes to any files when it runs, +those changes will not be staged. You will need to stage those changes too +before committing.

    +
    • +
  • +

    You may notice pre-commit mentioning about stashing changes - this is +because when it runs, any changes that aren't staged are stashed (saved +away temporarily) so it runs against only the staged changes; +after it has run, it pulls back those stashed changes, so they appear +again (still unstaged).

    +
    • +
+

Running pre-commit automatically:

+
    +
  • +

    If you run pre-commit install in a terminal window it will install a pre-commit hook - +this is a file which tells git to run some code each type you do a +particular action (a pre-commit hook runs at the start of processing +a commit, but there are other hooks e.g. pre-push).

    +
    • +
  • +

    Now, any time you perform a commit, pre-commit will run +automatically on the staged files - this is a handy way of making sure +that you don't accidentally commit code which will fail checks later.

    +
    • +
  • +

    You can still run it manually as outlined above, in addition to the +automated checks that it will do on commits.

    +
    • +
+

Running the checks from within GitHub

+

When commits are done on pull requests, and in any other scenarios +added to the on section of.github/workflows/linting.yml, +the GitHub Actions in that file will run.

+

In particular, the pre-commit.ci lite +action will run. This uses the code here +to run the same checks that get run locally +(as described in the .pre-commit-config.yaml file).

+

This will cause your commit, branch or pull request to get either a green tick +or a red cross against it, to show whether the code passed the checks or not. +This will happen automatically, when you push code on a branch that has a +pull request.

+

In addition, if pre-commit finds any errors that it is able to fix +(e.g. a missing blank line at the end of a file, or trailing whitespace), +it will do a commit of its own to fix those problems, and will push that +commit back to your branch on GitHub. This will then trigger another run, +which should now pass.

+

Note: This means that pre-commit will be adding commits to +your branch - this will need you to be pulling changes from GitHub +so you pick up the changes that have been added by pre-commit +otherwise you will hit a problem when you next try to push a commit +on your branch. You can pull in those changes by running git pull +, which is the equivalent of running git fetch then git merge . +This is no different to working on the same branch with another developer, +but it will be different to the workflow most of us have when working +on Predbat.

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/devices/index.html b/devices/index.html new file mode 100644 index 000000000..70530f1b8 --- /dev/null +++ b/devices/index.html @@ -0,0 +1,334 @@ + + + + + + + + Support 3rd party devices/integrations - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Support 3rd party devices/integrations
    • +
  • +
    • +
+
+
+
+
+ +

Support 3rd party devices/integrations

+

Wallbox Pulsar

+

https://www.home-assistant.io/integrations/wallbox/

+

Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in

+
car_charging_energy: 're:sensor.wallbox_portal_added_energy'
+car_charging_planned:
+  - 're:sensor.wallbox_portal_status_description'
+
+

Wallbox works with Octopus Intelligent GO, and can be triggered via Octopus themselves or via a HA automation linked to the Predbat slot sensor

+

Zappi

+

https://github.com/CJNE/ha-myenergi

+

Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in

+
car_charging_energy: 're:sensor.myenergi_zappi_[0-9a-z]+_charge_added_session'
+car_charging_planned:
+  - 're:sensor.myenergi_zappi_[0-9a-z]+_plug_status)'
+
+

Tesla

+

https://github.com/alandtse/tesla

+

Can be used to extract the cars current SOC and Charge limit. Also can be used to control the cars charging with an automation linked to the Predbat slot sensor

+
car_charging_limit:
+  - 're:number.xxx_charge_limit'
+car_charging_soc:
+  - 're:sensor.xxx_battery'
+
+

Toyota

+

https://github.com/DurgNomis-drol/ha_toyota - For Toyota EU cars only

+

Can be used to extract the cars current SOC.

+
car_charging_soc:
+  - 'sensor.toyota_XXX_battery_level'
+
+

Example sensor name for BZ4X - sensor.toyota_bz4x_battery_level

+

Renault

+

https://www.home-assistant.io/integrations/renault

+

Can be used to extract the cars current SoC.

+
car_charging_soc:
+  - 'sensor.battery'
+
+

Ohme

+

https://github.com/dan-r/HomeAssistant-Ohme

+

Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in. +Also can be used with Octopus Intelligent GO to map out the cars charging slots into Predbat

+

car charging energy

+
car_charging_energy: 'sensor.ohme_session_energy'
+
+

Octopus Intelligent GO

+
octopus_intelligent_slot: 'binary_sensor.ohme_slot_active'
+octopus_ready_time: 'time.ohme_target_time'
+octopus_charge_limit: 'number.ohme_target_percent'
+
+

Note: You should turn on switch.predbat_octopus_intelligent_ignore_unplugged as the Ohme charger does not clear its schedule when unplugged.

+

Using Ohme car charging plans on other tariff's e.g. Agile

+
octopus_intelligent_slot: 'binary_sensor.ohme_slot_active'
+octopus_ready_time: 'time.ohme_target_time'
+octopus_charge_limit: 'number.ohme_target_percent'
+octopus_slot_low_rate: False
+
+

Note: You should turn on switch.predbat_octopus_intelligent_ignore_unplugged as the Ohme charger does not clear its schedule when unplugged.

+

Determine if the car is charging now

+

Normally not recommended if you are on Intelligent GO, but can be useful for ad-hoc charging not planned via Predbat

+
car_charging_now:
+  - 'binary_sensor.ohme_car_charging'
+
+

PodPoint

+

https://github.com/mattrayner/pod-point-home-assistant-component

+

Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in.

+
car_charging_energy: 're:(sensor.psl_[0-9]+_current_energy)'
+car_charging_planned:
+  - 're:(sensor.psl_[0-9]+_status)'
+car_charging_planned_response:
+  - 'plugged in'
+  - 'connected-waiting-for-schedule'
+  - 'suspended-evse'
+  - 'pending'
+  - 'charging'
+car_charging_now:
+  - 're:(sensor.psl_[0-9]+_status)'
+car_charging_now_response:
+  - 'charging'
+
+

Also can be used to control the cars charging with an automation linked to the Predbat slot sensor. +The device needs to be set to 'Smart' mode in the PodPoint app. Your automation trigger should then set the switch.psl_XXXXXX_charging_allowed to on. And off to stop charging. This uses the PodPoint schedule override setting to start/stop the charge.

+

Hypervolt

+

https://github.com/gndean/home-assistant-hypervolt-charger

+

Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in (only V3 models).

+

For plugged in detection on V2 models, see guidance https://springfall2008.github.io/batpred/car-charging/#example-ev-and-charger-setup.

+
car_charging_energy: 're:(sensor.hypervolt_session_energy_total_increasing)'
+car_charging_planned:
+  - 're:(binary_sensor.hypervolt_car_plugged)'
+car_charging_planned_response:
+  - 'on'
+car_charging_now:
+  - 're:(sensor.hypervolt_charging_readiness)'
+car_charging_now_response:
+  - 'charging'
+
+

Note: sensor.hypervolt_session_energy_total_increasing defaults to 'unknown' between charging sessions.

+

Agile Tariff

+

To automate the schedule charging with Predbat, setup the automation to detect when there is a change to binary_sensor.predbat_car_charging_slot.

+

Ensure that select.hypervolt_charge_mode is in 'Boost', when predbat charging slot is 'on', set select.hypervolt_activation_mode to 'Plug and Charge', when it is 'off' set the 'Schedule', this is the recommended method for start/stop charging.

+

Octopus Energy

+

https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy

+

Can be used for energy rates, car charging and saving sessions

+

For energy rate

+
metric_octopus_import: 're:(sensor.(octopus_energy_|)electricity_[0-9a-z]+_[0-9a-z]+_current_rate)'
+metric_octopus_export: 're:(sensor.(octopus_energy_|)electricity_[0-9a-z]+_[0-9a-z]+_export_current_rate)'
+
+

For Octopus Intelligent GO

+
octopus_intelligent_slot: 're:(binary_sensor.octopus_energy([0-9a-z_]+|)_intelligent_dispatching)'
+octopus_ready_time: 're:(time.octopus_energy([0-9a-z_]+|)_intelligent_ready_time)'
+octopus_charge_limit: 're:(number.octopus_energy([0-9a-z_]+|)_intelligent_charge_limit)'
+
+

For Octopus Saving sessions

+
octopus_saving_session: 're:(binary_sensor.octopus_energy([0-9a-z_]+|)_saving_session(s|))'
+octopus_saving_session_octopoints_per_penny: 8
+
+

Nordpool

+

For adjustment to Octopus Intelligent

+

This is built into Predbat, see the apps.yaml configuration guide

+

As your energy rates (e.g. for those in Norway)

+

https://github.com/custom-components/nordpool/

+

Can be linked to Predbat to provide energy rates in your region e.g:

+
metric_octopus_import: 'sensor.nordpool_kwh_oslo_eur_3_10_025'
+
+

Solcast

+

https://github.com/BJReplay/ha-solcast-solar

+

For solar forecast data

+
pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)
+pv_forecast_tomorrow: re:(sensor.(solcast_|)(pv_forecast_|)forecast_tomorrow)
+pv_forecast_d3: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_3|d3))
+pv_forecast_d4: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_4|d4))
+
+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/energy-rates/index.html b/energy-rates/index.html new file mode 100644 index 000000000..e5abc4553 --- /dev/null +++ b/energy-rates/index.html @@ -0,0 +1,436 @@ + + + + + + + + Energy rates - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Energy rates
    • +
  • +
    • +
+
+
+
+
+ +

Energy rates

+

Predbat needs to know what your Import and (optionally) Export rates are so it can plan the optimal way to use your battery. +Your Import and Export rates can be simple flat rates, +more complex time of day tariffs (e.g. Economy 7, Octopus Flux), +or daily/half-hourly rates that track electricity market prices (e.g. Octopus Agile or Tracker).

+

Energy rates are all configured in the apps.yaml file that's stored in either the directory /addon_configs/6adb4f0d_predbat or /config/appdaemon/apps/batpred/config/ directory +depending on what type of Predbat installation method you have used.

+

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 edit this file - see editing configuration files within Home Assistant if you need to install an editor.

+

There are three different ways of configuring your Energy rates in apps.yaml, using the Octopus Energy Integration, using Octopus Rates URL's, +or manually defining your rates and time periods.

+

At least one of these methods must be used to define your import and export rates. If you don't then Predbat will assume zero for your energy rates.

+

Octopus Energy integration

+

If your electricity supplier is Octopus Energy then the simplest way to provide Predbat with your electricity pricing information +is to use the Octopus Energy integration.

+

The Octopus Energy integration connects to your Octopus Energy account and retrieves the tariffs you are on, and the current tariff rates. +If you change tariff within Octopus the integration will automatically retrieve the updated tariff information, and as tariff prices change, again they are automatically retrieved.

+

The integration also provides support for Intelligent Octopus charging to support car charging.

+

Follow the instructions provided in the Octopus Energy integration documentation to install and setup the integration.

+

Once installed, you will need to configure the integration (go to Settings / Devices & Services / Integrations / Octopus Energy then click 'Configure') +and provide the integration with your 'Octopus API key' (that you obtain from your Octopus account : Personal Details / API access).

+

CAUTION To get detailed energy rates needed by Predbat you need to go into Home Assistant and manually enable the following +Octopus Energy events which are disabled by default when the integration is installed:

+
  event.octopus_energy_electricity_xxxxxxxx_previous_day_rates
+  event.octopus_energy_electricity_xxxxxxxx_current_day_rates
+  event.octopus_energy_electricity_xxxxxxxx_next_day_rates
+
+  event.octopus_energy_electricity_xxxxxxxx_export_previous_day_rates
+  event.octopus_energy_electricity_xxxxxxxx_export_current_day_rates
+  event.octopus_energy_electricity_xxxxxxxx_export_next_day_rates
+
+  event.octopus_energy_gas_xxxxxxxx_previous_day_rates
+  event.octopus_energy_gas_xxxxxxxx_current_day_rates
+  event.octopus_energy_gas_xxxxxxxx_next_day_rates
+
+

To enable the above events:

+
    +
  • Go to Settings / Devices & Services / Integrations, choose Octopus Energy, then xx entities
    • +
  • You will see a list of entities (and events) supplied by the Octopus integration
    • +
  • Click the 'Filter' symbol on the top right hand corner (a series of lines in a downwards pointing arrow) and make sure all the options are selected
    • +
  • Then in the left hand-side search entities box, type "current_day"
    • +
  • Click on the first event that comes up, check the name is the right one
    • +
  • Click the cog wheel, then you should see the option to enable the event
    • +
  • Click the option to enable the event and press 'Update' to make the change
    • +
+

Repeat this for the other events.

+

The gas rates are only required if you have a gas boiler, an iBoost, and are using Predbat to determine whether it's cheaper to heat your hot water with the iBoost or via gas.

+

Verify that the integration is working correctly in Home Assistant by going to Developer Tools / States, and enter 'octopus' in the 'Filter entities' box. +Confirm that the Octopus entities are being populated correctly.

+

Configuring Predbat to use the Octopus Energy integration

+

The following configuration items in apps.yaml are used to configure Predbat to use the Octopus Energy integration. +They are set to a regular expression and should be auto-discovered so that Predbat automatically uses the Octopus Energy integration, +but you can comment out the regular expression lines to disable, or you set them manually.

+
    +
  • metric_octopus_import - Import rates from the Octopus Energy integration, should point to the sensor sensor.octopus_energy_electricity_METER_NUMBER_current_rate
    • +
  • metric_octopus_export - Export rates from the Octopus Energy integration, should point to the sensor sensor.octopus_energy_electricity_METER_NUMBER_export_current_rate
    • +
  • metric_octopus_gas - Gas rates from the Octopus Energy integration, should point to the sensor sensor.octopus_energy_gas_METER_NUMBER_current_rate
    • +
  • octopus_intelligent_slot - If you have the Octopus Intelligent Go tariff this should point to the 'slot' sensor binary_sensor.octopus_energy_ACCOUNT_ID_intelligent_dispatching
    • +
+

metric_octopus_gas is (as above) only required to be configured if you are using Predbat to determine whether to heat your hot water via your iBoost or gas.

+

If you do not have an export rate, or are not on the Octopus Go tariff, then the appropriate lines can be commented out in apps.yaml.

+

Standing charge

+

Predbat can also (optionally) include the daily standing charge in cost predictions. +The following configuration item in apps.yaml defaults to obtaining the standing charge from the Octopus Energy integration:

+
    +
  • metric_standing_charge - Standing charge in pounds. By default points to the Octopus Energy integration sensor sensor.octopus_energy_electricity_METER_NUMBER_current_standing_charge
    • +
+

You can manually change this to a standing charge in pounds, e.g. 0.50 is 50p, or delete this line from apps.yaml, or set it to zero +if you don't want the standing charge (and only have consumption usage) to be included in Predbat charts and output data.

+

Octopus Saving sessions

+

Predbat is able to automatically join you to Octopus saving sessions and plan battery activity for the saving session period to maximise your income.

+

For Predbat to automatically manage Octopus saving sessions the following additional configuration item in apps.yaml is used. +Like the electricity rates this is set in the apps.yaml template to a regular expression that should auto-discover the Octopus Energy integration.

+
    +
  • octopus_saving_session - Indicates if a saving session is active, should point to the sensor binary_sensor.octopus_energy_ACCOUNT_ID_octoplus_saving_sessions.
    • +
+

When a saving session is available it will be automatically joined by Predbat and should then appear as a joined session within the next 30 minutes.

+

In the Predbat plan, for joined saving sessions the energy rates for import and export will be overridden by adding the assumed saving rate to your normal rate. +The assumed rate will be taken from the Octopus Energy integration and converted into pence +using the octopus_saving_session_octopoints_per_penny configuration item in apps.yaml (default is 8).

+

If you normally cut back your house usage during a saving session then you can change input_number.predbat_load_scaling_saving to allow Predbat to assume an energy +reduction in this period. E.g. setting to a value of 0.8 would indicate you will use 80% of the normal consumption in that period (a 20% reduction).

+

As the saving session import and export rates are very high compared to normal Predbat will plan additional export during the saving session period. +If necessary, a pre-charge may happen at some point during the day to maintain the battery right level for the session.

+

Note that Predbat's operational mode select.predbat_mode must be set to either 'Control charge' +or 'Control charge & discharge' for Predbat to be able to manage the battery for the saving session.

+

If you do not have an export tariff then forced export will not apply and Predbat will just ensure you have enough battery charge to see you through the saving session period.

+

If you do not want Predbat to automatically join Octopus saving sessions and manage your battery activity for the session, +simply delete or comment out the octopus_saving_session entry in apps.yaml.

+

Octopus free (power up) events

+

Predbat can automatically detect Octopus free events and adjust your battery plan according.

+

For Predbat to automatically manage Octopus free sessions the following additional configuration item in apps.yaml is used.

+

Note: You must have signed up to Octoplus to benefit from these events

+

Like the electricity rates this is set in the apps.yaml template to a regular expression that should auto-discover the Octopus Energy integration.

+

octopus_free_session - Will point to the free event sensor that is exposed by the Octopus Energy Integration. This event sensor contains the dates/times of +all the free events.

+
  octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)'
+
+

Note: This event may need to be enabled in Home Assistant first How to Enable Octopus events

+

If you normally increase your house usage during a free session then you can change input_number.predbat_load_scaling_free to allow Predbat to assume an energy +increase in this period. E.g. setting to a value of 1.2 would indicate you will use 20% more energy that normal during this period. (Default is 1.2)

+

If you do not want Predbat to see these sessions then comment out the octopus_free_session setting.

+

Note: If the above is not working due to lack of data (via a 3rd party service) Predbat can scrape directly from the Octopus Web Site, this may +have its own issues due to change of format. If you enable this then sessions will be considered even if you forget to sign-up so be careful!

+
octopus_free_url: 'http://octopus.energy/free-electricity'
+
+

Octopus Rates URL

+

If you do not wish to use the Octopus Energy integration and are an Octopus Energy customer then you can configure Predbat to get the electricity rates +directly online from the Octopus website.

+

In apps.yaml configure the following lines:

+
    +
  • rates_import_octopus_url to point to the appropriate import tariff URL on the Octopus website
    • +
  • rates_export_octopus_url to point to the export tariff URL
    • +
+

e.g.

+
  rates_import_octopus_url : "https://api.octopus.energy/v1/products/FLUX-IMPORT-23-02-14/electricity-tariffs/E-1R-FLUX-IMPORT-23-02-14-A/standard-unit-rates"
+  rates_import_octopus_url : "https://api.octopus.energy/v1/products/AGILE-FLEX-BB-23-02-08/electricity-tariffs/E-1R-AGILE-FLEX-BB-23-02-08-A/standard-unit-rates"
+
+  rates_export_octopus_url: "https://api.octopus.energy/v1/products/FLUX-EXPORT-BB-23-02-14/electricity-tariffs/E-1R-FLUX-EXPORT-BB-23-02-14-A/standard-unit-rates"
+  rates_export_octopus_url: "https://api.octopus.energy/v1/products/AGILE-OUTGOING-BB-23-02-28/electricity-tariffs/E-1R-AGILE-OUTGOING-BB-23-02-28-A/standard-unit-rates/"
+  rates_export_octopus_url: "https://api.octopus.energy/v1/products/OUTGOING-FIX-12M-BB-23-02-09/electricity-tariffs/E-1R-OUTGOING-FIX-12M-BB-23-02-09-A/standard-unit-rates/"
+
+

If you configure the rates_import_octopus_url then Predbat will use this instead of metric_octopus or rates_import. +Similarly rates_export_octopus_url takes precedence over metric_octopus_export or rates_export.

+

Configuring the Octopus rates URL is an expert feature and for most users the Octopus Energy integration is a simpler solution to use.

+

Rate Bands to manually configure Energy Rates

+

If you are not an Octopus Energy customer, or you are but your energy rates repeat in a simple manner, you can configure your rate bands in apps.yaml using rates_import/rates_export/rates_gas.

+

Add the following entries to apps.yaml to define the pattern of rates over a 24-hour period:

+
rates_import:
+  - start: "HH:MM:SS"
+    end: "HH:MM:SS"
+    rate: pence
+rates_export:
+  - start: "HH:MM:SS"
+    end: "HH:MM:SS"
+    rate: pence
+rates_gas:
+  - start: "HH:MM:SS"
+    end: "HH:MM:SS"
+    rate: pence
+
+

start and end are in the time format of "HH:MM:SS" e.g. "12:30:00" and should be aligned to 30 minute slots normally. +rate is in pence e.g. 4.2

+

start and end can be omitted and Predbat will assume that you are on a single flat rate tariff.

+

If there are any gaps in the 24-hour period then a zero rate will be assumed.

+

The gas rates are only required if you have a gas boiler, an iBoost, and are using Predbat to determine whether it's cheaper to heat your hot water with the iBoost or via gas.

+

Manually over-riding energy rates

+

You can also override the import or export energy rates (regardless of whether they are set manually or via the Octopus Energy integration) by using the override feature in apps.yaml.

+

Rate override is used to set the specific date and time period where your rates are different, e.g. an Octopus Power Up session (zero rate for an hour or two), +or the British Gas half-price electricity on Sunday's.

+

Unfortunately there aren't any API's available to feed this information automatically into Predbat so you will have to edit apps.yaml manually +to set the appropriate rate over-ride dates and times:

+
rates_import_override:
+  - date: "YYYY-MM-DD"
+    start: "HH:MM:SS"
+    end: "HH:MM:SS"
+    rate: pence
+rates_export_override:
+  - date: "YYYY-MM-DD"
+    start: "HH:MM:SS"
+    end: "HH:MM:SS"
+    rate: pence
+
+

Optionally you can add a predicted load scaling factor for these periods using load_scaling, for example:

+
rates_import_override:
+  - date: '2024-01-21'
+    start: '17:30:00'
+    end: '18:30:00'
+    rate: 150
+    load_scaling: 0.8
+
+

This instructs Predbat that during a 1 hour period at 5:30-6:30pm on 21st of Jan set the import rate to 150p and assume our load will be 80% of normal (20% lower).

+

You can also make relative adjustments to your energy rates, e.g. if you want to avoid exporting during peak periods to improve your energy +saving session results you could make a relative adjustment to your export rates using rate_increment. +The reason not to just set rate is then when an energy saving session is active you do not want to ignore the higher export rate that is automatically provided by Octopus.

+

In this example we subtract 10p from our export rate during the period that saving sessions normally fall within and thus steer Predbat away from +force exporting during that time. The saving session will still work correctly as a 10p adjustment on rates >100p will have little/no impact.

+
rates_export_override:
+  - start: '17:00:00'
+    end: '19:00:00'
+    rate_increment: -10
+
+

You can also use a similar but opposite approach of setting a positive export rate_increment to encourage Predbat to discharge the battery at certain time periods.

+

If you have a very low overnight rate (such as Octopus Go) and want to ensure your battery is discharged just before the low rate period, +but you don't want to risk the battery running out too early (and importing at a higher rate), +you can add a rate export override for the period you want to discharge just before the low rate period:

+
rates_export_override:
+  - start: '22:30:00'
+    end: '23:30:00'
+    rate_increment: 10
+
+

You can also use rate_increment with load_scaling, e.g. a rate_increment of 0 can be used to just apply load scaling to certain defined periods.

+
    +
  • date is optional and if specified must be in the date format of "YYYY-MM-DD" e.g. "2023-09-09". +If a date is specified then the rate override applies that specific date, otherwise it applies to all dates
    • +
  • start and end must be specified in "HH:MM:SS" time format e.g. "12:30:00"
    • +
  • load_scaling is an optional percentage change factor in house load for the period - 1.0 would be no change, 0.8 is 80% of nominal house load, +2.0 would be a 100% increase (i.e. 2x) on normal historic house load
    • +
  • rate is optional figure in pence to override the rate for the specific period
    • +
  • rate_increment is optional and is the number of pence to add (or subtract) to the reported energy rates during this period
    • +
+

Rate offsets

+

If you are on an Agile or Tracker tariff you can tune future unknown energy rates by adjusting the entities input_number.predbat_metric_future_rate_offset_import (expert mode) +and input_number.predbat_metric_future_rate_offset_export (expert mode) inside Home Assistant to set the predicted offset for future unknown rates.

+

Future Agile energy rates

+

In the energy market it's possible to calculate the Octopus Agile rates from around 10am UK time using public data, you can +enable this in apps.yaml for Import, Export or both. This will approximate next day's rates based on the spot prices. +The approximation is only used until the real Octopus Agile rates are released around 4pm.

+
    +
  • futurerate_url - URL of future energy market prices; this should not normally need to be changed
    • +
  • futurerate_adjust_import and futurerate_adjust_export - Whether tomorrow's predicted import or export prices should be adjusted based on energy market prices or not. +Set these depending upon whether you have an agile tariff for import, export or both
    • +
  • futurerate_peak_start and futurerate_peak_end - during the peak period Octopus apply an additional peak-rate price adjustment. +These configuration items enable the peak-rate hours to be adjusted
    • +
+

CAUTION: You may violate the terms and conditions of the Nordpool site if you use this data and as such the authors of +Predbat accept no responsibility for any violations:

+

https://www.nordpoolgroup.com/en/About-us/terms-and-conditions-for-useofwebsite/

+
futurerate_url: 'https://dataportal-api.nordpoolgroup.com/api/DayAheadPrices?date=DATE&market=N2EX_DayAhead&deliveryArea=UK&currency=GBP'
+futurerate_adjust_import: True
+futurerate_adjust_export: False
+futurerate_peak_start: "16:00:00"
+futurerate_peak_end: "19:00:00"
+
+

Grid Carbon intensity

+

Predbat can also track Carbon intensity by linking it to an integration which provides this data.

+

UK Grid Carbon intensity

+

The National Grid provides this data, please install this integration: https://github.com/jfparis/sensor.carbon_intensity_uk

+

Once it is active update apps.yaml to link Predbat to the Sensor (if its not already in your template):

+
# Carbon Intensity data from National grid
+carbon_intensity: 're:(sensor.carbon_intensity_uk)'
+
+

By enabling switch.predbat_carbon_enable you can view Carbon Intensity in the predbat plan.

+

Predbat can also optimise your grid charging based on the Carbon footprint by setting input_number.predbat_carbon_metric.

+

image

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/faq/index.html b/faq/index.html new file mode 100644 index 000000000..c0e0ea2c3 --- /dev/null +++ b/faq/index.html @@ -0,0 +1,442 @@ + + + + + + + + FAQ - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • FAQ
    • +
  • +
    • +
+
+
+
+
+ +

FAQ

+

I've installed Predbat but I don't see the correct entities

+
    +
  • First look at predbat.status in Home Assistant and the Predbat/AppDaemon add-on log (which can be found in the list of log files in the System/Log area of the GUI). +See if any errors are warnings are found. If you see an error it's likely something is configured wrongly, +check your entity settings are correct.
    • +
  • Make sure Solcast is installed and it's auto-updated at least a couple of times a day (see the Solcast instructions). +The default solcast sensor names maybe wrong, you might need to update the apps.yaml config to match your own names +(some people don't have the solcast_ bit in their names)
    • +
  • Did you configure AppDaemon apps_dir correctly in appdaemon.yaml?
    • +
+

Why is my predicted charge % higher or lower than I might expect?

+
    +
  • Predbat is based on costing, so it will try to save you money. If you have the PV 10% option enabled it will also +take into account the more worse case scenario and how often it might happen, so if the forecast is a bit unreliable +it's better to charge more and not risk getting stung importing.
    • +
  • Have you checked your energy rates for import and export are correct, maybe check the rates graph and confirm. +If you do something like have export>import then Predbat will try to export as much as possible.
    • +
  • Have you tuned Solcast to match your output accurately?
    • +
  • Have you tuned predbat_best_soc_keep settings?
    • +
  • Do you have predicted car charging during the time period?
    • +
  • You can also tune predbat_load_scaling and predbat_pv_scaling to adjust predictions up and down a bit
    • +
  • Maybe your historical data includes car charging, you might want to filter this out using car_charging_hold in apps.yaml
    • +
+

Why didn't the slot actually get configured?

+
    +
  • Are you in read-only mode?
    • +
+

My plan doesn't include any charging?

+
    +
  • Do you have the predbat_mode set to Control charge (or Control charge & discharge)?
    • +
+

The charge limit keeps increasing/decreasing in the charge window or is unstable

+
    +
  • Check you don't have any other automations running that adjust GivTCP settings during this time. Some people had +a script that changes the reserve %, this will cause problems - please disable other automations and retry.
    • +
+

I changed a config item but it made no difference?

+
    +
  • You might have to wait a few minutes until the next update cycle. Depending on the speed of the computer that Predbat is running on, it can take 1-5 minutes for Predbat to run through. +You can see the date/time that Predbat last completed a run at the start of the Predbat HTML plan.
    • +
+

It's all running but I'm not getting very good results

+
    +
  • You might want to tune input_number.predbat_best_soc_keep to set a minimum target battery level, e.g. I use 2.0 (for 2kWh, which is just over 20% on a 9.5kWh battery). +If you set input_number.predbat_best_soc_keep too high then predbat could need to charge the battery in unfavourable import rates, so try to set it to a fairly low value, +especially if you have a small battery. If you set it to zero then predbat may not charge at all, so use 0.1 as a minimum.
    • +
  • Have a read of the energy rates configuration guide as depending on your tariff different settings maybe required
    • +
  • Check your solar production is well calibrated (you can compare solcast vs actually in the Home Assistant energy tab or on the GivEnergy portal)
    • +
  • Make sure your inverter max AC rate has been set correctly
    • +
  • If you have an EV that you charge then you will want some sort of car charging sensor or use the basic car charging hold feature or your load predictions maybe unreliable - see +Car charging
    • +
  • Do you have a solar diverter? If so maybe you want to try using the iBoost model settings.
    • +
  • 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)
    • +
+

When my battery is charging to 100% is fluctuates between 98% and 100%, and/or gives an error setting reserve

+

Some inverters e.g. GE AIO inverter won't allow the reserve to be set too 100, in which case set in apps.yaml

+
inverter_reserve_max : 98
+
+

And this should prevent the issue

+

The plan doesn't charge or discharge when I expect it to

+

Predbat can only work on the information its given, although it does run every 5 minutes when it re-evaluates the plan and adjusts if necessary.

+

The plan Predbat produces assumes that your average load and PV forecasts are accurate and Predbat will aim to give you the maximum return.

+

Make sure you have setup your Solcast solar forecast correctly with the number of panels, orientation, output, etc.

+

Projected daily load is determined from historical load information so make sure you have set days_previous and days_previous_weight in apps.yaml +to give appropriately representative load history to Predbat, and read the longer explanation of how days_previous works.

+

You could adjust input_number.predbat_load_scaling to 1.2 so the plan will incorporate 20% more expected load if you want to be more pessimistic about historical load, +and input_number.predbat_pv_scaling to similarly adjust the PV forecast - these and other adjustment options are described in the Scaling and Weight options.

+

It is very important to correctly set Predbat's Battery Loss Options +and Battery Margins 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 to suit their needs.

+

The SoC level that Predbat aims to keep in the battery input_number.predbat_best_soc_keep +and the absolute minimum SoC level input_number.predbat_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. +Conversely if you find Predbat is letting the battery exhaust too early, set predbat_best_soc_keep to 1.0 so Predbat will aim to keep 1kWh available for unexpected load.

+

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.predbat_battery_loss, input_number.predbat_battery_loss_discharge and input_number.predbat_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 then you can see the +effective import and export rates after losses that Predbat calculates in the Predbat plan.

+

Predbat also uses input_number.predbat_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.predbat_metric_min_improvement and input_number.predbat_metric_min_improvement_discharge (both expert mode settings) also affect Predbat's cost optimisation decisions +as to whether its cost beneficial to charge or discharge the battery +so could be tweaked if you feel Predbat is charging or discharging with marginal benefits. The defaults (0p and 0.1p respectively) should however give good results for most users.

+

Finally, it could be worth considering adding import or export rate increments to apps.yaml if you want to direct Predbat +to avoid or encourage charging or discharging in certain time periods - e.g. avoiding exporting in the time period saving sessions normally fall in, +or to encourage discharging just before import rates fall overnight.

+

Predbat is causing warning messages about 'exceed maximum size' in the Home Assistant Core log

+

If you have a large input_number.predbat_forecast_plan_hours then you may see warning messages in the Home Assistant Core log about the size of a number of Predbat entities, +the message will be "State attributes for predbat.XXXX exceed maximum size of 16384 bytes".

+

This is just a warning, the Predbat entity attributes aren't stored in the database anyway, +but you can suppress these warnings by adding the following to your configuration.yaml file:

+
# Filter out 'message too large' warnings from Predbat entities
+logger:
+  default: warning
+  filters:
+    homeassistant.components.recorder.db_schema:
+      - "State attributes for predbat.base10_export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.base10_import_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.base10_metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.base10_pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.battery_cycle exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.battery_cycle_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.battery_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.battery_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best_charge_limit exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best_export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best_import_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best_load_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best_metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best_pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best10_export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best10_import_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best10_metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.best10_pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.cost_today_export exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.cost_today_import exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.grid_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.grid_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.load_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.load_energy_actual exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.load_energy_adjusted exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.load_energy_predicted exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.load_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.load_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.plan_html exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.pv_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.pv_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.rates exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.soc_kw exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.soc_kw_base10 exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.soc_kw_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+      - "State attributes for predbat.soc_kw_best10 exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored"
+
+

Error - metric_octopus_import not set correctly or no energy rates can be read

+

If you get this error in the Predbat log file:

+
    +
  • Check that the Octopus integration is working and that event.octopus_energy_electricity_METER_NUMBER_current_day_rates +and sensor.octopus_electricity_energy_METER_NUMBER_current_rate are both populated by the integration.
    • +
  • Ensure that you have followed the Octopus Integration Installation instructions, including enabling the Octopus Integration events.
    • +
  • If you been using an older version of the Octopus integration and have upgraded to version 9 or above, then you may find that your energy sensors are named sensor.electricity_METER_NUMBER_current_rate +(i.e. no 'octopus_energy_' prefix) but the 'event' entities have the 'octopus_energy' prefix.
    +If the 'event' and 'sensor' entities are not consistently named then Predbat will not be able to find the event entities if the sensor names don't match what's expected.
    +To fix this, uninstall the Octopus integration, reboot Home Assistant, +delete all the old Octopus sensors, and re-install the Octopus Integration.
    • +
+

WARN: No solar data has been configured

+

If you get this warning message in the Predbat log file or you see that the 'PV kWh' column in the Predbat plan card is completely blank:

+
    +
  • Ensure that you have installed and configured Solcast correctly
    • +
  • Check the Solcast integration in Home Assistant is configured and enabled (go to Settings / Integrations / Solcast )
    • +
  • Check that there are no errors relating to Solcast in the Home Assistant log (go to Settings / System / Logs and view the 'Home Assistant Core' log). +If you see an error 429 message in the log then this is as a result of Solcast's rate limiting for Hobbyist accounts. +The only fix is to re-run the 'Solcast update' automation and hope that Solcast isn't as busy when you re-run.
    • +
  • Verify the solar forecast has been populated in Home Assistant by going to Developer Tools / States, filtering on 'solcast', +and checking that you can see the half-hourly solar forecasts in the Solcast entities
    • +
  • If you can see the solcast entities but there are no forecast PV figures, try running the 'Solcast update' automation you created, and check again the solcast entities
    • +
  • If the solcast entities are still not populated, try reloading the Solcast integration (go to System / Devices & Services / Integrations tab, click on 'Solcast PV Forecast', +click the three vertical dots beside 'Configure' and choose 'Reload' from the dropdown menu)
    • +
  • Check sensor.solcast_pv_api_limit (it's normally 10 for new Solcast accounts) meaning you can call the Solcast API 10 times a day +(but if you have two solar arrays, e.g. East/West) then retrieving the forecast will count as two API calls.
    +Compare this to sensor.solcast_pv_api_used to see how many Solcast API calls you have made today +(alternatively, you can confirm how many API calls you have made today by logging into your Solcast account).
    +If you've run out of API calls you will have to wait until midnight GMT for the API count to reset. +It's recommended that you don't include the Solcast forecast within your GivEnergy portal to avoid running out of API calls.
    • +
  • Check the Solcast server API status is OK
    • +
+

Note: Can not find battery charge curve

+

If you get the message "Note: Can not find battery charge curve, one of the required settings for soc_kw, battery_power and charge_rate are missing from apps.yaml" in the logfile +then Predbat is trying to create a battery charge curve but does not have access to the required history information in Home Assistant.

+

Creating the battery charge curve is described in the apps.yaml document. +The most likely cause of the above message appearing in the logfile is that you are controlling the inverter in REST mode +but have not uncommented the following entities in apps.yaml that Predbat needs to obtain history from to create the battery charge curve:

+
  charge_rate:
+    - number.givtcp_{geserial}_battery_charge_rate
+  discharge_rate:
+    - number.givtcp_{geserial}_battery_discharge_rate
+  battery_power:
+    - sensor.givtcp_{geserial}_battery_power
+  soc_kw:
+    - sensor.givtcp_{geserial}_soc_kwh
+
+

WARN: Inverter is in calibration mode

+

If you see the message "WARN: Inverter is in calibration mode, Predbat will not function correctly and will be disabled" in the logfile, +then Predbat has identified that your inverter is currently calibrating your battery. Predbat's status will also be set to 'Calibration'.

+

Predbat will set the inverter charge and discharge rates to maximum (if they are not already), SoC target to 100% and battery reserve to minimum (usually 4%), +and will not execute the plan nor enable battery charge or discharge.

+

Once the inverter finishes calibrating the battery, Predbat will resume normal operations.

+

Inverter time is xxx, Predbat computer time is xxx, this is xxx minutes skewed, Predbat may not function correctly

+

If the predbat.status gives a warning error about the inverter time:

+

IMAGE

+

Then it indicates that there is a mis-match between the clock that Predbat is using and the inverter time clock, and clearly with a clock mis-match, +charging and discharging your battery at specific times may not work as expected.

+

There are several potential causes of this problem:

+
    +
  • Check that the inverter time is correctly set, especially that its set to GMT (even if its summer time). +In the GivEnergy portal, go to My Inverters / Remote Control (cog symbol) / click SEND next to 'Set Date and Time'
    • +
  • Check that the time_zone in appdaemon.yaml is correctly set for your location (e.g. Europe/London)
    • +
  • The time zone for Predbat in apps.yaml needs to be set to the same value
    • +
  • Finally, check how often your inverter integration is polling your inverter for new data. For GivTCP the Self Run Loop Timer +is recommended to be set to a value of between 20 and 60 seconds.
    • +
+

If you have checked the above and keep getting “time is skewed” warnings then it means Home Assistant/predbat isn’t getting the same time from the inverter as it is expecting. +Either GivTCP has lost communications with the inverter or the inverter is stopped talking to the world.

+

If you look at the Logbook in Home Assistant you should see a steady stream of entities changing in HA. +In particular you will see the GivTCP inverter time entity changing every polling period, e.g. every 20 seconds.

+

Possible fixes:

+
    +
  • restart the GivTCP add-on
    • +
  • restart Home Assistant (although usually restarting GivTCP is enough)
    • +
  • power the inverter off, turn off panels and battery first, then the inverter, then follow the reverse sequence to power the inverter back on again. +This forces the inverter to reconnect to your wifi
    • +
  • do a ‘reset to defaults’ in the portal
    • +
+

If you keep getting the warning message, even sporadically, then this points to an underlying issue in your home network between Home Assistant and the inverter. +You may need to add a Wi-Fi repeater or ideally a fixed Ethernet connection to your inverter to improve signal strength if this keeps happening.

+

There is a Home Assistant automation that will alert you if GivTCP stops sending data to predbat.

+

I have another problem not listed above

+

If you are still having trouble feel free to raise a Github ticket for support

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/images/GivTCP-recommended-settings.png b/images/GivTCP-recommended-settings.png new file mode 100644 index 000000000..ebb4554cc Binary files /dev/null and b/images/GivTCP-recommended-settings.png differ diff --git a/images/Inverter-time-warning.png b/images/Inverter-time-warning.png new file mode 100644 index 000000000..f8b5b906c Binary files /dev/null and b/images/Inverter-time-warning.png differ diff --git a/images/codespaces-selection.png b/images/codespaces-selection.png new file mode 100644 index 000000000..484250818 Binary files /dev/null and b/images/codespaces-selection.png differ diff --git a/images/load_forecast.png b/images/load_forecast.png new file mode 100644 index 000000000..217f00a1b Binary files /dev/null and b/images/load_forecast.png differ diff --git a/images/output_data_dashboard_sample.png b/images/output_data_dashboard_sample.png new file mode 100644 index 000000000..3c5d0a1f2 Binary files /dev/null and b/images/output_data_dashboard_sample.png differ diff --git a/images/output_data_dynamic_dashboard.png b/images/output_data_dynamic_dashboard.png new file mode 100644 index 000000000..07fcf7b21 Binary files /dev/null and b/images/output_data_dynamic_dashboard.png differ diff --git a/images/predbat-html-debug-plan.png b/images/predbat-html-debug-plan.png new file mode 100644 index 000000000..c95e86104 Binary files /dev/null and b/images/predbat-html-debug-plan.png differ diff --git a/images/predbat-html-plan.png b/images/predbat-html-plan.png new file mode 100644 index 000000000..09e6e5e5d Binary files /dev/null and b/images/predbat-html-plan.png differ diff --git a/images/predbat-status-issue.png b/images/predbat-status-issue.png new file mode 100644 index 000000000..f599cb3cc Binary files /dev/null and b/images/predbat-status-issue.png differ diff --git a/img/favicon.ico b/img/favicon.ico new file mode 100644 index 000000000..e85006a3c Binary files /dev/null and b/img/favicon.ico differ diff --git a/index.html b/index.html new file mode 100644 index 000000000..9088e341a --- /dev/null +++ b/index.html @@ -0,0 +1,237 @@ + + + + + + + + Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Introduction
    • +
  • +
    • +
+
+
+
+
+ +

Introduction

+

Home battery prediction and automatic charging for Home Assistant supporting multiple inverters including:

+
    +
  • GivEnergy Hybrid, AC and AIO
    • +
  • Solis
    • +
  • Solax
    • +
  • Sunsynk
    • +
  • Huawei
    • +
  • SolarEdge
    • +
  • Fox
    • +
  • Sofar
    • +
  • LuxPower
    • +
  • Solar Assistant
    • +
+

Also known by some as Batpred or Batman!

+

icon image

+
Copyright (c) Trefor Southwell April 2024 - All rights reserved
+This software maybe used at not cost for personal use only
+No warranty is given, either expressed or implied
+
+

For support please raise a Github ticket or use the Facebook Group: Predbat and +watch my YouTube Channel

+

Some inverters have their own groups also e.g:

+ +

If you want to buy me a beer then please use Paypal - tdlj@tdlj.net +image

+

Taster

+

Once you are up and running you will get a chart that predicts your battery levels over time:

+

image

+

And you can also see this in a plan format predicting your overall costs and your carbon footprint (if enabled, UK only for now):

+

image

+

image

+

You can see a cost over time for the plan that Predbat has made and also how it might turn out if your solar production (should you have solar) +is lower than expected or if you use a bit more energy than planned (10% scenario):

+

image

+

You can see your energy rates over time and where the battery is being charged:

+

image

+

Power charts can show you how the prediction maps to your inverter:

+

image

+

You can model iBoost or similar solar diverters, this will be shown on your plan and you can even use it to trigger smart devices e.g. +an emersion heater based on energy rates.

+

image

+

You can predict when your car will charge and use Predbat to schedule the cheapest car charging slots:

+

image

+

Charts can track your cost saving using Predbat and from having a PV and Battery system

+

image

+

The calibration chart is useful for tuning the model for things like inverter losses until it matches reality:

+

image

+

Predbat can track your actual vs predicted energy usage and make real time adjustments to the predictions if you use more or less:

+

image

+

You can tune lots of parameters to match your system and needs:

+

image +image

+

You can also override the plan on a temporary basis if you have a particular reason to:

+

image

+

Please read the documentation for more information!

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + + Next » + + +
+ + + + + + + + + + + diff --git a/install/index.html b/install/index.html new file mode 100644 index 000000000..c9554aad1 --- /dev/null +++ b/install/index.html @@ -0,0 +1,678 @@ + + + + + + + + Install details - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Install details
    • +
  • +
    • +
+
+
+
+
+ +

Install

+

These instructions will take you through the process of installing and configuring Predbat for first time use.

+

If you have a working Predbat installation using AppDaemon and are changing to use the Predbat add-on, +the AppDaemon to Predbat add-on upgrade process is described below.

+

It's recommended that you watch the Predbat Video Guides before you start.

+

We have tried to make the documentation as comprehensive as possible but a level of familiarity with the basics of +Home Assistant, Add-on's, Integrations, Entities, File Editing and YAML is assumed. +There are plenty of "Home Assistant basics" tutorials on YouTube, but here are a few useful videos to introduce you to Home Assistant and displaying inverter data:

+ +

If you get stuck, please read the FAQ's and if necessary raise a Github ticket for support.

+

Inverter Control install

+

You will need to install an integration to communicate with and control your inverter. The specific integration you need will depend on the brand of inverter you have:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BrandIntegrationGithub Link
GivEnergyGivTCPhttps://github.com/britkat1980/ha-addons
GivEnergyGivEnergy Cloudhttps://github.com/springfall2008/ge_cloud
GivEnergy EMSGivEnergy Cloudhttps://github.com/springfall2008/ge_cloud
SolisSolaX ModBushttps://github.com/wills106/homeassistant-solax-modbus
Solax Gen4Solax Modbushttps://github.com/wills106/homeassistant-solax-modbus
SofarSofar MQTThttps://github.com/cmcgerty/Sofar2mqtt
HuaweiHuawei Modbushttps://github.com/wlcrs/huawei_solar
SolarEdgeSolarEdge Modbushttps://github.com/WillCodeForCats/solaredge-modbus-multi
SunSynkSunSynk Modbushttps://github.com/kellerza/sunsynk
FoxFox Modbushttps://github.com/nathanmarlor/foxess_modbus
LuxPowerLuxPythonhttps://github.com/guybw/LuxPython_DEV
+

Predbat was originally written for GivEnergy inverters controlled by the GivTCP add-on but has been extended for other inverter types.

+

Please see Inverter Setup for details on installing and configuring the appropriate inverter control software +so that Home Assistant is able to 'see' and manage your inverter.

+

You will need at least 24 hours history in Home Assistant for Predbat to work correctly, the default is 7 days (but you configure this back to 1 day if you need to).

+

NB: If you have multiple GivEnergy AIO's or a 3-phase inverter, GivTCP version 3 is required.

+

Editing Configuration Files in Home Assistant

+

The basic configuration for Predbat is stored in a configuration file called apps.yaml. +A standard template apps.yaml file will be installed as part of the Predbat installation and you will need to edit and customise this configuration file for your own system setup.

+

You will therefore need a method of editing configuration files within your Home Assistant environment.

+

There are severals ways to achieve this in Home Assistant, but two of the simplest are to use either the File Editor or Studio Code Server add-on's. +Whichever you use is a personal preference. File Editor is a bit simpler, Studio Code Server is more powerful +but does require HACS (the Home Assistant Community Store) to be installed first.

+

If you do not have one of these file editors already installed in Home Assistant:

+
    +
  • For Studio Code Server you will need to install HACS first if you don't currently have it installed
    • +
  • Go to Settings / Add-ons / Add-on Store (bottom right)
    • +
  • Scroll down the add-on store list, to find either 'File editor' or 'Studio Code Server' as appropriate, click on the add-on, click 'INSTALL'
    • +
  • Once the editor has been installed, ensure that the 'Start on boot' option is turned on, and click 'START' to start the add-on
    • +
+

Thereafter whenever you need to edit a configuration file in Home Assistant you can navigate to Settings / Add-on's / editor_you_chose_to_use / 'OPEN WEB UI'. +You can also turn the 'Show in sidebar' option on to give a quicker way to directly access the editor.

+

If you are using the File Editor to edit Predbat's configuration files, you will need to turn OFF the Enforce Basepath option +in order to access files in different directories (i.e. within the appdaemon directory):

+
    +
  • From the File editor add-on page, click on the 'Configuration' tab to change this setting). It is set to 'On' by default:
    +image
    • +
+

If you are using Studio Code Server it will default to showing just files and folders in the /config directory. +To access the entire HA directory structure, click the three horizontal bars to the left of 'Explorer', File, Open Folder, type '/' (root) and click OK.

+

Predbat add-on install

+

Recommended

+

The simplest way to install Predbat now is with the Predbat add-on.

+

Go to settings, add-ons, select Add-on Store, three dots on the top right, Repositories, then add the following repo +'https://github.com/springfall2008/predbat_addon' to the list and click close. Now refresh the list and find Predbat, click on it and click 'install'. +Ensure 'start on boot' is enabled and click 'start'.

+

NOTE: Throughout the rest of the Predbat documentation you will find reference to the Predbat configuration file apps.yaml and the Predbat logfile.

+

These are located under the Home Assistant directory /addon_configs/6adb4f0d_predbat which contains:

+
    +
  • predbat.log - Predbat's active logfile that reports detail of what Predbat is doing, and details of any errors
    • +
  • apps.yaml - Predbat's configuration file which will need to be customised to your system and requirements. This configuration process is described below.
    • +
+

You can use your file editor (i.e. 'File editor' or 'Studio Code Server' add-on) to open the directory /addon_configs/6adb4f0d_predbat and view these files.

+

If you have used the Predbat add-on installation method you do not need to install HACS or AppDaemon so you can skip directly to Solcast install below.

+

The Predbat web interface will work through the Predbat add-on, you can click on the 'Web UI' button to open it once Predbat is running.

+

If you wish to use Docker with Predbat its recommended you read the Docker installation instructions inside the Predbat add-on rather than going down the AppDaemon route +listed below.

+

Predbat installation into AppDaemon

+

Not Recommended

+

NOTE: The Predbat web interface will not work with the AppDaemon installation method.

+

This is the old way of installing Predbat, to firstly install HACS (the Home Assistant Community Store), then install the AppDaemon add-on, +and finally install Predbat from HACS to run within AppDaemon.

+

NOTE: If you are using AppDaemon you now must set ha_key and ha_url in apps.yaml to point to your Home Assistant. The key can be obtained from HA by creating an access token.

+

HACS install

+

Predbat and AppDaemon are available through the Home Assistant Community Store (HACS). You can install Predbat manually (see below) but its usually easier to install it through HACS.

+ +

AppDaemon install

+

Predbat is written in Python and runs on a continual loop (default every 5 minutes) within the AppDaemon add-on to Home Assistant. +The next task therefore is to install and configure AppDaemon.

+
    +
  • Install the AppDaemon add-on https://github.com/hassio-addons/addon-appdaemon
    • +
  • Once AppDaemon has finished installing, ensure that the 'Start on boot' option is turned on, then click 'START'
    • +
  • You will need to edit the appdaemon.yaml configuration file for AppDaemon and so will need to have either +the File Editor or Studio Code Server add-on's installed first
    • +
  • Find the appdaemon.yaml file in the directory /addon_configs/a0d7b954_appdaemon: image
    • +
  • Add to the appdaemon.yaml configuration file:
      +
    • A section app_dir which should refer to the directory /homeassistant/appdaemon/apps where Predbat will be installed
      • +
    • Ensure that the time_zone is set correctly (e.g. Europe/London)
      • +
    • Add thread_duration_warning_threshold: 120 in the appdaemon section
      • +
    +
    • +
  • It's recommended you also add a logs section and specify a new logfile location so that you can see the complete logs, I set mine +to /homeassistant/appdaemon/appdaemon.log and increase the logfile maximum size and number of logfile generations to capture a few days worth of logs.
    • +
+

Example AppDaemon config in appdaemon.yaml:

+
appdaemon:
+  latitude: 52.379189
+  longitude: 4.899431
+  elevation: 2
+  time_zone: Europe/London
+  thread_duration_warning_threshold: 120
+  plugins:
+    HASS:
+      type: hass
+  app_dir: /homeassistant/appdaemon/apps
+http:
+  url: http://homeassistant.local:5050
+admin:
+api:
+hadashboard:
+
+# write log records to a file, retaining 9 versions, rather than the standard appdaemon log
+logs:
+  main_log:
+    filename: /homeassistant/appdaemon/appdaemon.log
+    log_generations: 9
+    log_size: 10000000
+
+

CAUTION: If you are upgrading AppDaemon from an older version to version 0.15.2 or above you need to follow these steps to ensure Predbat continues working. +These are only required if you are upgrading AppDaemon from an old version, they're not required for new installations of AppDaemon:

+
    +
  • Make sure you have access to the HA filesystem, e.g. I use the Samba add-on and connect to the drives on my Mac, but you can use ssh also.
    • +
  • Update AppDaemon to the latest version
    • +
  • Go into the directory /addon_configs/a0d7b954_appdaemon and edit appdaemon.yaml. You need to add app_dir (see above) to point to the +old location and update your logfile location (if you have set it). You should remove the line that points to secrets.yaml +(most people don't use this file) or adjust it's path to the new location (/homeassistant/secrets.yaml)
    • +
  • Move the entire 'apps' directory from /addon_configs/a0d7b954_appdaemon (new location) to /config/appdaemon (the old location)
    • +
  • Restart AppDaemon
    • +
  • Check it has started and confirm Predbat is running correctly again.
    • +
+

Install Predbat through HACS

+

hacs_badge

+

If you install Predbat through HACS, once installed you will get automatic updates for each new release of Predbat!

+
    +
  • In HACS, click on Automation
    • +
  • Click on the three dots in the top right corner, choose Custom Repositories
    • +
  • Add https://github.com/springfall2008/batpred as a custom repository of Category 'AppDaemon' and click 'Add'
    • +
  • Click Explore and download repositories (bottom right), type 'Predbat' in the search box, select the Predbat Repository, then click 'Download' to install the Predbat app.
    • +
+

NOTE: Throughout the rest of the Predbat documentation you will find reference to the Predbat configuration file apps.yaml and the Predbat logfile.

+

As you are following the 'install Predbat through HACS' installation method these are located under the Home Assistant directory /config/appdaemon/ which contains:

+
    +
  • appdaemon.log - AppDaemon and Predbat's active logfile that reports detail of what Predbat is doing, and details of any errors
    • +
  • apps/batpred/config/apps.yaml - Predbat's configuration file which will need to be customised to your system and requirements. This configuration process is described below.
    • +
+

Predbat manual install

+

A manual install is suitable for those running Docker type systems where HACS does not function correctly and you had to manually install AppDaemon.

+

Note: Not recommended if you are using HACS

+
    +
  • Copy all the .py files to the /config/appdaemon/apps/ directory in Home Assistant (or wherever you set appdaemon app_dir to)
    • +
  • Copy apps/predbat/apps.yaml to the /config/appdaemon/apps/ directory in Home Assistant (or wherever you set appdaemon app_dir to)
    • +
  • +

    Edit in Home Assistant the /config/appdaemon/apps/apps.yaml file to configure Predbat

    +
    • +
  • +

    If you later install with HACS then you must move the apps.yaml into /config/appdaemon/apps/predbat/config

    +
    • +
+

Solcast Install

+

Predbat needs a solar forecast in order to predict solar generation and battery charging. +If you do have solar panels its recommended to use the Solcast integration to retrieve your forecast solar generation.

+

If you don't have one already, register for a free Solcast hobbyist account and enter the details of your system. +You can create 2 sites maximum under one (free hobbyist) account, if you have more aspects then its suggested you average the angle based on the number of panels +e.g. 7/10 240 degrees + 3/10 120 degrees.

+

Hybrid inverters only: If your hybrid inverter capacity is smaller than your array peak capacity, tell Solcast that your AC capacity is equal to your DC capacity +(both equal to your array peak kW). Otherwise, Solcast will provide forecast data clipped at your inverter capacity. Let Predbat handle any necessary clipping instead. +When supplied with the unclipped Solcast forecast data, Predbat can allow in its model for PV in excess of the inverter capacity going to battery charging +(bypassing the hybrid inverter).

+

You will need your API key for the next steps:

+

image

+

Predbat direct Solcast method

+

Predbat can obtain the solar forecast directly from Solcast and the Solcast integration described below is not required.

+

First get your API key from the Solcast web site, then as described in the Solcast apps.yaml documentation, +uncomment the Solcast cloud interface settings in apps.yaml and set the API key correctly:

+
solcast_host: 'https://api.solcast.com.au/'
+solcast_api_key: 'xxxx'
+solcast_poll_hours: 8
+
+

NB: If you use Predbat to obtain your solcast solar forecast then you can't +include the Solar Forecast within the Home Assistant Energy dashboard +as you can with the Solcast integration described below.
+The Solcast integration also contains a 'solar dampening' feature that may be useful to reduce the solar forecast that Predbat receives at certain times of day, +e.g. if your panels are shaded by trees or buildings.

+

Solcast Home Assistant integration method

+

Install the Solcast integration (https://github.com/BJReplay/ha-solcast-solar), create a free Solcast account, +configure details of your solar arrays, and request an API key that you enter into the Solcast integration in Home Assistant.

+

Predbat is configured in apps.yaml to automatically discover the Solcast forecast entities created by the Solcast integration in Home Assistant.

+

If you don't have any solar generation then use a file editor to comment out the following lines from the Solar forecast part of the apps.yaml configuration:

+
  pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)
+  pv_forecast_tomorrow: re:(sensor.(solcast_|)(pv_forecast_|)forecast_tomorrow)
+  pv_forecast_d3: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_3|d3))
+  pv_forecast_d4: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_4|d4))
+
+

Note that Predbat does not update Solcast integration for you so you will need to create your own Home Assistant automation that updates the solar +forecast a few times a day (e.g. dawn, dusk, and just before your nightly charge slot). Keep in mind hobbyist accounts only have 10 polls per day +so the refresh period needs to be less than this. If you use the same Solcast account for other automations the total polls needs to be kept under the limit or you will experience failures.

+

Due to the popularity of the Solcast Hobbyist service, Solcast have introduced rate limiting for Hobbyist (free) accounts. If your update gets a 429 error then this is due to rate limiting. +Solcast recommend that you poll for updated solar forecasts at random times, i.e. don't poll at precisely X o'clock and zero seconds. +The Solcast integration will auto-retry if it gets a 429 error, +but to minimise potential rate limiting the sample Solcast automation below contains non-precise poll times for just this reason.

+

Example Solcast update automation script:

+
alias: Solcast update
+description: "Update Solcast solar forecast"
+triggers:
+  - trigger: time
+    at:
+      - "06:02:34"
+      - "12:07:47"
+      - "18:09:56"
+      - "23:11:18"
+conditions: []
+actions:
+  - action: solcast_solar.update_forecasts
+    data: {}
+mode: single
+
+

Manually run the automation and then make sure the Solcast integration is working in Home Assistant by going to Developer Tools / States, filtering on 'solcast', +and checking that you can see the half-hourly solar forecasts in the Solcast entities.

+

Energy Rates

+

Predbat needs to know what your electricity import and export rates are in order to optimise battery charging and discharging to minimise your expenditure.

+

These rates are configured in Predbat's apps.yaml configuration file. Follow the instructions in the Energy Rates document.

+

Note: that if you are using the Octopus integration the 'sensor.octopus_xxx' and 'event.octopus_xxx' entities must have a similar pattern of +names for Predbat to work correctly - see the FAQ's if they are not.

+

Configuring Predbat

+

You will need to use a file editor (either the File editor or Studio Code Server add-on) to edit the apps.yaml file in Home Assistant +to configure Predbat - see Configuring apps.yaml.

+

When Predbat starts up initially it will perform a sanity check of itself and the configuration and confirm the right files are present. +You will see this check in the log, should it fail a warning will be issued and predbat.status will also reflect the warning. +While the above warning might not prevent Predbat from starting up, you should fix the issue ASAP as it may cause future problems.

+

Note: if you are running the Predbat through the Predbat add-on or via Docker you will get a logfile warning message +"Warn: unable to find /addon_configs/6adb4f0d_predbat/appdaemon.yaml skipping checks as Predbat maybe running outside of AppDaemon" - this is normal and can be ignored.

+

Predbat Output and Configuration Controls

+

As described above, the basic configuration of Predbat is held in the apps.yaml configuration file.

+

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 section describes these points in more detail including using the auto-generated predbat_dashboard.yaml dashboard file.

+

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.

+

The Predbat Configuration Guide 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 detailed Predbat Customisation Guide 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 and the other components it is dependent upon +(e.g. an inverter controller such as GivTCP, Solcast solar forecast, Octopus Energy integration, etc).

+

image

+

You have checked the Predbat log file 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 some dashboard pages to control and monitor Predbat, +and are ready to start Predbat generating your plan.

+

You may initially want to set select.predbat_mode to Monitor to see how Predbat operates, e.g. by studying the Predbat Plan. +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.
+NB: In Monitor mode Predbat will NOT plan any battery charge or discharge activity of its own, +it will report on the predicted battery charge level based on the current inverter charge & discharge settings, predicted house load and predicted solar generation.

+

In order to enable Predbat to start generating your plan you must delete the 'template: True' line in apps.yaml once you are happy with your configuration.

+

Predbat will automatically run, analyse your house load, battery status, solar prediction, etc and produce a plan based upon the current battery settings.

+

Check the Predbat logfile again for errors. Voluminous output is quite normal but any errors or warnings should be investigated. +Read the Predbat FAQ's for answers to common questions you may have. +Also check the Predbat status predbat.status - major errors will also be flagged here.

+

Once Predbat is running successfully 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 further customise Predbat's settings to meet your needs.

+

Set select.predbat_mode to the correct mode of operation for your system - usually 'Control charge' or 'Control charge & discharge'. +ALSO you should set switch.predbat_set_read_only to True to stop Predbat making any changes to your inverter.

+

You can see the planned solar and grid charging and discharging activity in the Predbat Plan. +Another set of views can be seen in the detailed Apex Charts showing Predbat's predictions.

+

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.

+

Updating Predbat

+

Note that any future updates to Predbat will not overwrite the apps.yaml configuration file that you have tailored to your setup. +If new Predbat releases introduce new features to apps.yaml you may therefore need to manually copy across the new apps.yaml settings from the Template apps.yaml.

+

Update via Home Assistant

+

Recommended

+

Predbat can now be updated using the Home Assistant update feature. When a new release is available you should see it in the Home Assistant settings:

+

image

+

Click on the update and select install:

+

image

+

Predbat built-in update

+

Recommended for manual selection of versions or automatic updates

+

Predbat can now update itself, just select the version of Predbat you want to install from the select.predbat_update drop down menu, +the latest version will be at the top of the list. Predbat will update itself and automatically restart.

+

Alternatively, if you turn on switch.predbat_auto_update, Predbat will automatically update itself as new releases are published on Github.

+

image

+

Once Predbat has been installed and configured you should update Predbat to the latest version by selecting the latest version in the select.predbat_update selector, +or by enabling the switch.predbat_auto_update to auto-update Predbat.

+

Please note that using the internal update mechanism of Predbat will not inform HACS that Predbat has been updated. If you used HACS to install Predbat you do not need +to use it again unless your system is in need of repair.

+

HACS Update

+

Not Recommended

+

HACS checks for updates and new releases only once a day by default, you can however force it to check again, or download a specific version +by using the 'Redownload' option from the top-right three dots menu for Predbat in the HACS Automation section.

+

NOTE: If you update Predbat through HACS you may need to restart AppDaemon as it sometimes reads the config wrongly during the update. +(If this happens you will get a template configuration error in the entity predbat.status).
+Go to Settings, Add-ons, AppDaemon, and click 'Restart'.

+

If you update Predbat via Home Assistant or via Predbat's build-in update then HACS will not know about this and you'll continue to get messages in HACS about updating Predbat.

+

Manual update of Predbat

+

Expert only

+

You can go to Github and download all the .py files from the releases tab and then manually copy these files +over the existing version in /config/appdaemon/apps/batpred/ manually.

+

Upgrading from AppDaemon to Predbat add-on

+

These steps assume you already have a working Predbat system and want to upgrade to using the Predbat add-on instead of using either the AppDaemon or the AppDaemon-predbat add-on.

+

Using the Predbat add-on is the strategic direction for Predbat and resolves some performance and data load issues that can occur with AppDaemon. +The Predbat code that runs is exactly the same and the configuration is exactly the same, its just changing the 'container' that Predbat runs within.

+
    +
  1. +

    Before starting, watch the installing Predbat add-on video

    +
    2. +
  2. +

    Although the upgrade steps are low risk, take a full backup of Home Assistant before starting

    +
    3. +
  3. +

    Install the Predbat add-on:

    +
      +
    • Add the Predbat add-on to the list of Repositories in the add-on store
      • +
    • Install the Predbat add-on
      • +
    • But do not start it - yet
      • +
    +
    4. +
  4. +

    Install a file editor if you don't have one already installed - either File Editor or Studio Code Server, it doesn't matter

    +
    5. +
  5. +

    Shutdown your existing AppDaemon or AppDaemon-predbat add-on:

    +
      +
    • Go to Settings/Add-ons
      • +
    • Click on the existing AppDaemon/AppDaemon-predbat add-on
      • +
    • Click STOP, and untick 'Start on boot'
      • +
    +
    6. +
  6. +

    Briefly start the new Predbat add-on so that it creates the addon_config folder and the template apps.yaml file:

    +
      +
    • Go to Settings/Add-ons
      • +
    • Click on the Predbat add-on
      • +
    • Click START, wait a minute for the add-on to initialise itself, then click STOP. A predbat status warning that you have a template apps.yaml file is normal and can be ignored
      • +
    +
    7. +
  7. +

    Open your file editor and open your existing apps.yaml file:

    +
      +
    • +

      If you are using the old 'combined AppDaemon/Predbat add-on installation method' it's in the directory /addon_configs/46f69597_appdaemon-predbat/apps, +or

      +
      • +
    • +

      with the HACS, Appdaemon add-on then Predbat installation method, it's in /config/appdaemon/apps/batpred/config/

      +
      • +
    +
    8. +
  8. +

    Select all the contents of the apps.yaml file and 'copy' (control-C, command-C, etc as appropriate)

    +
    9. +
  9. +

    Now open the template apps.yaml file that's supplied with the Predbat add-on and has been created in the directory /addon_configs/6adb4f0d_predbat, +select all the contents of the template apps.yaml file, and paste in the contents of your existing apps.yaml, overwriting the template with your specific configuration

    +
    10. +
  10. +

    Now you are ready to swap from running the AppDaemon or AppDaemon-predbat add-on to the Predbat add-on:

    +
      +
    • Go to Settings/Add-ons
      • +
    • Click on the existing AppDaemon/AppDaemon-predbat add-on
      • +
    • Make sure it is not running and 'Start on boot' is not ticked
      • +
    • Click the back arrow
      • +
    • Click on the Predbat add-on
      • +
    • Click START, and tick 'Start on boot'
      • +
    +
    11. +
  11. +

    If you are using the Predbat automatic monitor then you will need to enable the predbat_running binary sensor and change the automation, +replacing the AppDaemon add-on id (a0d7b954_appdaemon) with 'a06adb4f0d_predbat', and 'binary_sensor.appdaemon_running' with 'binary_sensor.predbat_running'.

    +
    12. +
+

And that's it.

+

You should check the Log tab to ensure it all starts properly, but it should do as you've copied over your existing configuration.

+

Note that if you are using the Predbat direct connection to Solcast then the Predbat add-on will need to download your solar forecast +so will use up one or two of your daily API calls (hobbyist accounts have a 10 API a day limit). +If you are using the Solcast integration then this won't be required.

+

You may find that the Predbat add-on installed with an older version of Predbat than you were previously using, +which might require you to update Predbat to the correct version.

+
    +
  1. When you are happy running the Predbat add-on you can delete the AppDaemon or AppDaemon-predbat add-on.
    2. +
+

Backing up Home Assistant and Predbat

+

It's strongly recommended that you implement an automatic mechanism to backup your Home Assistant and Predbat system.

+

There are several ways of backing up Home Assistant but one of the simplest is the Home Assistant Google Drive Backup +which is an add-on that runs every night, automatically makes a backup of Home Assistant (including Predbat), and copies that backup to a Google Drive for safe keeping.

+

If you create a new Google account specifically for your Home Assistant backups you will automatically get 15Gb of free Google Drive storage, enough for a couple of weeks of backups.

+

As well as the full Home Assistant backup you manually copy the contents of Predbat's apps.yaml configuration file to somewhere safe so that if you accidentally mis-edit it, +you can get Predbat working quickly again by copying it back again.

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/installation-summary/index.html b/installation-summary/index.html new file mode 100644 index 000000000..f0aa7ea0a --- /dev/null +++ b/installation-summary/index.html @@ -0,0 +1,228 @@ + + + + + + + + Install summary - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Install summary
    • +
  • +
    • +
+
+
+
+
+ +

Installation summary

+

Please see the sections below for how to achieve each step. This is just a checklist of things:

+
    +
  1. Before you start, its recommended that you watch the step by step installation videos, +see the video guides section for those and other videos
    2. +
  2. Make sure the right inverter control module is installed and running
    3. +
  3. Install a file editor (either the File editor or Studio Code Server add-on) to enable you to edit configuration files if you haven't already - Editing configuration files
    4. +
  4. Install Predbat, either: +
    5. +
  5. Register for a Solcast hobbyist account if you haven't already Solcast install and either: +
    6. +
  6. Follow the Energy Rates 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
    7. +
  7. Edit Predbat's apps.yaml configuration file to to match your system - apps.yaml settings
    +The apps.yaml file will be in either the directory /addon_configs/6adb4f0d_predbat 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
        • +
      +
      • +
    • You have your energy rates set correctly either using Octopus Energy integration or entered manually
      • +
    • That the Solcast integration (if being used) is matching the configuration correctly - should be automatic
      • +
    • If you have an electric car you have setup the Car Charging configuration
      • +
    +
    8. +
  8. Add the Predbat entities to your dashboard - Output data
    9. +
  9. Follow the Configuration Guide to set 'standard' Predbat configuration settings depending on your import and export tariffs
    10. +
  10. The detailed Customisation Guide lists all Predbat's controls and settings in Home Assistant that can be tuned for your system
    11. +
  11. Set up the Predbat Plan card so you can check what Predbat is planning to do - Create the Predbat Plan card
    12. +
  12. Set up the Apex Charts for other views on what Predbat is doing - Creating the charts
    13. +
  13. 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
      • +
    • Comment out or delete the 'template: True' line in apps.yaml 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
      • +
    +
    14. +
  14. Look at the FAQ for help
    15. +
+

Overview of the key configuration elements:

+

image

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/inverter-setup/index.html b/inverter-setup/index.html new file mode 100644 index 000000000..a43fadb06 --- /dev/null +++ b/inverter-setup/index.html @@ -0,0 +1,906 @@ + + + + + + + + Inverter setup - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Inverter setup
    • +
  • +
    • +
+
+
+
+
+ +

Inverter setup

+

PredBat was originally written for GivEnergy inverters using the GivTCP integration but this is now being extended to other inverter models:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameIntegrationTemplate
GivEnergy with GivTCPGivTCPgivenergy_givtcp.yaml
Solis Hybrid invertersSolax Modbus integrationginlong_solis.yaml
Solax Gen4 invertersSolax Modbus integration in Modbus Power Control Modesolax_sx4.yaml
Sofar invertersSofar MQTT integrationsofar.yaml
Huawei invertersHuawei Solarhuawei.yaml
SolarEdge invertersSolaredge Modbus Multisolaredge.yaml
Givenergy with GE Cloudge_cloudgivenergy_cloud.yaml
Givenergy with GE Cloud EMCge_cloudgivenergy_ems.yaml
SunSynkSunsynksunsynk.yaml
FoxFoxessfox.yaml
LuxPowerLuxPythonluxpower.yaml
Growatt with Solar AssistantSolar Assistantsolar_assistant_growatt.yaml
+

Note that support for all these inverters is in various stages of development. Please expect things to fail and report them as Issues on Github.

+

NB: By default the apps.yaml template for GivTCP is installed with Predbat. +If you are using a different inverter then you will need to copy the appropriate apps.yaml template from the above list and use it to replace the GivTCP apps.yaml - if +you copy but don't replace the standard template then Predbat will not function correctly.

+

GivEnergy with GivTCP

+

Its recommended that you firstly watch the Installing GivTCP and Mosquitto Add-on's video from Speak to the Geek. +Although the video covers GivTCP v2 and v3 has been recently released, the install and setup process is very similar.

+

The below instructions assume you are installing GivTCP v3, with changes highlighted against GivTCP v2 as covered in the video.

+
    +
  1. Install Mosquitto Broker add-on:
    2. +
+
    +
  • Go to Settings / Add-ons / Add-on Store (bottom right)
    • +
  • Scroll down the add-on store list, to find 'Mosquitto broker', click on the add-on, then click 'INSTALL'
    • +
  • Once the Mosquitto broker has been installed, ensure that the 'Start on boot' and 'Watchdog' options are turned on, and click 'START' to start the add-on
    • +
  • Next, configure Mosquitto broker by going to Settings / Devices and Services / Integrations. +Mosquitto broker should appear as a Discovered integration so click the blue 'CONFIGURE' button, then SUBMIT to complete configuring Mosquitto broker
    • +
  • With GivTCP v3 you no longer need to create a dedicated Home Assistant user for MQTT so this part of the video can be skipped over
    • +
+
    +
  1. Install the GivTCP add-on:
    2. +
+
    +
  • Go to Settings / Add-ons / Add-on Store
    • +
  • Click the three dots in the top right corner, then Repositories
    • +
  • You'll need to add the GivTCP repository as an additional custom repository so paste/type +'https://github.com/britkat1980/ha-addons' into the text box and click 'Add' the 'Close'
    +NB: this URL is for GivTCP v3, not v2 as covered in the video.
    • +
  • Click the back button and then re-navigate to Settings / Add-ons / Add-on Store so Home Assistant picks up the GivTCP add-on from the custom repository
    • +
  • Scroll down the add-on store list, to find 'GivTCP-V3', you should see the three addon's; the production version, the latest beta and the latest dev versions. +Click on the 'GivTCP' add-on, then click 'INSTALL'
    • +
  • Once GivTCP has been installed, ensure that the 'Start on boot' and 'Watchdog' options are turned on
    • +
+
    +
  1. Configure GivTCP:
    2. +
+
    +
  • The configuration process for GivTCP in v3 has changed from that shown in the video, +the Configuration tab is now no longer used and all configuration is now done via the add-on's Web interface
    • +
  • On the GivTCP add-on, click 'START' to start the add-on
    • +
  • Once the add-on has started, click 'Open Web UI' or go to http://homeassistant.local:8099/, then click 'Go to Config Page' to configure GivTCP
    • +
  • GivTCP will auto-discover your inverters and batteries so you shouldn't need to manually enter these, but check the IP address(s) it finds are correct
    • +
  • If you have multiple inverters you may wish to change the default device prefixes that GivTCP assigns ('givtcp', 'givtcp2', 'givtcp3', etc) +to make it easier to identify your devices within Home Assistant.
    +For example if you have a gateway and two AIO's you could use the prefixes 'GW', 'AIO-1' and 'AIO-2'. +The prefixes should be set before you start using GivTCP in anger +as changing the prefixes later on will result in both the old and new sensor names appearing in Home Assistant with the 'old' sensors being "unavailable".
    +Note that if you do change the givtcp prefixes then you will also have to edit the apps.yaml configuration file to match, +and change the sensor names that predbat is looking for (by default prefixed 'givtcp_xxx') to your new sensor naming structure
    • +
  • Click Next and Next to get to the Selfrun page, and turn on Self run. The Self Run Loop Timer is how often GivTCP will retrieve data from your inverters - it's +recommended that set this to a value between 20 and 60, but not less than 15 seconds as otherwise the inverter will then spend all its time talking to GivTCP +and won't communicate with the GivEnergy portal and app
    • +
  • GivTCP now auto-populates the MQTT page so as long as you're using Mosquitto broker within Home Assistant; +you won't need to create a dedicated MQTT user or enter the details on the MQTT page
    • +
  • You don't need to configure the Influx page. Tariff and Palm pages can also be skipped as these functions are done by Predbat
    • +
  • (Optional) On the Web page, you can turn the Dashboard on to see a simple power flow diagram for your inverters (similar to the GivEnergy mobile app)
    • +
  • On the 'Misc' page check that 'Print Raw' is set to on for added monitoring
    • +
  • Finally click 'Save and Restart' and GivTCP should start communicating with your inverters +and will automatically create a set of 'givtcp_xxx' entities in Home Assistant for your inverter data, inverter controls and battery data
    • +
  • Check the GivTCP Log tab that there aren't any errors; it should end with 'Publishing Home Assistant Discovery messages'
    • +
+
    +
  1. Specific Predbat configuration requirements for certain GivEnergy equipment
    2. +
+

The rest of the Predbat installation instructions should now be followed, +but its worth highlighting that there are a few specific settings that should be set for certain GivEnergy equipment. +These settings are documented in the appropriate place in the documentation, but for ease of identification, are repeated here:

+
    +
  • If you are using GivTCP v3 and have an AIO or 3 phase inverter then you will need to manually set geserial in apps.yaml to your inverter serial number
    • +
  • If you have a single AIO then control is directly to the AIO. Ensure geserial in apps.yaml is correctly picking the AIO and comment out geserial2 lines
    • +
  • If you have multiple AIO's then all control of the AIO's is done through the Gateway so geserial in apps.yaml should be set to the Gateway serial number
    • +
  • If you have multiple AIO's you might want to consider setting inverter charge and discharge limits +unless you want to charge and discharge at the full 12kWh!
    • +
  • If you have a 2.6kWh, 5.2kWh or AIO battery then you will need to set battery_scaling in apps.yaml +as the battery size is incorrectly reported to GivTCP
    • +
  • If you have a Gen 2, Gen 3 or AIO then you may need to set inverter_reserve_max in apps.yaml to 98. +If you have a Gen 1 or a firmware version that allows reserve being set to 100 then you can change the default from 98 to 100
    • +
  • If your inverter has been wired as an EPS (Emergency Power Supply) or AIO 'whole home backup', consider setting +input_number.predbat_set_reserve_min to reserve some battery power for use in emergencies.
    • +
+

NB: GivTCP and Predbat do not currently yet work together for 3 phase inverters. +This is being worked on by the author of GivTCP, e.g. see GivTCP issue: unable to charge or discharge 3 phase inverters with predbat

+

Solis Inverters

+

To run PredBat with Solis hybrid inverters, follow the following steps:

+
    +
  1. Install PredBat as per the Installation Summary
    2. +
  2. Ensure that you have the Solax Modbus integration running. There are a number of entities which this integration disables by default that you + will need to enable via the Home Assistant GUI:
    3. +
+ + + + + + + + + + + + + + + + + +
NameDescription
sensor.solisx_rtcReal Time Clock
sensor.solisx_battery_powerBattery Power
+
    +
  1. Instead of apps.yaml use ginlong_solis.yaml from this Repo as your starting template. + The majority of settings should be correct but please check. + You will need to un-comment the template line to enable it. Save it to the appropriate Predbat software directory. + Set solax_modbus_new in apps.yaml to True if you have integration version 2024.03.2 or greater
    2. +
  2. Ensure that the inverter is set Control Mode 35 - on the Solax integration this is Timed Charge/Discharge. + If you want to use the Reserve functionality within PredBat you will need to select Backup/Reserve (code 51) instead but be aware that + this is not fully tested. In due course these mode settings will be incorporated into the code.
    3. +
+

Solax Gen4 Inverters

+

Use the template configuration from: solax.sx4.yaml

+
    +
  • Set solax_modbus_new in apps.yaml to True if you have integration version 2024.03.2 or greater
    • +
+

Please see this ticket in Github for ongoing discussion: https://github.com/springfall2008/batpred/issues/259

+

Sofar Inverters

+

For this integration the key elements are:

+
    +
  • Hardware - sofar2mqtt EPS board - Relatively easy to solder and flash, or can be bought pre-made.
    • +
  • Software - Sofar MQTT integration - MQTT integration
    • +
  • Home Assistant configuration - sofar_inverter.yaml package (in templates directory) +with the MQTT sensors. This is the default with a couple of additional inputs to support battery capacity. This should be installed in Home Assistant.
    • +
  • +

    Predbat configuration - sofar.yaml template for Predbat (in templates directory). +This file should be copied to apps.yaml

    +
    • +
  • +

    Please note that the inverter needs to be put into "Passive Mode" for the sofar2mqtt to control the inverter.

    +
    • +
  • This integration has various limitations, it can charge and discharge the battery but does not have finer control over reserve and target SOC%
    • +
  • Note: You will need to change the min reserve in Home Assistant to match your minimum battery level (input_number.predbat_set_reserve_min).
    • +
+

Please see this ticket in Github for ongoing discussions: https://github.com/springfall2008/batpred/issues/395

+

Huawei Inverters

+

Discussion ticket is here: https://github.com/springfall2008/batpred/issues/684

+ +

SolarEdge Inverters

+

Discussion ticket is here: https://github.com/springfall2008/batpred/issues/181

+
    +
  • Please copy the template apps.yaml from https://github.com/springfall2008/batpred/blob/main/templates/solaredge.yaml and modify for your system
    • +
  • Ensure that number.solaredge_i1_storage_command_timeout is set to reasonably high value e.g. 3600 seconds to avoid the commands issued being cancelled
    • +
  • +

    Power Control Options, as well as Enable Battery Control, must be enabled in the Solaredge Modbus Multi integration configuration, +and switch.solaredge_i1_advanced_power_control must be on.

    +
    • +
  • +

    For pv_today, pv_power and load_power sensors to work you need to create this as a template within your Home Assistant configuration.yml +Please see: https://gist.github.com/Ashpork/f80fb0d3cb22356a12ed24734065061c. These sensors are not critical so you can just comment it out in apps.yaml +if you can't get it to work

    +
    • +
+
template:
+  - sensor:
+      - name: "Solar Panel Production W"
+        unique_id: solar_panel_production_w
+        unit_of_measurement: "W"
+        icon: mdi:solar-power
+        state: >
+          {% set i1_dc_power = states('sensor.solaredge_i1_dc_power') | float(0) %}
+          {% set b1_dc_power = states('sensor.solaredge_b1_dc_power') | float(0) %}
+          {% if (i1_dc_power + b1_dc_power <= 0) %}
+            0
+          {% else %}
+            {{ (i1_dc_power + b1_dc_power) }}
+          {% endif %}
+        availability: >
+          {{ states('sensor.solaredge_i1_dc_power') | is_number and states('sensor.solaredge_b1_dc_power') | is_number }}
+
+      - name: "Solar House Consumption W"
+        unique_id: solar_house_consumption_w
+        unit_of_measurement: "W"
+        icon: mdi:home
+        state: >
+          {% set i1_ac_power = states('sensor.solaredge_i1_ac_power') | float(0) %}
+          {% set m1_ac_power = states('sensor.solaredge_m1_ac_power') | float(0) %}
+          {% if (i1_ac_power - m1_ac_power <= 0) %}
+            0
+          {% else %}
+            {{ (i1_ac_power - m1_ac_power) }}
+          {% endif %}
+        availability: >
+          {{ states('sensor.solaredge_i1_ac_power') | is_number and states('sensor.solaredge_m1_ac_power') | is_number }}
+
+sensor:
+  - platform: integration
+    source: sensor.solar_panel_production_w
+    method: left
+    unit_prefix: k
+    name: solar_panel_production_kwh
+
+

Givenergy with ge_cloud

+

This is experimental system, please discuss on the ticket: https://github.com/springfall2008/batpred/issues/905

+
    +
  • First set up ge_cloud integration using your API key https://github.com/springfall2008/ge_cloud
    • +
  • Now copy the template givenergy_cloud.yaml from templates into your apps.yaml and edit
      +
    • Set geserial to your inverter serial
      • +
    +
    • +
  • Make sure discharge down to registers are set to 4% and slots 2, 3 and 4 for charge and discharge are disabled (if you have them)
    • +
+

Givenergy with EMC

+
    +
  • First set up ge_cloud integration using your API key https://github.com/springfall2008/ge_cloud
    • +
  • Now copy the template givenergy_emc.yaml from templates into your apps.yaml and edit
      +
    • Set geserial to your first inverter serial and geserial2 to the second (look in HA for entity names)
      • +
    • Set geseriale to the EMS inverter serial number (look in HA for entity names)
      • +
    +
    • +
  • Turn off slots 2, 3 and 4 for charge, export and discharge as Predbat will only use 1 slot (set the start and end times to 00:00)
    • +
+

Fox

+

Experimental

+ +

Template is in the templates area, give it a try

+

Lux Power

+

This requires the LuxPython component which integrates with your Lux Power inverter

+
    +
  • Copy the template luxpower.yaml from templates into your apps.yaml and edit inverter and battery settings as required
    • +
+

Growatt with Solar Assistant

+

You need to have a Solar Assistant installation https://solar-assistant.io

+

Copy the template solar_assistant_growatt.yaml from templates into your apps.yaml and edit inverter and battery settings as required (the template has growatt, yours might/will have different entity ids on Home Assistant)

+

Sunsynk

+
    +
  • Copy the Sunsynk apps.yaml template and edit for your system.
    • +
  • Create the automations below
    • +
  • Create the value templates below
    • +
+

See: https://github.com/springfall2008/batpred/issues/1331

+

SunSynk automations

+

Copy into your HA automations

+

Predbat Charge/Discharge Control

+
alias: Predbat Charge / Discharge Control
+description: ""
+trigger:
+  - platform: state
+    entity_id:
+      - binary_sensor.predbat_charging
+    to: "on"
+    id: predbat_charge_on
+  - platform: state
+    entity_id:
+      - binary_sensor.predbat_charging
+    to: "off"
+    id: predbat_charge_off
+  - platform: state
+    entity_id:
+      - binary_sensor.predbat_exporting
+    to: "on"
+    id: predbat_discharge_on
+  - platform: state
+    entity_id:
+      - binary_sensor.predbat_exporting
+    to: "off"
+    id: predbat_discharge_off
+condition: []
+action:
+  - choose:
+      - conditions:
+          - condition: trigger
+            id:
+              - predbat_charge_on
+        sequence:
+          - service: switch.turn_on
+            metadata: {}
+            data: {}
+            target:
+              entity_id: switch.sunsynk_grid_charge_timezone1
+      - conditions:
+          - condition: trigger
+            id:
+              - predbat_charge_off
+        sequence:
+          - service: switch.turn_off
+            target:
+              entity_id:
+                - switch.sunsynk_grid_charge_timezone1
+            data: {}
+      - conditions:
+          - condition: trigger
+            id:
+              - predbat_discharge_on
+        sequence:
+          - service: switch.turn_on
+            metadata: {}
+            data: {}
+            target:
+              entity_id: switch.sunsynk_solar_sell
+      - conditions:
+          - condition: trigger
+            id:
+              - predbat_discharge_off
+        sequence:
+          - service: switch.turn_off
+            target:
+              entity_id:
+                - switch.sunsynk_solar_sell
+            data: {}
+mode: single
+
+

Update the charge limits across all timezone's

+
alias: PredBat - Copy Charge Limit
+description: Copy Battery SOC to all time slots
+trigger:
+  - platform: state
+    entity_id:
+      - number.sunsynk_set_soc_timezone1
+    to: null
+condition: []
+action:
+  - service: number.set_value
+    data_template:
+      entity_id:
+        - number.sunsynk_set_soc_timezone2
+        - number.sunsynk_set_soc_timezone3
+        - number.sunsynk_set_soc_timezone4
+        - number.sunsynk_set_soc_timezone5
+        - number.sunsynk_set_soc_timezone6
+      value: "{{ states('number.sunsynk_set_soc_timezone1')|int(20) }}"
+mode: single
+
+

SunSynk Value templates

+

Copy into your template/sensor area of configuration.yaml

+
template:
+  sensor:
+    xxxxx
+
+

Sunsynk Battery Max Charge Rate

+
- name: "sunsynk_max_battery_charge_rate"
+  unit_of_measurement: "w"
+  state_class: measurement
+  state: >
+    {{ [8000,[states('input_number.sunsynk_battery_max_charge_current_limit')|int,states('sensor.sunsynk_battery_charge_limit_current')|int]|min
+        * states('sensor.sunsynk_battery_voltage')|float]|min }}
+
+

Sunsynk Battery Max DisCharge Rate

+
- name: "sunsynk_max_battery_discharge_rate"
+  unit_of_measurement: "w"
+  state_class: measurement
+  state: >
+    {{ [8000,[states('input_number.sunsynk_battery_max_discharge_current_limit')|int,states('sensor.sunsynk_battery_discharge_limit_current')|int]|min
+        * states('sensor.sunsynk_battery_voltage')|float]|min }}
+
+

Sunsynk Charge Rate Calc

+
- name: "sunsynk_charge_rate_calc"
+  unit_of_measurement: "w"
+  state_class: measurement
+  state: >
+     {{ [8000,[states('input_number.test_sunsynk_battery_max_charge_current')|int,states('sensor.sunsynk_battery_charge_limit_current')|int]|min
+         * states('sensor.sunsynk_battery_voltage')|float]|min }}
+
+

Sunsynk Discharge Rate Calc

+
- name: "sunsynk_discharge_rate_calc"
+  unit_of_measurement: "w"
+  state_class: measurement
+  state: >
+     {{ [8000,[states('input_number.test_sunsynk_battery_max_discharge_current')|int,states('sensor.sunsynk_battery_discharge_limit_current')|int]|min
+         * states('sensor.sunsynk_battery_voltage')|float]|min }}
+
+

I want to add an unsupported inverter to Predbat

+
    +
  • First copy one of the template configurations that is close to your system and try to configure it to match the sensors you have
    • +
  • Create a github ticket for support and add in what you know to the ticket
    • +
  • Then find out how to control your inverter inside Home Assistant, ideally share any automation you have to control the inverter
    • +
  • You can create a new inverter type in apps.yaml and change the options as to which controls it has
    • +
  • The easy way to integrate is to use a HA service to start charges and discharges, edit the template below
    • +
+
 inverter_type: MINE
+ inverter:
+    name : "My Shiny new Inverter"
+    has_rest_api: False
+    has_mqtt_api: False
+    output_charge_control: "power"
+    has_charge_enable_time: False
+    has_discharge_enable_time: False
+    has_target_soc: False
+    has_reserve_soc: False
+    charge_time_format: "S"
+    charge_time_entity_is_option: False
+    soc_units: "%"
+    num_load_entities: 1
+    has_ge_inverter_mode": False
+    time_button_press: False
+    clock_time_format: "%Y-%m-%d %H:%M:%S"
+    write_and_poll_sleep: 2
+    has_time_window: False
+    support_charge_freeze: False
+    support_discharge_freeze": False
+
+  # Services to control charging/discharging
+  charge_start_service:
+    service: select.select_option
+    entity_id: "select.solaredge_i1_storage_command_mode"
+    option: "Charge from Solar Power and Grid"
+  charge_stop_service:
+    service: select.select_option
+    entity_id: "select.solaredge_i1_storage_command_mode"
+    option: "Charge from Solar Power"
+  discharge_start_service:
+    service: select.select_option
+    entity_id: "select.solaredge_i1_storage_command_mode"
+    option: "Maximize Self Consumption"
+
+
+

Inverter control option

+

The follow options are supported per inverter:

+

has_rest_api

+

When True the REST API will be used to fetch data/control the inverter. This is currently only for GivEnergy inverters with GivTCP and givtcp_rest must be set in apps.yaml

+

has_mqtt_api

+

When True the MQTT API to Home Assistant will be used to issue control messages for the inverter

+

The mqtt/publish service is used with the topic as defined by mqtt_topic in apps.yaml

+

Messages will be sent these controls:

+

Values that are updated:

+
    +
  • topic/set/reserve - payload=reserve
    • +
  • topic/set/charge_rate - payload=new_rate
    • +
  • topic/set/discharge_rate - payload=new_rate
    • +
  • topic/set/target_soc - payload=target_soc
    • +
+

These three change between battery charge/discharge and auto (idle) mode:

+
    +
  • topic/set/charge - payload=charge_rate
    • +
  • topic/set/discharge - payload=discharge_rate
    • +
  • topic/set/auto - payload=true
    • +
+

Service API

+

When True a Home Assistant service will be used to issue control messages for the inverter

+

For each service you wish to use it must be defined in apps.yaml.

+

There are two ways to define a service, the basic mode:

+
charge_start_service: my_service_name_charge
+
+

Will call my_service_name_charge for the charge start service.

+

Or the custom method:

+
charge_start_service:
+   - service: my_charge_start_service
+     device_id: {device_id}
+     power: {power}
+     soc: {target_soc}
+
+

Here you can define all the values passed to the service and use the default values from the template or define your own.

+

You can also call more than one service e.g:

+
charge_start_service:
+   - service: my_charge_start_service
+     device_id: {device_id}
+     power: {power}
+     soc: {target_soc}
+   - service: switch.turn_off
+     entity_id: switch.tsunami_charger
+
+

charge_start_service

+

Called to start a charge

+

The default options passed in are:

+
    +
  • device_id - as defined in apps.yaml by device_id
    • +
  • target_soc - The SOC to charge to
    • +
  • power - The charge power to use
    • +
+

charge_freeze_service

+

If defined will be called for freeze charge, otherwise charge_start_service is used for freeze charge also.

+

discharge_start_service

+

Called to start a discharge

+

The default options passed in are:

+
    +
  • device_id - as defined in apps.yaml by device_id
    • +
  • target_soc - The SOC to discharge to
    • +
  • power - The discharge power to use
    • +
+

discharge_freeze_service

+

If defined will be called for Discharge freeze, otherwise discharge_start_service is used for freeze discharge also.

+

charge_stop_service

+

Called to stop a charge

+

device_id - as defined in apps.yaml by device_id

+

discharge_stop_service

+

Called to stop a discharge, if not set then charge_stop_service will be used instead

+
    +
  • device_id - as defined in apps.yaml by device_id
    • +
+

output_charge_control

+

Set to power, current or none

+

When power the inverter has a charge_rate and discharge_rate setting in watts defined in apps.yaml

+

When current the inverter has timed_charge_current and timed_discharge_current setting in amps defined in apps.yaml

+

charge_control_immediate

+

When True the inverter timed_charge_current or timed_discharge_current is used to control charging or discharging as/when it starts and stops rather than using a timed method.

+

current_dp

+

Sets the number of decimal places when setting the current in Amps, should be 0 or 1

+

has_charge_enable_time

+

When True the inverter has a setting defined in apps.yaml called scheduled_charge_enable when can be used to enable/disable timed charging.

+

has_discharge_enable_time

+

When True the inverter has a setting defined in apps.yaml called scheduled_discharge_enable when can be used to enable/disable timed discharging.

+

has_target_soc

+

When True the inverter has a target soc setting in apps.yaml called charge_limit, when False charging must be turned on and off by Predbat rather +than the inverter doing it based on the target %

+

has_reserve_soc

+

When True the inverter has a reserve soc setting in apps.yaml called reserve

+

has_timed_pause

+

When True the inverter has a setting in apps.yaml called pause_mode and settings pause_start_time and pause_end_time which can be used to pause the inverter from +charging and discharging the battery - this is for GivEnergy systems only right now.

+

charge_time_format

+

When set to "HH:MM:SS" the inverter has:

+

charge_start_time charge_end_time +discharge_start_time discharge_end_time

+

Which are option selectors in the format HH:MM:SS (e.g. 12:23:00) where seconds are always 00.

+

When set to "H M" the inverter has:

+

charge_start_hour charge_end_hour charge_start_minute charge_end_minute +discharge_start_hour discharge_end_hour discharge_start_minute discharge_end_minute

+

Settings in apps.yaml which can be used to set the start and end times of charges and discharges

+

charge_time_entity_is_option

+

When True charge_start_time charge_end_time discharge_start_time and discharge_end_time are all Options, when false they are number values.

+

clock_time_format

+

Defines the time format of the inverter clock setting inverter_time in apps.yaml

+

soc_units

+

Defines the units of the SOC setting (currently not used)

+

time_button_press

+

When true the inverter has a button press which is needed to update the inverter registers from the Home Assistant values.

+

The apps.yaml setting charge_discharge_update_button is the entity name of the button that must be pressed and polled until it updates after each inverter register change.

+

support_charge_freeze

+

When True the inverter supports charge freeze modes

+

support_discharge_freeze

+

When True the inverter supports discharge freeze modes

+

has_ge_inverter_mode

+

When True the inverter as the GivEnergy inverter modes (ECO, Timed Export etc).

+

num_load_entities

+

Sets the number of load_power_n settings in apps.yaml are present in addition to load_power (the default)

+

write_and_poll_sleep

+

Sets the number of seconds between polls of inverter settings

+

has_idle_time

+

When True the inverter has an idle time register which must be set to the start and end times for ECO mode (GivEnergy EMC)

+

can_span_midnight

+

When True start and end times for charge and discharge can span midnight e.g. 23:00:00 - 01:00:00 is a 2 hour slot.

+

charge_discharge_with_rate

+

When True when charging discharge rate must be 0 and visa-versa. When false the rate does not have to change.

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/js/html5shiv.min.js b/js/html5shiv.min.js new file mode 100644 index 000000000..1a01c94ba --- /dev/null +++ b/js/html5shiv.min.js @@ -0,0 +1,4 @@ +/** +* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed +*/ +!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="",k="hidden"in a,l=1==a.childNodes.length||function(){b.createElement("a");var a=b.createDocumentFragment();return"undefined"==typeof a.cloneNode||"undefined"==typeof a.createDocumentFragment||"undefined"==typeof a.createElement}()}catch(c){k=!0,l=!0}}();var t={elements:n.elements||"abbr article aside audio bdi canvas data datalist details dialog figcaption figure footer header hgroup main mark meter nav output picture progress section summary template time video",version:m,shivCSS:n.shivCSS!==!1,supportsUnknownElements:l,shivMethods:n.shivMethods!==!1,type:"default",shivDocument:j,createElement:g,createDocumentFragment:h,addElements:e};a.html5=t,j(b),"object"==typeof module&&module.exports&&(module.exports=t)}("undefined"!=typeof window?window:this,document); diff --git a/js/jquery-3.6.0.min.js b/js/jquery-3.6.0.min.js new file mode 100644 index 000000000..c4c6022f2 --- /dev/null +++ b/js/jquery-3.6.0.min.js @@ -0,0 +1,2 @@ +/*! jQuery v3.6.0 | (c) OpenJS Foundation and other contributors | jquery.org/license */ +!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType&&"function"!=typeof e.item},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.6.0",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\([^\\r\\n\\f])","g"),ne=function(e,t){var n="0x"+e.slice(1)-65536;return t||(n<0?String.fromCharCode(n+65536):String.fromCharCode(n>>10|55296,1023&n|56320))},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(p.childNodes),p.childNodes),t[p.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&(T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!N[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&(U.test(t)||z.test(t))){(f=ee.test(t)&&ye(e.parentNode)||e)===e&&d.scope||((s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=S)),o=(l=h(t)).length;while(o--)l[o]=(s?"#"+s:":scope")+" "+xe(l[o]);c=l.join(",")}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){N(t,!0)}finally{s===S&&e.removeAttribute("id")}}}return g(t.replace($,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[S]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e&&e.namespaceURI,n=e&&(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:p;return r!=C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),p!=C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.scope=ce(function(e){return a.appendChild(e).appendChild(C.createElement("div")),"undefined"!=typeof e.querySelectorAll&&!e.querySelectorAll(":scope fieldset div").length}),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=S,!C.getElementsByName||!C.getElementsByName(S).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){var t;a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+S+"-]").length||v.push("~="),(t=C.createElement("input")).setAttribute("name",""),e.appendChild(t),e.querySelectorAll("[name='']").length||v.push("\\["+M+"*name"+M+"*="+M+"*(?:''|\"\")"),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+S+"+*").length||v.push(".#.+[+~]"),e.querySelectorAll("\\\f"),v.push("[\\r\\n\\f]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",F)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},j=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)==(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e==C||e.ownerDocument==p&&y(p,e)?-1:t==C||t.ownerDocument==p&&y(p,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e==C?-1:t==C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]==p?-1:s[r]==p?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if(T(e),d.matchesSelector&&E&&!N[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){N(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=m[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&m(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?S.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?S.grep(e,function(e){return e===n!==r}):"string"!=typeof n?S.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(S.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||D,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:q.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof S?t[0]:t,S.merge(this,S.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),N.test(r[1])&&S.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(S):S.makeArray(e,this)}).prototype=S.fn,D=S(E);var L=/^(?:parents|prev(?:Until|All))/,H={children:!0,contents:!0,next:!0,prev:!0};function O(e,t){while((e=e[t])&&1!==e.nodeType);return e}S.fn.extend({has:function(e){var t=S(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i;ce=E.createDocumentFragment().appendChild(E.createElement("div")),(fe=E.createElement("input")).setAttribute("type","radio"),fe.setAttribute("checked","checked"),fe.setAttribute("name","t"),ce.appendChild(fe),y.checkClone=ce.cloneNode(!0).cloneNode(!0).lastChild.checked,ce.innerHTML="",y.noCloneChecked=!!ce.cloneNode(!0).lastChild.defaultValue,ce.innerHTML="",y.option=!!ce.lastChild;var ge={thead:[1,"","
"],col:[2,"","
"],tr:[2,"","
"],td:[3,"","
"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?S.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;n",""]);var me=/<|&#?\w+;/;function xe(e,t,n,r,i){for(var o,a,s,u,l,c,f=t.createDocumentFragment(),p=[],d=0,h=e.length;d\s*$/g;function je(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&S(e).children("tbody")[0]||e}function De(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function qe(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Le(e,t){var n,r,i,o,a,s;if(1===t.nodeType){if(Y.hasData(e)&&(s=Y.get(e).events))for(i in Y.remove(t,"handle events"),s)for(n=0,r=s[i].length;n").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var _t,zt=[],Ut=/(=)\?(?=&|$)|\?\?/;S.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=zt.pop()||S.expando+"_"+wt.guid++;return this[e]=!0,e}}),S.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Ut.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Ut.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Ut,"$1"+r):!1!==e.jsonp&&(e.url+=(Tt.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||S.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?S(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,zt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((_t=E.implementation.createHTMLDocument("").body).innerHTML="
",2===_t.childNodes.length),S.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=N.exec(e))?[t.createElement(i[1])]:(i=xe([e],t,o),o&&o.length&&S(o).remove(),S.merge([],i.childNodes)));var r,i,o},S.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(S.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},S.expr.pseudos.animated=function(t){return S.grep(S.timers,function(e){return t===e.elem}).length},S.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=S.css(e,"position"),c=S(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=S.css(e,"top"),u=S.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,S.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},S.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){S.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===S.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===S.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=S(e).offset()).top+=S.css(e,"borderTopWidth",!0),i.left+=S.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-S.css(r,"marginTop",!0),left:t.left-i.left-S.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===S.css(e,"position"))e=e.offsetParent;return e||re})}}),S.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;S.fn[t]=function(e){return $(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),S.each(["top","left"],function(e,n){S.cssHooks[n]=Fe(y.pixelPosition,function(e,t){if(t)return t=We(e,n),Pe.test(t)?S(e).position()[n]+"px":t})}),S.each({Height:"height",Width:"width"},function(a,s){S.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){S.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return $(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?S.css(e,t,i):S.style(e,t,n,i)},s,n?e:void 0,n)}})}),S.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){S.fn[t]=function(e){return this.on(t,e)}}),S.fn.extend({bind:function(e,t,n){return this.on(e,null,t,n)},unbind:function(e,t){return this.off(e,null,t)},delegate:function(e,t,n,r){return this.on(t,e,n,r)},undelegate:function(e,t,n){return 1===arguments.length?this.off(e,"**"):this.off(t,e||"**",n)},hover:function(e,t){return this.mouseenter(e).mouseleave(t||e)}}),S.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){S.fn[n]=function(e,t){return 0"),n("table.docutils.footnote").wrap("
"),n("table.docutils.citation").wrap("
"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n(''),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.prepend(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current").attr("aria-expanded","false"),t.addClass("current").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current").attr("aria-expanded","true");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").attr("aria-expanded","true");t[0].scrollIntoView()}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").attr("aria-expanded","false"),e.toggleClass("current").attr("aria-expanded",(function(n,e){return"true"==e?"false":"true"})))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t + + + + + + + Predbat automation API - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Predbat automation API
    • +
  • +
    • +
+
+
+
+
+ +

Predbat automation API

+

CAUTION This is an expert feature only, you can break Predbat if you set the wrong things here.

+

While for most people Predbat will do what you want without any adjustments there are some special cases where users wish to write some more complex +automations which override Predbat settings

+

For settings inside Home Assistant e.g. switch.predbat_, select.predbat_ and input_number.predbat_* you can already use an automation to change these values

+

For settings in apps.yaml its very difficult or impossible to update them via an automation.

+

For this reasons there is a selector called select.predbat_manual_api which works a bit like the manual override ones but this can have new values added using the select API in Home Assistant. +The only function the selector itself serves is to store override commands, you can clear from the selector but you have to set them using a service call.

+

Certain settings from apps.yaml maybe overridden using this method.

+

Each override is in a string format and works a bit like a web URL, setting the command and the values.

+

Data retention

+

The data for overrides is kept inside the Home Assistant selector itself and so will survive a reboot. There is likely a limit to the size of this data so be sure to remove +old overrides when you are done with them. Keep in mind its easy to lose all of the overrides with the 'off' option so do not keep important data here only use it for short term +automations.

+

Supported command formats

+

The supported formats are:

+
off
+<command>=<value>
+<command>(index)=<value>
+<command>?<name>=<value>
+<command>(index)?<name>=<value>
+<command>?<name>=<value>&<name2>=<value2>
+<command>(index)?<name>=<value>&<name2>=<value2>
+
+

Commands are disabled again by putting them in square brackets e.g:

+
[<command>?<name>=<value>&<name2>=<value2>]
+````
+
+Below is an example of setting a rate override, you can clear all overrides by calling 'off' or this specific one only by calling the same thing again but in square brackets []
+
+For the rates you can use **rates_export_override** or **rates_import_override** with all the same options as apps.yaml but in a URL type format
+
+```text
+rates_export_override?start=17:00:00&end=19:00:00&rate=0
+
+

If you override a single value item in a list with something like:

+
inverter_limit(0)=4000
+
+

To disable this override again:

+
[inverter_limit(0)=4000]
+
+

If you omit the index then all entries in the list will be overridden.

+

To disable all overrides

+
off
+
+

Supported overrides

+

The following settings can be overridden with this method:

+
    +
  • rates_export_override
    • +
  • rates_import_override
    • +
  • inverter_limit
    • +
  • export_limit
    • +
  • days_previous
    • +
  • days_previous_weight
    • +
  • inverter_battery_rate_min
    • +
  • inverter_reserve_max
    • +
  • battery_rate_max
    • +
  • car_charging_soc
    • +
  • car_charging_limit
    • +
  • car_charging_battery_size
    • +
  • battery_scaling
    • +
  • forecast_hours
    • +
  • import_export_scaling
    • +
  • inverter_limit_charge
    • +
  • inverter_limit_discharge
    • +
+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/output-data/index.html b/output-data/index.html new file mode 100644 index 000000000..e4f858622 --- /dev/null +++ b/output-data/index.html @@ -0,0 +1,958 @@ + + + + + + + + Output data - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Viewing Predbat data
    • +
  • Output data
    • +
  • +
    • +
+
+
+
+
+ +

Output data

+

Each time Predbat runs it outputs a lot of information about the current performance of your solar/battery system and the predicted load, PV, cost, CO2, car charging, etc.

+

This section of the documentation explains the different output and logging data that Predbat produces and gives an overview of how to display that information within Home Assistant. +There can never be a single Predbat dashboard that suits every user, so instead Predbat gives a starter-set of displays that can be adapted to your individual needs.

+

Web interface

+

NOTE: The Predbat web interface will not work with the AppDaemon or the Predbat-appdaemon installation methods.

+

Predbat has a Web interface active can be opened via the Predbat Add on by clicking on 'Web UI'. The web interface can be added to your sidebar by turning on the 'Show in Sidebar' toggle.

+

If you are not using the Predbat Add on then you may be able to access the Web Interface directly on port 5052 (e.g. with a Docker Container or Native on your Linux/MAC).

+

The Web interface can allow you to view the current plan, adjust the configuration, view the charts, check your apps.yaml and view the logfiles. You can change your view using +the top menu bar.

+

image

+

Displaying output data

+

Each Predbat configuration item is named input_number.predbat_xxx, switch.predbat_yyy or select.predbat_zzz depending on the control type.

+

Creating a simple Predbat dashboard

+

Each time Predbat runs it auto-generates a dashboard with the filename predbat_dashboard.yaml that can be used as a starter for your own Predbat dashboard. +Depending on how you installed Predbat this predbat_dashboard.yaml file will be held in one of three different directories in Home Assistant:

+ +

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 open +the predbat_dashboard.yaml file - see editing configuration files within Home Assistant if you need to install an editor.

+

Once opened, select and copy all the contents of the predbat_dashboard.yaml file and add the contents into a new dashboard page:

+
    +
  • +

    Go to System/Dashboards, click 'Open' against an existing dashboard or 'Add Dashboard'/'New dashboard from scratch'/enter a name/click Create, then click 'Open'

    +
    • +
  • +

    Click the pencil icon in the top right corner, click the blue 'Add card', scroll down the list of cards to the bottom and click 'Manual', +delete the template card configuration and paste the contents of the predbat_dashboard.yaml file copied earlier, then 'Save'.

    +
    • +
+

This will give you a simple Predbat control and output dashboard that you can then resequence and customise as you wish.

+

image

+

Creating a compact Predbat control dashboard

+

You can also create a dashboard page that's dynamically generated to automatically include all the Predbat control and output entities, +so when new entities are added in future Predbat releases, you don't have to edit the dashboard.

+

Firstly you need to install HACS if it isn't already installed, and then install two HACS front end components:

+ +

Installation steps:

+
    +
  • Click the HACS icon on the left-hand side panel
    • +
  • Click 'Frontend'
    • +
  • Click the three dots in the top right corner then 'Custom Repositories'
    • +
  • Paste (or type) in the following repository name https://github.com/RossMcMillan92/lovelace-collapsable-cards, choose Category of 'Lovelace', and click Add
    • +
  • Close the Custom repositories dialogue
    • +
  • Click 'Explore & Download Repositories'
    • +
  • Search for 'collapsable cards', click the name of it, check it's the right one, click 'Download', 'Download' again, then 'Reload'
    • +
  • Click 'Explore & Download Repositories' again, search for 'auto-entities', then 'Download', 'Download', 'Reload'
    • +
+

Now create the dynamic dashboard:

+
    +
  • Go to Settings/Dashboards, click 'Open' against an existing dashboard or 'Add Dashboard'/'New dashboard from scratch'/enter a name/click Create, then click 'Open'
    • +
  • Click the pencil icon in the top right corner, then the plus symbol on the far right of the next row to create a new View
    • +
  • Enter a title of the View, then Save
    • +
  • Click the blue 'Add card', scroll down the list of cards to the bottom and click 'Manual', +delete the template card configuration and copy/paste the following YAML into the dashboard and click 'Save':
    • +
+
type: vertical-stack
+title: Predbat 🦇
+cards:
+  - type: entities
+    entities:
+      - entity: predbat.status
+      - type: weblink
+        name: Predbat Web Console
+        url: /hassio/ingress/6adb4f0d_predbat
+      - entity: update.predbat_version
+      - entity: select.predbat_update
+      - entity: select.predbat_mode
+      - entity: select.predbat_saverestore
+      - entity: switch.predbat_active
+  - type: custom:collapsable-cards
+    title: 🔀 Control
+    defaultOpen: false
+    cards:
+      - type: custom:collapsable-cards
+        title: 🔢 Input Variables
+        defaultOpen: false
+        cards:
+          - type: custom:auto-entities
+            card:
+              type: entities
+            filter:
+              include:
+                - entity_id: input_number.predbat*
+              exclude: []
+            unique: true
+            sort:
+              method: friendly_name
+              numeric: false
+      - type: custom:collapsable-cards
+        title: 🔀 Switches
+        defaultOpen: false
+        cards:
+          - type: custom:auto-entities
+            card:
+              type: entities
+            filter:
+              include:
+                - entity_id: switch.predbat*
+              exclude: []
+            unique: true
+            sort:
+              method: friendly_name
+              numeric: false
+      - type: custom:collapsable-cards
+        title: 🔢 Selectors
+        defaultOpen: false
+        cards:
+          - type: custom:auto-entities
+            card:
+              type: entities
+            filter:
+              include:
+                - entity_id: select.predbat*
+              exclude: []
+            unique: true
+            sort:
+              method: friendly_name
+              numeric: false
+  - type: custom:collapsable-cards
+    title: '#️⃣ Sensors'
+    defaultOpen: false
+    cards:
+      - type: custom:collapsable-cards
+        title: 💷 Cost Sensors
+        defaultOpen: false
+        cards:
+          - type: custom:auto-entities
+            card:
+              type: entities
+            filter:
+              include:
+                - entity_id: predbat.*cost*
+                - entity_id: predbat.*rate*
+                - entity_id: predbat.*metric*
+              exclude:
+                - entity_id: predbat.*start*
+                - entity_id: predbat.*end*
+                - entity_id: predbat.*duration*
+            unique: true
+            sort:
+              method: friendly_name
+              numeric: false
+      - type: custom:collapsable-cards
+        title: 💷 Saving Sensors
+        defaultOpen: false
+        cards:
+          - type: custom:auto-entities
+            card:
+              type: entities
+            filter:
+              include:
+                - entity_id: predbat.*saving*
+              exclude:
+                - entity_id: predbat.*start*
+                - entity_id: predbat.*end*
+                - entity_id: predbat.*duration*
+            unique: true
+            sort:
+              method: friendly_name
+              numeric: false
+      - type: custom:collapsable-cards
+        title: 🕛 Time/Duration Sensors
+        defaultOpen: false
+        cards:
+          - type: custom:auto-entities
+            card:
+              type: entities
+            filter:
+              include:
+                - entity_id: predbat.*start*
+                - entity_id: predbat.*end*
+                - entity_id: predbat.*duration*
+                - entity_id: predbat.*record*
+              exclude: []
+            unique: true
+            sort:
+              method: friendly_name
+              numeric: false
+      - type: custom:collapsable-cards
+        title: ⚡ Power Sensors
+        defaultOpen: false
+        cards:
+          - type: custom:auto-entities
+            card:
+              type: entities
+            filter:
+              include:
+                - entity_id: predbat.*soc*
+                - entity_id: predbat.*energy*
+                - entity_id: predbat.*load*
+                - entity_id: predbat.*battery*
+                - entity_id: predbat.*kw*
+                - entity_id: predbat.*power*
+                - entity_id: predbat.*charge*
+                - entity_id: predbat.*iboost*
+                - entity_id: predbat.*grid*
+                - entity_id: sensor.predbat_pv*
+              exclude:
+                - entity_id: predbat.*savings*
+                - entity_id: predbat.*start*
+                - entity_id: predbat.*end*
+                - entity_id: predbat.*duration*
+                - entity_id: predbat.*record*
+            unique: true
+            sort:
+              method: friendly_name
+              numeric: false
+      - type: custom:collapsable-cards
+        title: 1️⃣ Binary Sensors
+        defaultOpen: false
+        cards:
+          - type: custom:auto-entities
+            card:
+              type: entities
+            filter:
+              include:
+                - entity_id: binary_sensor.predbat*
+              exclude: []
+            unique: true
+            sort:
+              method: friendly_name
+              numeric: false
+
+

This will give you a compact dynamically created list of all Predbat entities which groups the entities by type and is collapsed by default to prevent screen clutter.

+

image

+

Credit @DJBenson for the code.

+

Viewing the Predbat plan

+
    +
  • predbat.plan_html - A sensor that contains a HTML render of the Predbat predicted best plan, detailing import and export rates, predicted house load, solar generation, +battery SoC, car and iBoost charging, and Predbat's planned charging and discharging activities.
    • +
+

Its recommended to Create the Predbat Plan card as an easy way to see the plan that Predbat has created.

+

If you are using the Predbat add-on then the predbat plan can also be viewed via the 'Plan' tab of the Predbat web console.

+

Graphing the Predbat predictions

+

A set of Apex Charts can also be created to see graphically what Predbat plans to do - Creating the charts.

+

Basic status

+
    +
  • +

    switch.predbat_active - Automatically set by Predbat to On when Predbat is busy calculating or controlling your inverter, +or Off when Predbat is waiting for the next time it needs to perform a plan calculation update. +If you toggle this switch in Home Assistant it will force Predbat to perform an update now (useful for automations).

    +
    • +
  • +

    predbat.status - Gives the current status & errors and logs any changes that Predbat makes to your inverter. +The different Predbat status values and their meanings are detailed in what does Predbat do.

    +
    • +
+

image

+

predbat.status additionally has the following attributes that are automatically populated:

+
    +
  • Last updated - date and time that Predbat last updated the plan
    • +
  • Debug - A set of arrays containing Predbat's planned charging and discharging time windows and battery limits (in kWh)
    • +
  • Version - version of Predbat that's running
    • +
  • Error - binary value true or false depending upon whether Predbat is in an error status or nor
    • +
+

Baseline data

+

Predbat outputs the following sensors to predict what your battery is expected to do over the forecast_hours duration of the plan with no changes made by Predbat. +This is considered to be the 'baseline' plan:

+

NB: All of Predbat's forecasts are from midnight today to the forecast_hours duration (set in apps.yaml) into the future and shouldn't be confused with 'today' figures.

+

e.g. predbat.pv_energy is the actual PV energy from midnight today, and for the predicted forecast_hours (typically 48) ahead +so will be much larger than sensor.solcast_pv_forecast_today which is today's Solcast PV forecast.

+
    +
  • predbat.battery_cycle - Predicted baseline battery cycle in kWh (total kWh processed) with attributes of the prediction every 5 minutes to end of plan
    • +
  • predbat.battery_hours_left - The number of hours left until your home battery is predicted to run out under the baseline plan (stops at the maximum prediction time)
    • +
  • predbat.battery_power - The sensor is always zero; attributes contain the predicted remaining battery power under the baseline plan, in 5 minute slots, for charting
    • +
  • predbat.car_soc - The expected charge level of your car at the end of the baseline plan. Can also be charted
    • +
  • predbat.charge_end - Predicted end time of the next forced battery charging under the baseline plan
    • +
  • predbat.charge_limit - Predicted baseline battery charge limit for the next charge in percent with attributes of all future battery charging times & limits
    • +
  • predbat.charge_limit_kw - Predicted baseline battery charge limit for the next charge in kWh with attributes of future charging times & limits
    • +
  • predbat.charge_start - Predicted start time of the next forced battery charging under the baseline plan
    • +
  • predbat.duration - The duration of the prediction maximum in hours
    • +
  • predbat.export_energy - Total kWh of predicted exports under the baseline plan with attributes of the predicted export kWh and their time slots
    • +
  • predbat.grid_power - The sensor is always zero; attributes contain the predicted Grid power (positive or negative for import or export) +in kW per 5 minute slots to the end of the baseline plan for charting
    • +
  • predbat.import_energy - Total kWh of predicted imports under baseline plan with attributes of the predicted import kWh and their time slots
    • +
  • predbat.import_energy_battery - Total kWh of predicted import energy used to charge the home battery under the baseline plan
    • +
  • predbat.import_energy_house - Predicted import energy used by the home under the baseline plan that is not provided by your home battery +(e.g. due to a flat battery or load is above maximum discharge rate)
    • +
  • predbat.load_energy - Total kWh of predicted house load under the baseline plan with attributes of the predicted load kWh in 5 minute slots to the end of the plan
    • +
  • predbat.load_power - Total kW of predicted house load power to the end of the baseline plan, +with attributes of the average instantaneous house load power in kW in 5 minute slots to the end of the plan
    • +
  • predbat.metric - Total predicted cost for the baseline plan, taking account of predicted solar generation, house load, import and export rates. +Attributes contain data for charting the cost prediction in 5 minute slots to the end of the plan
    • +
  • predbat.pv_energy - Predicted PV energy in kWh under the baseline plan with attributes of the predicted PV generation in kWh with time slots
    • +
  • predbat.pv_power - Predicted PV power now with attributes that contain the predicted PV power in kW per 5 minute slots to the end of the baseline plan for charting
    • +
  • predbat.soc_kw - Predicted state of charge (in kWh) at the end of the baseline plan prediction, not very useful in itself, +but the attributes hold prediction data in 5 minute intervals which can be charted with Apex Charts (or similar)
    • +
  • predbat.soc_min_kwh - Predicted lowest battery SoC value in kWh under the baseline plan with attribute of the date/time that that lowest SoC occurs at
    • +
+

PV 10% Baseline data

+

Predbat outputs the following baseline results under the PV 10% scenario for the forecast_hours duration of the plan, these are known as the 'base10' predictions:

+
    +
  • predbat.base10_export_energy- Total predicted export energy in kWh for the PV 10% scenario, with attributes of the predicted export kWh and their time slots
    • +
  • predbat.base10_import_energy- Total predicted import energy in kWh for the PV 10% scenario, with attributes of the predicted import kWh and their time slots
    • +
  • predbat.base10_load_energy - Total predicted house load in kWh for the PV 10% scenario
    • +
  • predbat.base10_metric - Total predicted cost for the PV 10% scenario, with attributes of the cost prediction in 5 minute slots to the end of the plan for charting
    • +
  • predbat.base10_pv_energy - Predicted PV 10% energy in kWh with attributes of the predicted PV generation in kWh with time slots
    • +
  • predbat.soc_kw_base10 - Predicted final state of charge (in kWh) of the battery, +with attributes of the predicted SoC in 5 minute time slots to the end of the plan under the PV 10% scenario, for charting
    • +
+

Best Prediction data

+

Predbat outputs the following 'best' entities from the forecast (for the forecast_hours duration) based on the lowest cost consumption plan. +The 'best' plan in Predbat parlance is simply Predbat's lowest cost predicted plan:

+
    +
  • predbat.battery_cycle_best - Predicted best battery cycle in kWh (total kWh processed) with attributes of the prediction every 5 minutes to end of plan
    • +
  • predbat.battery_power_best - Predicted remaining battery power in kW with attributes of the future prediction in 5 minute slots
    • +
  • predbat.best_battery_hours_left - Predicted total number of hours of battery capacity left under the best plan
    • +
  • predbat.best_charge_end - Predicted end time of the next forced battery charging under the best plan
    • +
  • predbat.best_charge_limit - Predicted best battery charge limit for the next charge in percent with attributes of all future battery charging times & limits
    • +
  • predbat.best_charge_limit_kw - Predicted best battery charge limit for the next charge in kWh with attributes of future charging times & limits
    • +
  • predbat.best_charge_start - Predicted start time of the next forced battery charging under the best plan
    • +
  • predbat.best_export_end - Predicted end time of the next forced battery export under the best plan
    • +
  • predbat.best_export_limit - Predicted best battery export limit in percent (will be 0% when discharging or 100% when not) +with attributes of all future battery exports (kWh and time slots)
    • +
  • predbat.best_export_limit_kw - Predicted best battery export limit in kWh
    • +
  • predbat.best_export_start - Predicted start time of the next forced battery export under the best plan
    • +
  • predbat.best_export_energy - Total kWh of predicted exports under the best plan, with attributes of the predicted export kWh and their time slots
    • +
  • predbat.best_import_energy - Total kWh of predicted imports under best plan, with attributes of the predicted import kWh and their time slots
    • +
  • predbat.best_import_energy_battery - Total kWh of predicted import energy to charge the home battery under the best plan
    • +
  • predbat.best_import_energy_house - Total kWh of predicted import energy used directly by the house under the best plan +(e.g. due to a flat battery or the house load is greater than the max discharge rate)
    • +
  • predbat.best_load_energy - Total kWh of predicted house load energy in kWh under the best plan with attributes of the predicted load kWh in 5 minute slots to the end of the plan
    • +
  • predbat.best_metric - Total predicted cost for the best plan, taking account of predicted solar generation, house load, import and export rates. +Attributes contain data for charting the cost prediction in 5 minute slots to the end of the plan
    • +
  • predbat.best_pv_energy - Predicted PV energy in kWh under the best plan with attributes of the predicted PV generation in kWh with time slots
    • +
  • predbat.best_soc_min_kwh - Predicted lowest battery SoC value in kWh under the best plan with attribute of the date/time that that lowest SoC occurs at
    • +
  • predbat.car_soc_best - See Car data below
    • +
  • predbat.carbon_best - See Carbon data below
    • +
  • predbat.grid_power_best - The sensor is always zero; attributes contain the predicted Grid power (positive or negative for import or export), +in kW per 5 minute slots to the end of the best plan for charting
    • +
  • predbat.iboost_best - See iBoost data below
    • +
  • predbat.load_power_best - Total kW of predicted house load power to the end the best plan, +with attributes of the average instantaneous house load power in kW in 5 minute slots to the end of the plan
    • +
  • predbat.pv_power_best - The sensor is always zero; attributes contain the predicted PV power in kW per 5 minute slots to the end of the best plan for charting
    • +
  • predbat.soc_kw_best - Predicted final state of charge (in kWh) with attributes of the predicted SoC in 5 minute time slots to the end of the best plan, for charting
    • +
  • predbat.soc_kw_best_h1 - Single data point for the predicted state of charge in 1 hours time (useful for calibration charts, predicted vs actual)
    • +
  • predbat.soc_kw_best_h8 - Single data point for the predicted state of charge in 8 hours time (useful for calibration charts, predicted vs actual)
    • +
  • predbat.soc_kw_best_h12 - Single data point for the predicted state of charge in 12 hours time (useful for calibration charts, predicted vs actual)
    • +
+

Best PV 10% Prediction data

+

Predbat outputs the following best results under the PV 10% scenario for the forecast_hours duration, these are known as the 'best10' prediction:

+
    +
  • predbat.best10_metric - Predicted best cost in pence using the PV 10% solar forecast
    • +
  • predbat.best10_export_energy- Predicted best export energy in kWh for PV 10%
    • +
  • predbat.best10_import_energy- Predicted best import energy in kWH for PV 10%
    • +
  • predbat.best10_load_energy - Predicted best load energy in kWh for PV 10%
    • +
  • predbat.best10_pv_energy - Predicted best PV 10% energy in kWh
    • +
  • predbat.soc_kw_best10 - As soc_kw_best but using the PV 10%, also holds minute by minute data (in attributes) to be charted
    • +
+

In-day load adjustment data

+

The following sensors are used in the in-day adjustment chart - see creating the Predbat charts and in day load adjustment:

+
    +
  • predbat.load_energy_actual - Total kWh of house load to end of plan, energy up to 'now' taken from today's actual energy, energy after 'now' from Predbat's prediction. +Attributes of this actual/predicted energy in 5 minute slots from midnight today to the end of the plan for charting
    • +
  • predbat.load_energy_adjusted - Total kWh of predicted house load to end of plan, adjusted based on variance of today's actual load +to the predicted load (based on historical data), dampened according to input_number.predbat_metric_inday_adjust_damping. +Attributes contain the 5 minute slot forecasts to end of plan for charting
    • +
  • predbat.load_energy_predicted - Total predicted kWh of house load to end of plan, attributes of predicted load in 5 minute slots from midnight today to the end of the plan for charting
    • +
  • predbat.load_inday_adjustment - the % in-day adjustment factor used to adjust Predbat's predicted load by actual load today
    • +
+

'Today' energy data

+

The following sensors output by Predbat give the 'today' energy readings. +They mirror input sensors fed into Predbat in apps.yaml and are used in the data prediction chart - see creating the Predbat charts:

+
    +
  • predbat.export_energy_h0 - Mirrors the export_today sensor configured in apps.yaml and gives today's total kWh of export energy
    • +
  • predbat.import_energy_h0 - Mirrors the import_today sensor configured in apps.yaml and gives today's total kWh of import energy
    • +
  • predbat.load_energy_h0 - Mirrors the load_today sensor configured in apps.yaml and gives today's total kWh of house load energy
    • +
  • predbat.pv_energy_h0 - Mirrors the pv_today sensor configured in apps.yaml and gives today's total kWh of generated PV energy
    • +
  • predbat.soc_kw_h0 - Mirrors the soc_kwh sensor configured in apps.yaml and gives today's total kWh of battery state of charge (SoC). +Note that if you have configured battery scaling then soc_kw_h0 will have been scaled by the configured scaling factor
    • +
+

Battery status

+

The following sensors are set based upon what Predbat is currently controlling the battery to do:

+
    +
  • binary_sensor.predbat_charging - Set to 'on' when Predbat is force charging the battery (from solar, or if that is insufficient, from grid import), or 'off' otherwise
    • +
  • binary_sensor.predbat_exporting - Set to 'on' when Predbat is force discharging the battery for export income, 'off' otherwise.
    • +
+

These are useful for automations if for example you want to turn off car charging when the battery is being exported.

+

Export trigger

+
    +
  • binary_sensor.predbat_export_trigger_NAME - custom binary sensors that are set to On by Predbat when more than a specified amount of energy is being exported - see Triggers in apps.yaml
    • +
+

Prediction window

+
    +
  • predbat.record - The sensor is always zero; attributes contain the time window for the current predicted plan
    • +
+

Energy rate data

+

Low rate import entities

+
    +
  • predbat.low_rate_cost - The lowest import rate cost in Pence
    • +
  • predbat.low_rate_duration - The time duration in minutes of the next low rate slot
    • +
  • predbat.low_rate_end - End time of the next low import rate slot
    • +
  • predbat.low_rate_start - Start time of the next low import rate slot
    • +
  • predbat.low_rate_cost_2, predbat.low_rate_end_2, predbat.low_rate_start_2 - The cost and times of the following low import rate slot
    • +
  • binary_sensor.predbat_low_rate_slot - A sensor that is 'on' to indicate when there is a low energy rate import slot active, 'off' otherwise
    • +
+

High rate export entities

+
    +
  • predbat.high_rate_export_cost - The highest export rate cost in Pence
    • +
  • predbat.high_rate_export_duration - The time duration in minutes of the next high rate slot
    • +
  • predbat.high_rate_export_end - End time of the next high export rate slot
    • +
  • predbat.high_rate_export_start - Start time of the next high export rate slot
    • +
  • predbat.high_rate_export_cost_2, predbat.high_rate_export_end_2, predbat.high_rate_export_start_2 - The cost and times of the following high export rate slot
    • +
  • binary_sensor.predbat_high_rate_export_slot - A sensor that is 'on' to indicate when there is a high export rate slot active, 'off' otherwise
    • +
+

Other rate entities

+
    +
  • predbat.rates - The current energy import rate in Pence with attributes of yesterday's, todays and tomorrow's rates which can be charted
    • +
  • predbat.rates_export - The current energy export rates in Pence (also can be charted)
    • +
  • predbat.rates_gas - The current gas rates in Pence (also can be charted)
    • +
  • predbat.cost_today - The total cost of energy so far today (since midnight) with attributes of the total cost every 5 minutes since midnight today
    • +
  • predbat.cost_today_export - Same as predbat.cost_today, but for all export income since midnight today
    • +
  • predbat.cost_today_import - Same as predbat.cost_today, but for all import costs since midnight today
    • +
  • predbat.cost_hour - The total cost of energy averaged over the last hour
    • +
  • predbat.cost_today_export - Same as predbat.cost_hour, but for export
    • +
  • predbat.cost_today_import - Same as predbat.cost_hour, but for import
    • +
  • predbat.ppkwh_today - The cost in pence/kWh of the house load today accounting for the change in battery level
    • +
  • predbat.ppkwh_hour - The cost in pence/kWh of the house load averaged over the last hour, accounting for the change in battery level
    • +
+

Car data

+
    +
  • binary_sensor.predbat_car_charging_slot - A binary sensor indicating when to charge your car (if car planning is enabled) - which can be used in an automation +as described in Predbat led car charging
    • +
  • predbat.car_charging_start - The time that car charging is planned to start at, in HH:MM:SS format
    • +
  • predbat.car_soc_best - Predicted charge level of your car in the best plan at the end of the plan using the proposed car charging SoC% and charge window. Can also be charted
    • +
  • predbat.cost_today_car - Current cost in pence so far today of charging the car, with attribute of the projected future car charging costs and slots
    • +
  • predbat.cost_total_car - A running total in pence of the below cost_yesterday_car sensor, with attribute of the total in pounds
    • +
  • predbat.cost_yesterday_car - A sensor that gives the total energy costs in pence of charging the car for yesterday (00:00-23:59 on the previous day)
    • +
+

iBoost Solar Diverter data

+
    +
  • binary_sensor.predbat_iboost_active - A binary sensor indicating when there is excess solar and the solar diverter (e.g. iBoost, Eddi or just plain immersion heater) should be active, +can be used for automations to trigger the immersion heater boost
    • +
  • input_number.predbat_iboost_today - Gives the amount of energy modelled that will be sent to the solar diverter today, +increments during the day and is reset to zero at 11:30pm each night
    • +
  • predbat.iboost_best - Predicted energy in kWh going into the iBoost solar diverter under the best plan
    • +
+

Carbon data

+

The following sensors output by Predbat give historic and predicted carbon data. +They are used in the carbon chart - see creating the Predbat charts:

+

predbat.carbon - Predicted Carbon energy in g at the end of the plan with attributes giving the breakdown of predicted Carbon impact by half hour time slots +predbat.carbon_best - Predicted Carbon intensity in g for your home under the best plan based on grid imports, grid exports and the grid's projected carbon intensity +predbat.carbon_now - A sensor that gives the current Grid Carbon intensity in g/kWh +predbat.carbon_today - A sensor that tracks your home's Carbon impact today in g based on your grid import minus your grid export

+

Energy saving data

+

The following sensors output by Predbat give cost saving data that Predbat achieved, i.e. the financial benefits of using Predbat. +They are used in the daily cost saving and total cost savings charts - see creating the Predbat charts:

+
    +
  • predbat.cost_yesterday - A sensor that gives the total energy costs in pence for yesterday (00:00-23:59 on the previous day)
    • +
  • predbat.savings_total_actual - A running total in pence of the above cost_yesterday sensor, with attribute of the total in pounds
    • +
  • predbat.savings_total_predbat - A running total in pence of the below savings_yesterday_predbat sensor, with attribute of the total in pounds
    • +
  • predbat.savings_total_pvbat - A running total of the below savings_yesterday_pvbat sensor, with attribute of the total in pounds
    • +
  • predbat.savings_total_soc - A running total of what the final SoC in kWh would have been at the end of each day if you were not using Predbat
    • +
  • predbat.savings_yesterday_predbat - A sensor which tells you how much money Predbat saved you yesterday compared to not using Predbat, +and only charging at the lowest import rate in the 24 hour period
    • +
  • predbat.savings_yesterday_pvbat - A sensor which tells you how much money you saved from using Predbat +vs not having a PV and battery system at all and all house load being met from grid import
    • +
+

Solar forecast data

+

The following sensors give the forecast Solar data from Solcast. +Predbat populates these sensors irrespective of whether you are using the Predbat direct Solcast or Solcast integration method to get your Solar forecast, +but if you are using the Solcast integration then the Predbat sensors mirror the similarly named Solcast integration sensors so could be disabled if you so wish.

+
    +
  • sensor.predbat_pv_today - Tracks the PV forecast in kWh for today, attributes give the remaining amount today and the half hourly data
    • +
  • sensor.predbat_pv_tomorrow - Tracks the PV forecast in kWh for tomorrow, attributes give the remaining amount today and the half hourly data
    • +
  • sensor.predbat_pv_d2 - Similar to the above, but tracking the PV forecast for the day after tomorrow
    • +
  • sensor.predbat_pv_d3 - PV forecast for two days after tomorrow
    • +
  • sensor.predbat_pv_forecast_h0 - Tracks the PV 'power now' forecast in Watts, attributes give the 10% and 90% power now forecast
    • +
+

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!

+

If you are using the Predbat add-on then the logfile can easily be viewed via the 'Log' tab of the Predbat web console.

+

To directly view the physical logfile, it can be found in one of three different directories in Home Assistant with slightly different filenames depending on how you installed Predbat:

+ +

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 if you are not using the Predbat add-on. +See editing configuration files within 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 running the Home Assistant Companion app.

+

To create a new automation:

+
    +
  • Settings / Automations & Scenes
    • +
  • Create Automation / Create new Automation
    • +
  • Three dots (top right corner) / Edit in YAML
    • +
  • Delete the existing (template) automation code and copy/paste the supplied automation code below
    • +
+

GivTCP activity monitor

+

This automation will raise an alert if any of the following occur:

+
    +
  • The inverter goes offline for more than 15 minutes
    • +
  • No last_updated_time received from the inverter for more than 15 minutes
    • +
  • Inverter temperature less than 5 degrees for more than 15 minutes (should never happen)
    • +
  • The battery goes offline to the inverter for more than 15 minutes
    • +
  • GivTCP add-on is not running
    • +
  • Mosquitto broker add-on is not running
    • +
  • Predbat/AppDaemon-predbat or AppDaemon add-on (as appropriate) is not running
    • +
+

The script will need to be customised for your inverter id, battery id and mobile details, +and can be extended for multiple inverters and batteries by duplicating the triggers and adding appropriate battery and inverter id's.

+
alias: GivTCP activity monitor
+description: Alert when communications to GivTCP have ceased for 15 minutes
+triggers:
+  - trigger: state
+    entity_id: sensor.givtcp_<inverter id>_last_updated_time
+    to: "null"
+    for:
+      minutes: 15
+    variables:
+      alert_text: No GivTCP update received from inverter <id>
+      restart_app: GivTCP
+  - trigger: state
+    entity_id:
+      - sensor.givtcp_<inverter id>_status
+    from: online
+    for:
+      minutes: 15
+    variables:
+      alert_text: No GivTCP update received from inverter <id>
+      restart_app: GivTCP
+  - trigger: numeric_state
+    entity_id:
+      - sensor.givtcp_<inverter id>_invertor_temperature
+    for:
+      minutes: 15
+    below: 10
+    variables:
+      alert_text: No GivTCP update received from inverter <id>
+      restart_app: GivTCP
+  - trigger: state
+    entity_id:
+      - sensor.givtcp_<battery id>_battery_cells
+    to: unknown
+    for:
+      minutes: 15
+    variables:
+      alert_text: Battery <battery_id> is offline to GivTCP
+      restart_app: GivTCP
+  - trigger: state
+    entity_id:
+      - binary_sensor.givtcp_running
+    to: "off"
+    for:
+      minutes: 15
+    variables:
+      alert_text: GivTCP add-on is not running
+      restart_app: GivTCP
+  - trigger: state
+    entity_id:
+      - binary_sensor.mosquitto_broker_running
+    to: "off"
+    for:
+      minutes: 15
+    variables:
+      alert_text: Mosquitto Broker add-on is not running
+      restart_app: Mosquitto
+actions:
+  - action: notify.mobile_app_<your mobile device id>
+    alias: Send a notification
+    data:
+      title: GivTCP communication issue
+      message: |
+        {{now().strftime('%-d %b %H:%M')}} ISSUE:
+        {{ alert_text }} for the past 15 minutes, restarting
+        {{ restart_app }}
+      data:
+        visibility: public
+        persistent: true
+        push:
+          sound:
+            name: default
+            critical: 1
+            volume: 0.8
+          sticky: true
+          color: red
+  - choose:
+      - conditions:
+          - condition: template
+            value_template: "{{ restart_app == 'GivTCP' }}"
+        sequence:
+          - alias: Restart GivTCP add-on
+            action: hassio.addon_restart
+            data:
+              addon: 533ea71a_givtcp
+      - conditions:
+          - condition: template
+            value_template: "{{ restart_app == 'Mosquitto' }}"
+        sequence:
+          - alias: Restart Mosquitto add-on
+            action: hassio.addon_restart
+            data:
+              addon: core_mosquitto
+trace:
+  stored_traces: 20
+mode: single
+
+

The last two triggers (GivTCP and Mosquitto running) trigger if any of these add-ons that Predbat is dependent upon are not running. +You will need to enable a binary sensor for each add-on to be able to use these triggers in the automation:

+
    +
  • Navigate to Settings / Devices and Services / Devices and search for 'GivTCP'
    • +
  • Click on the GivTCP add-on, and under 'Sensors', click 'XX entities not shown'
    • +
  • Click the 'Running' sensor, then the cogwheel, and Enable the sensor
    • +
+

Repeat these steps for the 'Mosquitto' add-on.

+

As an extension to the above, if you don't want the automation to restart the failing add-on and instead just send an alert that there is a problem, delete the 'choose' code above. +Restarting GivTCP does however lose the current GivTCP log in Home Assistant.

+

NB: If you are using GivTCP v2 rather than v3, replace the '533ea71a_givtcp' with 'a6a2857d_givtcp'.

+

Predbat error monitor

+

This automation will raise an alert if Predbat's status turns to Error for more than 5 minutes.

+

In normal operation Predbat will automatically run and update its forecast every 5 minutes. If the automation detects that Predbat has not done this for 20 minutes, +then an alert will be raised and the automation will restart the Predbat add-on to try to resolve a 'hung Predbat' issue.

+

In the same way for the GivTCP and Mosquitto add-on's above, the last trigger requires you to enable a binary sensor that detects that the Predbat/AppDaemon add-on is running. +Follow the same steps to enable the binary sensor for either the 'Predbat', 'AppDaemon' or 'AppDaemon-predbat' add-on depending on which Predbat installation method you followed.

+

The script will need to be customised for your mobile details.

+
alias: Predbat error monitor
+description: Alert when Predbat has raised an exception
+trace:
+  stored_traces: 20
+triggers:
+  - trigger: template
+    alias: Predbat status contains 'Error' for 5 minutes
+    value_template: "{{ 'Error' in states('predbat.status') }}"
+    for:
+      minutes: 5
+    variables:
+      alert_text: >-
+        predbat status is {{ states('predbat.status') }}, error={{
+        state_attr('predbat.status', 'error') }}
+  - trigger: state
+    alias: Predbat is in error status for 5 minutes
+    entity_id: predbat.status
+    attribute: error
+    to: "true"
+    for:
+      minutes: 5
+    variables:
+      alert_text: >-
+        predbat status is {{ states('predbat.status') }}, error={{
+        state_attr('predbat.status', 'error') }}
+  - trigger: state
+    alias: Predbat status.last_updated has not changed for 20 minutes
+    entity_id: predbat.status
+    attribute: last_updated
+    for:
+      minutes: 20
+    variables:
+      alert_text: >-
+        Predbat stalled? Restarting. last_updated=' {{
+        state_attr('predbat.status','last_updated')|as_timestamp|timestamp_custom('%a
+        %H:%M') }}', unchanged for 20 mins; Status='{{ states('predbat.status')
+        }}'
+      restart_predbat: "Y"
+  - trigger: state
+    entity_id: binary_sensor.predbat_running
+    to: "off"
+    for:
+      minutes: 15
+    variables:
+      alert_text: Predbat add-on is not running
+      restart_predbat: "Y"
+actions:
+  - action: notify.mobile_app_<your mobile device id>
+    alias: Send alert message
+    data:
+      title: Predbat status issue
+      message: |
+        {{now().strftime('%-d %b %H:%M')}} ISSUE:
+        {{ alert_text }}
+      data:
+        visibility: public
+        persistent: true
+        push:
+          sound:
+            name: default
+            critical: 1
+            volume: 0.8
+        sticky: true
+        color: red
+  - if:
+      - condition: template
+        value_template: "{{ restart_predbat == 'Y' }}"
+    then:
+      - action: hassio.addon_restart
+        data:
+          addon: 6adb4f0d_predbat
+        alias: Restart Predbat add-on
+mode: single
+
+

NB: If you are using AppDaemon rather than the Predbat add-on, replace '6adb4f0d_predbat' with 'a0d7b954_appdaemon' and change 'binary_sensor.predbat_running' to 'binary_sensor.appdaemon_running'.

+

An error alert looks like this:

+

image

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/predbat-plan-card/index.html b/predbat-plan-card/index.html new file mode 100644 index 000000000..73c168d60 --- /dev/null +++ b/predbat-plan-card/index.html @@ -0,0 +1,383 @@ + + + + + + + + Predbat Plan card - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Viewing Predbat data
    • +
  • Predbat Plan card
    • +
  • +
    • +
+
+
+
+
+ +

Predbat Plan card

+

Predbat can create its own plan card which can be added to your Home Assistant dashboard.

+

At a glance the Predbat plan shows you the plan going forward of home demand, EV charging, iBoost and for your battery, and any actions that Predbat plans to take.

+

Displaying the Predbat plan

+

Firstly install the HTML template card in HACS:

+
    +
  • In HACS, click on Frontend
    • +
  • Click the blue Explore and download repositories button and type 'HTML'
    • +
  • Click on 'HTML Jinja2 Template card', then click the blue 'Download', then 'Download' again to install it
    • +
  • When prompted to 'reload your browser', click 'Reload'
    • +
+

NB: Do not install the very similarly named 'Lovelace Html card', it won't work! You must install 'HTML Jinja2 Template card'.

+

Next, on a Home Assistant dashboard, click the blue 'Add card', scroll down the list of cards to the bottom and click 'Manual', +delete the template card configuration and copy/paste the following to display the Predbat plan:

+
type: custom:html-template-card
+title: Predbat plan
+ignore_line_breaks: true
+content: |
+  {{ state_attr('predbat.plan_html', 'html') }}
+
+

You should see something like this:

+

image

+

If you get an error 'Custom element doesn't exist: html-template-card' then you've not installed the Jinja2 template card correctly from HACS.

+

Understanding the Predbat plan

+

For every half hour period (slot) that Predbat has planned for (the forecast_hours setting in apps.yaml), the Predbat plan shows:

+
    +
  • The import rate in pence for that slot
    • +
  • The export rate in pence for that slot
    • +
  • What 'status' Predbat will be in (e.g. Charging, Discharging)
    • +
  • Any limit applied (e.g. charging to 70%)
    • +
  • Forecast Solar generation (from Solcast)
    • +
  • Forecast house load (from your historical load data)
    • +
  • Planned car charging (if car charging is configured in Predbat)
    • +
  • Planned iBoost immersion heating (if iBoost is configured)
    • +
  • What the battery SoC will be at the start of the 30 minute slot
    • +
  • The forecast cost for the half hour slot
    • +
  • A running total cost
    • +
  • Forecast CO2 Carbon intensity and Carbon footprint emitted by the grid's electricity generation, and the direction of travel over the slot (if carbon forecasting is enabled)
    • +
+

Rate symbols (import and export):

+
    +
  • ? ⅆ - Rate that has been modified based on input_number.predbat_metric_future_rate_offset_import or input_number.predbat_metric_future_rate_offset_export
    • +
  • ? ⚖ - Rate that has been estimated using future rate estimation data (e.g. Nordpool)
    • +
  • = - Rate that has been overridden by the users apps.yaml
    • +
  • ± - Rate that has been adjusted with a rate offset in the users apps.yaml
    • +
  • $ - Rate that has been adjusted for an Octopus Saving session
    • +
  • ? - Rate that has not yet been defined and the previous days data was used instead
    • +
+

Battery SoC symbols:

+
    +
  • → - Current SoC expected to remain level
    • +
  • ↘ - Current SoC expected to fall
    • +
  • ↗ - Current SoC expected to rise
    • +
+

Cost symbols:

+
    +
  • → - Current cost expected to remain level
    • +
  • ↘ - Current cost expected to fall (due to export)
    • +
  • ↗ - Current cost expected to rise (due to import or standing charge)
    • +
+

Explaining each column in the Predbat plan in more detail:

+
    +
  • +

    Time - Predbat plans your home, solar and battery load in 30 minute slots, on the :00 and :30 minutes past each hour. +The Predbat slots are therefore aligned to Octopus Agile slots or rate change times on any other tariff.

    +
    • +
  • +

    Import - The import rate for that time slot in pence.
    +The rate will be coloured Blue if the price is zero pence or negative, +Green if the rate is less than the import rate threshold, +Red if the rate is more than 1.5 times the import rate threshold, +and Yellow if the rate is between 1 and 1.5 times the import rate threshold.
    +See the Predbat customisation guide for explanation of the import rate threshold (and over-riding it), but in essence +Predbat will consider blue and green-coloured slots as preferred candidates for importing, yellow and red (higher rates) will not.
    +If battery charging is planned by Predbat for a particular slot, the import rate for that slot will be highlighted in bold text.

    +
    • +
  • +

    Export - Similarly, the export rate for that time slot in pence.
    +The rate will be coloured White if the price is less than the export rate threshold, +Yellow if it is more than the export rate threshold, +and pale Red if the rate is more than 1.5 times the export rate threshold.
    +So in essence, Yellow and Red coloured export rates will be considered as priorities for exporting, White will not.
    +If battery discharging is planned by Predbat for a particular slot, the export rate for that slot will be highlighted in bold text.

    +
    • +
  • +

    State - Predbat's status controls whether the battery is charging, discharging to support house load (Demand mode), +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 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, Dark Grey for Freeze Discharging, 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_export_oncharge is set to True, +then within a 30 minute slot (and depending on import and export rates) Predbat could potentially plan for there to be both +charging and discharging activity - if Predbat plans this, state will show as both Charging and Exporting in the same slot.

    +
    • +
  • +

    Limit % - Alongside any battery activity (charging, discharging, etc) there will be a SoC limit. This limit is what the SoC is planned to be at the end of the 30 minute time slot. +e.g. 'Charge↗ 70%' is charge to 70% SoC, and 'Exp↘ 4%' is force exporting the battery to the 4% reserve level.

    +
    • +
  • +

    PV kWh - The predicted solar forecast for the half hour slot, estimated from the Solcast Forecast.
    +If the PV forecast is above 0.2kWh for the slot it will be coloured Melon Red with a little sun symbol, above 0.1kWh it will be Yellow with a sun symbol, +otherwise it will be Silver Grey.

    +
    • +
  • +

    Load kWh - The predicted house load for the half hour slot, estimated as a weighted average of the number of days_previous +Historical data from your inverter or other house load sensor.
    +If the load forecast is 0.5kWh or above for the slot it will be coloured Orangey-Red, from 0.25kWh to 0.5 it will be coloured Yellow, +above 0 to 0.25 it will be Light Green, and if zero, it will be coloured White.

    +
    • +
  • +

    Car kWh - The total predicted car charging for the half hour slot. This column will only be shown if num_cars in apps.yaml is 1 or more.
    +If the car is planned to be charged in that slot then the kWh will be coloured Yellow, otherwise it will be White.

    +
    • +
  • +

    iBoost kWh - The energy planned for solar diverter immersion heating such as iBoost or MyEnergi Eddi. +This column will only be shown if switch.predbat_iboost_enable is set to True.
    +If the solar diverter is planned to be on in that slot then the kWh will be coloured Yellow, otherwise it will be White.

    +
    • +
  • +

    SoC % - The estimate of battery State of Charge percentage at the start of the time slot +together with an arrow pointing up, to the right or downwards to indicate whether the battery SoC is increasing, remaining constant or decreasing during the time slot.
    +The 'SoC %' can be read in conjunction with the 'Limit %'; the SoC column gives the estimated SoC at the beginning of the slot, +the Limit column the estimated SoC at the end of the slot.
    +If the SoC is 50% or greater it will be coloured Green, 20% or greater, Yellow, and if less than 20%, Orangey-Red.

    +
    • +
  • +

    Cost - The estimated cost in pence for the time slot together with an arrow indicating whether the total cost today is increasing, staying flat or decreasing.
    +If the cost for the slot is 10p or more it will be coloured Orangey-Red, ½p or more it will be coloured Yellow, -½p or less it will be coloured Green, +otherwise it will be coloured White.

    +
    • +
  • +

    Total - The total cumulative cost so far for 'today' at the start of the slot, including the standing charge. +At midnight tonight this cumulative cost will be reset to the daily standing charge (or zero if metric_standing_charge wasn't set in apps.yaml).
    +Due to the way Predbat works, total cost is always reported (in Predbat output entities, this HTML plan, in the Apex charts, etc) +as starting from midnight today and adding on from there.
    +Looking at the sample Predbat plan above as an example, the plan starts at 10:00 with total cost today already being £3.13. The house load is then fully met through the day and evening +by the battery (with some PV top-up charging) so total cost remains constant at £3.13.
    +In the 22:30 and 23:00 slots there is a little grid import, and then at 23:30 there's grid import and the battery starts to be charged. +As you can see the Total continues to increase in the plan past midnight with each Total being +the Total from the preceding slot plus the Cost estimate from the preceding slot - reminder that Total gives the running total at the start of the slot.
    +Total cost is always coloured White.

    +
    • +
  • +

    CO2 (g/kWh) - The estimated CO2 Carbon intensity emitted by the grid when generating electricity at the start of the 30 minute slot. +This column will only be shown if switch.predbat_carbon_enable is set to True.
    +The CO2 value will be coloured according to how high the carbon footprint intensity is: greater or equal to 450g/kWh it will be deep red; greater or equal to 290, dark red; +then golden orange from 200 upwards; yellow from 120; green from 40 and light green if less than 40.

    +
    • +
  • +

    CO2 (kg) - The estimated CO2 Carbon footprint that the grid will emit generating electricity at the start of the slot and the direction of travel over the slot. +This column will only be shown if switch.predbat_carbon_enable is set to True.
    +The carbon amount in kg will be coloured according to the direction of travel over the slot; if the carbon value is rising by 10kg or more it will be orange with an upwards arrow; +if falling by 10kg or more it will green with a downwards arrow, and in the middle, white with a horizontal arrow.

    +
    • +
+

Debug mode for Predbat Plan

+

If Predbat expert mode is turned on then a number of additional controls and switches are made available in Home Assistant.

+

If switch.predbat_plan_debug is then turned on then the Predbat plan shows additional 'debugging' information for the import rate, export rate, load and PV columns.

+

The Predbat plan will now look like this with plan_debug turned on:

+

IMAGE

+

Import and Export rate will now show the actual rate (according to how you have setup the energy rates) and also in brackets the effective import or export rate.

+

The effective rate takes into account battery and inverter energy losses for charging and discharging and converting from DC to AC and vice-versa. +Note that the Cost and Total columns are always based upon the actual Import and Export rate.

+

Using the above debug plan as an example:

+
    +
  • +

    At 22:30 the battery is being charged. The actual import rate is 14.07p, but after conversion losses to store the grid AC into the DC battery, +the energy being put into the battery has effectively cost 14.81p - for every 1kWh of AC grid import you don't get 1kWh of DC stored in the battery, +so 1kWh of battery charge has effectively cost slightly more than the import rate.

    +
    • +
  • +

    At 00:30 the battery is being force exported and excess energy (above the estimated house load of 0.47kWh) will be exported. +The actual export rate is 18.22p, but after losses converting the stored DC battery charge into AC to supply the home and export it, +the energy being exported has effectively only earned 17.31p - it will take slightly more than 1kWh of stored DC battery charge to get 1kWh of AC to use or export +so each discharged and exported kWh actually earns slightly less.

    +
    • +
  • +

    Putting these together, at 00:00, the effective import rate (after losses) is 13.93p, the effective export rate is 17.31p, +so even though battery and inverter conversion losses have been incurred, there is still a 3.38p profit per kWh and +Predbat plans to charge and then exports the battery in the same slot to generate that profit.

    +
    • +
+

With debug mode turned on, the Load column shows the predicted load in kWh for the half hour slot and in brackets the modelled load variance value using the load variance model.

+

The PV column in debug mode changes shows the predicted PV generation in kWh for the half hour slot and the Solcast 10% forecast in brackets. +Note that Predbat's forecasted PV generation already contains a input_number.predbat_pv_metric10_weight weighted value of the Solcast 10% forecast.

+

Note that the values in brackets in the load and PV columns are each only shown if they are non-zero.

+

The debug mode on the Predbat plan can be quite useful to understand from the import and export rates after conversion losses, why Predbat plans to charge or force export the battery. +There's a further explanation of the Predbat forecast and plan in the FAQ's.

+

Customising and Reformatting the Predbat Plan

+

An additional independent front-end Home Assistant component the 'Predbat Table Card' is available on HACS that gives a number of additional customisation and configuration options +to tailor how the Predbat plan looks:

+
    +
  • Change the sequence of columns and which columns are shown in the plan
    • +
  • Restyle the columns, or retain the Predbat original colour scheme
    • +
  • Apply custom light/dark themes
    • +
+

See the Predbat Table Card repository for more details.

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/predheat/index.html b/predheat/index.html new file mode 100644 index 000000000..39e3730c0 --- /dev/null +++ b/predheat/index.html @@ -0,0 +1,280 @@ + + + + + + + + predheat - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Predheat
    • +
  • predheat
    • +
  • +
    • +
+
+
+
+
+ +

predheat

+

Predheat attempts to model water based central heating systems based on a boiler or a heat pump.

+

Operation

+

The app runs every 5 minutes and it will automatically update its prediction for the heating system for the next period, up to a maximum of 48 hours.

+

The inputs are as follows

+
    +
  • An external temperature sensor, can be a real one or one created by an Internet service
    • +
  • An internal temperature sensor, ideally from your home thermostat.
    • +
  • The target temperature sensor, this is what your home thermostat is set to.
    • +
  • A heating energy sensor in kWh (not strictly required but needed to plot historical usage and calibrate)
    • +
  • The flow temperature setting of your heating, can be static or a sensor
    • +
  • Your current energy rates, either from the Octopus Energy plugin or hand typed into the configuration
    • +
  • Some data about your home that you have to figure out for yourself and calibrate
    • +
+

The outputs are:

+
    +
  • Prediction of the internal house temperature going forward, including times when the heating will be active.
    • +
  • Your predicted energy usage and costs. The energy usage, if electric, can also be connected into Predbat to help you project your home battery usage.
    • +
+

Future versions will also offer Predbat to run in master mode, controlling your homes heating in the same way as a smart thermostat (e.g. Nest)

+

Installation guide

+

Predheat is now part of Predbat, first you will need to configure it using apps.yaml and then enable it by turning on switch.predbat_predheat_enable

+

Openweather install

+

See: https://www.home-assistant.io/integrations/openweathermap

+

First create an OpenWeather account and then register for a "One Call by Call" subscription plan. This does need a credit/debit card but won't cost anything. +You get 1000 API calls a day for free, so edit your limit in the account to 1000 to avoid ever being charged.

+

Then add in the Home Assistant service and connect up your API key to obtain hourly weather data. Use the v3.0 API and ensure you have a 2024 version of Home Assistant.

+

Apex Charts install

+

Use HACS to install Apex Charts (Lovelace frontend add-on) - https://github.com/RomRider/apexcharts-card

+

There is a template for the Predheat charts in: https://raw.githubusercontent.com/springfall2008/batpred/refs/heads/main/templates/example_chart_predbat.yaml_template

+

Create a new Apex chart for each chart in this template and copy the YAML code into the chart.

+

Configuration guide

+

First you need to edit apps.yaml to configure your system.

+

Copy the following template into The Predbat apps.yaml and edit the settings: predheat.yaml

+

Set the mode (mode) to 'gas' or 'pump' depending on if you have a gas boiler or heat pump +Set the external temperature sensor (external_temperature) either to a real sensor or create one from the open weather map by adding this sensor to your configuration.yaml file for HA:

+
template:
+  - sensor:
+    - name: "external_temperature"
+      unit_of_measurement: 'c'
+      state_class: measurement
+      state: >
+        {{ state_attr('weather.openweathermap', 'temperature') }}
+
+

Set internal_temperature to point to one or more internal temperature sensors, if you have a heating thermostat then ideally link it to this or to a sensor at least in a similar area of the house.

+

The weather configuration points to the Open Weather Map sensor by default so should work as-is.

+

Set the target_temperature to point to a sensor that indicates what your boiler thermostat is set to, or manually enter the temperature setting here.

+

Set smart_thermostat to True if your thermostat starts the boiler ahead of time for the new target temperature or False for regular options.

+

Set heating_energy To point to a sensor that indicates the energy consumed by your boiler/heat-pump in kWh. If the sensor isn't accurate then using heating_energy_scaling to adjust it to the actually energy consumed. +You can also comment this line out if you don't have a sensor, but no historical cost information will be produced.

+

Now you need to make a list of all your radiators in the house, measure them and look up their BTU output at Delta 50 and their volume in Litres. The links below maybe useful for various standard radiators:

+ +

Add up all the BTUs and divide by 3.41 to gain the heat output in Watts and set that in heat_output configuration option. +Add up all the litres of water, add in some extra for the piping and an expansion vessel if present (e.g. 5-10 litres) and set heat_volume accordingly.

+

Set the heat_max_power and heat_min_power to the minimum and maximum power output of your boiler/heat-pump in watts. This should be specified as the maximum output power +and not the maximum input energy. E.g. a heat pump with a COP of 4 might output 7kW but could only consume 1.7kW.

+

Set heating_cop to the nominal COP of your system. For a gas boiler use 1.0 (as the efficiency will be based on flow temperature) or for a heat pump set it to the best value which is likely around 4.0 (it will be scaled down for cold weather).

+

Set flow_temp To the target flow temperature of your system, either via a sensor or as a fixed value. E.g. gas boilers are often set to say 60 or 70 degrees while heat pumps are much lower e.g. 30 or 40.

+

Set flow_difference_target to be the difference in flow temperature (in vs out) where your heating system will run at full power if it is above. e.g. for gas boilers this maybe something around 40 while on a heat pump it could be much lower e.g. 10.

+

Set volume_temp If you have a sensor on your radiators which can confirm the water temperature, this must not be near the heat pump/boiler but instead as close to the +interior temperature sensor as possible. If you do not have a sensor then instead PredHeat will calculate the next temperature and store it in next_volume_temp for use +in the next calculation cycle.

+

For energy rates, they will come from the Predbat configuration, ensure you have your electric or gas rates set correctly.

+

Note you can also change the tables for gas_efficiency, heat_pump_efficiency and delta_correction in the Predheat configuration but the defaults should be fine to get going.

+

Now comes the tricky part, we need to calculate the heat loss for your house:

+

What will help here is historical temperature data, find a time period in the last few weeks when your heating was turned off (for a few hours beforehand) and the house is cooling down. +Measure the number of degrees the house drops by in a given time period. Divide that figure (e.g. 1.5 degrees) by the time period e.g. (3 hours) and then again divide it by the +average difference between the inside and outside temperature +(e.g. 19 degrees inside, 9 degrees outside, so a temperature difference of 4 degrees) = 1.5 degrees / 3 hours / 10 degrees difference = 0.05. Set that figure to heat_loss_degrees. +It maybe best to compute this when it's cold out and if you have your heating turned off overnight.

+

Note in future versions of Predheat I might make this calculation automatic.

+

Next we need to work out the number of watts of heat loss in the house, this can be done by looking at the energy consumed when the heating comes on. Pick a period of heating, +ideally from the time the temperature starts increasing for a complete hour of increase, looking at the increase in temperature in degrees, +add to that static heat loss which is heat_loss_degrees (internal temp - external temp) 1 hours to get the total degrees accounted for. +Now divide that by the external temperature difference again / (internal_temp - external_temp) and multiply the final figure by the energy your system consumed in Watts +during that period (can be found either from your sensor or just by looking at your energy bill for the same 1 hour period).

+

The final figure should be the number of watts your house loses per 1 degree of external temperature difference and be set to heat_loss_watts

+

Then you can set heat_gain_static to be the static heat output of other things in your house eg. computers and people. You can figure this out by looking at how many degrees of +temperature difference your house can maintain without any heating and multiply up your heat loss watts figure by this.

+

Weather Compensation

+

If your heat source makes use of weather compensation then add the following to the configuration to map out your heat curve. The example has a flow temp of 45C at -3C outside and 25C at 15C outside:

+

yaml weather_compensation: + -20: 45.0 + -3: 45.0 + 15: 25.0 + 20: 25.0

+

Predheat will fill in the gaps between the points provided.

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + +
+ + + + + + + + + diff --git a/search.html b/search.html new file mode 100644 index 000000000..8f2b9dbc2 --- /dev/null +++ b/search.html @@ -0,0 +1,168 @@ + + + + + + + + Predbat Documentation + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • +
    • +
+
+
+
+
+ + +

Search Results

+ +
+ + +
+ +
+ Searching... +
+ + +
+
+ +
+
+ +
+ +
+ +
+ + + + + +
+ + + + + + + + + diff --git a/search/lunr.js b/search/lunr.js new file mode 100644 index 000000000..aca0a167f --- /dev/null +++ b/search/lunr.js @@ -0,0 +1,3475 @@ +/** + * lunr - http://lunrjs.com - A bit like Solr, but much smaller and not as bright - 2.3.9 + * Copyright (C) 2020 Oliver Nightingale + * @license MIT + */ + +;(function(){ + +/** + * A convenience function for configuring and constructing + * a new lunr Index. + * + * A lunr.Builder instance is created and the pipeline setup + * with a trimmer, stop word filter and stemmer. + * + * This builder object is yielded to the configuration function + * that is passed as a parameter, allowing the list of fields + * and other builder parameters to be customised. + * + * All documents _must_ be added within the passed config function. + * + * @example + * var idx = lunr(function () { + * this.field('title') + * this.field('body') + * this.ref('id') + * + * documents.forEach(function (doc) { + * this.add(doc) + * }, this) + * }) + * + * @see {@link lunr.Builder} + * @see {@link lunr.Pipeline} + * @see {@link lunr.trimmer} + * @see {@link lunr.stopWordFilter} + * @see {@link lunr.stemmer} + * @namespace {function} lunr + */ +var lunr = function (config) { + var builder = new lunr.Builder + + builder.pipeline.add( + lunr.trimmer, + lunr.stopWordFilter, + lunr.stemmer + ) + + builder.searchPipeline.add( + lunr.stemmer + ) + + config.call(builder, builder) + return builder.build() +} + +lunr.version = "2.3.9" +/*! + * lunr.utils + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * A namespace containing utils for the rest of the lunr library + * @namespace lunr.utils + */ +lunr.utils = {} + +/** + * Print a warning message to the console. + * + * @param {String} message The message to be printed. + * @memberOf lunr.utils + * @function + */ +lunr.utils.warn = (function (global) { + /* eslint-disable no-console */ + return function (message) { + if (global.console && console.warn) { + console.warn(message) + } + } + /* eslint-enable no-console */ +})(this) + +/** + * Convert an object to a string. + * + * In the case of `null` and `undefined` the function returns + * the empty string, in all other cases the result of calling + * `toString` on the passed object is returned. + * + * @param {Any} obj The object to convert to a string. + * @return {String} string representation of the passed object. + * @memberOf lunr.utils + */ +lunr.utils.asString = function (obj) { + if (obj === void 0 || obj === null) { + return "" + } else { + return obj.toString() + } +} + +/** + * Clones an object. + * + * Will create a copy of an existing object such that any mutations + * on the copy cannot affect the original. + * + * Only shallow objects are supported, passing a nested object to this + * function will cause a TypeError. + * + * Objects with primitives, and arrays of primitives are supported. + * + * @param {Object} obj The object to clone. + * @return {Object} a clone of the passed object. + * @throws {TypeError} when a nested object is passed. + * @memberOf Utils + */ +lunr.utils.clone = function (obj) { + if (obj === null || obj === undefined) { + return obj + } + + var clone = Object.create(null), + keys = Object.keys(obj) + + for (var i = 0; i < keys.length; i++) { + var key = keys[i], + val = obj[key] + + if (Array.isArray(val)) { + clone[key] = val.slice() + continue + } + + if (typeof val === 'string' || + typeof val === 'number' || + typeof val === 'boolean') { + clone[key] = val + continue + } + + throw new TypeError("clone is not deep and does not support nested objects") + } + + return clone +} +lunr.FieldRef = function (docRef, fieldName, stringValue) { + this.docRef = docRef + this.fieldName = fieldName + this._stringValue = stringValue +} + +lunr.FieldRef.joiner = "/" + +lunr.FieldRef.fromString = function (s) { + var n = s.indexOf(lunr.FieldRef.joiner) + + if (n === -1) { + throw "malformed field ref string" + } + + var fieldRef = s.slice(0, n), + docRef = s.slice(n + 1) + + return new lunr.FieldRef (docRef, fieldRef, s) +} + +lunr.FieldRef.prototype.toString = function () { + if (this._stringValue == undefined) { + this._stringValue = this.fieldName + lunr.FieldRef.joiner + this.docRef + } + + return this._stringValue +} +/*! + * lunr.Set + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * A lunr set. + * + * @constructor + */ +lunr.Set = function (elements) { + this.elements = Object.create(null) + + if (elements) { + this.length = elements.length + + for (var i = 0; i < this.length; i++) { + this.elements[elements[i]] = true + } + } else { + this.length = 0 + } +} + +/** + * A complete set that contains all elements. + * + * @static + * @readonly + * @type {lunr.Set} + */ +lunr.Set.complete = { + intersect: function (other) { + return other + }, + + union: function () { + return this + }, + + contains: function () { + return true + } +} + +/** + * An empty set that contains no elements. + * + * @static + * @readonly + * @type {lunr.Set} + */ +lunr.Set.empty = { + intersect: function () { + return this + }, + + union: function (other) { + return other + }, + + contains: function () { + return false + } +} + +/** + * Returns true if this set contains the specified object. + * + * @param {object} object - Object whose presence in this set is to be tested. + * @returns {boolean} - True if this set contains the specified object. + */ +lunr.Set.prototype.contains = function (object) { + return !!this.elements[object] +} + +/** + * Returns a new set containing only the elements that are present in both + * this set and the specified set. + * + * @param {lunr.Set} other - set to intersect with this set. + * @returns {lunr.Set} a new set that is the intersection of this and the specified set. + */ + +lunr.Set.prototype.intersect = function (other) { + var a, b, elements, intersection = [] + + if (other === lunr.Set.complete) { + return this + } + + if (other === lunr.Set.empty) { + return other + } + + if (this.length < other.length) { + a = this + b = other + } else { + a = other + b = this + } + + elements = Object.keys(a.elements) + + for (var i = 0; i < elements.length; i++) { + var element = elements[i] + if (element in b.elements) { + intersection.push(element) + } + } + + return new lunr.Set (intersection) +} + +/** + * Returns a new set combining the elements of this and the specified set. + * + * @param {lunr.Set} other - set to union with this set. + * @return {lunr.Set} a new set that is the union of this and the specified set. + */ + +lunr.Set.prototype.union = function (other) { + if (other === lunr.Set.complete) { + return lunr.Set.complete + } + + if (other === lunr.Set.empty) { + return this + } + + return new lunr.Set(Object.keys(this.elements).concat(Object.keys(other.elements))) +} +/** + * A function to calculate the inverse document frequency for + * a posting. This is shared between the builder and the index + * + * @private + * @param {object} posting - The posting for a given term + * @param {number} documentCount - The total number of documents. + */ +lunr.idf = function (posting, documentCount) { + var documentsWithTerm = 0 + + for (var fieldName in posting) { + if (fieldName == '_index') continue // Ignore the term index, its not a field + documentsWithTerm += Object.keys(posting[fieldName]).length + } + + var x = (documentCount - documentsWithTerm + 0.5) / (documentsWithTerm + 0.5) + + return Math.log(1 + Math.abs(x)) +} + +/** + * A token wraps a string representation of a token + * as it is passed through the text processing pipeline. + * + * @constructor + * @param {string} [str=''] - The string token being wrapped. + * @param {object} [metadata={}] - Metadata associated with this token. + */ +lunr.Token = function (str, metadata) { + this.str = str || "" + this.metadata = metadata || {} +} + +/** + * Returns the token string that is being wrapped by this object. + * + * @returns {string} + */ +lunr.Token.prototype.toString = function () { + return this.str +} + +/** + * A token update function is used when updating or optionally + * when cloning a token. + * + * @callback lunr.Token~updateFunction + * @param {string} str - The string representation of the token. + * @param {Object} metadata - All metadata associated with this token. + */ + +/** + * Applies the given function to the wrapped string token. + * + * @example + * token.update(function (str, metadata) { + * return str.toUpperCase() + * }) + * + * @param {lunr.Token~updateFunction} fn - A function to apply to the token string. + * @returns {lunr.Token} + */ +lunr.Token.prototype.update = function (fn) { + this.str = fn(this.str, this.metadata) + return this +} + +/** + * Creates a clone of this token. Optionally a function can be + * applied to the cloned token. + * + * @param {lunr.Token~updateFunction} [fn] - An optional function to apply to the cloned token. + * @returns {lunr.Token} + */ +lunr.Token.prototype.clone = function (fn) { + fn = fn || function (s) { return s } + return new lunr.Token (fn(this.str, this.metadata), this.metadata) +} +/*! + * lunr.tokenizer + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * A function for splitting a string into tokens ready to be inserted into + * the search index. Uses `lunr.tokenizer.separator` to split strings, change + * the value of this property to change how strings are split into tokens. + * + * This tokenizer will convert its parameter to a string by calling `toString` and + * then will split this string on the character in `lunr.tokenizer.separator`. + * Arrays will have their elements converted to strings and wrapped in a lunr.Token. + * + * Optional metadata can be passed to the tokenizer, this metadata will be cloned and + * added as metadata to every token that is created from the object to be tokenized. + * + * @static + * @param {?(string|object|object[])} obj - The object to convert into tokens + * @param {?object} metadata - Optional metadata to associate with every token + * @returns {lunr.Token[]} + * @see {@link lunr.Pipeline} + */ +lunr.tokenizer = function (obj, metadata) { + if (obj == null || obj == undefined) { + return [] + } + + if (Array.isArray(obj)) { + return obj.map(function (t) { + return new lunr.Token( + lunr.utils.asString(t).toLowerCase(), + lunr.utils.clone(metadata) + ) + }) + } + + var str = obj.toString().toLowerCase(), + len = str.length, + tokens = [] + + for (var sliceEnd = 0, sliceStart = 0; sliceEnd <= len; sliceEnd++) { + var char = str.charAt(sliceEnd), + sliceLength = sliceEnd - sliceStart + + if ((char.match(lunr.tokenizer.separator) || sliceEnd == len)) { + + if (sliceLength > 0) { + var tokenMetadata = lunr.utils.clone(metadata) || {} + tokenMetadata["position"] = [sliceStart, sliceLength] + tokenMetadata["index"] = tokens.length + + tokens.push( + new lunr.Token ( + str.slice(sliceStart, sliceEnd), + tokenMetadata + ) + ) + } + + sliceStart = sliceEnd + 1 + } + + } + + return tokens +} + +/** + * The separator used to split a string into tokens. Override this property to change the behaviour of + * `lunr.tokenizer` behaviour when tokenizing strings. By default this splits on whitespace and hyphens. + * + * @static + * @see lunr.tokenizer + */ +lunr.tokenizer.separator = /[\s\-]+/ +/*! + * lunr.Pipeline + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * lunr.Pipelines maintain an ordered list of functions to be applied to all + * tokens in documents entering the search index and queries being ran against + * the index. + * + * An instance of lunr.Index created with the lunr shortcut will contain a + * pipeline with a stop word filter and an English language stemmer. Extra + * functions can be added before or after either of these functions or these + * default functions can be removed. + * + * When run the pipeline will call each function in turn, passing a token, the + * index of that token in the original list of all tokens and finally a list of + * all the original tokens. + * + * The output of functions in the pipeline will be passed to the next function + * in the pipeline. To exclude a token from entering the index the function + * should return undefined, the rest of the pipeline will not be called with + * this token. + * + * For serialisation of pipelines to work, all functions used in an instance of + * a pipeline should be registered with lunr.Pipeline. Registered functions can + * then be loaded. If trying to load a serialised pipeline that uses functions + * that are not registered an error will be thrown. + * + * If not planning on serialising the pipeline then registering pipeline functions + * is not necessary. + * + * @constructor + */ +lunr.Pipeline = function () { + this._stack = [] +} + +lunr.Pipeline.registeredFunctions = Object.create(null) + +/** + * A pipeline function maps lunr.Token to lunr.Token. A lunr.Token contains the token + * string as well as all known metadata. A pipeline function can mutate the token string + * or mutate (or add) metadata for a given token. + * + * A pipeline function can indicate that the passed token should be discarded by returning + * null, undefined or an empty string. This token will not be passed to any downstream pipeline + * functions and will not be added to the index. + * + * Multiple tokens can be returned by returning an array of tokens. Each token will be passed + * to any downstream pipeline functions and all will returned tokens will be added to the index. + * + * Any number of pipeline functions may be chained together using a lunr.Pipeline. + * + * @interface lunr.PipelineFunction + * @param {lunr.Token} token - A token from the document being processed. + * @param {number} i - The index of this token in the complete list of tokens for this document/field. + * @param {lunr.Token[]} tokens - All tokens for this document/field. + * @returns {(?lunr.Token|lunr.Token[])} + */ + +/** + * Register a function with the pipeline. + * + * Functions that are used in the pipeline should be registered if the pipeline + * needs to be serialised, or a serialised pipeline needs to be loaded. + * + * Registering a function does not add it to a pipeline, functions must still be + * added to instances of the pipeline for them to be used when running a pipeline. + * + * @param {lunr.PipelineFunction} fn - The function to check for. + * @param {String} label - The label to register this function with + */ +lunr.Pipeline.registerFunction = function (fn, label) { + if (label in this.registeredFunctions) { + lunr.utils.warn('Overwriting existing registered function: ' + label) + } + + fn.label = label + lunr.Pipeline.registeredFunctions[fn.label] = fn +} + +/** + * Warns if the function is not registered as a Pipeline function. + * + * @param {lunr.PipelineFunction} fn - The function to check for. + * @private + */ +lunr.Pipeline.warnIfFunctionNotRegistered = function (fn) { + var isRegistered = fn.label && (fn.label in this.registeredFunctions) + + if (!isRegistered) { + lunr.utils.warn('Function is not registered with pipeline. This may cause problems when serialising the index.\n', fn) + } +} + +/** + * Loads a previously serialised pipeline. + * + * All functions to be loaded must already be registered with lunr.Pipeline. + * If any function from the serialised data has not been registered then an + * error will be thrown. + * + * @param {Object} serialised - The serialised pipeline to load. + * @returns {lunr.Pipeline} + */ +lunr.Pipeline.load = function (serialised) { + var pipeline = new lunr.Pipeline + + serialised.forEach(function (fnName) { + var fn = lunr.Pipeline.registeredFunctions[fnName] + + if (fn) { + pipeline.add(fn) + } else { + throw new Error('Cannot load unregistered function: ' + fnName) + } + }) + + return pipeline +} + +/** + * Adds new functions to the end of the pipeline. + * + * Logs a warning if the function has not been registered. + * + * @param {lunr.PipelineFunction[]} functions - Any number of functions to add to the pipeline. + */ +lunr.Pipeline.prototype.add = function () { + var fns = Array.prototype.slice.call(arguments) + + fns.forEach(function (fn) { + lunr.Pipeline.warnIfFunctionNotRegistered(fn) + this._stack.push(fn) + }, this) +} + +/** + * Adds a single function after a function that already exists in the + * pipeline. + * + * Logs a warning if the function has not been registered. + * + * @param {lunr.PipelineFunction} existingFn - A function that already exists in the pipeline. + * @param {lunr.PipelineFunction} newFn - The new function to add to the pipeline. + */ +lunr.Pipeline.prototype.after = function (existingFn, newFn) { + lunr.Pipeline.warnIfFunctionNotRegistered(newFn) + + var pos = this._stack.indexOf(existingFn) + if (pos == -1) { + throw new Error('Cannot find existingFn') + } + + pos = pos + 1 + this._stack.splice(pos, 0, newFn) +} + +/** + * Adds a single function before a function that already exists in the + * pipeline. + * + * Logs a warning if the function has not been registered. + * + * @param {lunr.PipelineFunction} existingFn - A function that already exists in the pipeline. + * @param {lunr.PipelineFunction} newFn - The new function to add to the pipeline. + */ +lunr.Pipeline.prototype.before = function (existingFn, newFn) { + lunr.Pipeline.warnIfFunctionNotRegistered(newFn) + + var pos = this._stack.indexOf(existingFn) + if (pos == -1) { + throw new Error('Cannot find existingFn') + } + + this._stack.splice(pos, 0, newFn) +} + +/** + * Removes a function from the pipeline. + * + * @param {lunr.PipelineFunction} fn The function to remove from the pipeline. + */ +lunr.Pipeline.prototype.remove = function (fn) { + var pos = this._stack.indexOf(fn) + if (pos == -1) { + return + } + + this._stack.splice(pos, 1) +} + +/** + * Runs the current list of functions that make up the pipeline against the + * passed tokens. + * + * @param {Array} tokens The tokens to run through the pipeline. + * @returns {Array} + */ +lunr.Pipeline.prototype.run = function (tokens) { + var stackLength = this._stack.length + + for (var i = 0; i < stackLength; i++) { + var fn = this._stack[i] + var memo = [] + + for (var j = 0; j < tokens.length; j++) { + var result = fn(tokens[j], j, tokens) + + if (result === null || result === void 0 || result === '') continue + + if (Array.isArray(result)) { + for (var k = 0; k < result.length; k++) { + memo.push(result[k]) + } + } else { + memo.push(result) + } + } + + tokens = memo + } + + return tokens +} + +/** + * Convenience method for passing a string through a pipeline and getting + * strings out. This method takes care of wrapping the passed string in a + * token and mapping the resulting tokens back to strings. + * + * @param {string} str - The string to pass through the pipeline. + * @param {?object} metadata - Optional metadata to associate with the token + * passed to the pipeline. + * @returns {string[]} + */ +lunr.Pipeline.prototype.runString = function (str, metadata) { + var token = new lunr.Token (str, metadata) + + return this.run([token]).map(function (t) { + return t.toString() + }) +} + +/** + * Resets the pipeline by removing any existing processors. + * + */ +lunr.Pipeline.prototype.reset = function () { + this._stack = [] +} + +/** + * Returns a representation of the pipeline ready for serialisation. + * + * Logs a warning if the function has not been registered. + * + * @returns {Array} + */ +lunr.Pipeline.prototype.toJSON = function () { + return this._stack.map(function (fn) { + lunr.Pipeline.warnIfFunctionNotRegistered(fn) + + return fn.label + }) +} +/*! + * lunr.Vector + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * A vector is used to construct the vector space of documents and queries. These + * vectors support operations to determine the similarity between two documents or + * a document and a query. + * + * Normally no parameters are required for initializing a vector, but in the case of + * loading a previously dumped vector the raw elements can be provided to the constructor. + * + * For performance reasons vectors are implemented with a flat array, where an elements + * index is immediately followed by its value. E.g. [index, value, index, value]. This + * allows the underlying array to be as sparse as possible and still offer decent + * performance when being used for vector calculations. + * + * @constructor + * @param {Number[]} [elements] - The flat list of element index and element value pairs. + */ +lunr.Vector = function (elements) { + this._magnitude = 0 + this.elements = elements || [] +} + + +/** + * Calculates the position within the vector to insert a given index. + * + * This is used internally by insert and upsert. If there are duplicate indexes then + * the position is returned as if the value for that index were to be updated, but it + * is the callers responsibility to check whether there is a duplicate at that index + * + * @param {Number} insertIdx - The index at which the element should be inserted. + * @returns {Number} + */ +lunr.Vector.prototype.positionForIndex = function (index) { + // For an empty vector the tuple can be inserted at the beginning + if (this.elements.length == 0) { + return 0 + } + + var start = 0, + end = this.elements.length / 2, + sliceLength = end - start, + pivotPoint = Math.floor(sliceLength / 2), + pivotIndex = this.elements[pivotPoint * 2] + + while (sliceLength > 1) { + if (pivotIndex < index) { + start = pivotPoint + } + + if (pivotIndex > index) { + end = pivotPoint + } + + if (pivotIndex == index) { + break + } + + sliceLength = end - start + pivotPoint = start + Math.floor(sliceLength / 2) + pivotIndex = this.elements[pivotPoint * 2] + } + + if (pivotIndex == index) { + return pivotPoint * 2 + } + + if (pivotIndex > index) { + return pivotPoint * 2 + } + + if (pivotIndex < index) { + return (pivotPoint + 1) * 2 + } +} + +/** + * Inserts an element at an index within the vector. + * + * Does not allow duplicates, will throw an error if there is already an entry + * for this index. + * + * @param {Number} insertIdx - The index at which the element should be inserted. + * @param {Number} val - The value to be inserted into the vector. + */ +lunr.Vector.prototype.insert = function (insertIdx, val) { + this.upsert(insertIdx, val, function () { + throw "duplicate index" + }) +} + +/** + * Inserts or updates an existing index within the vector. + * + * @param {Number} insertIdx - The index at which the element should be inserted. + * @param {Number} val - The value to be inserted into the vector. + * @param {function} fn - A function that is called for updates, the existing value and the + * requested value are passed as arguments + */ +lunr.Vector.prototype.upsert = function (insertIdx, val, fn) { + this._magnitude = 0 + var position = this.positionForIndex(insertIdx) + + if (this.elements[position] == insertIdx) { + this.elements[position + 1] = fn(this.elements[position + 1], val) + } else { + this.elements.splice(position, 0, insertIdx, val) + } +} + +/** + * Calculates the magnitude of this vector. + * + * @returns {Number} + */ +lunr.Vector.prototype.magnitude = function () { + if (this._magnitude) return this._magnitude + + var sumOfSquares = 0, + elementsLength = this.elements.length + + for (var i = 1; i < elementsLength; i += 2) { + var val = this.elements[i] + sumOfSquares += val * val + } + + return this._magnitude = Math.sqrt(sumOfSquares) +} + +/** + * Calculates the dot product of this vector and another vector. + * + * @param {lunr.Vector} otherVector - The vector to compute the dot product with. + * @returns {Number} + */ +lunr.Vector.prototype.dot = function (otherVector) { + var dotProduct = 0, + a = this.elements, b = otherVector.elements, + aLen = a.length, bLen = b.length, + aVal = 0, bVal = 0, + i = 0, j = 0 + + while (i < aLen && j < bLen) { + aVal = a[i], bVal = b[j] + if (aVal < bVal) { + i += 2 + } else if (aVal > bVal) { + j += 2 + } else if (aVal == bVal) { + dotProduct += a[i + 1] * b[j + 1] + i += 2 + j += 2 + } + } + + return dotProduct +} + +/** + * Calculates the similarity between this vector and another vector. + * + * @param {lunr.Vector} otherVector - The other vector to calculate the + * similarity with. + * @returns {Number} + */ +lunr.Vector.prototype.similarity = function (otherVector) { + return this.dot(otherVector) / this.magnitude() || 0 +} + +/** + * Converts the vector to an array of the elements within the vector. + * + * @returns {Number[]} + */ +lunr.Vector.prototype.toArray = function () { + var output = new Array (this.elements.length / 2) + + for (var i = 1, j = 0; i < this.elements.length; i += 2, j++) { + output[j] = this.elements[i] + } + + return output +} + +/** + * A JSON serializable representation of the vector. + * + * @returns {Number[]} + */ +lunr.Vector.prototype.toJSON = function () { + return this.elements +} +/* eslint-disable */ +/*! + * lunr.stemmer + * Copyright (C) 2020 Oliver Nightingale + * Includes code from - http://tartarus.org/~martin/PorterStemmer/js.txt + */ + +/** + * lunr.stemmer is an english language stemmer, this is a JavaScript + * implementation of the PorterStemmer taken from http://tartarus.org/~martin + * + * @static + * @implements {lunr.PipelineFunction} + * @param {lunr.Token} token - The string to stem + * @returns {lunr.Token} + * @see {@link lunr.Pipeline} + * @function + */ +lunr.stemmer = (function(){ + var step2list = { + "ational" : "ate", + "tional" : "tion", + "enci" : "ence", + "anci" : "ance", + "izer" : "ize", + "bli" : "ble", + "alli" : "al", + "entli" : "ent", + "eli" : "e", + "ousli" : "ous", + "ization" : "ize", + "ation" : "ate", + "ator" : "ate", + "alism" : "al", + "iveness" : "ive", + "fulness" : "ful", + "ousness" : "ous", + "aliti" : "al", + "iviti" : "ive", + "biliti" : "ble", + "logi" : "log" + }, + + step3list = { + "icate" : "ic", + "ative" : "", + "alize" : "al", + "iciti" : "ic", + "ical" : "ic", + "ful" : "", + "ness" : "" + }, + + c = "[^aeiou]", // consonant + v = "[aeiouy]", // vowel + C = c + "[^aeiouy]*", // consonant sequence + V = v + "[aeiou]*", // vowel sequence + + mgr0 = "^(" + C + ")?" + V + C, // [C]VC... is m>0 + meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$", // [C]VC[V] is m=1 + mgr1 = "^(" + C + ")?" + V + C + V + C, // [C]VCVC... is m>1 + s_v = "^(" + C + ")?" + v; // vowel in stem + + var re_mgr0 = new RegExp(mgr0); + var re_mgr1 = new RegExp(mgr1); + var re_meq1 = new RegExp(meq1); + var re_s_v = new RegExp(s_v); + + var re_1a = /^(.+?)(ss|i)es$/; + var re2_1a = /^(.+?)([^s])s$/; + var re_1b = /^(.+?)eed$/; + var re2_1b = /^(.+?)(ed|ing)$/; + var re_1b_2 = /.$/; + var re2_1b_2 = /(at|bl|iz)$/; + var re3_1b_2 = new RegExp("([^aeiouylsz])\\1$"); + var re4_1b_2 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + + var re_1c = /^(.+?[^aeiou])y$/; + var re_2 = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + + var re_3 = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + + var re_4 = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + var re2_4 = /^(.+?)(s|t)(ion)$/; + + var re_5 = /^(.+?)e$/; + var re_5_1 = /ll$/; + var re3_5 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + + var porterStemmer = function porterStemmer(w) { + var stem, + suffix, + firstch, + re, + re2, + re3, + re4; + + if (w.length < 3) { return w; } + + firstch = w.substr(0,1); + if (firstch == "y") { + w = firstch.toUpperCase() + w.substr(1); + } + + // Step 1a + re = re_1a + re2 = re2_1a; + + if (re.test(w)) { w = w.replace(re,"$1$2"); } + else if (re2.test(w)) { w = w.replace(re2,"$1$2"); } + + // Step 1b + re = re_1b; + re2 = re2_1b; + if (re.test(w)) { + var fp = re.exec(w); + re = re_mgr0; + if (re.test(fp[1])) { + re = re_1b_2; + w = w.replace(re,""); + } + } else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = re_s_v; + if (re2.test(stem)) { + w = stem; + re2 = re2_1b_2; + re3 = re3_1b_2; + re4 = re4_1b_2; + if (re2.test(w)) { w = w + "e"; } + else if (re3.test(w)) { re = re_1b_2; w = w.replace(re,""); } + else if (re4.test(w)) { w = w + "e"; } + } + } + + // Step 1c - replace suffix y or Y by i if preceded by a non-vowel which is not the first letter of the word (so cry -> cri, by -> by, say -> say) + re = re_1c; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + w = stem + "i"; + } + + // Step 2 + re = re_2; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = re_mgr0; + if (re.test(stem)) { + w = stem + step2list[suffix]; + } + } + + // Step 3 + re = re_3; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = re_mgr0; + if (re.test(stem)) { + w = stem + step3list[suffix]; + } + } + + // Step 4 + re = re_4; + re2 = re2_4; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = re_mgr1; + if (re.test(stem)) { + w = stem; + } + } else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = re_mgr1; + if (re2.test(stem)) { + w = stem; + } + } + + // Step 5 + re = re_5; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = re_mgr1; + re2 = re_meq1; + re3 = re3_5; + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) { + w = stem; + } + } + + re = re_5_1; + re2 = re_mgr1; + if (re.test(w) && re2.test(w)) { + re = re_1b_2; + w = w.replace(re,""); + } + + // and turn initial Y back to y + + if (firstch == "y") { + w = firstch.toLowerCase() + w.substr(1); + } + + return w; + }; + + return function (token) { + return token.update(porterStemmer); + } +})(); + +lunr.Pipeline.registerFunction(lunr.stemmer, 'stemmer') +/*! + * lunr.stopWordFilter + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * lunr.generateStopWordFilter builds a stopWordFilter function from the provided + * list of stop words. + * + * The built in lunr.stopWordFilter is built using this generator and can be used + * to generate custom stopWordFilters for applications or non English languages. + * + * @function + * @param {Array} token The token to pass through the filter + * @returns {lunr.PipelineFunction} + * @see lunr.Pipeline + * @see lunr.stopWordFilter + */ +lunr.generateStopWordFilter = function (stopWords) { + var words = stopWords.reduce(function (memo, stopWord) { + memo[stopWord] = stopWord + return memo + }, {}) + + return function (token) { + if (token && words[token.toString()] !== token.toString()) return token + } +} + +/** + * lunr.stopWordFilter is an English language stop word list filter, any words + * contained in the list will not be passed through the filter. + * + * This is intended to be used in the Pipeline. If the token does not pass the + * filter then undefined will be returned. + * + * @function + * @implements {lunr.PipelineFunction} + * @params {lunr.Token} token - A token to check for being a stop word. + * @returns {lunr.Token} + * @see {@link lunr.Pipeline} + */ +lunr.stopWordFilter = lunr.generateStopWordFilter([ + 'a', + 'able', + 'about', + 'across', + 'after', + 'all', + 'almost', + 'also', + 'am', + 'among', + 'an', + 'and', + 'any', + 'are', + 'as', + 'at', + 'be', + 'because', + 'been', + 'but', + 'by', + 'can', + 'cannot', + 'could', + 'dear', + 'did', + 'do', + 'does', + 'either', + 'else', + 'ever', + 'every', + 'for', + 'from', + 'get', + 'got', + 'had', + 'has', + 'have', + 'he', + 'her', + 'hers', + 'him', + 'his', + 'how', + 'however', + 'i', + 'if', + 'in', + 'into', + 'is', + 'it', + 'its', + 'just', + 'least', + 'let', + 'like', + 'likely', + 'may', + 'me', + 'might', + 'most', + 'must', + 'my', + 'neither', + 'no', + 'nor', + 'not', + 'of', + 'off', + 'often', + 'on', + 'only', + 'or', + 'other', + 'our', + 'own', + 'rather', + 'said', + 'say', + 'says', + 'she', + 'should', + 'since', + 'so', + 'some', + 'than', + 'that', + 'the', + 'their', + 'them', + 'then', + 'there', + 'these', + 'they', + 'this', + 'tis', + 'to', + 'too', + 'twas', + 'us', + 'wants', + 'was', + 'we', + 'were', + 'what', + 'when', + 'where', + 'which', + 'while', + 'who', + 'whom', + 'why', + 'will', + 'with', + 'would', + 'yet', + 'you', + 'your' +]) + +lunr.Pipeline.registerFunction(lunr.stopWordFilter, 'stopWordFilter') +/*! + * lunr.trimmer + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * lunr.trimmer is a pipeline function for trimming non word + * characters from the beginning and end of tokens before they + * enter the index. + * + * This implementation may not work correctly for non latin + * characters and should either be removed or adapted for use + * with languages with non-latin characters. + * + * @static + * @implements {lunr.PipelineFunction} + * @param {lunr.Token} token The token to pass through the filter + * @returns {lunr.Token} + * @see lunr.Pipeline + */ +lunr.trimmer = function (token) { + return token.update(function (s) { + return s.replace(/^\W+/, '').replace(/\W+$/, '') + }) +} + +lunr.Pipeline.registerFunction(lunr.trimmer, 'trimmer') +/*! + * lunr.TokenSet + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * A token set is used to store the unique list of all tokens + * within an index. Token sets are also used to represent an + * incoming query to the index, this query token set and index + * token set are then intersected to find which tokens to look + * up in the inverted index. + * + * A token set can hold multiple tokens, as in the case of the + * index token set, or it can hold a single token as in the + * case of a simple query token set. + * + * Additionally token sets are used to perform wildcard matching. + * Leading, contained and trailing wildcards are supported, and + * from this edit distance matching can also be provided. + * + * Token sets are implemented as a minimal finite state automata, + * where both common prefixes and suffixes are shared between tokens. + * This helps to reduce the space used for storing the token set. + * + * @constructor + */ +lunr.TokenSet = function () { + this.final = false + this.edges = {} + this.id = lunr.TokenSet._nextId + lunr.TokenSet._nextId += 1 +} + +/** + * Keeps track of the next, auto increment, identifier to assign + * to a new tokenSet. + * + * TokenSets require a unique identifier to be correctly minimised. + * + * @private + */ +lunr.TokenSet._nextId = 1 + +/** + * Creates a TokenSet instance from the given sorted array of words. + * + * @param {String[]} arr - A sorted array of strings to create the set from. + * @returns {lunr.TokenSet} + * @throws Will throw an error if the input array is not sorted. + */ +lunr.TokenSet.fromArray = function (arr) { + var builder = new lunr.TokenSet.Builder + + for (var i = 0, len = arr.length; i < len; i++) { + builder.insert(arr[i]) + } + + builder.finish() + return builder.root +} + +/** + * Creates a token set from a query clause. + * + * @private + * @param {Object} clause - A single clause from lunr.Query. + * @param {string} clause.term - The query clause term. + * @param {number} [clause.editDistance] - The optional edit distance for the term. + * @returns {lunr.TokenSet} + */ +lunr.TokenSet.fromClause = function (clause) { + if ('editDistance' in clause) { + return lunr.TokenSet.fromFuzzyString(clause.term, clause.editDistance) + } else { + return lunr.TokenSet.fromString(clause.term) + } +} + +/** + * Creates a token set representing a single string with a specified + * edit distance. + * + * Insertions, deletions, substitutions and transpositions are each + * treated as an edit distance of 1. + * + * Increasing the allowed edit distance will have a dramatic impact + * on the performance of both creating and intersecting these TokenSets. + * It is advised to keep the edit distance less than 3. + * + * @param {string} str - The string to create the token set from. + * @param {number} editDistance - The allowed edit distance to match. + * @returns {lunr.Vector} + */ +lunr.TokenSet.fromFuzzyString = function (str, editDistance) { + var root = new lunr.TokenSet + + var stack = [{ + node: root, + editsRemaining: editDistance, + str: str + }] + + while (stack.length) { + var frame = stack.pop() + + // no edit + if (frame.str.length > 0) { + var char = frame.str.charAt(0), + noEditNode + + if (char in frame.node.edges) { + noEditNode = frame.node.edges[char] + } else { + noEditNode = new lunr.TokenSet + frame.node.edges[char] = noEditNode + } + + if (frame.str.length == 1) { + noEditNode.final = true + } + + stack.push({ + node: noEditNode, + editsRemaining: frame.editsRemaining, + str: frame.str.slice(1) + }) + } + + if (frame.editsRemaining == 0) { + continue + } + + // insertion + if ("*" in frame.node.edges) { + var insertionNode = frame.node.edges["*"] + } else { + var insertionNode = new lunr.TokenSet + frame.node.edges["*"] = insertionNode + } + + if (frame.str.length == 0) { + insertionNode.final = true + } + + stack.push({ + node: insertionNode, + editsRemaining: frame.editsRemaining - 1, + str: frame.str + }) + + // deletion + // can only do a deletion if we have enough edits remaining + // and if there are characters left to delete in the string + if (frame.str.length > 1) { + stack.push({ + node: frame.node, + editsRemaining: frame.editsRemaining - 1, + str: frame.str.slice(1) + }) + } + + // deletion + // just removing the last character from the str + if (frame.str.length == 1) { + frame.node.final = true + } + + // substitution + // can only do a substitution if we have enough edits remaining + // and if there are characters left to substitute + if (frame.str.length >= 1) { + if ("*" in frame.node.edges) { + var substitutionNode = frame.node.edges["*"] + } else { + var substitutionNode = new lunr.TokenSet + frame.node.edges["*"] = substitutionNode + } + + if (frame.str.length == 1) { + substitutionNode.final = true + } + + stack.push({ + node: substitutionNode, + editsRemaining: frame.editsRemaining - 1, + str: frame.str.slice(1) + }) + } + + // transposition + // can only do a transposition if there are edits remaining + // and there are enough characters to transpose + if (frame.str.length > 1) { + var charA = frame.str.charAt(0), + charB = frame.str.charAt(1), + transposeNode + + if (charB in frame.node.edges) { + transposeNode = frame.node.edges[charB] + } else { + transposeNode = new lunr.TokenSet + frame.node.edges[charB] = transposeNode + } + + if (frame.str.length == 1) { + transposeNode.final = true + } + + stack.push({ + node: transposeNode, + editsRemaining: frame.editsRemaining - 1, + str: charA + frame.str.slice(2) + }) + } + } + + return root +} + +/** + * Creates a TokenSet from a string. + * + * The string may contain one or more wildcard characters (*) + * that will allow wildcard matching when intersecting with + * another TokenSet. + * + * @param {string} str - The string to create a TokenSet from. + * @returns {lunr.TokenSet} + */ +lunr.TokenSet.fromString = function (str) { + var node = new lunr.TokenSet, + root = node + + /* + * Iterates through all characters within the passed string + * appending a node for each character. + * + * When a wildcard character is found then a self + * referencing edge is introduced to continually match + * any number of any characters. + */ + for (var i = 0, len = str.length; i < len; i++) { + var char = str[i], + final = (i == len - 1) + + if (char == "*") { + node.edges[char] = node + node.final = final + + } else { + var next = new lunr.TokenSet + next.final = final + + node.edges[char] = next + node = next + } + } + + return root +} + +/** + * Converts this TokenSet into an array of strings + * contained within the TokenSet. + * + * This is not intended to be used on a TokenSet that + * contains wildcards, in these cases the results are + * undefined and are likely to cause an infinite loop. + * + * @returns {string[]} + */ +lunr.TokenSet.prototype.toArray = function () { + var words = [] + + var stack = [{ + prefix: "", + node: this + }] + + while (stack.length) { + var frame = stack.pop(), + edges = Object.keys(frame.node.edges), + len = edges.length + + if (frame.node.final) { + /* In Safari, at this point the prefix is sometimes corrupted, see: + * https://github.com/olivernn/lunr.js/issues/279 Calling any + * String.prototype method forces Safari to "cast" this string to what + * it's supposed to be, fixing the bug. */ + frame.prefix.charAt(0) + words.push(frame.prefix) + } + + for (var i = 0; i < len; i++) { + var edge = edges[i] + + stack.push({ + prefix: frame.prefix.concat(edge), + node: frame.node.edges[edge] + }) + } + } + + return words +} + +/** + * Generates a string representation of a TokenSet. + * + * This is intended to allow TokenSets to be used as keys + * in objects, largely to aid the construction and minimisation + * of a TokenSet. As such it is not designed to be a human + * friendly representation of the TokenSet. + * + * @returns {string} + */ +lunr.TokenSet.prototype.toString = function () { + // NOTE: Using Object.keys here as this.edges is very likely + // to enter 'hash-mode' with many keys being added + // + // avoiding a for-in loop here as it leads to the function + // being de-optimised (at least in V8). From some simple + // benchmarks the performance is comparable, but allowing + // V8 to optimize may mean easy performance wins in the future. + + if (this._str) { + return this._str + } + + var str = this.final ? '1' : '0', + labels = Object.keys(this.edges).sort(), + len = labels.length + + for (var i = 0; i < len; i++) { + var label = labels[i], + node = this.edges[label] + + str = str + label + node.id + } + + return str +} + +/** + * Returns a new TokenSet that is the intersection of + * this TokenSet and the passed TokenSet. + * + * This intersection will take into account any wildcards + * contained within the TokenSet. + * + * @param {lunr.TokenSet} b - An other TokenSet to intersect with. + * @returns {lunr.TokenSet} + */ +lunr.TokenSet.prototype.intersect = function (b) { + var output = new lunr.TokenSet, + frame = undefined + + var stack = [{ + qNode: b, + output: output, + node: this + }] + + while (stack.length) { + frame = stack.pop() + + // NOTE: As with the #toString method, we are using + // Object.keys and a for loop instead of a for-in loop + // as both of these objects enter 'hash' mode, causing + // the function to be de-optimised in V8 + var qEdges = Object.keys(frame.qNode.edges), + qLen = qEdges.length, + nEdges = Object.keys(frame.node.edges), + nLen = nEdges.length + + for (var q = 0; q < qLen; q++) { + var qEdge = qEdges[q] + + for (var n = 0; n < nLen; n++) { + var nEdge = nEdges[n] + + if (nEdge == qEdge || qEdge == '*') { + var node = frame.node.edges[nEdge], + qNode = frame.qNode.edges[qEdge], + final = node.final && qNode.final, + next = undefined + + if (nEdge in frame.output.edges) { + // an edge already exists for this character + // no need to create a new node, just set the finality + // bit unless this node is already final + next = frame.output.edges[nEdge] + next.final = next.final || final + + } else { + // no edge exists yet, must create one + // set the finality bit and insert it + // into the output + next = new lunr.TokenSet + next.final = final + frame.output.edges[nEdge] = next + } + + stack.push({ + qNode: qNode, + output: next, + node: node + }) + } + } + } + } + + return output +} +lunr.TokenSet.Builder = function () { + this.previousWord = "" + this.root = new lunr.TokenSet + this.uncheckedNodes = [] + this.minimizedNodes = {} +} + +lunr.TokenSet.Builder.prototype.insert = function (word) { + var node, + commonPrefix = 0 + + if (word < this.previousWord) { + throw new Error ("Out of order word insertion") + } + + for (var i = 0; i < word.length && i < this.previousWord.length; i++) { + if (word[i] != this.previousWord[i]) break + commonPrefix++ + } + + this.minimize(commonPrefix) + + if (this.uncheckedNodes.length == 0) { + node = this.root + } else { + node = this.uncheckedNodes[this.uncheckedNodes.length - 1].child + } + + for (var i = commonPrefix; i < word.length; i++) { + var nextNode = new lunr.TokenSet, + char = word[i] + + node.edges[char] = nextNode + + this.uncheckedNodes.push({ + parent: node, + char: char, + child: nextNode + }) + + node = nextNode + } + + node.final = true + this.previousWord = word +} + +lunr.TokenSet.Builder.prototype.finish = function () { + this.minimize(0) +} + +lunr.TokenSet.Builder.prototype.minimize = function (downTo) { + for (var i = this.uncheckedNodes.length - 1; i >= downTo; i--) { + var node = this.uncheckedNodes[i], + childKey = node.child.toString() + + if (childKey in this.minimizedNodes) { + node.parent.edges[node.char] = this.minimizedNodes[childKey] + } else { + // Cache the key for this node since + // we know it can't change anymore + node.child._str = childKey + + this.minimizedNodes[childKey] = node.child + } + + this.uncheckedNodes.pop() + } +} +/*! + * lunr.Index + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * An index contains the built index of all documents and provides a query interface + * to the index. + * + * Usually instances of lunr.Index will not be created using this constructor, instead + * lunr.Builder should be used to construct new indexes, or lunr.Index.load should be + * used to load previously built and serialized indexes. + * + * @constructor + * @param {Object} attrs - The attributes of the built search index. + * @param {Object} attrs.invertedIndex - An index of term/field to document reference. + * @param {Object} attrs.fieldVectors - Field vectors + * @param {lunr.TokenSet} attrs.tokenSet - An set of all corpus tokens. + * @param {string[]} attrs.fields - The names of indexed document fields. + * @param {lunr.Pipeline} attrs.pipeline - The pipeline to use for search terms. + */ +lunr.Index = function (attrs) { + this.invertedIndex = attrs.invertedIndex + this.fieldVectors = attrs.fieldVectors + this.tokenSet = attrs.tokenSet + this.fields = attrs.fields + this.pipeline = attrs.pipeline +} + +/** + * A result contains details of a document matching a search query. + * @typedef {Object} lunr.Index~Result + * @property {string} ref - The reference of the document this result represents. + * @property {number} score - A number between 0 and 1 representing how similar this document is to the query. + * @property {lunr.MatchData} matchData - Contains metadata about this match including which term(s) caused the match. + */ + +/** + * Although lunr provides the ability to create queries using lunr.Query, it also provides a simple + * query language which itself is parsed into an instance of lunr.Query. + * + * For programmatically building queries it is advised to directly use lunr.Query, the query language + * is best used for human entered text rather than program generated text. + * + * At its simplest queries can just be a single term, e.g. `hello`, multiple terms are also supported + * and will be combined with OR, e.g `hello world` will match documents that contain either 'hello' + * or 'world', though those that contain both will rank higher in the results. + * + * Wildcards can be included in terms to match one or more unspecified characters, these wildcards can + * be inserted anywhere within the term, and more than one wildcard can exist in a single term. Adding + * wildcards will increase the number of documents that will be found but can also have a negative + * impact on query performance, especially with wildcards at the beginning of a term. + * + * Terms can be restricted to specific fields, e.g. `title:hello`, only documents with the term + * hello in the title field will match this query. Using a field not present in the index will lead + * to an error being thrown. + * + * Modifiers can also be added to terms, lunr supports edit distance and boost modifiers on terms. A term + * boost will make documents matching that term score higher, e.g. `foo^5`. Edit distance is also supported + * to provide fuzzy matching, e.g. 'hello~2' will match documents with hello with an edit distance of 2. + * Avoid large values for edit distance to improve query performance. + * + * Each term also supports a presence modifier. By default a term's presence in document is optional, however + * this can be changed to either required or prohibited. For a term's presence to be required in a document the + * term should be prefixed with a '+', e.g. `+foo bar` is a search for documents that must contain 'foo' and + * optionally contain 'bar'. Conversely a leading '-' sets the terms presence to prohibited, i.e. it must not + * appear in a document, e.g. `-foo bar` is a search for documents that do not contain 'foo' but may contain 'bar'. + * + * To escape special characters the backslash character '\' can be used, this allows searches to include + * characters that would normally be considered modifiers, e.g. `foo\~2` will search for a term "foo~2" instead + * of attempting to apply a boost of 2 to the search term "foo". + * + * @typedef {string} lunr.Index~QueryString + * @example Simple single term query + * hello + * @example Multiple term query + * hello world + * @example term scoped to a field + * title:hello + * @example term with a boost of 10 + * hello^10 + * @example term with an edit distance of 2 + * hello~2 + * @example terms with presence modifiers + * -foo +bar baz + */ + +/** + * Performs a search against the index using lunr query syntax. + * + * Results will be returned sorted by their score, the most relevant results + * will be returned first. For details on how the score is calculated, please see + * the {@link https://lunrjs.com/guides/searching.html#scoring|guide}. + * + * For more programmatic querying use lunr.Index#query. + * + * @param {lunr.Index~QueryString} queryString - A string containing a lunr query. + * @throws {lunr.QueryParseError} If the passed query string cannot be parsed. + * @returns {lunr.Index~Result[]} + */ +lunr.Index.prototype.search = function (queryString) { + return this.query(function (query) { + var parser = new lunr.QueryParser(queryString, query) + parser.parse() + }) +} + +/** + * A query builder callback provides a query object to be used to express + * the query to perform on the index. + * + * @callback lunr.Index~queryBuilder + * @param {lunr.Query} query - The query object to build up. + * @this lunr.Query + */ + +/** + * Performs a query against the index using the yielded lunr.Query object. + * + * If performing programmatic queries against the index, this method is preferred + * over lunr.Index#search so as to avoid the additional query parsing overhead. + * + * A query object is yielded to the supplied function which should be used to + * express the query to be run against the index. + * + * Note that although this function takes a callback parameter it is _not_ an + * asynchronous operation, the callback is just yielded a query object to be + * customized. + * + * @param {lunr.Index~queryBuilder} fn - A function that is used to build the query. + * @returns {lunr.Index~Result[]} + */ +lunr.Index.prototype.query = function (fn) { + // for each query clause + // * process terms + // * expand terms from token set + // * find matching documents and metadata + // * get document vectors + // * score documents + + var query = new lunr.Query(this.fields), + matchingFields = Object.create(null), + queryVectors = Object.create(null), + termFieldCache = Object.create(null), + requiredMatches = Object.create(null), + prohibitedMatches = Object.create(null) + + /* + * To support field level boosts a query vector is created per + * field. An empty vector is eagerly created to support negated + * queries. + */ + for (var i = 0; i < this.fields.length; i++) { + queryVectors[this.fields[i]] = new lunr.Vector + } + + fn.call(query, query) + + for (var i = 0; i < query.clauses.length; i++) { + /* + * Unless the pipeline has been disabled for this term, which is + * the case for terms with wildcards, we need to pass the clause + * term through the search pipeline. A pipeline returns an array + * of processed terms. Pipeline functions may expand the passed + * term, which means we may end up performing multiple index lookups + * for a single query term. + */ + var clause = query.clauses[i], + terms = null, + clauseMatches = lunr.Set.empty + + if (clause.usePipeline) { + terms = this.pipeline.runString(clause.term, { + fields: clause.fields + }) + } else { + terms = [clause.term] + } + + for (var m = 0; m < terms.length; m++) { + var term = terms[m] + + /* + * Each term returned from the pipeline needs to use the same query + * clause object, e.g. the same boost and or edit distance. The + * simplest way to do this is to re-use the clause object but mutate + * its term property. + */ + clause.term = term + + /* + * From the term in the clause we create a token set which will then + * be used to intersect the indexes token set to get a list of terms + * to lookup in the inverted index + */ + var termTokenSet = lunr.TokenSet.fromClause(clause), + expandedTerms = this.tokenSet.intersect(termTokenSet).toArray() + + /* + * If a term marked as required does not exist in the tokenSet it is + * impossible for the search to return any matches. We set all the field + * scoped required matches set to empty and stop examining any further + * clauses. + */ + if (expandedTerms.length === 0 && clause.presence === lunr.Query.presence.REQUIRED) { + for (var k = 0; k < clause.fields.length; k++) { + var field = clause.fields[k] + requiredMatches[field] = lunr.Set.empty + } + + break + } + + for (var j = 0; j < expandedTerms.length; j++) { + /* + * For each term get the posting and termIndex, this is required for + * building the query vector. + */ + var expandedTerm = expandedTerms[j], + posting = this.invertedIndex[expandedTerm], + termIndex = posting._index + + for (var k = 0; k < clause.fields.length; k++) { + /* + * For each field that this query term is scoped by (by default + * all fields are in scope) we need to get all the document refs + * that have this term in that field. + * + * The posting is the entry in the invertedIndex for the matching + * term from above. + */ + var field = clause.fields[k], + fieldPosting = posting[field], + matchingDocumentRefs = Object.keys(fieldPosting), + termField = expandedTerm + "/" + field, + matchingDocumentsSet = new lunr.Set(matchingDocumentRefs) + + /* + * if the presence of this term is required ensure that the matching + * documents are added to the set of required matches for this clause. + * + */ + if (clause.presence == lunr.Query.presence.REQUIRED) { + clauseMatches = clauseMatches.union(matchingDocumentsSet) + + if (requiredMatches[field] === undefined) { + requiredMatches[field] = lunr.Set.complete + } + } + + /* + * if the presence of this term is prohibited ensure that the matching + * documents are added to the set of prohibited matches for this field, + * creating that set if it does not yet exist. + */ + if (clause.presence == lunr.Query.presence.PROHIBITED) { + if (prohibitedMatches[field] === undefined) { + prohibitedMatches[field] = lunr.Set.empty + } + + prohibitedMatches[field] = prohibitedMatches[field].union(matchingDocumentsSet) + + /* + * Prohibited matches should not be part of the query vector used for + * similarity scoring and no metadata should be extracted so we continue + * to the next field + */ + continue + } + + /* + * The query field vector is populated using the termIndex found for + * the term and a unit value with the appropriate boost applied. + * Using upsert because there could already be an entry in the vector + * for the term we are working with. In that case we just add the scores + * together. + */ + queryVectors[field].upsert(termIndex, clause.boost, function (a, b) { return a + b }) + + /** + * If we've already seen this term, field combo then we've already collected + * the matching documents and metadata, no need to go through all that again + */ + if (termFieldCache[termField]) { + continue + } + + for (var l = 0; l < matchingDocumentRefs.length; l++) { + /* + * All metadata for this term/field/document triple + * are then extracted and collected into an instance + * of lunr.MatchData ready to be returned in the query + * results + */ + var matchingDocumentRef = matchingDocumentRefs[l], + matchingFieldRef = new lunr.FieldRef (matchingDocumentRef, field), + metadata = fieldPosting[matchingDocumentRef], + fieldMatch + + if ((fieldMatch = matchingFields[matchingFieldRef]) === undefined) { + matchingFields[matchingFieldRef] = new lunr.MatchData (expandedTerm, field, metadata) + } else { + fieldMatch.add(expandedTerm, field, metadata) + } + + } + + termFieldCache[termField] = true + } + } + } + + /** + * If the presence was required we need to update the requiredMatches field sets. + * We do this after all fields for the term have collected their matches because + * the clause terms presence is required in _any_ of the fields not _all_ of the + * fields. + */ + if (clause.presence === lunr.Query.presence.REQUIRED) { + for (var k = 0; k < clause.fields.length; k++) { + var field = clause.fields[k] + requiredMatches[field] = requiredMatches[field].intersect(clauseMatches) + } + } + } + + /** + * Need to combine the field scoped required and prohibited + * matching documents into a global set of required and prohibited + * matches + */ + var allRequiredMatches = lunr.Set.complete, + allProhibitedMatches = lunr.Set.empty + + for (var i = 0; i < this.fields.length; i++) { + var field = this.fields[i] + + if (requiredMatches[field]) { + allRequiredMatches = allRequiredMatches.intersect(requiredMatches[field]) + } + + if (prohibitedMatches[field]) { + allProhibitedMatches = allProhibitedMatches.union(prohibitedMatches[field]) + } + } + + var matchingFieldRefs = Object.keys(matchingFields), + results = [], + matches = Object.create(null) + + /* + * If the query is negated (contains only prohibited terms) + * we need to get _all_ fieldRefs currently existing in the + * index. This is only done when we know that the query is + * entirely prohibited terms to avoid any cost of getting all + * fieldRefs unnecessarily. + * + * Additionally, blank MatchData must be created to correctly + * populate the results. + */ + if (query.isNegated()) { + matchingFieldRefs = Object.keys(this.fieldVectors) + + for (var i = 0; i < matchingFieldRefs.length; i++) { + var matchingFieldRef = matchingFieldRefs[i] + var fieldRef = lunr.FieldRef.fromString(matchingFieldRef) + matchingFields[matchingFieldRef] = new lunr.MatchData + } + } + + for (var i = 0; i < matchingFieldRefs.length; i++) { + /* + * Currently we have document fields that match the query, but we + * need to return documents. The matchData and scores are combined + * from multiple fields belonging to the same document. + * + * Scores are calculated by field, using the query vectors created + * above, and combined into a final document score using addition. + */ + var fieldRef = lunr.FieldRef.fromString(matchingFieldRefs[i]), + docRef = fieldRef.docRef + + if (!allRequiredMatches.contains(docRef)) { + continue + } + + if (allProhibitedMatches.contains(docRef)) { + continue + } + + var fieldVector = this.fieldVectors[fieldRef], + score = queryVectors[fieldRef.fieldName].similarity(fieldVector), + docMatch + + if ((docMatch = matches[docRef]) !== undefined) { + docMatch.score += score + docMatch.matchData.combine(matchingFields[fieldRef]) + } else { + var match = { + ref: docRef, + score: score, + matchData: matchingFields[fieldRef] + } + matches[docRef] = match + results.push(match) + } + } + + /* + * Sort the results objects by score, highest first. + */ + return results.sort(function (a, b) { + return b.score - a.score + }) +} + +/** + * Prepares the index for JSON serialization. + * + * The schema for this JSON blob will be described in a + * separate JSON schema file. + * + * @returns {Object} + */ +lunr.Index.prototype.toJSON = function () { + var invertedIndex = Object.keys(this.invertedIndex) + .sort() + .map(function (term) { + return [term, this.invertedIndex[term]] + }, this) + + var fieldVectors = Object.keys(this.fieldVectors) + .map(function (ref) { + return [ref, this.fieldVectors[ref].toJSON()] + }, this) + + return { + version: lunr.version, + fields: this.fields, + fieldVectors: fieldVectors, + invertedIndex: invertedIndex, + pipeline: this.pipeline.toJSON() + } +} + +/** + * Loads a previously serialized lunr.Index + * + * @param {Object} serializedIndex - A previously serialized lunr.Index + * @returns {lunr.Index} + */ +lunr.Index.load = function (serializedIndex) { + var attrs = {}, + fieldVectors = {}, + serializedVectors = serializedIndex.fieldVectors, + invertedIndex = Object.create(null), + serializedInvertedIndex = serializedIndex.invertedIndex, + tokenSetBuilder = new lunr.TokenSet.Builder, + pipeline = lunr.Pipeline.load(serializedIndex.pipeline) + + if (serializedIndex.version != lunr.version) { + lunr.utils.warn("Version mismatch when loading serialised index. Current version of lunr '" + lunr.version + "' does not match serialized index '" + serializedIndex.version + "'") + } + + for (var i = 0; i < serializedVectors.length; i++) { + var tuple = serializedVectors[i], + ref = tuple[0], + elements = tuple[1] + + fieldVectors[ref] = new lunr.Vector(elements) + } + + for (var i = 0; i < serializedInvertedIndex.length; i++) { + var tuple = serializedInvertedIndex[i], + term = tuple[0], + posting = tuple[1] + + tokenSetBuilder.insert(term) + invertedIndex[term] = posting + } + + tokenSetBuilder.finish() + + attrs.fields = serializedIndex.fields + + attrs.fieldVectors = fieldVectors + attrs.invertedIndex = invertedIndex + attrs.tokenSet = tokenSetBuilder.root + attrs.pipeline = pipeline + + return new lunr.Index(attrs) +} +/*! + * lunr.Builder + * Copyright (C) 2020 Oliver Nightingale + */ + +/** + * lunr.Builder performs indexing on a set of documents and + * returns instances of lunr.Index ready for querying. + * + * All configuration of the index is done via the builder, the + * fields to index, the document reference, the text processing + * pipeline and document scoring parameters are all set on the + * builder before indexing. + * + * @constructor + * @property {string} _ref - Internal reference to the document reference field. + * @property {string[]} _fields - Internal reference to the document fields to index. + * @property {object} invertedIndex - The inverted index maps terms to document fields. + * @property {object} documentTermFrequencies - Keeps track of document term frequencies. + * @property {object} documentLengths - Keeps track of the length of documents added to the index. + * @property {lunr.tokenizer} tokenizer - Function for splitting strings into tokens for indexing. + * @property {lunr.Pipeline} pipeline - The pipeline performs text processing on tokens before indexing. + * @property {lunr.Pipeline} searchPipeline - A pipeline for processing search terms before querying the index. + * @property {number} documentCount - Keeps track of the total number of documents indexed. + * @property {number} _b - A parameter to control field length normalization, setting this to 0 disabled normalization, 1 fully normalizes field lengths, the default value is 0.75. + * @property {number} _k1 - A parameter to control how quickly an increase in term frequency results in term frequency saturation, the default value is 1.2. + * @property {number} termIndex - A counter incremented for each unique term, used to identify a terms position in the vector space. + * @property {array} metadataWhitelist - A list of metadata keys that have been whitelisted for entry in the index. + */ +lunr.Builder = function () { + this._ref = "id" + this._fields = Object.create(null) + this._documents = Object.create(null) + this.invertedIndex = Object.create(null) + this.fieldTermFrequencies = {} + this.fieldLengths = {} + this.tokenizer = lunr.tokenizer + this.pipeline = new lunr.Pipeline + this.searchPipeline = new lunr.Pipeline + this.documentCount = 0 + this._b = 0.75 + this._k1 = 1.2 + this.termIndex = 0 + this.metadataWhitelist = [] +} + +/** + * Sets the document field used as the document reference. Every document must have this field. + * The type of this field in the document should be a string, if it is not a string it will be + * coerced into a string by calling toString. + * + * The default ref is 'id'. + * + * The ref should _not_ be changed during indexing, it should be set before any documents are + * added to the index. Changing it during indexing can lead to inconsistent results. + * + * @param {string} ref - The name of the reference field in the document. + */ +lunr.Builder.prototype.ref = function (ref) { + this._ref = ref +} + +/** + * A function that is used to extract a field from a document. + * + * Lunr expects a field to be at the top level of a document, if however the field + * is deeply nested within a document an extractor function can be used to extract + * the right field for indexing. + * + * @callback fieldExtractor + * @param {object} doc - The document being added to the index. + * @returns {?(string|object|object[])} obj - The object that will be indexed for this field. + * @example Extracting a nested field + * function (doc) { return doc.nested.field } + */ + +/** + * Adds a field to the list of document fields that will be indexed. Every document being + * indexed should have this field. Null values for this field in indexed documents will + * not cause errors but will limit the chance of that document being retrieved by searches. + * + * All fields should be added before adding documents to the index. Adding fields after + * a document has been indexed will have no effect on already indexed documents. + * + * Fields can be boosted at build time. This allows terms within that field to have more + * importance when ranking search results. Use a field boost to specify that matches within + * one field are more important than other fields. + * + * @param {string} fieldName - The name of a field to index in all documents. + * @param {object} attributes - Optional attributes associated with this field. + * @param {number} [attributes.boost=1] - Boost applied to all terms within this field. + * @param {fieldExtractor} [attributes.extractor] - Function to extract a field from a document. + * @throws {RangeError} fieldName cannot contain unsupported characters '/' + */ +lunr.Builder.prototype.field = function (fieldName, attributes) { + if (/\//.test(fieldName)) { + throw new RangeError ("Field '" + fieldName + "' contains illegal character '/'") + } + + this._fields[fieldName] = attributes || {} +} + +/** + * A parameter to tune the amount of field length normalisation that is applied when + * calculating relevance scores. A value of 0 will completely disable any normalisation + * and a value of 1 will fully normalise field lengths. The default is 0.75. Values of b + * will be clamped to the range 0 - 1. + * + * @param {number} number - The value to set for this tuning parameter. + */ +lunr.Builder.prototype.b = function (number) { + if (number < 0) { + this._b = 0 + } else if (number > 1) { + this._b = 1 + } else { + this._b = number + } +} + +/** + * A parameter that controls the speed at which a rise in term frequency results in term + * frequency saturation. The default value is 1.2. Setting this to a higher value will give + * slower saturation levels, a lower value will result in quicker saturation. + * + * @param {number} number - The value to set for this tuning parameter. + */ +lunr.Builder.prototype.k1 = function (number) { + this._k1 = number +} + +/** + * Adds a document to the index. + * + * Before adding fields to the index the index should have been fully setup, with the document + * ref and all fields to index already having been specified. + * + * The document must have a field name as specified by the ref (by default this is 'id') and + * it should have all fields defined for indexing, though null or undefined values will not + * cause errors. + * + * Entire documents can be boosted at build time. Applying a boost to a document indicates that + * this document should rank higher in search results than other documents. + * + * @param {object} doc - The document to add to the index. + * @param {object} attributes - Optional attributes associated with this document. + * @param {number} [attributes.boost=1] - Boost applied to all terms within this document. + */ +lunr.Builder.prototype.add = function (doc, attributes) { + var docRef = doc[this._ref], + fields = Object.keys(this._fields) + + this._documents[docRef] = attributes || {} + this.documentCount += 1 + + for (var i = 0; i < fields.length; i++) { + var fieldName = fields[i], + extractor = this._fields[fieldName].extractor, + field = extractor ? extractor(doc) : doc[fieldName], + tokens = this.tokenizer(field, { + fields: [fieldName] + }), + terms = this.pipeline.run(tokens), + fieldRef = new lunr.FieldRef (docRef, fieldName), + fieldTerms = Object.create(null) + + this.fieldTermFrequencies[fieldRef] = fieldTerms + this.fieldLengths[fieldRef] = 0 + + // store the length of this field for this document + this.fieldLengths[fieldRef] += terms.length + + // calculate term frequencies for this field + for (var j = 0; j < terms.length; j++) { + var term = terms[j] + + if (fieldTerms[term] == undefined) { + fieldTerms[term] = 0 + } + + fieldTerms[term] += 1 + + // add to inverted index + // create an initial posting if one doesn't exist + if (this.invertedIndex[term] == undefined) { + var posting = Object.create(null) + posting["_index"] = this.termIndex + this.termIndex += 1 + + for (var k = 0; k < fields.length; k++) { + posting[fields[k]] = Object.create(null) + } + + this.invertedIndex[term] = posting + } + + // add an entry for this term/fieldName/docRef to the invertedIndex + if (this.invertedIndex[term][fieldName][docRef] == undefined) { + this.invertedIndex[term][fieldName][docRef] = Object.create(null) + } + + // store all whitelisted metadata about this token in the + // inverted index + for (var l = 0; l < this.metadataWhitelist.length; l++) { + var metadataKey = this.metadataWhitelist[l], + metadata = term.metadata[metadataKey] + + if (this.invertedIndex[term][fieldName][docRef][metadataKey] == undefined) { + this.invertedIndex[term][fieldName][docRef][metadataKey] = [] + } + + this.invertedIndex[term][fieldName][docRef][metadataKey].push(metadata) + } + } + + } +} + +/** + * Calculates the average document length for this index + * + * @private + */ +lunr.Builder.prototype.calculateAverageFieldLengths = function () { + + var fieldRefs = Object.keys(this.fieldLengths), + numberOfFields = fieldRefs.length, + accumulator = {}, + documentsWithField = {} + + for (var i = 0; i < numberOfFields; i++) { + var fieldRef = lunr.FieldRef.fromString(fieldRefs[i]), + field = fieldRef.fieldName + + documentsWithField[field] || (documentsWithField[field] = 0) + documentsWithField[field] += 1 + + accumulator[field] || (accumulator[field] = 0) + accumulator[field] += this.fieldLengths[fieldRef] + } + + var fields = Object.keys(this._fields) + + for (var i = 0; i < fields.length; i++) { + var fieldName = fields[i] + accumulator[fieldName] = accumulator[fieldName] / documentsWithField[fieldName] + } + + this.averageFieldLength = accumulator +} + +/** + * Builds a vector space model of every document using lunr.Vector + * + * @private + */ +lunr.Builder.prototype.createFieldVectors = function () { + var fieldVectors = {}, + fieldRefs = Object.keys(this.fieldTermFrequencies), + fieldRefsLength = fieldRefs.length, + termIdfCache = Object.create(null) + + for (var i = 0; i < fieldRefsLength; i++) { + var fieldRef = lunr.FieldRef.fromString(fieldRefs[i]), + fieldName = fieldRef.fieldName, + fieldLength = this.fieldLengths[fieldRef], + fieldVector = new lunr.Vector, + termFrequencies = this.fieldTermFrequencies[fieldRef], + terms = Object.keys(termFrequencies), + termsLength = terms.length + + + var fieldBoost = this._fields[fieldName].boost || 1, + docBoost = this._documents[fieldRef.docRef].boost || 1 + + for (var j = 0; j < termsLength; j++) { + var term = terms[j], + tf = termFrequencies[term], + termIndex = this.invertedIndex[term]._index, + idf, score, scoreWithPrecision + + if (termIdfCache[term] === undefined) { + idf = lunr.idf(this.invertedIndex[term], this.documentCount) + termIdfCache[term] = idf + } else { + idf = termIdfCache[term] + } + + score = idf * ((this._k1 + 1) * tf) / (this._k1 * (1 - this._b + this._b * (fieldLength / this.averageFieldLength[fieldName])) + tf) + score *= fieldBoost + score *= docBoost + scoreWithPrecision = Math.round(score * 1000) / 1000 + // Converts 1.23456789 to 1.234. + // Reducing the precision so that the vectors take up less + // space when serialised. Doing it now so that they behave + // the same before and after serialisation. Also, this is + // the fastest approach to reducing a number's precision in + // JavaScript. + + fieldVector.insert(termIndex, scoreWithPrecision) + } + + fieldVectors[fieldRef] = fieldVector + } + + this.fieldVectors = fieldVectors +} + +/** + * Creates a token set of all tokens in the index using lunr.TokenSet + * + * @private + */ +lunr.Builder.prototype.createTokenSet = function () { + this.tokenSet = lunr.TokenSet.fromArray( + Object.keys(this.invertedIndex).sort() + ) +} + +/** + * Builds the index, creating an instance of lunr.Index. + * + * This completes the indexing process and should only be called + * once all documents have been added to the index. + * + * @returns {lunr.Index} + */ +lunr.Builder.prototype.build = function () { + this.calculateAverageFieldLengths() + this.createFieldVectors() + this.createTokenSet() + + return new lunr.Index({ + invertedIndex: this.invertedIndex, + fieldVectors: this.fieldVectors, + tokenSet: this.tokenSet, + fields: Object.keys(this._fields), + pipeline: this.searchPipeline + }) +} + +/** + * Applies a plugin to the index builder. + * + * A plugin is a function that is called with the index builder as its context. + * Plugins can be used to customise or extend the behaviour of the index + * in some way. A plugin is just a function, that encapsulated the custom + * behaviour that should be applied when building the index. + * + * The plugin function will be called with the index builder as its argument, additional + * arguments can also be passed when calling use. The function will be called + * with the index builder as its context. + * + * @param {Function} plugin The plugin to apply. + */ +lunr.Builder.prototype.use = function (fn) { + var args = Array.prototype.slice.call(arguments, 1) + args.unshift(this) + fn.apply(this, args) +} +/** + * Contains and collects metadata about a matching document. + * A single instance of lunr.MatchData is returned as part of every + * lunr.Index~Result. + * + * @constructor + * @param {string} term - The term this match data is associated with + * @param {string} field - The field in which the term was found + * @param {object} metadata - The metadata recorded about this term in this field + * @property {object} metadata - A cloned collection of metadata associated with this document. + * @see {@link lunr.Index~Result} + */ +lunr.MatchData = function (term, field, metadata) { + var clonedMetadata = Object.create(null), + metadataKeys = Object.keys(metadata || {}) + + // Cloning the metadata to prevent the original + // being mutated during match data combination. + // Metadata is kept in an array within the inverted + // index so cloning the data can be done with + // Array#slice + for (var i = 0; i < metadataKeys.length; i++) { + var key = metadataKeys[i] + clonedMetadata[key] = metadata[key].slice() + } + + this.metadata = Object.create(null) + + if (term !== undefined) { + this.metadata[term] = Object.create(null) + this.metadata[term][field] = clonedMetadata + } +} + +/** + * An instance of lunr.MatchData will be created for every term that matches a + * document. However only one instance is required in a lunr.Index~Result. This + * method combines metadata from another instance of lunr.MatchData with this + * objects metadata. + * + * @param {lunr.MatchData} otherMatchData - Another instance of match data to merge with this one. + * @see {@link lunr.Index~Result} + */ +lunr.MatchData.prototype.combine = function (otherMatchData) { + var terms = Object.keys(otherMatchData.metadata) + + for (var i = 0; i < terms.length; i++) { + var term = terms[i], + fields = Object.keys(otherMatchData.metadata[term]) + + if (this.metadata[term] == undefined) { + this.metadata[term] = Object.create(null) + } + + for (var j = 0; j < fields.length; j++) { + var field = fields[j], + keys = Object.keys(otherMatchData.metadata[term][field]) + + if (this.metadata[term][field] == undefined) { + this.metadata[term][field] = Object.create(null) + } + + for (var k = 0; k < keys.length; k++) { + var key = keys[k] + + if (this.metadata[term][field][key] == undefined) { + this.metadata[term][field][key] = otherMatchData.metadata[term][field][key] + } else { + this.metadata[term][field][key] = this.metadata[term][field][key].concat(otherMatchData.metadata[term][field][key]) + } + + } + } + } +} + +/** + * Add metadata for a term/field pair to this instance of match data. + * + * @param {string} term - The term this match data is associated with + * @param {string} field - The field in which the term was found + * @param {object} metadata - The metadata recorded about this term in this field + */ +lunr.MatchData.prototype.add = function (term, field, metadata) { + if (!(term in this.metadata)) { + this.metadata[term] = Object.create(null) + this.metadata[term][field] = metadata + return + } + + if (!(field in this.metadata[term])) { + this.metadata[term][field] = metadata + return + } + + var metadataKeys = Object.keys(metadata) + + for (var i = 0; i < metadataKeys.length; i++) { + var key = metadataKeys[i] + + if (key in this.metadata[term][field]) { + this.metadata[term][field][key] = this.metadata[term][field][key].concat(metadata[key]) + } else { + this.metadata[term][field][key] = metadata[key] + } + } +} +/** + * A lunr.Query provides a programmatic way of defining queries to be performed + * against a {@link lunr.Index}. + * + * Prefer constructing a lunr.Query using the {@link lunr.Index#query} method + * so the query object is pre-initialized with the right index fields. + * + * @constructor + * @property {lunr.Query~Clause[]} clauses - An array of query clauses. + * @property {string[]} allFields - An array of all available fields in a lunr.Index. + */ +lunr.Query = function (allFields) { + this.clauses = [] + this.allFields = allFields +} + +/** + * Constants for indicating what kind of automatic wildcard insertion will be used when constructing a query clause. + * + * This allows wildcards to be added to the beginning and end of a term without having to manually do any string + * concatenation. + * + * The wildcard constants can be bitwise combined to select both leading and trailing wildcards. + * + * @constant + * @default + * @property {number} wildcard.NONE - The term will have no wildcards inserted, this is the default behaviour + * @property {number} wildcard.LEADING - Prepend the term with a wildcard, unless a leading wildcard already exists + * @property {number} wildcard.TRAILING - Append a wildcard to the term, unless a trailing wildcard already exists + * @see lunr.Query~Clause + * @see lunr.Query#clause + * @see lunr.Query#term + * @example query term with trailing wildcard + * query.term('foo', { wildcard: lunr.Query.wildcard.TRAILING }) + * @example query term with leading and trailing wildcard + * query.term('foo', { + * wildcard: lunr.Query.wildcard.LEADING | lunr.Query.wildcard.TRAILING + * }) + */ + +lunr.Query.wildcard = new String ("*") +lunr.Query.wildcard.NONE = 0 +lunr.Query.wildcard.LEADING = 1 +lunr.Query.wildcard.TRAILING = 2 + +/** + * Constants for indicating what kind of presence a term must have in matching documents. + * + * @constant + * @enum {number} + * @see lunr.Query~Clause + * @see lunr.Query#clause + * @see lunr.Query#term + * @example query term with required presence + * query.term('foo', { presence: lunr.Query.presence.REQUIRED }) + */ +lunr.Query.presence = { + /** + * Term's presence in a document is optional, this is the default value. + */ + OPTIONAL: 1, + + /** + * Term's presence in a document is required, documents that do not contain + * this term will not be returned. + */ + REQUIRED: 2, + + /** + * Term's presence in a document is prohibited, documents that do contain + * this term will not be returned. + */ + PROHIBITED: 3 +} + +/** + * A single clause in a {@link lunr.Query} contains a term and details on how to + * match that term against a {@link lunr.Index}. + * + * @typedef {Object} lunr.Query~Clause + * @property {string[]} fields - The fields in an index this clause should be matched against. + * @property {number} [boost=1] - Any boost that should be applied when matching this clause. + * @property {number} [editDistance] - Whether the term should have fuzzy matching applied, and how fuzzy the match should be. + * @property {boolean} [usePipeline] - Whether the term should be passed through the search pipeline. + * @property {number} [wildcard=lunr.Query.wildcard.NONE] - Whether the term should have wildcards appended or prepended. + * @property {number} [presence=lunr.Query.presence.OPTIONAL] - The terms presence in any matching documents. + */ + +/** + * Adds a {@link lunr.Query~Clause} to this query. + * + * Unless the clause contains the fields to be matched all fields will be matched. In addition + * a default boost of 1 is applied to the clause. + * + * @param {lunr.Query~Clause} clause - The clause to add to this query. + * @see lunr.Query~Clause + * @returns {lunr.Query} + */ +lunr.Query.prototype.clause = function (clause) { + if (!('fields' in clause)) { + clause.fields = this.allFields + } + + if (!('boost' in clause)) { + clause.boost = 1 + } + + if (!('usePipeline' in clause)) { + clause.usePipeline = true + } + + if (!('wildcard' in clause)) { + clause.wildcard = lunr.Query.wildcard.NONE + } + + if ((clause.wildcard & lunr.Query.wildcard.LEADING) && (clause.term.charAt(0) != lunr.Query.wildcard)) { + clause.term = "*" + clause.term + } + + if ((clause.wildcard & lunr.Query.wildcard.TRAILING) && (clause.term.slice(-1) != lunr.Query.wildcard)) { + clause.term = "" + clause.term + "*" + } + + if (!('presence' in clause)) { + clause.presence = lunr.Query.presence.OPTIONAL + } + + this.clauses.push(clause) + + return this +} + +/** + * A negated query is one in which every clause has a presence of + * prohibited. These queries require some special processing to return + * the expected results. + * + * @returns boolean + */ +lunr.Query.prototype.isNegated = function () { + for (var i = 0; i < this.clauses.length; i++) { + if (this.clauses[i].presence != lunr.Query.presence.PROHIBITED) { + return false + } + } + + return true +} + +/** + * Adds a term to the current query, under the covers this will create a {@link lunr.Query~Clause} + * to the list of clauses that make up this query. + * + * The term is used as is, i.e. no tokenization will be performed by this method. Instead conversion + * to a token or token-like string should be done before calling this method. + * + * The term will be converted to a string by calling `toString`. Multiple terms can be passed as an + * array, each term in the array will share the same options. + * + * @param {object|object[]} term - The term(s) to add to the query. + * @param {object} [options] - Any additional properties to add to the query clause. + * @returns {lunr.Query} + * @see lunr.Query#clause + * @see lunr.Query~Clause + * @example adding a single term to a query + * query.term("foo") + * @example adding a single term to a query and specifying search fields, term boost and automatic trailing wildcard + * query.term("foo", { + * fields: ["title"], + * boost: 10, + * wildcard: lunr.Query.wildcard.TRAILING + * }) + * @example using lunr.tokenizer to convert a string to tokens before using them as terms + * query.term(lunr.tokenizer("foo bar")) + */ +lunr.Query.prototype.term = function (term, options) { + if (Array.isArray(term)) { + term.forEach(function (t) { this.term(t, lunr.utils.clone(options)) }, this) + return this + } + + var clause = options || {} + clause.term = term.toString() + + this.clause(clause) + + return this +} +lunr.QueryParseError = function (message, start, end) { + this.name = "QueryParseError" + this.message = message + this.start = start + this.end = end +} + +lunr.QueryParseError.prototype = new Error +lunr.QueryLexer = function (str) { + this.lexemes = [] + this.str = str + this.length = str.length + this.pos = 0 + this.start = 0 + this.escapeCharPositions = [] +} + +lunr.QueryLexer.prototype.run = function () { + var state = lunr.QueryLexer.lexText + + while (state) { + state = state(this) + } +} + +lunr.QueryLexer.prototype.sliceString = function () { + var subSlices = [], + sliceStart = this.start, + sliceEnd = this.pos + + for (var i = 0; i < this.escapeCharPositions.length; i++) { + sliceEnd = this.escapeCharPositions[i] + subSlices.push(this.str.slice(sliceStart, sliceEnd)) + sliceStart = sliceEnd + 1 + } + + subSlices.push(this.str.slice(sliceStart, this.pos)) + this.escapeCharPositions.length = 0 + + return subSlices.join('') +} + +lunr.QueryLexer.prototype.emit = function (type) { + this.lexemes.push({ + type: type, + str: this.sliceString(), + start: this.start, + end: this.pos + }) + + this.start = this.pos +} + +lunr.QueryLexer.prototype.escapeCharacter = function () { + this.escapeCharPositions.push(this.pos - 1) + this.pos += 1 +} + +lunr.QueryLexer.prototype.next = function () { + if (this.pos >= this.length) { + return lunr.QueryLexer.EOS + } + + var char = this.str.charAt(this.pos) + this.pos += 1 + return char +} + +lunr.QueryLexer.prototype.width = function () { + return this.pos - this.start +} + +lunr.QueryLexer.prototype.ignore = function () { + if (this.start == this.pos) { + this.pos += 1 + } + + this.start = this.pos +} + +lunr.QueryLexer.prototype.backup = function () { + this.pos -= 1 +} + +lunr.QueryLexer.prototype.acceptDigitRun = function () { + var char, charCode + + do { + char = this.next() + charCode = char.charCodeAt(0) + } while (charCode > 47 && charCode < 58) + + if (char != lunr.QueryLexer.EOS) { + this.backup() + } +} + +lunr.QueryLexer.prototype.more = function () { + return this.pos < this.length +} + +lunr.QueryLexer.EOS = 'EOS' +lunr.QueryLexer.FIELD = 'FIELD' +lunr.QueryLexer.TERM = 'TERM' +lunr.QueryLexer.EDIT_DISTANCE = 'EDIT_DISTANCE' +lunr.QueryLexer.BOOST = 'BOOST' +lunr.QueryLexer.PRESENCE = 'PRESENCE' + +lunr.QueryLexer.lexField = function (lexer) { + lexer.backup() + lexer.emit(lunr.QueryLexer.FIELD) + lexer.ignore() + return lunr.QueryLexer.lexText +} + +lunr.QueryLexer.lexTerm = function (lexer) { + if (lexer.width() > 1) { + lexer.backup() + lexer.emit(lunr.QueryLexer.TERM) + } + + lexer.ignore() + + if (lexer.more()) { + return lunr.QueryLexer.lexText + } +} + +lunr.QueryLexer.lexEditDistance = function (lexer) { + lexer.ignore() + lexer.acceptDigitRun() + lexer.emit(lunr.QueryLexer.EDIT_DISTANCE) + return lunr.QueryLexer.lexText +} + +lunr.QueryLexer.lexBoost = function (lexer) { + lexer.ignore() + lexer.acceptDigitRun() + lexer.emit(lunr.QueryLexer.BOOST) + return lunr.QueryLexer.lexText +} + +lunr.QueryLexer.lexEOS = function (lexer) { + if (lexer.width() > 0) { + lexer.emit(lunr.QueryLexer.TERM) + } +} + +// This matches the separator used when tokenising fields +// within a document. These should match otherwise it is +// not possible to search for some tokens within a document. +// +// It is possible for the user to change the separator on the +// tokenizer so it _might_ clash with any other of the special +// characters already used within the search string, e.g. :. +// +// This means that it is possible to change the separator in +// such a way that makes some words unsearchable using a search +// string. +lunr.QueryLexer.termSeparator = lunr.tokenizer.separator + +lunr.QueryLexer.lexText = function (lexer) { + while (true) { + var char = lexer.next() + + if (char == lunr.QueryLexer.EOS) { + return lunr.QueryLexer.lexEOS + } + + // Escape character is '\' + if (char.charCodeAt(0) == 92) { + lexer.escapeCharacter() + continue + } + + if (char == ":") { + return lunr.QueryLexer.lexField + } + + if (char == "~") { + lexer.backup() + if (lexer.width() > 0) { + lexer.emit(lunr.QueryLexer.TERM) + } + return lunr.QueryLexer.lexEditDistance + } + + if (char == "^") { + lexer.backup() + if (lexer.width() > 0) { + lexer.emit(lunr.QueryLexer.TERM) + } + return lunr.QueryLexer.lexBoost + } + + // "+" indicates term presence is required + // checking for length to ensure that only + // leading "+" are considered + if (char == "+" && lexer.width() === 1) { + lexer.emit(lunr.QueryLexer.PRESENCE) + return lunr.QueryLexer.lexText + } + + // "-" indicates term presence is prohibited + // checking for length to ensure that only + // leading "-" are considered + if (char == "-" && lexer.width() === 1) { + lexer.emit(lunr.QueryLexer.PRESENCE) + return lunr.QueryLexer.lexText + } + + if (char.match(lunr.QueryLexer.termSeparator)) { + return lunr.QueryLexer.lexTerm + } + } +} + +lunr.QueryParser = function (str, query) { + this.lexer = new lunr.QueryLexer (str) + this.query = query + this.currentClause = {} + this.lexemeIdx = 0 +} + +lunr.QueryParser.prototype.parse = function () { + this.lexer.run() + this.lexemes = this.lexer.lexemes + + var state = lunr.QueryParser.parseClause + + while (state) { + state = state(this) + } + + return this.query +} + +lunr.QueryParser.prototype.peekLexeme = function () { + return this.lexemes[this.lexemeIdx] +} + +lunr.QueryParser.prototype.consumeLexeme = function () { + var lexeme = this.peekLexeme() + this.lexemeIdx += 1 + return lexeme +} + +lunr.QueryParser.prototype.nextClause = function () { + var completedClause = this.currentClause + this.query.clause(completedClause) + this.currentClause = {} +} + +lunr.QueryParser.parseClause = function (parser) { + var lexeme = parser.peekLexeme() + + if (lexeme == undefined) { + return + } + + switch (lexeme.type) { + case lunr.QueryLexer.PRESENCE: + return lunr.QueryParser.parsePresence + case lunr.QueryLexer.FIELD: + return lunr.QueryParser.parseField + case lunr.QueryLexer.TERM: + return lunr.QueryParser.parseTerm + default: + var errorMessage = "expected either a field or a term, found " + lexeme.type + + if (lexeme.str.length >= 1) { + errorMessage += " with value '" + lexeme.str + "'" + } + + throw new lunr.QueryParseError (errorMessage, lexeme.start, lexeme.end) + } +} + +lunr.QueryParser.parsePresence = function (parser) { + var lexeme = parser.consumeLexeme() + + if (lexeme == undefined) { + return + } + + switch (lexeme.str) { + case "-": + parser.currentClause.presence = lunr.Query.presence.PROHIBITED + break + case "+": + parser.currentClause.presence = lunr.Query.presence.REQUIRED + break + default: + var errorMessage = "unrecognised presence operator'" + lexeme.str + "'" + throw new lunr.QueryParseError (errorMessage, lexeme.start, lexeme.end) + } + + var nextLexeme = parser.peekLexeme() + + if (nextLexeme == undefined) { + var errorMessage = "expecting term or field, found nothing" + throw new lunr.QueryParseError (errorMessage, lexeme.start, lexeme.end) + } + + switch (nextLexeme.type) { + case lunr.QueryLexer.FIELD: + return lunr.QueryParser.parseField + case lunr.QueryLexer.TERM: + return lunr.QueryParser.parseTerm + default: + var errorMessage = "expecting term or field, found '" + nextLexeme.type + "'" + throw new lunr.QueryParseError (errorMessage, nextLexeme.start, nextLexeme.end) + } +} + +lunr.QueryParser.parseField = function (parser) { + var lexeme = parser.consumeLexeme() + + if (lexeme == undefined) { + return + } + + if (parser.query.allFields.indexOf(lexeme.str) == -1) { + var possibleFields = parser.query.allFields.map(function (f) { return "'" + f + "'" }).join(', '), + errorMessage = "unrecognised field '" + lexeme.str + "', possible fields: " + possibleFields + + throw new lunr.QueryParseError (errorMessage, lexeme.start, lexeme.end) + } + + parser.currentClause.fields = [lexeme.str] + + var nextLexeme = parser.peekLexeme() + + if (nextLexeme == undefined) { + var errorMessage = "expecting term, found nothing" + throw new lunr.QueryParseError (errorMessage, lexeme.start, lexeme.end) + } + + switch (nextLexeme.type) { + case lunr.QueryLexer.TERM: + return lunr.QueryParser.parseTerm + default: + var errorMessage = "expecting term, found '" + nextLexeme.type + "'" + throw new lunr.QueryParseError (errorMessage, nextLexeme.start, nextLexeme.end) + } +} + +lunr.QueryParser.parseTerm = function (parser) { + var lexeme = parser.consumeLexeme() + + if (lexeme == undefined) { + return + } + + parser.currentClause.term = lexeme.str.toLowerCase() + + if (lexeme.str.indexOf("*") != -1) { + parser.currentClause.usePipeline = false + } + + var nextLexeme = parser.peekLexeme() + + if (nextLexeme == undefined) { + parser.nextClause() + return + } + + switch (nextLexeme.type) { + case lunr.QueryLexer.TERM: + parser.nextClause() + return lunr.QueryParser.parseTerm + case lunr.QueryLexer.FIELD: + parser.nextClause() + return lunr.QueryParser.parseField + case lunr.QueryLexer.EDIT_DISTANCE: + return lunr.QueryParser.parseEditDistance + case lunr.QueryLexer.BOOST: + return lunr.QueryParser.parseBoost + case lunr.QueryLexer.PRESENCE: + parser.nextClause() + return lunr.QueryParser.parsePresence + default: + var errorMessage = "Unexpected lexeme type '" + nextLexeme.type + "'" + throw new lunr.QueryParseError (errorMessage, nextLexeme.start, nextLexeme.end) + } +} + +lunr.QueryParser.parseEditDistance = function (parser) { + var lexeme = parser.consumeLexeme() + + if (lexeme == undefined) { + return + } + + var editDistance = parseInt(lexeme.str, 10) + + if (isNaN(editDistance)) { + var errorMessage = "edit distance must be numeric" + throw new lunr.QueryParseError (errorMessage, lexeme.start, lexeme.end) + } + + parser.currentClause.editDistance = editDistance + + var nextLexeme = parser.peekLexeme() + + if (nextLexeme == undefined) { + parser.nextClause() + return + } + + switch (nextLexeme.type) { + case lunr.QueryLexer.TERM: + parser.nextClause() + return lunr.QueryParser.parseTerm + case lunr.QueryLexer.FIELD: + parser.nextClause() + return lunr.QueryParser.parseField + case lunr.QueryLexer.EDIT_DISTANCE: + return lunr.QueryParser.parseEditDistance + case lunr.QueryLexer.BOOST: + return lunr.QueryParser.parseBoost + case lunr.QueryLexer.PRESENCE: + parser.nextClause() + return lunr.QueryParser.parsePresence + default: + var errorMessage = "Unexpected lexeme type '" + nextLexeme.type + "'" + throw new lunr.QueryParseError (errorMessage, nextLexeme.start, nextLexeme.end) + } +} + +lunr.QueryParser.parseBoost = function (parser) { + var lexeme = parser.consumeLexeme() + + if (lexeme == undefined) { + return + } + + var boost = parseInt(lexeme.str, 10) + + if (isNaN(boost)) { + var errorMessage = "boost must be numeric" + throw new lunr.QueryParseError (errorMessage, lexeme.start, lexeme.end) + } + + parser.currentClause.boost = boost + + var nextLexeme = parser.peekLexeme() + + if (nextLexeme == undefined) { + parser.nextClause() + return + } + + switch (nextLexeme.type) { + case lunr.QueryLexer.TERM: + parser.nextClause() + return lunr.QueryParser.parseTerm + case lunr.QueryLexer.FIELD: + parser.nextClause() + return lunr.QueryParser.parseField + case lunr.QueryLexer.EDIT_DISTANCE: + return lunr.QueryParser.parseEditDistance + case lunr.QueryLexer.BOOST: + return lunr.QueryParser.parseBoost + case lunr.QueryLexer.PRESENCE: + parser.nextClause() + return lunr.QueryParser.parsePresence + default: + var errorMessage = "Unexpected lexeme type '" + nextLexeme.type + "'" + throw new lunr.QueryParseError (errorMessage, nextLexeme.start, nextLexeme.end) + } +} + + /** + * export the module via AMD, CommonJS or as a browser global + * Export code from https://github.com/umdjs/umd/blob/master/returnExports.js + */ + ;(function (root, factory) { + if (typeof define === 'function' && define.amd) { + // AMD. Register as an anonymous module. + define(factory) + } else if (typeof exports === 'object') { + /** + * Node. Does not work with strict CommonJS, but + * only CommonJS-like environments that support module.exports, + * like Node. + */ + module.exports = factory() + } else { + // Browser globals (root is window) + root.lunr = factory() + } + }(this, function () { + /** + * Just return a value to define the module export. + * This example returns an object, but the module + * can return a function as the exported value. + */ + return lunr + })) +})(); diff --git a/search/main.js b/search/main.js new file mode 100644 index 000000000..a5e469d7c --- /dev/null +++ b/search/main.js @@ -0,0 +1,109 @@ +function getSearchTermFromLocation() { + var sPageURL = window.location.search.substring(1); + var sURLVariables = sPageURL.split('&'); + for (var i = 0; i < sURLVariables.length; i++) { + var sParameterName = sURLVariables[i].split('='); + if (sParameterName[0] == 'q') { + return decodeURIComponent(sParameterName[1].replace(/\+/g, '%20')); + } + } +} + +function joinUrl (base, path) { + if (path.substring(0, 1) === "/") { + // path starts with `/`. Thus it is absolute. + return path; + } + if (base.substring(base.length-1) === "/") { + // base ends with `/` + return base + path; + } + return base + "/" + path; +} + +function escapeHtml (value) { + return value.replace(/&/g, '&') + .replace(/"/g, '"') + .replace(//g, '>'); +} + +function formatResult (location, title, summary) { + return ''; +} + +function displayResults (results) { + var search_results = document.getElementById("mkdocs-search-results"); + while (search_results.firstChild) { + search_results.removeChild(search_results.firstChild); + } + if (results.length > 0){ + for (var i=0; i < results.length; i++){ + var result = results[i]; + var html = formatResult(result.location, result.title, result.summary); + search_results.insertAdjacentHTML('beforeend', html); + } + } else { + var noResultsText = search_results.getAttribute('data-no-results-text'); + if (!noResultsText) { + noResultsText = "No results found"; + } + search_results.insertAdjacentHTML('beforeend', '

' + noResultsText + '

'); + } +} + +function doSearch () { + var query = document.getElementById('mkdocs-search-query').value; + if (query.length > min_search_length) { + if (!window.Worker) { + displayResults(search(query)); + } else { + searchWorker.postMessage({query: query}); + } + } else { + // Clear results for short queries + displayResults([]); + } +} + +function initSearch () { + var search_input = document.getElementById('mkdocs-search-query'); + if (search_input) { + search_input.addEventListener("keyup", doSearch); + } + var term = getSearchTermFromLocation(); + if (term) { + search_input.value = term; + doSearch(); + } +} + +function onWorkerMessage (e) { + if (e.data.allowSearch) { + initSearch(); + } else if (e.data.results) { + var results = e.data.results; + displayResults(results); + } else if (e.data.config) { + min_search_length = e.data.config.min_search_length-1; + } +} + +if (!window.Worker) { + console.log('Web Worker API not supported'); + // load index in main thread + $.getScript(joinUrl(base_url, "search/worker.js")).done(function () { + console.log('Loaded worker'); + init(); + window.postMessage = function (msg) { + onWorkerMessage({data: msg}); + }; + }).fail(function (jqxhr, settings, exception) { + console.error('Could not load worker.js'); + }); +} else { + // Wrap search in a web worker + var searchWorker = new Worker(joinUrl(base_url, "search/worker.js")); + searchWorker.postMessage({init: true}); + searchWorker.onmessage = onWorkerMessage; +} diff --git a/search/search_index.json b/search/search_index.json new file mode 100644 index 000000000..d368f0f52 --- /dev/null +++ b/search/search_index.json @@ -0,0 +1 @@ +{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Introduction Home battery prediction and automatic charging for Home Assistant supporting multiple inverters including: GivEnergy Hybrid, AC and AIO Solis Solax Sunsynk Huawei SolarEdge Fox Sofar LuxPower Solar Assistant Also known by some as Batpred or Batman! Copyright (c) Trefor Southwell April 2024 - All rights reserved This software maybe used at not cost for personal use only No warranty is given, either expressed or implied For support please raise a Github ticket or use the Facebook Group: Predbat and watch my YouTube Channel Some inverters have their own groups also e.g: GivTCP Solis If you want to buy me a beer then please use Paypal - tdlj@tdlj.net Taster Once you are up and running you will get a chart that predicts your battery levels over time: And you can also see this in a plan format predicting your overall costs and your carbon footprint (if enabled, UK only for now): You can see a cost over time for the plan that Predbat has made and also how it might turn out if your solar production (should you have solar) is lower than expected or if you use a bit more energy than planned (10% scenario): You can see your energy rates over time and where the battery is being charged: Power charts can show you how the prediction maps to your inverter: You can model iBoost or similar solar diverters, this will be shown on your plan and you can even use it to trigger smart devices e.g. an emersion heater based on energy rates. You can predict when your car will charge and use Predbat to schedule the cheapest car charging slots: Charts can track your cost saving using Predbat and from having a PV and Battery system The calibration chart is useful for tuning the model for things like inverter losses until it matches reality: Predbat can track your actual vs predicted energy usage and make real time adjustments to the predictions if you use more or less: You can tune lots of parameters to match your system and needs: You can also override the plan on a temporary basis if you have a particular reason to: Please read the documentation for more information!","title":"Introduction"},{"location":"#introduction","text":"Home battery prediction and automatic charging for Home Assistant supporting multiple inverters including: GivEnergy Hybrid, AC and AIO Solis Solax Sunsynk Huawei SolarEdge Fox Sofar LuxPower Solar Assistant Also known by some as Batpred or Batman! Copyright (c) Trefor Southwell April 2024 - All rights reserved This software maybe used at not cost for personal use only No warranty is given, either expressed or implied For support please raise a Github ticket or use the Facebook Group: Predbat and watch my YouTube Channel Some inverters have their own groups also e.g: GivTCP Solis If you want to buy me a beer then please use Paypal - tdlj@tdlj.net","title":"Introduction"},{"location":"#taster","text":"Once you are up and running you will get a chart that predicts your battery levels over time: And you can also see this in a plan format predicting your overall costs and your carbon footprint (if enabled, UK only for now): You can see a cost over time for the plan that Predbat has made and also how it might turn out if your solar production (should you have solar) is lower than expected or if you use a bit more energy than planned (10% scenario): You can see your energy rates over time and where the battery is being charged: Power charts can show you how the prediction maps to your inverter: You can model iBoost or similar solar diverters, this will be shown on your plan and you can even use it to trigger smart devices e.g. an emersion heater based on energy rates. You can predict when your car will charge and use Predbat to schedule the cheapest car charging slots: Charts can track your cost saving using Predbat and from having a PV and Battery system The calibration chart is useful for tuning the model for things like inverter losses until it matches reality: Predbat can track your actual vs predicted energy usage and make real time adjustments to the predictions if you use more or less: You can tune lots of parameters to match your system and needs: You can also override the plan on a temporary basis if you have a particular reason to: Please read the documentation for more information!","title":"Taster"},{"location":"apps-yaml/","text":"apps.yaml settings The basic Predbat configuration is defined in the apps.yaml file. Depending on how you installed Predbat the apps.yaml file will be held in one of three different directories in Home Assistant: if you have used the Predbat add-on installation method , apps.yaml will be in the directory /addon_configs/6adb4f0d_predbat , with the HACS, Appdaemon add-on then Predbat installation method , it's in /config/appdaemon/apps/batpred/config/ , or if the combined AppDaemon/Predbat add-on installation method was used, it's in /addon_configs/46f69597_appdaemon-predbat/apps . 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 edit the apps.yaml file - see editing configuration files within Home Assistant if you need to install an editor. This section of the documentation describes what the different configuration items in apps.yaml do. When you edit apps.yaml , the change will automatically be detected and Predbat will be reloaded with the updated file. You don't need to restart the Predbat or AppDaemon add-on for your edits to take effect. Warning! apps.yaml file format When editing the apps.yaml file you must ensure that the file remains correctly formatted. YAML files are especially finicky about how the file contents are indented and its very easy to end up with an incorrectly formatted file that will cause problems for Predbat. The YAML Basics from This Smart Home is a good introduction video to how YAML should be correctly structured, but as a brief introduction, YAML files consist of an entity name, colon then the entity value, for example: timezone: Europe/London Or the entity can be set to a list of values with each value being on a new line, two spaces, a dash, then the value. For example: car_charging_now_response: - 'yes' - 'on' The two spaces before the dash are especially critical. Its easy to mis-edit and have one or three spaces which isn't valid YAML. NB: the sequence of entries in apps.yaml doesn't matter, as long as the YAML itself is structured correctly you can move things and edit things anywhere in the file. Templates You can find template configurations in the following location: https://github.com/springfall2008/batpred/tree/main/templates The GivEnergy GivTCP template will be installed by default but if you are using another inverter please copy the correct template into the directory where your apps.yaml is stored, replacing the existing apps.yaml file, and modify it from there. Please read Inverter Setup for inverter control software and details of setting apps.yaml for non-GivEnergy inverters Checking your apps.yaml Syntax errors will be highlighted by the Home Assistant editor or via other YAML aware editors such as VSCode. Once you have completed your apps.yaml and started Predbat you may want to open the Predbat Web Interface and click on 'apps.yaml'. Review any items shown in a red background as those do not match (its okay for a 2nd inverter not to match if you only have one configured). Regular expressions that do not match can be ignored if you are not supporting that feature (e.g. Car SOC if you don't have a car). As an example these do not match and are shown in the web interface in red, I'm ignoring them as I only have one inverter and I'm using the Predbat internal Solcast rather than the external integration: Basics Basic configuration items prefix Set to the prefix name to be used for all entities that Predbat creates in Home Assistant. Default 'predbat'. Unlikely that you will need to change this. prefix: predbat timezone Set to your local timezone, default is Europe/London. It must be set to a valid Python time zone for your location timezone: Europe/London currency_symbols Sets your symbol to use for your main currency e.g. \u00a3 or $ and for 1/100th unit e.g. p or c currency_symbols: - '\u00a3' - 'p' template Initially set to True, this is used to stop Predbat from operating until you have finished configuring your apps.yaml. Once you have made all other required changes to apps.yaml this line should be deleted or commented out: template: True Home assistant connection Predbat can speak directly to Home Assistant rather than going via AppDaemon. If you are using a standard add-on then this will be automatic and you do not need to set this. If you run AppDaemon/Predbat in a Docker then you will need to set the URL or IP address of Home Assistant and the access key which is the long lived access token you can create inside Home Assistant. Currently if this communication is not established Predbat will fallback to AppDaemon, however some users have experienced failures due to a 10-second timeout set by AppDaemon. In future versions of Predbat, AppDaemon will be removed. ha_url: 'http://homeassistant.local:8123' ha_key: 'xxxxxxxxxxx' TIP: You can replace homeassistant.local with the IP address of your Home Assistant server if you have it set to a fixed IP address. This will remove the need for a DNS lookup of the IP address every time Predbat talks to Home Assistant and may improve reliability as a result. threads If defined sets the number of threads to use during plan calculation, the default is 'auto' which will use the same number of threads as you have CPUs in your system. Valid values are: 'auto' - Use the same number of threads as your CPU count '0' - Don't use threads - disabled 'N' - Use N threads, recommended values are between 2 and 8 threads: auto notify_devices A list of device names to notify when Predbat sends a notification. The default is just 'notify' which contacts all mobile devices notify_devices: - mobile_app_treforsiphone12_2 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, if you just want Predbat to assume the house load on a particular day is the same as the same day of last week: days_previous: - 7 Or if you want Predbat to take the average of the same day for the last two weeks: days_previous: - 7 - 14 Further details and worked examples of 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: 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: 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: days_previous_weight: - 1 forecast_hours the number of hours that Predbat will forecast ahead, 48 is the suggested amount, although other values can be used such as 30 or 36 if you have a small battery and thus don't need to forecast 2 days ahead. forecast_hours: 48 Inverter information The template apps.yaml comes pre-configured with regular expressions that should auto-discover the GivTCP Home Assistant entity names. If you have more than one inverter or entity names are non-standard then you will need to edit apps.yaml for your inverter entities num_inverters The number of inverters you have. If you increase this above 1 you must provide multiple of each of the inverter entities num_inverters: 1 geserial Only for GE inverters, this is a helper regular expression to find your inverter serial number, if it doesn't work edit it manually or change individual entities to match. If you have more than one inverter you will need one per inverter to be used in the later configuration lines geserial: 're:sensor.givtcp_(.+)_soc_kwh' geserial2: 're:sensor.givtcp2_(.+)_soc_kwh' If you are running GivTCP v3 and have an AIO or a 3 phase inverter then the helper regular expression will not correctly work and you will need to manually set geserial in apps.yaml to your inverter serial number, e.g.: geserial: 'chNNNNgZZZ' TIP: If you have a single GivEnergy AIO, all control is directly to the AIO and the gateway is not required. Check the GivTCP configuration to determine whether inverter 1 (the givtcp sensors) is the AIO or the gateway, or inverter 2 (the givtcp2 sensors) is the AIO or gateway. Then in apps.yaml comment out the lines corresponding to the gateway, leaving just the givtcp or givtcp2 lines for the AIO. Also delete the appropriate givtcp_rest inverter control line corresponding to the gateway so that Predbat controls the AIO directly. TIP2: If you have multiple GivEnergy AIO's, all the AIO's are controlled by the AIO gateway and not controlled individually. geserial should be manually configured to be your AIO gateway serial number 'gwNNNNgZZZ' and all the geserial2 lines should be commented out in apps.yaml. You should also delete the second givtcp_rest inverter control line so that Predbat controls the AIO's via the gateway. GivTCP version 3 is required for multiple AIO's or a 3 phase inverter. Historical data Predbat can either get historical data (house load, import, export and PV generation) directly from GivTCP or it can obtain it from the GivEnergy cloud. Unless you have a specific reason to not use the GivTCP data (e.g. you've lost your GivTCP data), its recommended to use GivTCP. Data from Home Assistant The following configuration entries in apps.yaml are pre-configured to automatically use the appropriate sensors. If you have a 3-phase electricity supply and one inverter (and battery) on each phase then you will need to add one line for the load, import, export and PV sensors for each of the 3 phases. If you have a single phase electricity supply and multiple inverters on the phase then you will need to add one line for each of the load and PV sensors. You don't need multiple lines for the import or export sensors as each inverter will give the total import or export information. Edit if necessary if you have non-standard sensor names: load_today - Entity name for the house load in kWh today (must be incrementing) import_today - Imported energy today in kWh (incrementing) export_today - Exported energy today in kWh (incrementing) pv_today - PV energy today in kWh (incrementing). If you have multiple inverters, enter each inverter PV sensor on a separate line. If you have an AC-coupled inverter then enter the Home Assistant sensor for your PV inverter. If you don't have any PV panels, comment or delete this line out of apps.yaml. See the Workarounds section below for configuration settings for scaling these if required. If you have multiple inverters then you may find that the load_today figures are incorrect as the inverters share the house load between them. In this circumstance one solution is to create a Home Assistant template helper to calculate house load from {pv generation}+{battery discharge}-{battery charge}+{import}-{export}. e.g. {{ ( states('sensor.givtcp_XXX_pv_energy_today_kwh')|float(0) + ... + states('sensor.givtcp_XXX_battery_discharge_energy_today_kwh')|float(0) + ... - states('sensor.givtcp_XXX_battery_charge_energy_today_kwh')|float(0) - ... + states('sensor.givtcp_XXX_import_energy_today_kwh')|float(0) - states('sensor.givtcp_XXX_export_energy_today_kwh')|float(0) ) | round(1) }} GivEnergy Cloud Data If you have an issue with the GivTCP data, Predbat can get the required historical data from the GivEnergy cloud instead. This data is updated every 30 minutes. Obviously connecting to the cloud is less efficient and means that Predbat will be dependent upon your internet connection and the GivEnergy cloud to operate. ge_cloud_data - When True Predbat will use the GE Cloud integration for inverter data rather than GivTCP sensors for load_today, import_today and export_today ge_cloud_serial - Set the inverter serial number to use for the cloud data ge_cloud_key - Set to your API Key for the GE Cloud (long string) Load filtering By default if Predbat sees a gap in the historical load data it will fill it with average data. This is to help in the cases of small amounts of lost data. For entire lost days you should change days_previous to point to different days(s) or include 3 or more days and if you set switch.predbat_load_filter_modal to true, the lowest day's historical load will be discarded. load_filter_threshold - Sets the number of minutes of zero load data to be considered a gap (that's filled with average data), the default is 30. To disable, set it to 1440. iBoost energy iboost_energy_today - Set to a sensor which tracks the amount of energy sent to your solar diverter, can also be used to subtract from your historical load for more accurate predictions. Inverter control configurations inverter_limit - One per inverter. When set defines the maximum AC output power in watts for your inverter or micro-inverters (e.g. 3600). This is used by Predbat in calculating the plan to emulate clipping that occurs in the inverter when your solar produces more than the inverter can handle, but it won't be that accurate as the source of the data isn't minute by minute. If you have a separate Solar inverter as well then add the solar inverter limit to the battery inverter limit to give one total amount. For example, if you have a GivEnergy hybrid inverter you should set export_limit to 3600 or 5000 depending on which size inverter you have. If though you have a GivEnergy All-in-one (6kW AC limit) and a 5kW Solis solar inverter, you should set inverter_limit to 11000 (6000+5000). For multiple All-in-one's, add each of their limits together, plus any separate solar inverter limits. NB: inverter_limit is ONLY used by Predbat to improve the quality of the plan, any solar clipping is done by the inverter and is not controlled by Predbat. export_limit - One per inverter (optional). When set defines the maximum watts of AC power your inverter can export to the grid at (e.g. 2500). This is used by Predbat in calculating the plan to emulate your inverter's software export limit setting that you will have if your G98/G99 approval was lower than your maximum inverter power (check your install information for details). If you do not set an export limit then it's the same as the inverter limit. NB: export_limit is ONLY used by Predbat to improve the quality of the plan, any export limit is done by the inverter and is not controlled by Predbat. inverter_limit_charge and inverter_limit_discharge - One per inverter (optional). When set in Watts, overrides the maximum charge/discharge rate settings used when controlling the inverter. This can be used if you need Predbat to cap your inverter battery rate (e.g. charge overnight at a slower rate to reduce inverter/battery heating) as Predbat will normally configure all timed charges or discharges to be at the inverter's maximum rate. Controlling the Inverter There are a few different ways to control your inverter: Home Assistant entity controls (standard) GivTCP REST Interface (GivEnergy Inverters only) Service API MQTT API Home Assistant entity inverter control Predbat can control inverters by updating Home Assistant entities. The template apps.yaml for is pre-configured with regular expressions for many configuration items, but some of them may need updating to match your system. If you only have a single inverter then the second inverter lines can be commented out if so desired or left in place (as they are ignored). The givtcp_rest line should be commented out/deleted on anything but GivTCP REST mode. charge_rate - Battery charge rate entity in watts discharge_rate - Battery discharge max rate entity in watts battery_power - Current battery power in watts battery_voltage - Current battery voltage (only needed for inverters controlled via amps) battery_rate_max - Sets the maximum battery charge/discharge rate in watts (e.g. 2500) pv_power - Current PV power in watts load_power - Current load power in watts soc_kw - Entity name of the battery SOC in kWh, should be the inverter one not an individual battery soc_max - Entity name for the maximum charge level for the battery battery_min_soc - When set limits the target SOC% setting for charge and discharge to a minimum percentage value reserve - sensor name for the reserve setting in % inverter_reserve_max - When set defines the maximum reserve setting in % (default is 100) inverter_mode - Givenergy inverter mode control inverter_time - Inverter timestamp, used to track the last update of the inverter data charge_start_time - Battery charge start time entity charge_end_time - Battery charge end time entity charge_limit - Entity name for used to set the SOC target for the battery in percentage (AC charge target) scheduled_charge_enable - Scheduled charge enable config scheduled_discharge_enable - Scheduled discharge enable config discharge_start_time - scheduled discharge slot_1 start time discharge_end_time - scheduled discharge slot_1 end time pause_mode - Givenergy pause mode register (if present) pause_start_time - scheduled pause start time (only if supported by your inverter) pause_end_time - scheduled pause start time (only if supported by your inverter) inverter_battery_rate_min - Defines the minimum discharge/charge rate of the battery in watts (default is 0) If you are using REST control the configuration items should still be kept as not all controls work with REST. See section below on creating the battery charge power curve . REST Interface inverter control For GivEnergy inverters Predbat can control the inverter directly via REST instead of via the Home Assistant GivTCP inverter controls detailed above. When configured in apps.yaml, control communication from Predbat to GivTCP is via REST which bypasses some issues with MQTT. givtcp_rest - One entry per Inverter, sets the GivTCP REST API URL ( http://homeassistant.local:6345 is the normal address and port for the first inverter, and the same address but ending :6346 if you have a second inverter - if you don't have a second inverter (or if you have multiple AIO's that are controlled through the gateway), delete the second line. If you are using Docker then change 'homeassistant.local' to the Docker IP address. TIP: You can replace homeassistant.local with the IP address of your Home Assistant server if you have it set to a fixed IP address. This may improve reliability of the REST connection as it doesn't need to lookup the HA server IP address each time. To check your REST is working open up the readData API point in a Web browser e.g: http://homeassistant.local:6345/readData If you get a bunch of inverter information back then it's working! Note that Predbat will still retrieve inverter information via REST, this configuration only applies to how Predbat controls the inverter. Service API Some inverters have the Service API enabled, this allows the configuration to call an arbitrary Home Assistant service to start/stop charging and discharging charge_start_service - Should be set to a service that is called when charging starts charge_freeze_service - If your inverter supports charge freeze set to a service that starts this mode charge_stop_service - Should be set to a service that is called when charging/charge freeze stops discharge_start_service - Should be set to a service that is called when force export (discharge) starts discharge_freeze_service - If your inverter supports export freeze set to a service that starts this mode discharge_stop_service - Should be set to a service that is called when export/export freeze stops Services that are not configuration will not be called. Example service is below: charge_start_service: service: switch.turn_off entity_id: \"switch.sunsynk_inverter_use_timer\" See Service API for details. Note that device_id will be passed to the service automatically, it can be set in apps.yaml. MQTT API Some Inverters are enabled with an MQTT API, in this case certain MQTT messages are send via the HA MQTT service. The mqtt_topic in apps.yaml set in the root of the MQTT topic (shown as topic below). Set reserve Called when the reserve is changed topic: topic /set/reserve payload: reserve Set target soc Called when the target (charge %) SOC is set. topic: topic /set/target_soc payload: soc Set charge rate Called to change the charge rate in Watts topic: topic /set/charge_rate payload: charge_rate Set discharge rate Called to change the discharge rate in Watts topic: topic /set/discharge_rate payload: discharge_rate Set charge Called when a charge is started topic: topic /set/charge payload: charge_rate Set discharge Called when a forced export (discharge) is started topic: topic /set/discharge payload: discharge_rate Set auto Called when a charge/discharge is cancelled and the inverter goes back to home demand mode. topic: topic /set/auto payload: true Solcast Solar Forecast As described in the Predbat installation instructions , Predbat needs a solar forecast in order to predict solar generation and battery charging which can be provided by the Solcast integration. By default the template apps.yaml is pre-configured to use the Solcast forecast integration for Home Assistant. The apps.yaml contains regular expressions for the following configuration items that should auto-discover the Solcast forecast entity names. They are unlikely to need changing although a few people have reported their entity names don't contain 'solcast' so worth checking, or edit if you have non-standard names: pv_forecast_today - Entity name for today's Solcast forecast pv_forecast_tomorrow - Entity name for tomorrow's Solcast's forecast pv_forecast_d3 - Entity name for Solcast's forecast for day 3 pv_forecast_d4 - Entity name for Solcast's forecast for day 4 (also d5, d6 & d7 are supported, but not that useful) If you do not have a PV array then comment out or delete these Solcast lines from apps.yaml . Alternatively, Predbat can obtain the solar forecast directly from Solcast and the Solcast integration is thus not required. Uncomment the following Solcast cloud interface settings in apps.yaml and set the API key correctly: solcast_host: 'https://api.solcast.com.au/' solcast_api_key: 'xxxx' solcast_poll_hours: 8 Note that by default the solcast API will be used to download all sites (up to 2 for hobby accounts), if you want to override this set your sites manually using solcast_sites as an array of site IDs: solcast_sites: - 'xxxx' If you have more than 2 array orientations and thus more than one Solcast API key, enter each key in a list, i.e.: api_key: - xxxx_API_key_1 - yyyy_API_key_2 Keep in mind hobbyist accounts only have 10 polls per day so you need to ensure that the solcast_poll_hours refresh period is set so that you do not exceed the 10 poll limit. If you have two arrays then each Solcast refresh will consume 2 polls. If you use the same Solcast account for other automations the total polls needs to be kept under the limit or you will experience failures. If you have multiple PV arrays connected to hybrid inverters or you have AC-coupled inverters, then ensure your PV configuration in Solcast covers all arrays. If however you have a mixed PV array setup with some PV that does not feed into the inverters that Predbat is managing (e.g. hybrid GE inverters with an older firmware but a separate older FIT array that directly feeds AC into the house), then it's recommended that Solcast is only configured for the PV connected to the inverters that Predbat is managing. NB: Gen2, Gen3 and Gen1 hybrid inverters with the 'fast performance' firmware are able to charge their batteries from excess AC that would be exported, so for these inverters you should configure Solcast with your total solar generation capability. Solcast produces 3 forecasted PV estimates, the 'central' (50% or most likely to occur) PV forecast, the '10%' (1 in 10 more cloud coverage 'worst case') PV forecast, and the '90%' (1 in 10 less cloud coverage 'best case') PV forecast. By default Predbat will use the central (PV50) estimate and applies to it the input_number.predbat_pv_metric10_weight weighting of the 10% (worst case) estimate. You can thus adjust the metric10_weight to be more pessimistic about the solar forecast. 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 over the 30 minute slot 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. If pv_estimate is set to 10 then input_number.predbat_pv_metric10_weight in Home Assistant should be set to 1.0. See also PV configuration options in Home Assistant . Energy Rates 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 and are listed here just for completeness: metric_octopus_import - Import rates from the Octopus Energy integration metric_octopus_export - Export rates from the Octopus Energy integration metric_octopus_gas - Gas rates from the Octopus Energy integration octopus_intelligent_slot - Octopus Intelligent GO slot sensor from the Octopus Energy integration octopus_saving_session - Energy saving sessions sensor from the Octopus Energy integration octopus_saving_session_octopoints_per_penny - Sets the Octopoints per pence rates_import_octopus_url - Octopus pricing URL (over-rides metric_octopus_import) rates_export_octopus_url - Octopus export pricing URL (over-rides metric_octopus_export) metric_standing_charge - Standing charge in pounds rates_import - Import rates over a 24-hour period with start and end times rates_export - Export rates over a 24-hour period with start and end times rates_gas - Gas rates over a 24-hour period with start and end times rates_import_override - Over-ride import rate for specific date and time range, e.g. Octopus Power-up events rates_export_override - Over-ride export rate for specific date and time range futurerate_url - URL of future energy market prices for Agile users futurerate_adjust_import and futurerate_adjust_export - Whether tomorrow's predicted import or export prices should be adjusted based on market prices or not futurerate_peak_start and futurerate_peak_end - start/end times for peak-rate adjustment carbon_intensity - Carbon intensity of the grid in half hour slots from an integration. Car Charging Integration Predbat is able to include electric vehicle charging in its plan and manage the battery activity so that the battery isn't discharged into your car when the car is charging (although you can over-ride this if you wish by setting the switch.predbat_car_charging_from_battery to True in Home Assistant). There are two different ways of planning car charging into cheap slots with Predbat, either by the Octopus Energy integration or by Predbat identifying the cheapest slots. These approaches and the set of settings that need to be configured together are described in Car Charging . The full list of car charging configuration items in apps.yaml that are used to plan car charging activity within Predbat are described below. The Home Assistant controls (switches, input numbers, selectors, etc) related to car charging are described in Car Charging configuration within Home Assistant , with brief mention of pertinent controls included here alongside the apps.yaml configuration items where relevant for context. num_cars should be set in apps.yaml to the number of cars you want Predbat to plan for. Set to 0 if you don't have an EV (and the remaining car sensors in apps.yaml can safely be commented out or deleted as they won't be required). NB: num_cars must be set correctly regardless of whether you are using Octopus Intelligent Go to control your EV charging or Predbat to control the charging; or else Predbat could start discharging your battery when the EV is charging. car_charging_exclusive should be set to True for each car in apps.yaml if you have multiple cars configured in Predbat, but only one car charger. This indicates that only one car may charge at once (the first car reporting as plugged in will be considered as charging). If you set this to False for each car then it is assumed that the car can charge independently, and hence two or more cars could charge at once. One entry per car. car_charging_exclusive: - True - True Car Charging Filtering 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.predbat_car_charging_hold - A Home Assistant switch that when turned on (True) tells Predbat to remove car charging data from your historical house load so that Predbat's battery prediction plan is not distorted by previous car charging. 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 that should auto-detect the appropriate Wallbox and Zappi car charger sensors, or edit as necessary in apps.yaml for your charger sensor. This can be set to a list of car charging energy sensors, one per line if you have multiple EV car chargers. TIP: 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.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 sensor data by if required (e.g. set to 0.001 to convert Watts to kW). If you do not have a suitable car charging energy 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.predbat_car_charging_threshold (default 6 = 6kW)- Sets the kW power threshold above which home consumption is assumed to be car charging and input_number.predbat_car_charging_rate will be subtracted from the historical load data. Planned Car Charging These features allow Predbat to know when you plan to charge your car. If you have Intelligent Octopus tariff then planning of charging is done via the Octopus app and Predbat obtains this information through the Octopus Energy integration in Home Assistant. switch.predbat_octopus_intelligent_charging - When this Home Assistant switch is enabled, Predbat will plan charging around the Intelligent Octopus slots, taking it into account for battery load and generating the slot information The following apps.yaml configuration items are pre-defined with regular expressions to point to appropriate sensors in the Octopus Energy integration. You should not normally need to change these if you have the Octopus Intelligent tariff: octopus_intelligent_slot - Points to the Octopus Energy integration 'intelligent dispatching' sensor that indicates whether you are within an Octopus Energy \"smart charge\" slot, and provides the list of future planned charging activity. octopus_ready_time - Points to the Octopus Energy integration sensor that details when the car charging will be completed by. octopus_charge_limit - Points to the Octopus Energy integration sensor that provides the car charging limit. octopus_slot_low_rate - Default is True, meaning any Octopus Intelligent Slot reported will be at the lowest rate if at home. If False the existing rates only will be used which is only suitable for tariff's other than IOG. If you don't use Intelligent Octopus then the above 3 Octopus Intelligent configuration lines in apps.yaml can be commented out or deleted, and there are a number of other apps.yaml configuration items that should be set: car_charging_planned - Optional, can be set to a Home Assistant sensor (e.g. from your car charger integration) which lets Predbat know the car is plugged in and planned to charge during low rate slots. Or manually set it to 'False' to disable this feature, or 'True' to always enable. The apps.yaml template supplied with Predbat comes pre-configured with a regular expression that should automatically match Zappi or Wallbox car chargers. If you have a different type of charger you will need to configure it manually. car_charging_planned_response - An array of values for the above car_charging_planned sensor which indicate that the car is plugged in and will charge in the next low rate slot. The template apps.yaml comes with a set of pre-defined sensor values that should match most EV chargers. Customise for your car charger sensor if it sets sensor values that are not in the list. car_charging_now - For some cases finding details of planned car charging is difficult to obtain. The car_charging_now configuration item can be set to point to a Home Assistant sensor that tells you that the car is currently charging. Predbat will then assume this 30 minute slot is used for charging regardless of the plan. If Octopus Intelligent Charging is enabled and car_charging_now indicates the car is charging then Predbat will also assume that this is a low rate slot for the car/house (and might therefore start charging the battery), otherwise electricity import rates are taken from the normal rate data. CAUTION: Do not use car_charging_now with Predbat led charging or you will create an infinite loop. Do you use car_charging_now with Octopus intelligent unless you can't make it work any other way as it will assume all car charging is at low rate. car_charging_now_response - Set to the range of positive responses for car_charging_now to indicate that the car is charging. Useful if you have a sensor for your car charger that isn't binary. To make planned car charging more accurate, configure the following items in apps.yaml : car_charging_battery_size - Set this value in apps.yaml to the car's battery size in kWh. If not set, Predbat defaults to 100kWh. It will be used to predict when to stop car charging. car_charging_limit - You should configure this to point to a sensor that specifies the % limit the car is set to charge to. This could be a sensor on the EV charger integration or a Home Assistant helper entity you can set as you wish. If you don't specify a sensor Predbat will default to 100% - i.e. fill the car to full. car_charging_soc - You should configure this to point to a sensor (on the HA integration for your EV charger) that specifies the car's current charge level expressed as a percentage - it must NOT be set to a sensor that gives the car's current kWh value as this will cause Predbat to charge the car to an incorrect level. If you don't specify a sensor, Predbat will default to 0%. Multiple Electric Cars Multiple cars can be planned with Predbat, in which case you should set num_cars in apps.yaml to the number of cars you want to plan car_charging_limit , car_charging_planned , car_charging_battery_size and car_charging_soc must then be a list of values (i.e. 2 entries for 2 cars) If you have Intelligent Octopus then Car 0 will be managed by the Octopus Energy integration, if its enabled Each car will have it's own Home Assistant slot sensor created e.g. binary_sensor.predbat_car_charging_slot_1 , SoC planning sensor e.g predbat.car_soc_1 and predbat.car_soc_best_1 for car 1 Load Forecast In addition to the historical house load data that Predbat uses by default, you can optionally provide a forecast of future load such as is produced by Predheat for Hot water and Heat Pump heating systems or via Predai load_forecast - this should be configured to point to a sensor and attribute. The attribute must in either The format of 'last_updated' timestamp and 'energy' in incrementing kWh. The format of a dictionary of timestamps and energy data in incremental KWh. For example: Or apps.yaml should be configured to point to the forecast sensor and attribute (in the above formats) like this: load_forecast: - sensor_name$attribute_name So if using Predheat it would be configured as: load_forecast: - predheat.heat_energy$external Set load_forecast_only to True if you do not wish to use the Predbat forecast but instead want to use this as your only forecast data e.g using PredAi: load_forecast_only: True load_forecast: - sensor.givtcp_{geserial}_load_energy_today_kwh_prediction$results Balance Inverters When you have two or more inverters it's possible they get out of sync so they are at different charge levels or they start to cross-charge (one discharges into another). When enabled, balance inverters tries to recover this situation by disabling either charging or discharging from one of the batteries until they re-align. Most of the Predbat configuration for balancing inverters is through a number of Home Assistant controls for Balancing Inverters , but there is one configuration item in apps.yaml : balance_inverters_seconds: seconds Defines how often to run the inverter balancing, 30 seconds is recommended if your machine is fast enough, but the default is 60 seconds. Workarounds There are a number of different configuration items in apps.yaml that can be used to tweak the way Predbat operates and workaround weirdness you may have from your inverter and battery setup. Clock skew clock_skew: minutes Skews the local (computer) time that Predbat uses (from the computer that Predbat is running on). Set to 1 means add a minute to the Predbat computer time, set to -1 means take a minute off the Predbat computer time. This clock adjustment will be used by Predbat when real-time actions happen e.g. triggering a charge or discharge. If your inverter's time is different to the time on the computer running Home Assistant, you may need to skew the time settings made on the inverter when you trigger charging or discharging. Again 1 means the inverter is 1 minute fast and -1 means the inverter is 1 minute slow. Separate start and end options are applied to the start and end time windows, mostly as you want to start battery activity late (not early) and finish early (not late). You can adjust the charge and discharge times written to the inverter by setting the following in apps.yaml : inverter_clock_skew_start: minutes inverter_clock_skew_end: minutes Skews the setting of the charge slot registers vs the predicted start time inverter_clock_skew_discharge_start: minutes inverter_clock_skew_discharge_end: minutes Skews the setting of the discharge slot registers vs the predicted start time Battery size scaling battery_scaling: - scale Default value 1.0. Multiple battery size scales can be entered, one per inverter on separate lines. This setting is used to scale the battery reported SoC kWh to make it appear bigger or larger than it is. As the GivEnergy inverters treat all batteries attached to an inverter as in effect one giant battery, if you have multiple batteries on an inverter that need scaling you should enter a composite scaling value for all batteries attached to the inverter. TIP: If you have a GivEnergy 2.6 or 5.2kWh battery then it will have an 80% depth of discharge but it will falsely report its capacity as being the 100% size, so set battery_scaling to 0.8 to report the correct usable capacity figure to Predbat. TIP: Likewise, if you have one or multiple GivEnergy All in One (AIO)'s, it will incorrectly report the 13.5kWh usable capacity of each AIO as 15.9kWh, so set battery_scaling to 0.85 to correct this. If you are going chart your battery SoC in Home Assistant then you may want to use predbat.soc_kw_h0 as your current SoC rather than the usual givtcp_SERIAL_NUMBER_soc GivTCP entity so everything lines up. Import export scaling import_export_scaling: scale Default value 1.0. Used to scale the import & export kWh data from GivTCP if the inverter information is incorrect. Inverter rate minimum inverter_battery_rate_min: watts One per inverter (optional), set in Watts, when set models a \"bug\" in the inverter firmware in some models where if charge or discharge rates are set to 0 you actually get a small amount of charge or discharge. Recommended setting is 200 for Gen 1 hybrids with this issue. Inverter reserve maximum inverter_reserve_max: percent Global, sets the maximum reserve % that may be set to the inverter, the default is 98, as some Gen 2 & Gen 3 inverters and AIO firmware versions refuse to be set to 100. Comment the line out or set to 100 if your inverter allows setting to 100%. Automatic restarts If the add-on that is providing the inverter control stops functioning it can prevent Predbat from functioning correctly. In this case you can tell Predbat how to restart the add-on using a service. Right now only communication loss with GE inverters is detectable but in future other systems will be supported. When enabled if communication is lost then the service configured will be triggered and can cause a restart which may restart the connection. This maybe useful with GivTCP if you have time sync errors or lose the REST service every now and again. The auto_restart itself is a list of commands to run to trigger a restart. The shell command will call a 'sh' shell and can be used to delete files and suchlike. The service command is used to call a service, and can contain arguments of addon and/or entity_id . The configuration below is for GivTCP v3. auto_restart: - shell: 'rm -rf /homeassistant/GivTCP/*.pkl' - service: hassio/addon_restart addon: 533ea71a_givtcp NB: If you are running GivTCP v2 then the line '533ea71a_givtcp' must be replaced with 'a6a2857d_givtcp' as the slug-id (Home Assistant add-on identifier) is different between GivTCP v2 and v3. Battery charge/discharge curves Some batteries tail off their charge rate at high SoC% or their discharge rate at low SoC%, and these optional configuration items enables you to model this tail-off in Predbat. Note that the charge/discharge curves only affect the accuracy of the charging/discharging model Predbat applies in the forward battery plan, Predbat will still instruct the inverter to charge/discharge at full rate regardless of the charging curve. If you know the battery charge or discharge curves (e.g. manufacturer info or your own testing) then you can manually configure this in apps.yaml, or Predbat can calculate the curves based upon historical inverter charging/discharging data in Home Assistant. If the battery has not recently been fully charged or fully discharged then Predbat will not be able to calculate the curves and you'll get a warning in the logfile. battery_charge_power_curve - This optional configuration item enables you to model in Predbat a tail off in charging at high SoC%. Enter the charging curve as a series of steps of % of max charge rate for each SoC percentage. 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. 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 ). If the battery_charge_power_curve option is not set in apps.yaml and Predbat performs an initial run (e.g. due to restarting the Predbat/AppDaemon add-on, or an edit being made to apps.yaml), then Predbat will automatically calculate the charging curve for you from historical battery charging information. You should look at the Predbat logfile to find the predicted battery charging curve and copy/paste it into your apps.yaml file. The logfile will also include a recommendation for how to set your battery_rate_max_scaling setting in HA. The YouTube video charging curve and low power charging explains how the curve works and shows how Predbat automatically creates it. 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 configure the charge curve in apps.yaml. 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. These must be configured in apps.yaml to point to Home Assistant entities that have appropriate history data for your inverter/battery. If you have a GivEnergy inverter and are using the recommended default REST mode to control your inverter then you will need to uncomment out the following entries in apps.yaml : charge_rate: - number.givtcp_{geserial}_battery_charge_rate battery_power: - sensor.givtcp_{geserial}_battery_power soc_kw: - sensor.givtcp_{geserial}_soc_kwh Example charging curve from a GivEnergy 9.5kWh battery with latest firmware and Gen 1 inverter: battery_charge_power_curve: 91 : 0.91 92 : 0.81 93 : 0.71 94 : 0.62 95 : 0.52 96 : 0.43 97 : 0.33 98 : 0.24 99 : 0.24 100 : 0.24 battery_discharge_power_curve - This optional configuration item enables you to model in Predbat a tail off in discharging at low SoC%. Enter the discharging curve as a series of steps of % of max discharge rate for each SoC percentage. The default is 1.0 (full power) discharge all the way to 0%. If the battery_discharge_power_curve option is not set in apps.yaml and Predbat performs an initial run (e.g. due to restarting the Predbat/AppDaemon add-on, or an edit being made to apps.yaml), then Predbat will automatically calculate the discharging curve for you from historical battery discharging information. You should look at the Predbat logfile to find the predicted battery discharging curve and copy/paste it into your apps.yaml file. Setting This option to auto will cause the computed curve to be stored and used automatically. This may not work very well if you don't do regular discharges to empty the battery. In the same way as for the battery charge curve above, Predbat needs to have access to historical Home Assistant data for battery_discharge_rate, battery_power and soc_kw. These must be configured in apps.yaml to point to Home Assistant entities that have appropriate history data for your inverter/battery. If you are using REST mode to control your GivEnergy inverter then the following entries in apps.yaml will need to be uncommented : discharge_rate: - number.givtcp_{geserial}_battery_discharge_rate battery_power: - sensor.givtcp_{geserial}_battery_power soc_kw: - sensor.givtcp_{geserial}_soc_kwh Triggers export_triggers - The export trigger feature is useful to help trigger your own automations based on Predbat predicting in the plan that you will have spare solar energy that would be exported - this could happen if the battery is full or there is more predicted solar generation than can be charged into the battery. You can use the trigger in an automation, for example you could turn on an immersion heater or the washing machine to consume the excess solar power. The triggers count export energy until the next active charge slot only. For each trigger give a name, the minutes of export needed, and the energy required in that time. Multiple triggers can be enabled by Predbat at once so in total you could use too much energy if multiple triggered automations all run. Each trigger specified in apps.yaml will create a Home Assistant entity called 'binary_sensor.predbat_export_trigger_ name ' which will be turned on when the predicted trigger conditions are valid. Connect this binary sensor to your automation to start whatever you want to trigger. Set the name for each trigger, the number of minutes of solar export you need, and the amount of energy in kWh you will need available during that time period in apps.yaml: For example: export_triggers: - name: \"large\" minutes: 60 energy: 1.0 - name: \"small\" minutes: 15 energy: 0.25 Note: Predbat will set an export trigger to True if in the plan it predicts that there will be more than the specified amount of excess solar energy over the specified time period. In the example above, the 'large' trigger will be set to True for the 1 hour period where Predbat predicts that there will be a total of 1kWh of excess solar generation over that time period . For clarity the trigger is not set based on actual excess solar generation or export. It should also be recognised that this prediction could be wrong; there could be less solar generation or more house load than was predicted in the plan. If you wish to trigger activities based on Predbat charging or discharging the battery rather than spare solar energy you can instead use the following binary sensors in Home Assistant: binary_sensor.predbat_charging - Will be True when the home battery is inside a charge slot (either being charged or being held at a level). Note that this does include charge freeze slots where the discharge rate is set to zero without charging the battery. binary_sensor.predbat_exporting - 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: 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: 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: 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: days_previous: - 2 - 3 - 4 - 5 - 6 - 7 - 8","title":"apps.yaml settings"},{"location":"apps-yaml/#appsyaml-settings","text":"The basic Predbat configuration is defined in the apps.yaml file. Depending on how you installed Predbat the apps.yaml file will be held in one of three different directories in Home Assistant: if you have used the Predbat add-on installation method , apps.yaml will be in the directory /addon_configs/6adb4f0d_predbat , with the HACS, Appdaemon add-on then Predbat installation method , it's in /config/appdaemon/apps/batpred/config/ , or if the combined AppDaemon/Predbat add-on installation method was used, it's in /addon_configs/46f69597_appdaemon-predbat/apps . 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 edit the apps.yaml file - see editing configuration files within Home Assistant if you need to install an editor. This section of the documentation describes what the different configuration items in apps.yaml do. When you edit apps.yaml , the change will automatically be detected and Predbat will be reloaded with the updated file. You don't need to restart the Predbat or AppDaemon add-on for your edits to take effect.","title":"apps.yaml settings"},{"location":"apps-yaml/#warning-appsyaml-file-format","text":"When editing the apps.yaml file you must ensure that the file remains correctly formatted. YAML files are especially finicky about how the file contents are indented and its very easy to end up with an incorrectly formatted file that will cause problems for Predbat. The YAML Basics from This Smart Home is a good introduction video to how YAML should be correctly structured, but as a brief introduction, YAML files consist of an entity name, colon then the entity value, for example: timezone: Europe/London Or the entity can be set to a list of values with each value being on a new line, two spaces, a dash, then the value. For example: car_charging_now_response: - 'yes' - 'on' The two spaces before the dash are especially critical. Its easy to mis-edit and have one or three spaces which isn't valid YAML. NB: the sequence of entries in apps.yaml doesn't matter, as long as the YAML itself is structured correctly you can move things and edit things anywhere in the file.","title":"Warning! apps.yaml file format"},{"location":"apps-yaml/#templates","text":"You can find template configurations in the following location: https://github.com/springfall2008/batpred/tree/main/templates The GivEnergy GivTCP template will be installed by default but if you are using another inverter please copy the correct template into the directory where your apps.yaml is stored, replacing the existing apps.yaml file, and modify it from there. Please read Inverter Setup for inverter control software and details of setting apps.yaml for non-GivEnergy inverters","title":"Templates"},{"location":"apps-yaml/#checking-your-appsyaml","text":"Syntax errors will be highlighted by the Home Assistant editor or via other YAML aware editors such as VSCode. Once you have completed your apps.yaml and started Predbat you may want to open the Predbat Web Interface and click on 'apps.yaml'. Review any items shown in a red background as those do not match (its okay for a 2nd inverter not to match if you only have one configured). Regular expressions that do not match can be ignored if you are not supporting that feature (e.g. Car SOC if you don't have a car). As an example these do not match and are shown in the web interface in red, I'm ignoring them as I only have one inverter and I'm using the Predbat internal Solcast rather than the external integration:","title":"Checking your apps.yaml"},{"location":"apps-yaml/#basics","text":"Basic configuration items","title":"Basics"},{"location":"apps-yaml/#prefix","text":"Set to the prefix name to be used for all entities that Predbat creates in Home Assistant. Default 'predbat'. Unlikely that you will need to change this. prefix: predbat","title":"prefix"},{"location":"apps-yaml/#timezone","text":"Set to your local timezone, default is Europe/London. It must be set to a valid Python time zone for your location timezone: Europe/London","title":"timezone"},{"location":"apps-yaml/#currency_symbols","text":"Sets your symbol to use for your main currency e.g. \u00a3 or $ and for 1/100th unit e.g. p or c currency_symbols: - '\u00a3' - 'p'","title":"currency_symbols"},{"location":"apps-yaml/#template","text":"Initially set to True, this is used to stop Predbat from operating until you have finished configuring your apps.yaml. Once you have made all other required changes to apps.yaml this line should be deleted or commented out: template: True","title":"template"},{"location":"apps-yaml/#home-assistant-connection","text":"Predbat can speak directly to Home Assistant rather than going via AppDaemon. If you are using a standard add-on then this will be automatic and you do not need to set this. If you run AppDaemon/Predbat in a Docker then you will need to set the URL or IP address of Home Assistant and the access key which is the long lived access token you can create inside Home Assistant. Currently if this communication is not established Predbat will fallback to AppDaemon, however some users have experienced failures due to a 10-second timeout set by AppDaemon. In future versions of Predbat, AppDaemon will be removed. ha_url: 'http://homeassistant.local:8123' ha_key: 'xxxxxxxxxxx' TIP: You can replace homeassistant.local with the IP address of your Home Assistant server if you have it set to a fixed IP address. This will remove the need for a DNS lookup of the IP address every time Predbat talks to Home Assistant and may improve reliability as a result.","title":"Home assistant connection"},{"location":"apps-yaml/#threads","text":"If defined sets the number of threads to use during plan calculation, the default is 'auto' which will use the same number of threads as you have CPUs in your system. Valid values are: 'auto' - Use the same number of threads as your CPU count '0' - Don't use threads - disabled 'N' - Use N threads, recommended values are between 2 and 8 threads: auto","title":"threads"},{"location":"apps-yaml/#notify_devices","text":"A list of device names to notify when Predbat sends a notification. The default is just 'notify' which contacts all mobile devices notify_devices: - mobile_app_treforsiphone12_2","title":"notify_devices"},{"location":"apps-yaml/#days_previous","text":"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, if you just want Predbat to assume the house load on a particular day is the same as the same day of last week: days_previous: - 7 Or if you want Predbat to take the average of the same day for the last two weeks: days_previous: - 7 - 14 Further details and worked examples of 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: 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: 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: days_previous_weight: - 1","title":"days_previous"},{"location":"apps-yaml/#forecast_hours","text":"the number of hours that Predbat will forecast ahead, 48 is the suggested amount, although other values can be used such as 30 or 36 if you have a small battery and thus don't need to forecast 2 days ahead. forecast_hours: 48","title":"forecast_hours"},{"location":"apps-yaml/#inverter-information","text":"The template apps.yaml comes pre-configured with regular expressions that should auto-discover the GivTCP Home Assistant entity names. If you have more than one inverter or entity names are non-standard then you will need to edit apps.yaml for your inverter entities","title":"Inverter information"},{"location":"apps-yaml/#num_inverters","text":"The number of inverters you have. If you increase this above 1 you must provide multiple of each of the inverter entities num_inverters: 1","title":"num_inverters"},{"location":"apps-yaml/#geserial","text":"Only for GE inverters, this is a helper regular expression to find your inverter serial number, if it doesn't work edit it manually or change individual entities to match. If you have more than one inverter you will need one per inverter to be used in the later configuration lines geserial: 're:sensor.givtcp_(.+)_soc_kwh' geserial2: 're:sensor.givtcp2_(.+)_soc_kwh' If you are running GivTCP v3 and have an AIO or a 3 phase inverter then the helper regular expression will not correctly work and you will need to manually set geserial in apps.yaml to your inverter serial number, e.g.: geserial: 'chNNNNgZZZ' TIP: If you have a single GivEnergy AIO, all control is directly to the AIO and the gateway is not required. Check the GivTCP configuration to determine whether inverter 1 (the givtcp sensors) is the AIO or the gateway, or inverter 2 (the givtcp2 sensors) is the AIO or gateway. Then in apps.yaml comment out the lines corresponding to the gateway, leaving just the givtcp or givtcp2 lines for the AIO. Also delete the appropriate givtcp_rest inverter control line corresponding to the gateway so that Predbat controls the AIO directly. TIP2: If you have multiple GivEnergy AIO's, all the AIO's are controlled by the AIO gateway and not controlled individually. geserial should be manually configured to be your AIO gateway serial number 'gwNNNNgZZZ' and all the geserial2 lines should be commented out in apps.yaml. You should also delete the second givtcp_rest inverter control line so that Predbat controls the AIO's via the gateway. GivTCP version 3 is required for multiple AIO's or a 3 phase inverter.","title":"geserial"},{"location":"apps-yaml/#historical-data","text":"Predbat can either get historical data (house load, import, export and PV generation) directly from GivTCP or it can obtain it from the GivEnergy cloud. Unless you have a specific reason to not use the GivTCP data (e.g. you've lost your GivTCP data), its recommended to use GivTCP.","title":"Historical data"},{"location":"apps-yaml/#data-from-home-assistant","text":"The following configuration entries in apps.yaml are pre-configured to automatically use the appropriate sensors. If you have a 3-phase electricity supply and one inverter (and battery) on each phase then you will need to add one line for the load, import, export and PV sensors for each of the 3 phases. If you have a single phase electricity supply and multiple inverters on the phase then you will need to add one line for each of the load and PV sensors. You don't need multiple lines for the import or export sensors as each inverter will give the total import or export information. Edit if necessary if you have non-standard sensor names: load_today - Entity name for the house load in kWh today (must be incrementing) import_today - Imported energy today in kWh (incrementing) export_today - Exported energy today in kWh (incrementing) pv_today - PV energy today in kWh (incrementing). If you have multiple inverters, enter each inverter PV sensor on a separate line. If you have an AC-coupled inverter then enter the Home Assistant sensor for your PV inverter. If you don't have any PV panels, comment or delete this line out of apps.yaml. See the Workarounds section below for configuration settings for scaling these if required. If you have multiple inverters then you may find that the load_today figures are incorrect as the inverters share the house load between them. In this circumstance one solution is to create a Home Assistant template helper to calculate house load from {pv generation}+{battery discharge}-{battery charge}+{import}-{export}. e.g. {{ ( states('sensor.givtcp_XXX_pv_energy_today_kwh')|float(0) + ... + states('sensor.givtcp_XXX_battery_discharge_energy_today_kwh')|float(0) + ... - states('sensor.givtcp_XXX_battery_charge_energy_today_kwh')|float(0) - ... + states('sensor.givtcp_XXX_import_energy_today_kwh')|float(0) - states('sensor.givtcp_XXX_export_energy_today_kwh')|float(0) ) | round(1) }}","title":"Data from Home Assistant"},{"location":"apps-yaml/#givenergy-cloud-data","text":"If you have an issue with the GivTCP data, Predbat can get the required historical data from the GivEnergy cloud instead. This data is updated every 30 minutes. Obviously connecting to the cloud is less efficient and means that Predbat will be dependent upon your internet connection and the GivEnergy cloud to operate. ge_cloud_data - When True Predbat will use the GE Cloud integration for inverter data rather than GivTCP sensors for load_today, import_today and export_today ge_cloud_serial - Set the inverter serial number to use for the cloud data ge_cloud_key - Set to your API Key for the GE Cloud (long string)","title":"GivEnergy Cloud Data"},{"location":"apps-yaml/#load-filtering","text":"By default if Predbat sees a gap in the historical load data it will fill it with average data. This is to help in the cases of small amounts of lost data. For entire lost days you should change days_previous to point to different days(s) or include 3 or more days and if you set switch.predbat_load_filter_modal to true, the lowest day's historical load will be discarded. load_filter_threshold - Sets the number of minutes of zero load data to be considered a gap (that's filled with average data), the default is 30. To disable, set it to 1440.","title":"Load filtering"},{"location":"apps-yaml/#iboost-energy","text":"iboost_energy_today - Set to a sensor which tracks the amount of energy sent to your solar diverter, can also be used to subtract from your historical load for more accurate predictions.","title":"iBoost energy"},{"location":"apps-yaml/#inverter-control-configurations","text":"inverter_limit - One per inverter. When set defines the maximum AC output power in watts for your inverter or micro-inverters (e.g. 3600). This is used by Predbat in calculating the plan to emulate clipping that occurs in the inverter when your solar produces more than the inverter can handle, but it won't be that accurate as the source of the data isn't minute by minute. If you have a separate Solar inverter as well then add the solar inverter limit to the battery inverter limit to give one total amount. For example, if you have a GivEnergy hybrid inverter you should set export_limit to 3600 or 5000 depending on which size inverter you have. If though you have a GivEnergy All-in-one (6kW AC limit) and a 5kW Solis solar inverter, you should set inverter_limit to 11000 (6000+5000). For multiple All-in-one's, add each of their limits together, plus any separate solar inverter limits. NB: inverter_limit is ONLY used by Predbat to improve the quality of the plan, any solar clipping is done by the inverter and is not controlled by Predbat. export_limit - One per inverter (optional). When set defines the maximum watts of AC power your inverter can export to the grid at (e.g. 2500). This is used by Predbat in calculating the plan to emulate your inverter's software export limit setting that you will have if your G98/G99 approval was lower than your maximum inverter power (check your install information for details). If you do not set an export limit then it's the same as the inverter limit. NB: export_limit is ONLY used by Predbat to improve the quality of the plan, any export limit is done by the inverter and is not controlled by Predbat. inverter_limit_charge and inverter_limit_discharge - One per inverter (optional). When set in Watts, overrides the maximum charge/discharge rate settings used when controlling the inverter. This can be used if you need Predbat to cap your inverter battery rate (e.g. charge overnight at a slower rate to reduce inverter/battery heating) as Predbat will normally configure all timed charges or discharges to be at the inverter's maximum rate.","title":"Inverter control configurations"},{"location":"apps-yaml/#controlling-the-inverter","text":"There are a few different ways to control your inverter: Home Assistant entity controls (standard) GivTCP REST Interface (GivEnergy Inverters only) Service API MQTT API","title":"Controlling the Inverter"},{"location":"apps-yaml/#home-assistant-entity-inverter-control","text":"Predbat can control inverters by updating Home Assistant entities. The template apps.yaml for is pre-configured with regular expressions for many configuration items, but some of them may need updating to match your system. If you only have a single inverter then the second inverter lines can be commented out if so desired or left in place (as they are ignored). The givtcp_rest line should be commented out/deleted on anything but GivTCP REST mode. charge_rate - Battery charge rate entity in watts discharge_rate - Battery discharge max rate entity in watts battery_power - Current battery power in watts battery_voltage - Current battery voltage (only needed for inverters controlled via amps) battery_rate_max - Sets the maximum battery charge/discharge rate in watts (e.g. 2500) pv_power - Current PV power in watts load_power - Current load power in watts soc_kw - Entity name of the battery SOC in kWh, should be the inverter one not an individual battery soc_max - Entity name for the maximum charge level for the battery battery_min_soc - When set limits the target SOC% setting for charge and discharge to a minimum percentage value reserve - sensor name for the reserve setting in % inverter_reserve_max - When set defines the maximum reserve setting in % (default is 100) inverter_mode - Givenergy inverter mode control inverter_time - Inverter timestamp, used to track the last update of the inverter data charge_start_time - Battery charge start time entity charge_end_time - Battery charge end time entity charge_limit - Entity name for used to set the SOC target for the battery in percentage (AC charge target) scheduled_charge_enable - Scheduled charge enable config scheduled_discharge_enable - Scheduled discharge enable config discharge_start_time - scheduled discharge slot_1 start time discharge_end_time - scheduled discharge slot_1 end time pause_mode - Givenergy pause mode register (if present) pause_start_time - scheduled pause start time (only if supported by your inverter) pause_end_time - scheduled pause start time (only if supported by your inverter) inverter_battery_rate_min - Defines the minimum discharge/charge rate of the battery in watts (default is 0) If you are using REST control the configuration items should still be kept as not all controls work with REST. See section below on creating the battery charge power curve .","title":"Home Assistant entity inverter control"},{"location":"apps-yaml/#rest-interface-inverter-control","text":"For GivEnergy inverters Predbat can control the inverter directly via REST instead of via the Home Assistant GivTCP inverter controls detailed above. When configured in apps.yaml, control communication from Predbat to GivTCP is via REST which bypasses some issues with MQTT. givtcp_rest - One entry per Inverter, sets the GivTCP REST API URL ( http://homeassistant.local:6345 is the normal address and port for the first inverter, and the same address but ending :6346 if you have a second inverter - if you don't have a second inverter (or if you have multiple AIO's that are controlled through the gateway), delete the second line. If you are using Docker then change 'homeassistant.local' to the Docker IP address. TIP: You can replace homeassistant.local with the IP address of your Home Assistant server if you have it set to a fixed IP address. This may improve reliability of the REST connection as it doesn't need to lookup the HA server IP address each time. To check your REST is working open up the readData API point in a Web browser e.g: http://homeassistant.local:6345/readData If you get a bunch of inverter information back then it's working! Note that Predbat will still retrieve inverter information via REST, this configuration only applies to how Predbat controls the inverter.","title":"REST Interface inverter control"},{"location":"apps-yaml/#service-api","text":"Some inverters have the Service API enabled, this allows the configuration to call an arbitrary Home Assistant service to start/stop charging and discharging charge_start_service - Should be set to a service that is called when charging starts charge_freeze_service - If your inverter supports charge freeze set to a service that starts this mode charge_stop_service - Should be set to a service that is called when charging/charge freeze stops discharge_start_service - Should be set to a service that is called when force export (discharge) starts discharge_freeze_service - If your inverter supports export freeze set to a service that starts this mode discharge_stop_service - Should be set to a service that is called when export/export freeze stops Services that are not configuration will not be called. Example service is below: charge_start_service: service: switch.turn_off entity_id: \"switch.sunsynk_inverter_use_timer\" See Service API for details. Note that device_id will be passed to the service automatically, it can be set in apps.yaml.","title":"Service API"},{"location":"apps-yaml/#mqtt-api","text":"Some Inverters are enabled with an MQTT API, in this case certain MQTT messages are send via the HA MQTT service. The mqtt_topic in apps.yaml set in the root of the MQTT topic (shown as topic below).","title":"MQTT API"},{"location":"apps-yaml/#set-reserve","text":"Called when the reserve is changed topic: topic /set/reserve payload: reserve","title":"Set reserve"},{"location":"apps-yaml/#set-target-soc","text":"Called when the target (charge %) SOC is set. topic: topic /set/target_soc payload: soc","title":"Set target soc"},{"location":"apps-yaml/#set-charge-rate","text":"Called to change the charge rate in Watts topic: topic /set/charge_rate payload: charge_rate","title":"Set charge rate"},{"location":"apps-yaml/#set-discharge-rate","text":"Called to change the discharge rate in Watts topic: topic /set/discharge_rate payload: discharge_rate","title":"Set discharge rate"},{"location":"apps-yaml/#set-charge","text":"Called when a charge is started topic: topic /set/charge payload: charge_rate","title":"Set charge"},{"location":"apps-yaml/#set-discharge","text":"Called when a forced export (discharge) is started topic: topic /set/discharge payload: discharge_rate","title":"Set discharge"},{"location":"apps-yaml/#set-auto","text":"Called when a charge/discharge is cancelled and the inverter goes back to home demand mode. topic: topic /set/auto payload: true","title":"Set auto"},{"location":"apps-yaml/#solcast-solar-forecast","text":"As described in the Predbat installation instructions , Predbat needs a solar forecast in order to predict solar generation and battery charging which can be provided by the Solcast integration. By default the template apps.yaml is pre-configured to use the Solcast forecast integration for Home Assistant. The apps.yaml contains regular expressions for the following configuration items that should auto-discover the Solcast forecast entity names. They are unlikely to need changing although a few people have reported their entity names don't contain 'solcast' so worth checking, or edit if you have non-standard names: pv_forecast_today - Entity name for today's Solcast forecast pv_forecast_tomorrow - Entity name for tomorrow's Solcast's forecast pv_forecast_d3 - Entity name for Solcast's forecast for day 3 pv_forecast_d4 - Entity name for Solcast's forecast for day 4 (also d5, d6 & d7 are supported, but not that useful) If you do not have a PV array then comment out or delete these Solcast lines from apps.yaml . Alternatively, Predbat can obtain the solar forecast directly from Solcast and the Solcast integration is thus not required. Uncomment the following Solcast cloud interface settings in apps.yaml and set the API key correctly: solcast_host: 'https://api.solcast.com.au/' solcast_api_key: 'xxxx' solcast_poll_hours: 8 Note that by default the solcast API will be used to download all sites (up to 2 for hobby accounts), if you want to override this set your sites manually using solcast_sites as an array of site IDs: solcast_sites: - 'xxxx' If you have more than 2 array orientations and thus more than one Solcast API key, enter each key in a list, i.e.: api_key: - xxxx_API_key_1 - yyyy_API_key_2 Keep in mind hobbyist accounts only have 10 polls per day so you need to ensure that the solcast_poll_hours refresh period is set so that you do not exceed the 10 poll limit. If you have two arrays then each Solcast refresh will consume 2 polls. If you use the same Solcast account for other automations the total polls needs to be kept under the limit or you will experience failures. If you have multiple PV arrays connected to hybrid inverters or you have AC-coupled inverters, then ensure your PV configuration in Solcast covers all arrays. If however you have a mixed PV array setup with some PV that does not feed into the inverters that Predbat is managing (e.g. hybrid GE inverters with an older firmware but a separate older FIT array that directly feeds AC into the house), then it's recommended that Solcast is only configured for the PV connected to the inverters that Predbat is managing. NB: Gen2, Gen3 and Gen1 hybrid inverters with the 'fast performance' firmware are able to charge their batteries from excess AC that would be exported, so for these inverters you should configure Solcast with your total solar generation capability. Solcast produces 3 forecasted PV estimates, the 'central' (50% or most likely to occur) PV forecast, the '10%' (1 in 10 more cloud coverage 'worst case') PV forecast, and the '90%' (1 in 10 less cloud coverage 'best case') PV forecast. By default Predbat will use the central (PV50) estimate and applies to it the input_number.predbat_pv_metric10_weight weighting of the 10% (worst case) estimate. You can thus adjust the metric10_weight to be more pessimistic about the solar forecast. 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 over the 30 minute slot 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. If pv_estimate is set to 10 then input_number.predbat_pv_metric10_weight in Home Assistant should be set to 1.0. See also PV configuration options in Home Assistant .","title":"Solcast Solar Forecast"},{"location":"apps-yaml/#energy-rates","text":"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 and are listed here just for completeness: metric_octopus_import - Import rates from the Octopus Energy integration metric_octopus_export - Export rates from the Octopus Energy integration metric_octopus_gas - Gas rates from the Octopus Energy integration octopus_intelligent_slot - Octopus Intelligent GO slot sensor from the Octopus Energy integration octopus_saving_session - Energy saving sessions sensor from the Octopus Energy integration octopus_saving_session_octopoints_per_penny - Sets the Octopoints per pence rates_import_octopus_url - Octopus pricing URL (over-rides metric_octopus_import) rates_export_octopus_url - Octopus export pricing URL (over-rides metric_octopus_export) metric_standing_charge - Standing charge in pounds rates_import - Import rates over a 24-hour period with start and end times rates_export - Export rates over a 24-hour period with start and end times rates_gas - Gas rates over a 24-hour period with start and end times rates_import_override - Over-ride import rate for specific date and time range, e.g. Octopus Power-up events rates_export_override - Over-ride export rate for specific date and time range futurerate_url - URL of future energy market prices for Agile users futurerate_adjust_import and futurerate_adjust_export - Whether tomorrow's predicted import or export prices should be adjusted based on market prices or not futurerate_peak_start and futurerate_peak_end - start/end times for peak-rate adjustment carbon_intensity - Carbon intensity of the grid in half hour slots from an integration.","title":"Energy Rates"},{"location":"apps-yaml/#car-charging-integration","text":"Predbat is able to include electric vehicle charging in its plan and manage the battery activity so that the battery isn't discharged into your car when the car is charging (although you can over-ride this if you wish by setting the switch.predbat_car_charging_from_battery to True in Home Assistant). There are two different ways of planning car charging into cheap slots with Predbat, either by the Octopus Energy integration or by Predbat identifying the cheapest slots. These approaches and the set of settings that need to be configured together are described in Car Charging . The full list of car charging configuration items in apps.yaml that are used to plan car charging activity within Predbat are described below. The Home Assistant controls (switches, input numbers, selectors, etc) related to car charging are described in Car Charging configuration within Home Assistant , with brief mention of pertinent controls included here alongside the apps.yaml configuration items where relevant for context. num_cars should be set in apps.yaml to the number of cars you want Predbat to plan for. Set to 0 if you don't have an EV (and the remaining car sensors in apps.yaml can safely be commented out or deleted as they won't be required). NB: num_cars must be set correctly regardless of whether you are using Octopus Intelligent Go to control your EV charging or Predbat to control the charging; or else Predbat could start discharging your battery when the EV is charging. car_charging_exclusive should be set to True for each car in apps.yaml if you have multiple cars configured in Predbat, but only one car charger. This indicates that only one car may charge at once (the first car reporting as plugged in will be considered as charging). If you set this to False for each car then it is assumed that the car can charge independently, and hence two or more cars could charge at once. One entry per car. car_charging_exclusive: - True - True","title":"Car Charging Integration"},{"location":"apps-yaml/#car-charging-filtering","text":"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.predbat_car_charging_hold - A Home Assistant switch that when turned on (True) tells Predbat to remove car charging data from your historical house load so that Predbat's battery prediction plan is not distorted by previous car charging. 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 that should auto-detect the appropriate Wallbox and Zappi car charger sensors, or edit as necessary in apps.yaml for your charger sensor. This can be set to a list of car charging energy sensors, one per line if you have multiple EV car chargers. TIP: 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.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 sensor data by if required (e.g. set to 0.001 to convert Watts to kW). If you do not have a suitable car charging energy 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.predbat_car_charging_threshold (default 6 = 6kW)- Sets the kW power threshold above which home consumption is assumed to be car charging and input_number.predbat_car_charging_rate will be subtracted from the historical load data.","title":"Car Charging Filtering"},{"location":"apps-yaml/#planned-car-charging","text":"These features allow Predbat to know when you plan to charge your car. If you have Intelligent Octopus tariff then planning of charging is done via the Octopus app and Predbat obtains this information through the Octopus Energy integration in Home Assistant. switch.predbat_octopus_intelligent_charging - When this Home Assistant switch is enabled, Predbat will plan charging around the Intelligent Octopus slots, taking it into account for battery load and generating the slot information The following apps.yaml configuration items are pre-defined with regular expressions to point to appropriate sensors in the Octopus Energy integration. You should not normally need to change these if you have the Octopus Intelligent tariff: octopus_intelligent_slot - Points to the Octopus Energy integration 'intelligent dispatching' sensor that indicates whether you are within an Octopus Energy \"smart charge\" slot, and provides the list of future planned charging activity. octopus_ready_time - Points to the Octopus Energy integration sensor that details when the car charging will be completed by. octopus_charge_limit - Points to the Octopus Energy integration sensor that provides the car charging limit. octopus_slot_low_rate - Default is True, meaning any Octopus Intelligent Slot reported will be at the lowest rate if at home. If False the existing rates only will be used which is only suitable for tariff's other than IOG. If you don't use Intelligent Octopus then the above 3 Octopus Intelligent configuration lines in apps.yaml can be commented out or deleted, and there are a number of other apps.yaml configuration items that should be set: car_charging_planned - Optional, can be set to a Home Assistant sensor (e.g. from your car charger integration) which lets Predbat know the car is plugged in and planned to charge during low rate slots. Or manually set it to 'False' to disable this feature, or 'True' to always enable. The apps.yaml template supplied with Predbat comes pre-configured with a regular expression that should automatically match Zappi or Wallbox car chargers. If you have a different type of charger you will need to configure it manually. car_charging_planned_response - An array of values for the above car_charging_planned sensor which indicate that the car is plugged in and will charge in the next low rate slot. The template apps.yaml comes with a set of pre-defined sensor values that should match most EV chargers. Customise for your car charger sensor if it sets sensor values that are not in the list. car_charging_now - For some cases finding details of planned car charging is difficult to obtain. The car_charging_now configuration item can be set to point to a Home Assistant sensor that tells you that the car is currently charging. Predbat will then assume this 30 minute slot is used for charging regardless of the plan. If Octopus Intelligent Charging is enabled and car_charging_now indicates the car is charging then Predbat will also assume that this is a low rate slot for the car/house (and might therefore start charging the battery), otherwise electricity import rates are taken from the normal rate data. CAUTION: Do not use car_charging_now with Predbat led charging or you will create an infinite loop. Do you use car_charging_now with Octopus intelligent unless you can't make it work any other way as it will assume all car charging is at low rate. car_charging_now_response - Set to the range of positive responses for car_charging_now to indicate that the car is charging. Useful if you have a sensor for your car charger that isn't binary. To make planned car charging more accurate, configure the following items in apps.yaml : car_charging_battery_size - Set this value in apps.yaml to the car's battery size in kWh. If not set, Predbat defaults to 100kWh. It will be used to predict when to stop car charging. car_charging_limit - You should configure this to point to a sensor that specifies the % limit the car is set to charge to. This could be a sensor on the EV charger integration or a Home Assistant helper entity you can set as you wish. If you don't specify a sensor Predbat will default to 100% - i.e. fill the car to full. car_charging_soc - You should configure this to point to a sensor (on the HA integration for your EV charger) that specifies the car's current charge level expressed as a percentage - it must NOT be set to a sensor that gives the car's current kWh value as this will cause Predbat to charge the car to an incorrect level. If you don't specify a sensor, Predbat will default to 0%.","title":"Planned Car Charging"},{"location":"apps-yaml/#multiple-electric-cars","text":"Multiple cars can be planned with Predbat, in which case you should set num_cars in apps.yaml to the number of cars you want to plan car_charging_limit , car_charging_planned , car_charging_battery_size and car_charging_soc must then be a list of values (i.e. 2 entries for 2 cars) If you have Intelligent Octopus then Car 0 will be managed by the Octopus Energy integration, if its enabled Each car will have it's own Home Assistant slot sensor created e.g. binary_sensor.predbat_car_charging_slot_1 , SoC planning sensor e.g predbat.car_soc_1 and predbat.car_soc_best_1 for car 1","title":"Multiple Electric Cars"},{"location":"apps-yaml/#load-forecast","text":"In addition to the historical house load data that Predbat uses by default, you can optionally provide a forecast of future load such as is produced by Predheat for Hot water and Heat Pump heating systems or via Predai load_forecast - this should be configured to point to a sensor and attribute. The attribute must in either The format of 'last_updated' timestamp and 'energy' in incrementing kWh. The format of a dictionary of timestamps and energy data in incremental KWh. For example: Or apps.yaml should be configured to point to the forecast sensor and attribute (in the above formats) like this: load_forecast: - sensor_name$attribute_name So if using Predheat it would be configured as: load_forecast: - predheat.heat_energy$external Set load_forecast_only to True if you do not wish to use the Predbat forecast but instead want to use this as your only forecast data e.g using PredAi: load_forecast_only: True load_forecast: - sensor.givtcp_{geserial}_load_energy_today_kwh_prediction$results","title":"Load Forecast"},{"location":"apps-yaml/#balance-inverters","text":"When you have two or more inverters it's possible they get out of sync so they are at different charge levels or they start to cross-charge (one discharges into another). When enabled, balance inverters tries to recover this situation by disabling either charging or discharging from one of the batteries until they re-align. Most of the Predbat configuration for balancing inverters is through a number of Home Assistant controls for Balancing Inverters , but there is one configuration item in apps.yaml : balance_inverters_seconds: seconds Defines how often to run the inverter balancing, 30 seconds is recommended if your machine is fast enough, but the default is 60 seconds.","title":"Balance Inverters"},{"location":"apps-yaml/#workarounds","text":"There are a number of different configuration items in apps.yaml that can be used to tweak the way Predbat operates and workaround weirdness you may have from your inverter and battery setup.","title":"Workarounds"},{"location":"apps-yaml/#clock-skew","text":"clock_skew: minutes Skews the local (computer) time that Predbat uses (from the computer that Predbat is running on). Set to 1 means add a minute to the Predbat computer time, set to -1 means take a minute off the Predbat computer time. This clock adjustment will be used by Predbat when real-time actions happen e.g. triggering a charge or discharge. If your inverter's time is different to the time on the computer running Home Assistant, you may need to skew the time settings made on the inverter when you trigger charging or discharging. Again 1 means the inverter is 1 minute fast and -1 means the inverter is 1 minute slow. Separate start and end options are applied to the start and end time windows, mostly as you want to start battery activity late (not early) and finish early (not late). You can adjust the charge and discharge times written to the inverter by setting the following in apps.yaml : inverter_clock_skew_start: minutes inverter_clock_skew_end: minutes Skews the setting of the charge slot registers vs the predicted start time inverter_clock_skew_discharge_start: minutes inverter_clock_skew_discharge_end: minutes Skews the setting of the discharge slot registers vs the predicted start time","title":"Clock skew"},{"location":"apps-yaml/#battery-size-scaling","text":"battery_scaling: - scale Default value 1.0. Multiple battery size scales can be entered, one per inverter on separate lines. This setting is used to scale the battery reported SoC kWh to make it appear bigger or larger than it is. As the GivEnergy inverters treat all batteries attached to an inverter as in effect one giant battery, if you have multiple batteries on an inverter that need scaling you should enter a composite scaling value for all batteries attached to the inverter. TIP: If you have a GivEnergy 2.6 or 5.2kWh battery then it will have an 80% depth of discharge but it will falsely report its capacity as being the 100% size, so set battery_scaling to 0.8 to report the correct usable capacity figure to Predbat. TIP: Likewise, if you have one or multiple GivEnergy All in One (AIO)'s, it will incorrectly report the 13.5kWh usable capacity of each AIO as 15.9kWh, so set battery_scaling to 0.85 to correct this. If you are going chart your battery SoC in Home Assistant then you may want to use predbat.soc_kw_h0 as your current SoC rather than the usual givtcp_SERIAL_NUMBER_soc GivTCP entity so everything lines up.","title":"Battery size scaling"},{"location":"apps-yaml/#import-export-scaling","text":"import_export_scaling: scale Default value 1.0. Used to scale the import & export kWh data from GivTCP if the inverter information is incorrect.","title":"Import export scaling"},{"location":"apps-yaml/#inverter-rate-minimum","text":"inverter_battery_rate_min: watts One per inverter (optional), set in Watts, when set models a \"bug\" in the inverter firmware in some models where if charge or discharge rates are set to 0 you actually get a small amount of charge or discharge. Recommended setting is 200 for Gen 1 hybrids with this issue.","title":"Inverter rate minimum"},{"location":"apps-yaml/#inverter-reserve-maximum","text":"inverter_reserve_max: percent Global, sets the maximum reserve % that may be set to the inverter, the default is 98, as some Gen 2 & Gen 3 inverters and AIO firmware versions refuse to be set to 100. Comment the line out or set to 100 if your inverter allows setting to 100%.","title":"Inverter reserve maximum"},{"location":"apps-yaml/#automatic-restarts","text":"If the add-on that is providing the inverter control stops functioning it can prevent Predbat from functioning correctly. In this case you can tell Predbat how to restart the add-on using a service. Right now only communication loss with GE inverters is detectable but in future other systems will be supported. When enabled if communication is lost then the service configured will be triggered and can cause a restart which may restart the connection. This maybe useful with GivTCP if you have time sync errors or lose the REST service every now and again. The auto_restart itself is a list of commands to run to trigger a restart. The shell command will call a 'sh' shell and can be used to delete files and suchlike. The service command is used to call a service, and can contain arguments of addon and/or entity_id . The configuration below is for GivTCP v3. auto_restart: - shell: 'rm -rf /homeassistant/GivTCP/*.pkl' - service: hassio/addon_restart addon: 533ea71a_givtcp NB: If you are running GivTCP v2 then the line '533ea71a_givtcp' must be replaced with 'a6a2857d_givtcp' as the slug-id (Home Assistant add-on identifier) is different between GivTCP v2 and v3.","title":"Automatic restarts"},{"location":"apps-yaml/#battery-chargedischarge-curves","text":"Some batteries tail off their charge rate at high SoC% or their discharge rate at low SoC%, and these optional configuration items enables you to model this tail-off in Predbat. Note that the charge/discharge curves only affect the accuracy of the charging/discharging model Predbat applies in the forward battery plan, Predbat will still instruct the inverter to charge/discharge at full rate regardless of the charging curve. If you know the battery charge or discharge curves (e.g. manufacturer info or your own testing) then you can manually configure this in apps.yaml, or Predbat can calculate the curves based upon historical inverter charging/discharging data in Home Assistant. If the battery has not recently been fully charged or fully discharged then Predbat will not be able to calculate the curves and you'll get a warning in the logfile. battery_charge_power_curve - This optional configuration item enables you to model in Predbat a tail off in charging at high SoC%. Enter the charging curve as a series of steps of % of max charge rate for each SoC percentage. 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. 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 ). If the battery_charge_power_curve option is not set in apps.yaml and Predbat performs an initial run (e.g. due to restarting the Predbat/AppDaemon add-on, or an edit being made to apps.yaml), then Predbat will automatically calculate the charging curve for you from historical battery charging information. You should look at the Predbat logfile to find the predicted battery charging curve and copy/paste it into your apps.yaml file. The logfile will also include a recommendation for how to set your battery_rate_max_scaling setting in HA. The YouTube video charging curve and low power charging explains how the curve works and shows how Predbat automatically creates it. 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 configure the charge curve in apps.yaml. 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. These must be configured in apps.yaml to point to Home Assistant entities that have appropriate history data for your inverter/battery. If you have a GivEnergy inverter and are using the recommended default REST mode to control your inverter then you will need to uncomment out the following entries in apps.yaml : charge_rate: - number.givtcp_{geserial}_battery_charge_rate battery_power: - sensor.givtcp_{geserial}_battery_power soc_kw: - sensor.givtcp_{geserial}_soc_kwh Example charging curve from a GivEnergy 9.5kWh battery with latest firmware and Gen 1 inverter: battery_charge_power_curve: 91 : 0.91 92 : 0.81 93 : 0.71 94 : 0.62 95 : 0.52 96 : 0.43 97 : 0.33 98 : 0.24 99 : 0.24 100 : 0.24 battery_discharge_power_curve - This optional configuration item enables you to model in Predbat a tail off in discharging at low SoC%. Enter the discharging curve as a series of steps of % of max discharge rate for each SoC percentage. The default is 1.0 (full power) discharge all the way to 0%. If the battery_discharge_power_curve option is not set in apps.yaml and Predbat performs an initial run (e.g. due to restarting the Predbat/AppDaemon add-on, or an edit being made to apps.yaml), then Predbat will automatically calculate the discharging curve for you from historical battery discharging information. You should look at the Predbat logfile to find the predicted battery discharging curve and copy/paste it into your apps.yaml file. Setting This option to auto will cause the computed curve to be stored and used automatically. This may not work very well if you don't do regular discharges to empty the battery. In the same way as for the battery charge curve above, Predbat needs to have access to historical Home Assistant data for battery_discharge_rate, battery_power and soc_kw. These must be configured in apps.yaml to point to Home Assistant entities that have appropriate history data for your inverter/battery. If you are using REST mode to control your GivEnergy inverter then the following entries in apps.yaml will need to be uncommented : discharge_rate: - number.givtcp_{geserial}_battery_discharge_rate battery_power: - sensor.givtcp_{geserial}_battery_power soc_kw: - sensor.givtcp_{geserial}_soc_kwh","title":"Battery charge/discharge curves"},{"location":"apps-yaml/#triggers","text":"export_triggers - The export trigger feature is useful to help trigger your own automations based on Predbat predicting in the plan that you will have spare solar energy that would be exported - this could happen if the battery is full or there is more predicted solar generation than can be charged into the battery. You can use the trigger in an automation, for example you could turn on an immersion heater or the washing machine to consume the excess solar power. The triggers count export energy until the next active charge slot only. For each trigger give a name, the minutes of export needed, and the energy required in that time. Multiple triggers can be enabled by Predbat at once so in total you could use too much energy if multiple triggered automations all run. Each trigger specified in apps.yaml will create a Home Assistant entity called 'binary_sensor.predbat_export_trigger_ name ' which will be turned on when the predicted trigger conditions are valid. Connect this binary sensor to your automation to start whatever you want to trigger. Set the name for each trigger, the number of minutes of solar export you need, and the amount of energy in kWh you will need available during that time period in apps.yaml: For example: export_triggers: - name: \"large\" minutes: 60 energy: 1.0 - name: \"small\" minutes: 15 energy: 0.25 Note: Predbat will set an export trigger to True if in the plan it predicts that there will be more than the specified amount of excess solar energy over the specified time period. In the example above, the 'large' trigger will be set to True for the 1 hour period where Predbat predicts that there will be a total of 1kWh of excess solar generation over that time period . For clarity the trigger is not set based on actual excess solar generation or export. It should also be recognised that this prediction could be wrong; there could be less solar generation or more house load than was predicted in the plan. If you wish to trigger activities based on Predbat charging or discharging the battery rather than spare solar energy you can instead use the following binary sensors in Home Assistant: binary_sensor.predbat_charging - Will be True when the home battery is inside a charge slot (either being charged or being held at a level). Note that this does include charge freeze slots where the discharge rate is set to zero without charging the battery. binary_sensor.predbat_exporting - 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.","title":"Triggers"},{"location":"apps-yaml/#understanding-how-days_previous-works","text":"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: 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: 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: 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: days_previous: - 2 - 3 - 4 - 5 - 6 - 7 - 8","title":"Understanding how days_previous works"},{"location":"car-charging/","text":"Car charging As a bare minimum a HA-controllable smart plug with a granny charger could be used, but do consider there could be an electrical spike to the car if the smart plug is turned off when the car is charging. A proper car charger and HA integration is preferable. You will firstly need to have installed the appropriate Home Assistant integration for your car charger. Configure apps.yaml for your car charging Start by configuring the Car charging settings in apps.yaml . Car Charging Planning There are two ways that Predbat can plan the slots for charging your car: If you have the Intelligent Octopus import tariff, have completed enrollment of your car/charger to Intelligent Octopus (requires a compatible charger or car), and you have installed the Octopus Energy integration - in which case Predbat will use the car charging slots allocated by Octopus Energy in battery prediction. The Octopus Energy integration supports Octopus 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 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 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 Home Assistant 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 car's current 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 The switch switch.predbat_octopus_intelligent_ignore_unplugged ( expert mode ) can be used to prevent Predbat from assuming the car will be charging or that future extra low rate slots apply when the car is unplugged. This will only work correctly if car_charging_planned is set correctly in apps.yaml to detect your car being plugged in Let the Octopus app control when your car charges. Predbat-led charging - Here Predbat plans and can initiate the car charging based on the upcoming low import rate slots Ensure car_charging_limit , car_charging_soc and car_charging_planned are set correctly in apps.yaml to point to the appropriate sensors from your EV (see Car charging config in apps.yaml ) Check (and if necessary add) the sensor response value from the sensor configured in car_charging_planned that is returned when the car is 'plugged in and ready to charge' is in the list of car_charging_planned_response values configured in apps.yaml If your car does not have a state of charge (SoC) sensor you can set switch.predbat_car_charging_manual_soc to True to have Predbat create input_number.predbat_car_charging_manual_soc_kwh which will hold the cars SoC in kWh. You will need to manually set this to the cars current charge level before charging, Predbat will increment it during charging sessions but will not reset it automatically. NB: input_number.predbat_car_charging_manual_soc_kwh must be set to the current kWh value of your car battery NOT a percentage SoC figure otherwise Predbat won't know how much energy there currently is in the battery. NB2: If you have car_charging_soc set and working for your car SoC sensor in apps.yaml, switch.predbat_car_charging_manual_soc must be set to Off as otherwise the car SoC sensor will be ignored Ensure switch.predbat_octopus_intelligent_charging in Home Assistant is set to Off Set input_number.predbat_car_charging_rate to the car's charging rate in kW per hour (e.g. 7.5 for 7.5kWh) Set select.predbat_car_charging_plan_time to the time you want the car charging to be completed by Turn on switch.predbat_car_charging_plan_smart if you want to use the cheapest slots only. When disabled (turned off) all low rate slots will be used in time order You can set input_number.predbat_car_charging_plan_max_price if you want to set a maximum price in pence per kWh to charge your car (e.g. 10p). If you set this to zero, this feature is disabled, and all low rate slots will be used. This may mean you need to use expert mode and change your low rate threshold to configure which slots should be considered if you have a tariff with more than 2 import rates (e.g. Flux) WARNING: Do not set car_charging_now or you will create a circular dependency. Predbat will set binary_sensor.predbat_car_charging_slot when it determines the car can be charged; you will need to write a Home Assistant automation based on this sensor to control when your car charges. A sample automation to start/stop car charging using a Zappi car charger and the MyEnergi Zappi integration is as follows, this should be adapted for your own charger type and how it controls starting/stopping car charging: alias: Car charging description: \"Start/stop car charging based on Predbat determined slots\" triggers: - trigger: state entity_id: - binary_sensor.predbat_car_charging_slot actions: - choose: - conditions: - condition: state entity_id: binary_sensor.predbat_car_charging_slot state: \"on\" sequence: - service: select.select_option data: option: Eco+ target: entity_id: select.myenergi_zappi_charge_mode - conditions: - condition: state entity_id: binary_sensor.predbat_car_charging_slot state: \"off\" sequence: - service: select.select_option data: option: Stopped target: entity_id: select.myenergi_zappi_charge_mode mode: single NOTE: Multiple cars can be planned with Predbat. Additional Car charging configurations If you have one charger and multiple cars configured in Predbat then set car_charging_exclusive in apps.yaml to True to indicate that only one car may charge at once (the first car reporting as plugged in will be considered as charging). If you set this to False then it is assumed each car can charge independently and hence two or more could charge at once car_charging_exclusive: - True - True See Car charging filtering and Planned car charging in the apps.yaml settings section of the documentation. switch.predbat_car_charging_from_battery - When set to True the car can drain the home battery, Predbat will manage the correct level of battery accordingly. When set to False home battery discharge will be prevented when your car charges, all load from the car and home will be from the grid. This is achieved by setting the battery discharge rate to 0 during car charging and to the maximum otherwise. The home battery can still charge from the grid/solar in either case. Only use this if Predbat knows your car charging plan, e.g. you are using Intelligent Octopus or you use the car slots in Predbat to control your car charging. input_number.predbat_car_charging_loss gives the percentage amount of energy lost when charging the car (load in the home vs energy added to the battery). A good setting is 0.08 which is 8%. Example EV and charger setup Sample setup and Predbat automation to use the cheapest charging slots with no/limited Home Assistant Integration. MG4 EV Vehicle with a Hypervolt Car Charger. There is no 3rd party integration with the MG, and the Hypervolt car charger doesn't understand when an EV is plugged in. Yet it can be stopped and started with a 3rd party integration. In Home Assistant, create two helper entities (Settings / Devices & Services / Helpers) of type 'Number', and for each set 'Unit of Measurement' to 'kWh': Car Max Charge - input_number.car_max_charge Car Manual SoC - input_number.car_manual_soc Create a 'Dropdown' helper entity that has two options 'true' and 'false' (in lower case): Car Charger Plugged in - input_select.car_charger_plugged_in Within the apps.yaml configuration file specify the following configuration settings: Find the line for car_charger_battery_size and enter the Car Battery Size in kWh: Example car_charging_battery_size: - 61.7 Specify the Car Charging Limit to use the Car Max Charge helper entity created earlier: car_charging_limit: - 'input_number.car_max_charge' Find car_charging_planned and replace the template Wallbox and Zappi regular expression with your new dropdown helper entity: car_charging_planned: - 'input_select.car_charger_plugged_in' Find car_charging_planned_response and add 'true' to the list: car_charging_planned_response: - 'yes' - 'on' - 'true' If possible, add an entity keeping track of the kWh used for car charging to car_charging_energy . If your charging device doesn't keep track of kWh but you can measure the power sent to the car charger (e.g. from the EV charger integration or an energy monitor/smart plug for the EV charger) then you can create another helper entity to convert kW power into kWh: Create a helper entity (Settings / Devices & Services / Helpers) of type 'Integration - Riemann Sum integral': Name : car_energy_used Input sensor : sensor that measures power consumed by the car charger Integration method : Right Riemann sum Metric prefix : k (kilo) Please look into Integration - Riemann sum integral to convert kW into kWh. And add your custom car charging energy sensor in apps.yaml in place of the template Wallbox and Zappi regular expression: Example car_charging_energy: 'sensor.car_energy_used' car_charging_now must be commented out (hashed out) in apps.yaml : #car_charging_now: # - off Save the apps.yaml file and exit. In Home Assistant, turn on the following Predbat control switches: switch.predbat_car_charging_hold switch.predbat_car_charging_manual_soc switch.predbat_car_charging_plan_smart And turn off the Predbat control switch: switch.predbat_octopus_intelligent_charging HA Charging Slot Automation In Home Assistant (Settings / Automation & Scenes), create an automation to monitor the Predbat car charging slot sensor and turn the charger on and off according to the Predbat plan (the numeric entity id's below would need replacing with the appropriate sensor name for your car charger): alias: Car Charging Slot description: \"\" triggers: - trigger: state entity_id: - binary_sensor.predbat_car_charging_slot actions: - if: - condition: state entity_id: binary_sensor.predbat_car_charging_slot state: \"off\" then: - type: turn_off entity_id: f6de2df0758744aba60f6b5f domain: switch - if: - condition: state entity_id: binary_sensor.predbat_car_charging_slot state: \"on\" then: - type: turn_on entity_id: f6de2df0758744aba60f6b5f domain: switch mode: single Finally, for simplicity, add the below entities to your HA Dashboard so you can set them when needed: Car Max Charge - input_number.car_max_charge Car Manual SoC - input_number.car_manual_soc Car Charger Plugged in - input_select.car_charger_plugged_in Annoyingly, you have to calculate the kWh your vehicle has in total by taking the Percentage left in the car / 100 * Total Car Battery capacity. For example: 65/100*61.7=40.1 Enter '40.1' into 'Car Manual SoC' and '80%' into 'Car Max charge'. Once the charger is switched to true and your Car Max charge (target SoC) % is higher than the kWh currently in the car, Predbat will plan and charge the car with the kW that are needed to reach the target SoC.","title":"Car charging"},{"location":"car-charging/#car-charging","text":"As a bare minimum a HA-controllable smart plug with a granny charger could be used, but do consider there could be an electrical spike to the car if the smart plug is turned off when the car is charging. A proper car charger and HA integration is preferable. You will firstly need to have installed the appropriate Home Assistant integration for your car charger.","title":"Car charging"},{"location":"car-charging/#configure-appsyaml-for-your-car-charging","text":"Start by configuring the Car charging settings in apps.yaml .","title":"Configure apps.yaml for your car charging"},{"location":"car-charging/#car-charging-planning","text":"There are two ways that Predbat can plan the slots for charging your car: If you have the Intelligent Octopus import tariff, have completed enrollment of your car/charger to Intelligent Octopus (requires a compatible charger or car), and you have installed the Octopus Energy integration - in which case Predbat will use the car charging slots allocated by Octopus Energy in battery prediction. The Octopus Energy integration supports Octopus 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 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 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 Home Assistant 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 car's current 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 The switch switch.predbat_octopus_intelligent_ignore_unplugged ( expert mode ) can be used to prevent Predbat from assuming the car will be charging or that future extra low rate slots apply when the car is unplugged. This will only work correctly if car_charging_planned is set correctly in apps.yaml to detect your car being plugged in Let the Octopus app control when your car charges. Predbat-led charging - Here Predbat plans and can initiate the car charging based on the upcoming low import rate slots Ensure car_charging_limit , car_charging_soc and car_charging_planned are set correctly in apps.yaml to point to the appropriate sensors from your EV (see Car charging config in apps.yaml ) Check (and if necessary add) the sensor response value from the sensor configured in car_charging_planned that is returned when the car is 'plugged in and ready to charge' is in the list of car_charging_planned_response values configured in apps.yaml If your car does not have a state of charge (SoC) sensor you can set switch.predbat_car_charging_manual_soc to True to have Predbat create input_number.predbat_car_charging_manual_soc_kwh which will hold the cars SoC in kWh. You will need to manually set this to the cars current charge level before charging, Predbat will increment it during charging sessions but will not reset it automatically. NB: input_number.predbat_car_charging_manual_soc_kwh must be set to the current kWh value of your car battery NOT a percentage SoC figure otherwise Predbat won't know how much energy there currently is in the battery. NB2: If you have car_charging_soc set and working for your car SoC sensor in apps.yaml, switch.predbat_car_charging_manual_soc must be set to Off as otherwise the car SoC sensor will be ignored Ensure switch.predbat_octopus_intelligent_charging in Home Assistant is set to Off Set input_number.predbat_car_charging_rate to the car's charging rate in kW per hour (e.g. 7.5 for 7.5kWh) Set select.predbat_car_charging_plan_time to the time you want the car charging to be completed by Turn on switch.predbat_car_charging_plan_smart if you want to use the cheapest slots only. When disabled (turned off) all low rate slots will be used in time order You can set input_number.predbat_car_charging_plan_max_price if you want to set a maximum price in pence per kWh to charge your car (e.g. 10p). If you set this to zero, this feature is disabled, and all low rate slots will be used. This may mean you need to use expert mode and change your low rate threshold to configure which slots should be considered if you have a tariff with more than 2 import rates (e.g. Flux) WARNING: Do not set car_charging_now or you will create a circular dependency. Predbat will set binary_sensor.predbat_car_charging_slot when it determines the car can be charged; you will need to write a Home Assistant automation based on this sensor to control when your car charges. A sample automation to start/stop car charging using a Zappi car charger and the MyEnergi Zappi integration is as follows, this should be adapted for your own charger type and how it controls starting/stopping car charging: alias: Car charging description: \"Start/stop car charging based on Predbat determined slots\" triggers: - trigger: state entity_id: - binary_sensor.predbat_car_charging_slot actions: - choose: - conditions: - condition: state entity_id: binary_sensor.predbat_car_charging_slot state: \"on\" sequence: - service: select.select_option data: option: Eco+ target: entity_id: select.myenergi_zappi_charge_mode - conditions: - condition: state entity_id: binary_sensor.predbat_car_charging_slot state: \"off\" sequence: - service: select.select_option data: option: Stopped target: entity_id: select.myenergi_zappi_charge_mode mode: single NOTE: Multiple cars can be planned with Predbat.","title":"Car Charging Planning"},{"location":"car-charging/#additional-car-charging-configurations","text":"If you have one charger and multiple cars configured in Predbat then set car_charging_exclusive in apps.yaml to True to indicate that only one car may charge at once (the first car reporting as plugged in will be considered as charging). If you set this to False then it is assumed each car can charge independently and hence two or more could charge at once car_charging_exclusive: - True - True See Car charging filtering and Planned car charging in the apps.yaml settings section of the documentation. switch.predbat_car_charging_from_battery - When set to True the car can drain the home battery, Predbat will manage the correct level of battery accordingly. When set to False home battery discharge will be prevented when your car charges, all load from the car and home will be from the grid. This is achieved by setting the battery discharge rate to 0 during car charging and to the maximum otherwise. The home battery can still charge from the grid/solar in either case. Only use this if Predbat knows your car charging plan, e.g. you are using Intelligent Octopus or you use the car slots in Predbat to control your car charging. input_number.predbat_car_charging_loss gives the percentage amount of energy lost when charging the car (load in the home vs energy added to the battery). A good setting is 0.08 which is 8%.","title":"Additional Car charging configurations"},{"location":"car-charging/#example-ev-and-charger-setup","text":"Sample setup and Predbat automation to use the cheapest charging slots with no/limited Home Assistant Integration. MG4 EV Vehicle with a Hypervolt Car Charger. There is no 3rd party integration with the MG, and the Hypervolt car charger doesn't understand when an EV is plugged in. Yet it can be stopped and started with a 3rd party integration. In Home Assistant, create two helper entities (Settings / Devices & Services / Helpers) of type 'Number', and for each set 'Unit of Measurement' to 'kWh': Car Max Charge - input_number.car_max_charge Car Manual SoC - input_number.car_manual_soc Create a 'Dropdown' helper entity that has two options 'true' and 'false' (in lower case): Car Charger Plugged in - input_select.car_charger_plugged_in Within the apps.yaml configuration file specify the following configuration settings: Find the line for car_charger_battery_size and enter the Car Battery Size in kWh: Example car_charging_battery_size: - 61.7 Specify the Car Charging Limit to use the Car Max Charge helper entity created earlier: car_charging_limit: - 'input_number.car_max_charge' Find car_charging_planned and replace the template Wallbox and Zappi regular expression with your new dropdown helper entity: car_charging_planned: - 'input_select.car_charger_plugged_in' Find car_charging_planned_response and add 'true' to the list: car_charging_planned_response: - 'yes' - 'on' - 'true' If possible, add an entity keeping track of the kWh used for car charging to car_charging_energy . If your charging device doesn't keep track of kWh but you can measure the power sent to the car charger (e.g. from the EV charger integration or an energy monitor/smart plug for the EV charger) then you can create another helper entity to convert kW power into kWh: Create a helper entity (Settings / Devices & Services / Helpers) of type 'Integration - Riemann Sum integral': Name : car_energy_used Input sensor : sensor that measures power consumed by the car charger Integration method : Right Riemann sum Metric prefix : k (kilo) Please look into Integration - Riemann sum integral to convert kW into kWh. And add your custom car charging energy sensor in apps.yaml in place of the template Wallbox and Zappi regular expression: Example car_charging_energy: 'sensor.car_energy_used' car_charging_now must be commented out (hashed out) in apps.yaml : #car_charging_now: # - off Save the apps.yaml file and exit. In Home Assistant, turn on the following Predbat control switches: switch.predbat_car_charging_hold switch.predbat_car_charging_manual_soc switch.predbat_car_charging_plan_smart And turn off the Predbat control switch: switch.predbat_octopus_intelligent_charging HA Charging Slot Automation In Home Assistant (Settings / Automation & Scenes), create an automation to monitor the Predbat car charging slot sensor and turn the charger on and off according to the Predbat plan (the numeric entity id's below would need replacing with the appropriate sensor name for your car charger): alias: Car Charging Slot description: \"\" triggers: - trigger: state entity_id: - binary_sensor.predbat_car_charging_slot actions: - if: - condition: state entity_id: binary_sensor.predbat_car_charging_slot state: \"off\" then: - type: turn_off entity_id: f6de2df0758744aba60f6b5f domain: switch - if: - condition: state entity_id: binary_sensor.predbat_car_charging_slot state: \"on\" then: - type: turn_on entity_id: f6de2df0758744aba60f6b5f domain: switch mode: single Finally, for simplicity, add the below entities to your HA Dashboard so you can set them when needed: Car Max Charge - input_number.car_max_charge Car Manual SoC - input_number.car_manual_soc Car Charger Plugged in - input_select.car_charger_plugged_in Annoyingly, you have to calculate the kWh your vehicle has in total by taking the Percentage left in the car / 100 * Total Car Battery capacity. For example: 65/100*61.7=40.1 Enter '40.1' into 'Car Manual SoC' and '80%' into 'Car Max charge'. Once the charger is switched to true and your Car Max charge (target SoC) % is higher than the kWh currently in the car, Predbat will plan and charge the car with the kW that are needed to reach the target SoC.","title":"Example EV and charger setup"},{"location":"caution/","text":"Some words of caution Predbat is a powerful hobbyist system that can control many home battery and solar systems. While every attempt has been made to make it as easy to use as possible it does require a certain amount of technical skills. Increased energy costs While Predbat normally will save you money an incorrectly configured Predbat can cause your battery to be badly managed and thus increase your electricity bills, I'd recommend carefully changing what you install is doing once you have enabled it for the first time. Flash memory Some inverters have a flash memory which has a limited lifespan and so depending on the way register writes are managed controller your inverter can act to reduce this lifespan. In normal operation this should not be an issue but if you have a setup that performs large number of register writes all the time its possible you could eventually run into this issue. For example on a current GivEnergy inverters its assumed around 1 million register writes could be the current usable limit (although firmware changes may increase this limit) This would give you around 270 writes per day or around 1 every 5 minutes. Each change of mode requires more than one register write, e.g. start time, end time, scheduled charge enable, pause mode etc - this could be around 6 registers. This means one change of mode every 30 minutes on average would be okay. However given most plans will have larger gaps (often hours) where the battery is either in Demand mode, charging or exporting where registers are not changing it is unlikely to hit this limit. Given different inverter designs may have different limits it is a wise precaution to avoid your plan being too busy if it doesn't gain you very much. Things you can do to have a less complex plan include: Keep calculate export during charge off Set metric battery cycle to a small non-zero value e.g. 0.5 Ensure inverter losses are set to a representative value Turn off charge_low_power mode Avoid using balance inverters which can make register changes one or twice a minute unless you are sure this is not an issue Predbat creates an entity called predbat.inverter_register_writes which can be used to check the total number of writes across all inverters, if you divide this by the time period of use and by the number of inverters you will be able to figure out the actual rate of register writes.","title":"Words of caution"},{"location":"caution/#some-words-of-caution","text":"Predbat is a powerful hobbyist system that can control many home battery and solar systems. While every attempt has been made to make it as easy to use as possible it does require a certain amount of technical skills.","title":"Some words of caution"},{"location":"caution/#increased-energy-costs","text":"While Predbat normally will save you money an incorrectly configured Predbat can cause your battery to be badly managed and thus increase your electricity bills, I'd recommend carefully changing what you install is doing once you have enabled it for the first time.","title":"Increased energy costs"},{"location":"caution/#flash-memory","text":"Some inverters have a flash memory which has a limited lifespan and so depending on the way register writes are managed controller your inverter can act to reduce this lifespan. In normal operation this should not be an issue but if you have a setup that performs large number of register writes all the time its possible you could eventually run into this issue. For example on a current GivEnergy inverters its assumed around 1 million register writes could be the current usable limit (although firmware changes may increase this limit) This would give you around 270 writes per day or around 1 every 5 minutes. Each change of mode requires more than one register write, e.g. start time, end time, scheduled charge enable, pause mode etc - this could be around 6 registers. This means one change of mode every 30 minutes on average would be okay. However given most plans will have larger gaps (often hours) where the battery is either in Demand mode, charging or exporting where registers are not changing it is unlikely to hit this limit. Given different inverter designs may have different limits it is a wise precaution to avoid your plan being too busy if it doesn't gain you very much. Things you can do to have a less complex plan include: Keep calculate export during charge off Set metric battery cycle to a small non-zero value e.g. 0.5 Ensure inverter losses are set to a representative value Turn off charge_low_power mode Avoid using balance inverters which can make register changes one or twice a minute unless you are sure this is not an issue Predbat creates an entity called predbat.inverter_register_writes which can be used to check the total number of writes across all inverters, if you divide this by the time period of use and by the number of inverters you will be able to figure out the actual rate of register writes.","title":"Flash memory"},{"location":"configuration-guide/","text":"Configuration guide First get the basics set up, ensure you have the inverter controls configured , you have configured apps.yaml to your setup, and the solar forecast is 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 Predbat can tell what part of your historical load is EV charging. You might want to also set the car charging plan so you can predict when your car is plugged in and how much it will charge. It is recommended that you create a dashboard page 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 details all the Predbat customisation options. 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. For a Hybrid inverter the inverter loss includes the loss on inverting PV as well going AC to DC when importing. Battery loss charge and discharge are factors to account for the loss in charging and discharging the battery as DC. For a AC coupled inverter the inverter loss is just the loss of the battery inverter, if you need to model the loss of your PV inverter then use input_number.predbat_pv_scaling or adjust your Solcast output. Battery loss charge and discharge are factors to account for the loss in charging and discharging the battery as DC. 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.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. 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 0.5p (meaning charging and discharging the battery would effectively cost an extra 1p per kWh) but can be set to 0 if you want to turn this feature off. 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 and don't want Predbat to force export (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 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 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_metric_min_improvement 0 Charge less if it's cost neutral input_number.predbat_metric_min_improvement_export 5 Export only if there is a profit You should set select.predbat_mode to 'Control charge' Cheap night rate, with a good export rate (e.g. Intelligent Octopus with Octopus Outgoing) Follow the instructions from the Cheap Night rate above, but also you will also want to have automatic export occurring when the export rates are profitable. Item Value Comment 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 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 input_number.predbat_metric_min_improvement 0 Charge less if it's cost neutral input_number.predbat_metric_min_improvement_export 5 Export only if there is a profit input_number.predbat_metric_battery_cycle 0-2 Higher numbers mean less charging and discharging but higher costs input_number.predbat_best_soc_min 0 Can be set non-zero if you want to force a minimum charge level 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 export 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 Predbat to calculate and control charging and discharging input_number.predbat_best_soc_keep 0.5 Use the full battery without going empty 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 input_number.predbat_metric_min_improvement 0 Charge less if it's cost neutral input_number.predbat_metric_min_improvement_export 5 Export only if there is a profit input_number.predbat_metric_battery_cycle 0-2 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' Half hourly variable rates (e.g. Octopus Agile) Recommended settings - these must be changed in Home Assistant once Predbat is running: Item Value Comment 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 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.predbat_metric_min_improvement 0 Charge less if it's cost neutral input_number.predbat_metric_min_improvement_export 5 Export only if there is a profit input_number.predbat_metric_battery_cycle 0-2 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'","title":"Configuration guide"},{"location":"configuration-guide/#configuration-guide","text":"First get the basics set up, ensure you have the inverter controls configured , you have configured apps.yaml to your setup, and the solar forecast is 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 Predbat can tell what part of your historical load is EV charging. You might want to also set the car charging plan so you can predict when your car is plugged in and how much it will charge. It is recommended that you create a dashboard page 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 details all the Predbat customisation options. 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. For a Hybrid inverter the inverter loss includes the loss on inverting PV as well going AC to DC when importing. Battery loss charge and discharge are factors to account for the loss in charging and discharging the battery as DC. For a AC coupled inverter the inverter loss is just the loss of the battery inverter, if you need to model the loss of your PV inverter then use input_number.predbat_pv_scaling or adjust your Solcast output. Battery loss charge and discharge are factors to account for the loss in charging and discharging the battery as DC. 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.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. 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 0.5p (meaning charging and discharging the battery would effectively cost an extra 1p per kWh) but can be set to 0 if you want to turn this feature off. 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.","title":"Configuration guide"},{"location":"configuration-guide/#fixed-daily-rates","text":"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'.","title":"Fixed daily rates"},{"location":"configuration-guide/#cheap-night-rate-with-bad-export-rate-eg-octopus-go-economy-7-etc","text":"In this scenario you will want to charge overnight based on the next day's solar forecast and don't want Predbat to force export (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 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 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_metric_min_improvement 0 Charge less if it's cost neutral input_number.predbat_metric_min_improvement_export 5 Export only if there is a profit You should set select.predbat_mode to 'Control charge'","title":"Cheap night rate with bad export rate (e.g. Octopus Go, Economy 7 etc)"},{"location":"configuration-guide/#cheap-night-rate-with-a-good-export-rate-eg-intelligent-octopus-with-octopus-outgoing","text":"Follow the instructions from the Cheap Night rate above, but also you will also want to have automatic export occurring when the export rates are profitable. Item Value Comment 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 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 input_number.predbat_metric_min_improvement 0 Charge less if it's cost neutral input_number.predbat_metric_min_improvement_export 5 Export only if there is a profit input_number.predbat_metric_battery_cycle 0-2 Higher numbers mean less charging and discharging but higher costs input_number.predbat_best_soc_min 0 Can be set non-zero if you want to force a minimum charge level You should set select.predbat_mode to 'Control charge & discharge'","title":"Cheap night rate, with a good export rate (e.g. Intelligent Octopus with Octopus Outgoing)"},{"location":"configuration-guide/#multiple-rates-for-import-and-export-eg-octopus-flux-cozy","text":"Follow the instructions from Cheap Night rate above, but also you will want to have automatic export 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 Predbat to calculate and control charging and discharging input_number.predbat_best_soc_keep 0.5 Use the full battery without going empty 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 input_number.predbat_metric_min_improvement 0 Charge less if it's cost neutral input_number.predbat_metric_min_improvement_export 5 Export only if there is a profit input_number.predbat_metric_battery_cycle 0-2 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'","title":"Multiple rates for import and export (e.g. Octopus Flux & Cozy)"},{"location":"configuration-guide/#half-hourly-variable-rates-eg-octopus-agile","text":"Recommended settings - these must be changed in Home Assistant once Predbat is running: Item Value Comment 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 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.predbat_metric_min_improvement 0 Charge less if it's cost neutral input_number.predbat_metric_min_improvement_export 5 Export only if there is a profit input_number.predbat_metric_battery_cycle 0-2 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'","title":"Half hourly variable rates (e.g. Octopus Agile)"},{"location":"creating-charts/","text":"Creating the charts There are a number of fancy Apex charts that can be produced from Predbat data - things like Home Battery SoC prediction, Cost prediction, Energy Rates, etc. There's a Video Guide to the different charts available on YouTube. To install the charts: Install Apex Charts https://github.com/RomRider/apexcharts-card : In HACS, click on Frontend Click the blue Explore and download repositories button and type 'apex' Click on 'apexcharts-card', then click the blue 'Download', then 'Download' again to install it When prompted to 'reload your browser', click 'Reload' Next, on a Home Assistant dashboard you create the charts you want. There are multiple charts, for each section of the example chart yaml file , create a new apexcharts card and copy the YAML into it: Click the blue 'Add card', scroll down the list of cards to the bottom and click 'Custom: ApexCharts card' Delete the template card configuration and copy/paste ONE Apex chart from the example file Click 'Save' Repeat (adding Apex chart card, copy paste card config) for all of the charts you want to see Customise as you like If you get an error 'Custom element doesn't exist: apexcharts-card' then you've not installed the Apex Charts card correctly from HACS. See the video guides for a walkthrough of what the different charts show. Example charts:","title":"Creating the charts"},{"location":"creating-charts/#creating-the-charts","text":"There are a number of fancy Apex charts that can be produced from Predbat data - things like Home Battery SoC prediction, Cost prediction, Energy Rates, etc. There's a Video Guide to the different charts available on YouTube. To install the charts: Install Apex Charts https://github.com/RomRider/apexcharts-card : In HACS, click on Frontend Click the blue Explore and download repositories button and type 'apex' Click on 'apexcharts-card', then click the blue 'Download', then 'Download' again to install it When prompted to 'reload your browser', click 'Reload' Next, on a Home Assistant dashboard you create the charts you want. There are multiple charts, for each section of the example chart yaml file , create a new apexcharts card and copy the YAML into it: Click the blue 'Add card', scroll down the list of cards to the bottom and click 'Custom: ApexCharts card' Delete the template card configuration and copy/paste ONE Apex chart from the example file Click 'Save' Repeat (adding Apex chart card, copy paste card config) for all of the charts you want to see Customise as you like If you get an error 'Custom element doesn't exist: apexcharts-card' then you've not installed the Apex Charts card correctly from HACS. See the video guides for a walkthrough of what the different charts show. Example charts:","title":"Creating the charts"},{"location":"customisation/","text":"Customisation This document describes the Predbat configuration items in Home Assistant that you can modify to customise Predbat to fit your needs. All of these settings are entities that can be configured directly in Home Assistant (unlike the ' apps.yaml ' configuration items that have to be edited with a file editor). See Displaying output data 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 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 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 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. Predbat mode The mode that Predbat operates in will change the operation, this can be configured with select.predbat_mode drop down menu as follows: Monitor Control SOC Only Control charge Control charge & discharge If the switch.predbat_set_read_only is set to True then this prevents Predbat from making modifications to the inverter settings (regardless of the configuration). Predbat will continue making and updating its prediction plan every 5 minutes, but no inverter changes will be made. This is useful if you want to over-ride what Predbat is planning to do (e.g. your own automation), or whilst you are learning how Predbat works prior to turning it on 'in anger'. NOTE: Changing the Predbat mode or the read only switch will cause Predbat to reset the inverter settings to default, this will disable both charge and discharge, reset charge and discharge rates to full power and reset the reserve to the default setting Predbat Monitor mode 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 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: 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, you have a 'no export' limitation from your electricity supplier, or if you want to preserve the battery for home demand. Predbat Control charge & discharge mode In Control charge & discharge mode Predbat will set both charge and force export (discharge) times and control charge and force export percentages. If you have set the switch.predbat_set_export_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 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 By default Predbat controls the inverter and updates the plan every 5 minutes, this can however use a lot of CPU power especially on more complex tariffs like Agile when run on lower power machines such as Raspberry PIs and some thin clients. You can tweak input_number.predbat_calculate_plan_every ( expert mode ) to reduce the frequency of replanning while keeping the inverter control in the 5 minute slots. E.g. a value of 10 or 15 minutes should also give good results. If you have performance problems leave switch.predbat_calculate_second_pass ( expert mode ) turned Off as it's quite CPU intensive and provides very little improvement for most systems. You can can enable combine_charge_slots and combine_export_slots in order to speed up planning. Note: Combining export slots may prevent optimal forced export. Combining charge slots is usually fine for tariffs with longer periods of fixed rates but can limit the planning ability in some cases. The number of threads you use can change your performance, you can set threads in apps.yaml to 0 to disable threading if you don't have multiple CPUs available or set it to 'auto' (the default) to use one thread per CPU. Its recommended you don't set this to an odd number of threads. Battery loss options input_number.predbat_battery_loss is an assumed percentage figure for energy lost when charging the battery, the default 0.05 is 5%. input_number.predbat_battery_loss_discharge is an assumed percentage figure for energy lost whilst discharging the battery, the default 0.05 is 5%. input_number.predbat_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. TIP: Make sure you set the losses correctly, they are decimal percentages, don't set to '4' thinking it'll be 4%, Predbat will take this as being 400% and your plan will be very strange! switch.predbat_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.predbat_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 have a 9.5kWh battery and think it will last say 6000 complete cycles and it cost you \u00a34000, then each full charge and discharge cycle is 19kWh and so the cost per complete cycle is \u00a34000 / 19 / 6000 = 3.5p. Taking the 3.5p per cycle example, if you set predbat_metric_battery_cycle to 1.75 (half of 3.5) then Predbat will apply the \"virtual cost\" of 1.75p 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. If you configure this number higher then more expensive plans will be selected which avoids charging and discharging your battery as much. 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. Figures of around 0p-2p are recommended, the default is 0p per kWh. 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). input_number.metric_self_sufficiency ( expert mode ) A price in pence per kWh used to skew the calculations towards self sufficiency. Effectively saying to Predbat to account for imports at a higher price than reality in the calculation and thus selecting plans with less import. If you want to be as self sufficient as possible then set this to the difference between your lowest import rate and the highest export rate to take exports that require additional import appear unprofitable. This setting will not impact the real calculated costs and is only used for plan selection. Values of 5-10p maybe worth trying if you prefer to avoid importing even if it saves you money. Scaling and weight options input_number.predbat_battery_rate_max_scaling is a percentage factor to adjust your maximum charge rate from that reported by the inverter. For example a value of 0.95 would be 95% and indicate charging at 5% slower than reported. For GE inverters the charge rate reports the max AC rate and thus needs to be reduced by inverter losses. You can try computing your discharge curve and check recommendations for changing this figure in the logfile. input_number.predbat_battery_rate_max_scaling_discharge is a percentage factor to adjust your maximum discharge rate from that reported by the inverter. For GE inverters the discharge rate is reported as the max AC rate and thus is fairly accurate. You can try computing your discharge curve and check recommendations for changing this figure in the logfile. 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.predbat_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.predbat_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.predbat_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). Solar PV adjustment options See also PV configuration options in apps.yaml including explanation of PV10, PV50 and PV90 terminology. input_number.predbat_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.predbat_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 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 day from the list of days to use (provided you have more than 1 day selected in days_previous). This can be used to ignore a single low usage day in your average calculation. By default is feature is enabled but can be disabled only in expert mode. Car Charging There are a number of configuration items in Home Assistant for Predbat to control your car charging. These are described in detail in Car Charging and are listed here just for completeness: switch.predbat_car_charging_hold - remove historical car charging load from the house load input_number.predbat_car_charging_threshold - power threshold above which Predbat assumes the car is being charged input_number.predbat_car_charging_energy_scale - used to scale the car_charging_energy sensor in apps.yaml input_number.predbat_car_charging_rate - car's charging rate in kW per hour input_number.predbat_car_charging_loss - percentage energy lost when charging the car switch.predbat_octopus_intelligent_charging - controls whether Octopus Intelligent (via the Octopus Energy integration) controls the car charging or Predbat plans the car charging switch.predbat_octopus_intelligent_ignore_unplugged ( expert mode ) - used with Octopus Intelligent to prevent Predbat from assuming the car will be charging when the car is unplugged binary_sensor.predbat_car_charging_slot - set to True by Predbat when the car should be charged (Predbat-led charging) select.predbat_car_charging_plan_time - the time you want the car to be charged by switch.predbat_car_charging_plan_smart - allows Predbat to allocate car charging slots to the cheapest times rather than all low rate slots input_number.predbat_car_charging_plan_max_price - maximum price per kWh to pay when charging your car switch.predbat_car_charging_from_battery - prevent the car draining the home battery when charging switch.predbat_car_charging_manual_soc - ignore the car_charging_soc car SoC sensor set in apps.yaml input_number.predbat_car_charging_manual_soc_kwh - manually maintained car SoC (used if car SoC sensor is not available) Calculation options See the Predbat mode setting as above for basic calculation options input_number.predbat_forecast_plan_hours is the minimum length of the Predbat charge plan, and is the number of hours after the first charge slot to include in the plan. The default of 24 hours is the recommended value (to match energy rate cycles). Note that the actual length of the Predbat plan will vary depending upon when the first charge slot is. switch.predbat_calculate_export_oncharge ( expert mode ) When True calculated export slots will disable or move charge slots, allowing them to intermix. When False export slots will never be placed into charge slots. switch.predbat_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_inverter_set_charge_before - ( expert_mode ) When True charge slots will be programmed before their start time, when False they will only be configured when the charging time starts. switch.predbat_calculate_tweak_plan ( expert mode ) When True causes Predbat to perform a second pass optimisation across the next 8 charge and export windows in time order. 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 force export late. switch.predbat_calculate_second_pass ( expert mode ) When True causes Predbat to perform a second pass optimisation across all the charge and export windows in time order. 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 force export late. switch.calculate_import_low_export ( expert_mode ) When True import slots of the same value are sorted by export price. When False they are sorted just by price and then time. The default is True. By default with this option enabled if there are multiple charge slots of the same price Predbat will try to charge when the export rates are lowest thus leaving the higher export slots available. switch.calculate_export_high_import ( expert_mode ) When True export slots of the same value are sorted by import price (to avoid the low import slots for export). When False they are sorted just by price and then time. The default is False. By default with this option disabled the latest export slot of the same value will be picked, this is useful for fixed price export tariffs where you want to export as late in the day as you can. Battery margins and metrics options input_number.predbat_best_soc_keep is the minimum battery level in kWh that Predbat will to try to keep the battery above for the Predbat plan. This is a soft constraint only that's used for longer term planning and is ignored for the forthcoming first 4 hours of the plan. As this is not used for short-term planning it's possible for your SoC to drop below this - use input_number.predbat_best_soc_min if you want to force all charges to be above a set level. 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. input_number.predbat_best_soc_keep_weight ( expert_mode ) Is used to tune how strongly you want the keep metric to apply. A value of 0 would essentially ignore keep while higher values will make it more important to always stay above your keep threshold even if it costs more money to do so. The default is 0.5 - this is the recommended setting. input_number.predbat_best_soc_min ( expert mode ) sets the minimum charge level (in kWh) for charging during each slot and the minimum force export 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. input_number.predbat_best_soc_max ( expert mode ) sets the maximum charge level (in kWh) for charging during each slot. A value of 0 disables this feature. input_number.combine_rate_threshold ( expert mode ) sets a threshold (in pence) to combine charge or export slots together into a single larger average rate slot. The default is 0p which disables this feature and all rate changes result in a new slot. switch.predbat_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 disabled (False) switch.predbat_combine_export_slots ( expert mode ) Controls if export 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.predbat_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 input_number.predbat_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). input_number.predbat_metric_min_improvement_export ( expert mode ) Sets the minimum pence cost improvement it's worth doing a forced export for. A value of 5 is the default which prevents any marginal exports as they must be worth at least 5 pence for a 30 minute slot (less for shorter slots. If you increase this value (e.g. you only want to force export if definitely very profitable), then exports will become less common. The value is in pence per 30 minutes of export time. input_number.predbat_rate_low_threshold ( expert mode ) When set to 0 (the default) Predbat will automatically look at the future import rates in the plan and determine the import rate threshold below which a slot will be considered to be a potential charging slot. If rate_low_threshold is set to a non zero value this will set the threshold below future average import rates as the minimum to consider for a charge window, e.g. setting to 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. input_number.predbat_rate_high_threshold ( expert mode ) When set to 0 (the default) Predbat will automatically look at the future export rates in the plan and determine the threshold above which a slot can be considered a potential exporting slot. If rate_high_threshold is set to a non zero value this will set the threshold above future average export rates as the minimum export rate to consider exporting for, e.g. setting to 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. input_number.predbat_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. 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.predbat_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. switch.predbat_calculate_inday_adjustment ( expert mode ) Enabled by default with damping of 0.95. When enabled will calculate the difference between today's actual load and today's predicated load and adjust the rest of the days usage prediction accordingly. A scale factor can be set with input_number.predbat_metric_inday_adjust_damping ( expert mode ) to either scale up or down the impact of the in-day adjustment (lower numbers scale down its impact). The in-day adjustment factor can be seen in predbat.load_inday_adjustment and charted with the In Day Adjustment chart (template can be found in the charts template in Github). input_number.predbat_carbon_metric ( carbon enable ) When Carbon footprint tracking is enabled ( switch.predbat_carbon_enable ) you can specify a cost per Kg of CO2 used to weight the selection of plans. Values of around 10-200 will give varying outcomes to trade off cost vs carbon footprint of your system. Note: Carbon footprint tracking can only be enabled if apps.yaml is configured to point to the correct CO2 cost sensor Inverter control options switch.predbat_set_status_notify Enables mobile notification about changes to the Predbat state (e.g. Charge, Export etc). On by default. switch.predbat_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 automatically determined by Predbat to be the lowest possible rate to meet the charge target. This is only really effective for charge windows >30 minutes. If this setting is turned on, its strongly recommended that you create a battery_power_charge_curve in apps.yaml as otherwise the low power charge may not reach the charge target in time. This setting is off by default. The YouTube video low power charging and charging curve explains how the low power charging works and shows how Predbat automatically creates it. input_number.predbat_charge_low_power_margin ( set_charge_low_power ) Controls how many minutes before the completion time to target finishing charging, this defaults to 10 but can be changed between 0 and 30. switch.predbat_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. switch.predbat_set_export_freeze When enabled will allow Predbat to export Solar to the grid rather than charging the battery. Enabled by default on those inverters that have this support. switch.predbat_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. switch.predbat_set_export_freeze_only ( expert mode ) When enabled forced export is prevented, but export 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 switch.predbat_inverter_hybrid set to False then if switch.predbat_inverter_soc_reset ( expert mode ) is set to True then the target SOC % will be reset to 100% outside of a charge window. This may be required for the AIO inverter to ensure it charges from solar. The default for this switch is True but it can be disabled in expert mode if need be. input_number.predbat_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. If you want to pre-prepare the battery to retain extra charge in the event of a high likelihood of a grid power outage such as storms predicted, you can increase set_reserve_min to 100%, and then change it back afterwards. (Obviously this is only any use if your inverter is wired to act as an Emergency Power Supply or whole-home backup 'island mode' on the GivEnergy AIO). switch.predbat_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. Balance Inverters When you have two or more inverters it's possible they get out of sync so they are at different charge levels or they start to cross-charge (one discharges into another). When enabled, balance inverters tries to recover this situation by disabling either charging or discharging from one of the batteries until they re-align. The apps.yaml contains a setting balance_inverters_seconds which defines how often to run the balancing, 30 seconds is recommended if your machine is fast enough, but the default is 60 seconds. Enable the switch.predbat_balance_inverters_enable switch in Home Assistant to enable this feature. switch.predbat_balance_inverters_charge - Is used to toggle on/off balancing while the batteries are charging switch.predbat_balance_inverters_discharge - Is used to toggle on/off balancing while the batteries are discharging switch.predbat_balance_inverters_crosscharge - Is used to toggle on/off balancing when the batteries are cross charging input_number.predbat_balance_inverters_threshold_charge - Sets the minimum percentage divergence of SoC during charge before balancing, default is 1% input_number.predbat_balance_inverters_threshold_discharge - Sets the minimum percentage divergence of SoC during discharge before balancing, default is 1% Cloud coverage and load variance Predbat tries to model passing clouds by modulating the PV forecast data on a 5 minute interval up and down while retaining the same predicted total. The amount of modulation depends on the difference between the PV50% (default) and PV10% scenario produced by Solcast. You can disable this feature ( expert mode only ) using switch.predbat_metric_cloud_enable Predbat tries to model changes in your household load by modulating the historical data on a 5 minute interval up and down while retaining the same predicted total. The amount of modulation depends on the standard deviation of your load predictions over the coming period (currently 4 hours). You can disable this feature ( expert mode only ) using switch.metric_load_divergence_enable iBoost model options Predbat has an 'iBoost model' that can be used to model using excess solar energy to heat hot water (or similar) instead of it being exported to the grid. This model can be used to control any solar diverter device, for example an iBoost (e.g. using a Fingerbot or similar device to physically press the 'boost' button on the iBoost), a MyEnergy Eddi (using the MyEnergy integration), or it can be used with a high power smart switch to turn on the hot water cylinder immersion heater when there is excess solar. So although Predbat refers to controlling an iBoost, you are not limited to just an iBoost device when using this model within Predbat. To turn the model on, switch.predbat_iboost_enable needs to be enabled. The predicted output from the iBoost solar diverter model is returned in predbat.iboost_best and is populated in the 'iBoost' column of the Predbat plan . iBoost basic configuration When you turn on predbat_iBoost_enable the following additional Home Assistant entities are created by Predbat: input_number.predbat_iboost_max_energy Sets the maximum energy in kWh that the solar diverter can consume during a day before turning off - default 3kWh. input_number.predbat_iboost_max_power Sets the maximum power in watts that the solar diverter will consume - default 2400. input_number.predbat_iboost_min_power Sets the minimum power in watts that the solar diverter will consume - default 500. input_number.predbat_iboost_value_scaling Sets how to account for the value of iBoost units of energy. The default value of 0.75 means that each kWh of energy diverted is accounted for a 0.75 x The lowest future import rate. Higher values will generate plans with more solar diversion while lower values will generate less. A value of 0 means all diverted energy should be ignored in planning (assumed to be zero value). switch.predbat_iboost_energy_subtract When enabled (default) energy reported by the iboost_energy_today sensor configured in apps.yaml will be subtracted from your historical load data to improve the accuracy of predictions. If you are using PredAI you will also need to subtract this data inside PredAI configuration. Different boost modes can be selected: iBoost modes Solar switch.predbat_iboost_solar When enabled assumes the diverter will use solar power to boost the hot water heating. Only excess solar will be used, this is solar that will be otherwise exported and not stored in your battery. input_number.predbat_iboost_min_soc sets the minimum home battery SoC percentage that must be in the battery before the solar diverter is turned on. The default is 0 meaning hot water heating can occur regardless of what SoC level the battery is at. Battery switch.predbat_iboost_charging If set to on, the diverter will operate when the battery is charging (can be combined with solar) Energy rates only If both of the above are off, but iBoost is enabled then boost will happen solely based on energy rates (see below). switch.predbat_iboost_smart Will pick the lowest import rate slots within a 24-hour period to achieve the desired energy as specified by input_number.predbat_iboost_max_energy . Only slots of at or below the rate threshold will be selected. Note this option only applies when iboost_solar and iboost battery are both off. input_number.predbat_iboost_smart_min_length Sets the minimum slot length in minutes to iBoost for (only applies for energy rate only modes). The default is 30 minutes but can be set in multiples of 30. Increasing this slot size could increase costs depending on your tariff. switch.predbat_iboost_on_export If set to on allows iBoost to run even if the battery is force exporting to the grid, otherwise it won't run in these circumstances. switch.iboost_prevent_discharge When set will stop your battery from discharging when iBoost is active and thus prevent your battery from draining to the diverter. This switch will it will work in all modes is not recommended to be used when iBoost Solar is enabled as it will prevent your battery from discharging during excess solar periods which could cause additional imports due to passing clouds. iBoost energy rate filtering input_number.predbat_iboost_rate_threshold Sets the maximum import rate (in pence) that the diverter will trigger on, defaults to 100. input_number.predbat_iboost_rate_threshold_export Sets the maximum export rate (in pence) that the diverter will trigger on, defaults to 100. switch.predbat_iboost_gas When enabled will control the diverter to only operate when import electric rates are lower than gas rates. switch.predbat_iboost_gas_export When enabled will control the diverter to only operate when export electric rates are lower than gas rates. These can be useful if you have the choice to heat your hot water by immersion heater or by gas boiler. Note: Gas rates have to be configured in apps.yaml using metric_octopus_gas . input_number.predbat_iboost_gas_scale Sets the scaling of the gas rates (set in apps.yaml )used before comparing with electric rates, to account for gas boiler losses and efficiency. It should be set to the reciprocal of the boiler efficiency, i.e. for an 80% efficient gas boiler, set to 1.25. iBoost control iBoost output data You will see input_number.predbat_iboost_today entity which tracks the estimated kWh consumed by the solar diverter during the day, and resets at midnight every night. The binary_sensor.predbat_iboost_active entity will be enabled when the solar diverter should be active, can be used for automations to trigger the immersion heater boost. The attributes within this sensor include 'solar' which includes Solar diversion should be active and 'full' which indicates iboost should run at maximum rate (could be during a charge cycle or grid import). Example template automation for controlling the solar diverter: alias: Solar Diverter description: \"Start/stop solar diverter based on Predbat determined slots\" trigger: - platform: state entity_id: - binary_sensor.predbat_iboost_active action: - choose: - conditions: - condition: state entity_id: binary_sensor.predbat_iboost_active state: \"True\" sequence: - conditions: - condition: state entity_id: binary_sensor.predbat_iboost_active state: \"False\" sequence: mode: single If you have an incrementing sensor that tracks the solar diverter energy usage then to make your predictions more accurate you should set the iboost_energy_today sensor in apps.yaml to point to it, and optionally set iboost_energy_scaling if the sensor isn't in kWh (e.g. set to 0.001 if the sensor is in Watts). The sensor should be an incrementing sensor which can reset at midnight or not. Holiday mode When you go away you are likely to use less electricity and so the previous load data will be quite pessimistic. Using the Home Assistant entity input_number.predbat_holiday_days_left you can set the number of full days that you will be away for (including today). The number will count down by 1 day at midnight until it gets back to zero. Whilst holiday days left is non-zero, Predbat's 'holiday mode' is active. When Predbat's 'holiday mode' is active the historical load data will be taken from yesterday's data (1 day ago) rather than from the days_previous setting in apps.yaml . This means Predbat will adjust more quickly to the new usage pattern. If you have been away for a longer period of time (more than your normal days_previous setting) then obviously it's going to take longer for the historical data to catch up, you could then enable holiday mode for another 7 days after your return. In summary: For short holidays set holiday_days_left to the number of full days you are away, including today but excluding the return day For longer holidays set holiday_days_left to the number of days you are away plus another 7 days until the data catches back up Manual control 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 you should then control it yourself using GivTCP or the App appropriate to your inverter. A better alternative in some cases is to tell Predbat what you want it to do using the manual force features: 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 with an upside down 'F' symbol. 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_export selector can be used to manually force an export within a 30 minute slot in the same way as the manual force charge feature. The force export takes priority over force charging. The select.predbat_manual_demand selector is used to force Predbat to demand mode during a 30 minute slot, this implies no forced grid charging or exporting of the battery. House load will be supplied from solar, or from the battery if there is insufficient solar, or grid import if there is insufficient battery charge. This is described as 'ECO' Mode for GivEnergy inverters but other inverters use different terminology. The select.predbat_manual_freeze_charge selector is used to force Predbat to freeze charge during a 30 minute slot, this implies the battery will not discharge and hold at the current level. The grid maybe used if solar is not enough to cover the load. The select.predbat_manual_freeze_export selector is used to force Predbat to freeze export during a 30 minute slot, this implies the battery will not charge but will still discharge for the house load. Any solar will be exported to the grid. When you use the manual override features you can only select times in the next 18 hours, the overrides will be removed once their time slot expires (they do not repeat). _NOTE: once you select a time slot from any of the select.predbat_manual_ selectors the selected time slot is immediately marked on the drop-down and you can then make another change. Predbat still has to update the plan which it will be doing so in the background, and this can take a few minutes to run (depending on the speed and power of the PC you are running Home Assistant on) so don't be surprised why the Predbat plan doesn't change immediately - remember you can see the date/time the plan was last updated on the first row of the plan. CAUTION: If you leave Predbat turned off for a long period of time then the override timeslots could end up repeating when you restart Debug switch.predbat_debug_enable when on prints lots of debug, leave off by default switch.predbat_plan_debug ( expert mode ) when enabled adds some extra debug to the Predbat HTML plan - see Predbat Plan debug mode for more details.","title":"Customisation"},{"location":"customisation/#customisation","text":"This document describes the Predbat configuration items in Home Assistant that you can modify to customise Predbat to fit your needs. All of these settings are entities that can be configured directly in Home Assistant (unlike the ' apps.yaml ' configuration items that have to be edited with a file editor). See Displaying output data for information on how to view and edit these entities within Home Assistant.","title":"Customisation"},{"location":"customisation/#saving-and-restoring-predbat-settings","text":"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 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 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.","title":"Saving and restoring Predbat settings"},{"location":"customisation/#predbat-mode","text":"The mode that Predbat operates in will change the operation, this can be configured with select.predbat_mode drop down menu as follows: Monitor Control SOC Only Control charge Control charge & discharge If the switch.predbat_set_read_only is set to True then this prevents Predbat from making modifications to the inverter settings (regardless of the configuration). Predbat will continue making and updating its prediction plan every 5 minutes, but no inverter changes will be made. This is useful if you want to over-ride what Predbat is planning to do (e.g. your own automation), or whilst you are learning how Predbat works prior to turning it on 'in anger'. NOTE: Changing the Predbat mode or the read only switch will cause Predbat to reset the inverter settings to default, this will disable both charge and discharge, reset charge and discharge rates to full power and reset the reserve to the default setting","title":"Predbat mode"},{"location":"customisation/#predbat-monitor-mode","text":"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.","title":"Predbat Monitor mode"},{"location":"customisation/#predbat-control-soc-only-mode","text":"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 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: You must manually set any charging required on the inverter and if the charge window is disabled then no charging will take place.","title":"Predbat Control SOC only mode"},{"location":"customisation/#predbat-control-charge-mode","text":"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, you have a 'no export' limitation from your electricity supplier, or if you want to preserve the battery for home demand.","title":"Predbat Control charge mode"},{"location":"customisation/#predbat-control-charge-discharge-mode","text":"In Control charge & discharge mode Predbat will set both charge and force export (discharge) times and control charge and force export percentages. If you have set the switch.predbat_set_export_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.","title":"Predbat Control charge & discharge mode"},{"location":"customisation/#expert-mode","text":"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.","title":"Expert mode"},{"location":"customisation/#performance-related","text":"By default Predbat controls the inverter and updates the plan every 5 minutes, this can however use a lot of CPU power especially on more complex tariffs like Agile when run on lower power machines such as Raspberry PIs and some thin clients. You can tweak input_number.predbat_calculate_plan_every ( expert mode ) to reduce the frequency of replanning while keeping the inverter control in the 5 minute slots. E.g. a value of 10 or 15 minutes should also give good results. If you have performance problems leave switch.predbat_calculate_second_pass ( expert mode ) turned Off as it's quite CPU intensive and provides very little improvement for most systems. You can can enable combine_charge_slots and combine_export_slots in order to speed up planning. Note: Combining export slots may prevent optimal forced export. Combining charge slots is usually fine for tariffs with longer periods of fixed rates but can limit the planning ability in some cases. The number of threads you use can change your performance, you can set threads in apps.yaml to 0 to disable threading if you don't have multiple CPUs available or set it to 'auto' (the default) to use one thread per CPU. Its recommended you don't set this to an odd number of threads.","title":"Performance related"},{"location":"customisation/#battery-loss-options","text":"input_number.predbat_battery_loss is an assumed percentage figure for energy lost when charging the battery, the default 0.05 is 5%. input_number.predbat_battery_loss_discharge is an assumed percentage figure for energy lost whilst discharging the battery, the default 0.05 is 5%. input_number.predbat_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. TIP: Make sure you set the losses correctly, they are decimal percentages, don't set to '4' thinking it'll be 4%, Predbat will take this as being 400% and your plan will be very strange! switch.predbat_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.predbat_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 have a 9.5kWh battery and think it will last say 6000 complete cycles and it cost you \u00a34000, then each full charge and discharge cycle is 19kWh and so the cost per complete cycle is \u00a34000 / 19 / 6000 = 3.5p. Taking the 3.5p per cycle example, if you set predbat_metric_battery_cycle to 1.75 (half of 3.5) then Predbat will apply the \"virtual cost\" of 1.75p 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. If you configure this number higher then more expensive plans will be selected which avoids charging and discharging your battery as much. 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. Figures of around 0p-2p are recommended, the default is 0p per kWh. 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). input_number.metric_self_sufficiency ( expert mode ) A price in pence per kWh used to skew the calculations towards self sufficiency. Effectively saying to Predbat to account for imports at a higher price than reality in the calculation and thus selecting plans with less import. If you want to be as self sufficient as possible then set this to the difference between your lowest import rate and the highest export rate to take exports that require additional import appear unprofitable. This setting will not impact the real calculated costs and is only used for plan selection. Values of 5-10p maybe worth trying if you prefer to avoid importing even if it saves you money.","title":"Battery loss options"},{"location":"customisation/#scaling-and-weight-options","text":"input_number.predbat_battery_rate_max_scaling is a percentage factor to adjust your maximum charge rate from that reported by the inverter. For example a value of 0.95 would be 95% and indicate charging at 5% slower than reported. For GE inverters the charge rate reports the max AC rate and thus needs to be reduced by inverter losses. You can try computing your discharge curve and check recommendations for changing this figure in the logfile. input_number.predbat_battery_rate_max_scaling_discharge is a percentage factor to adjust your maximum discharge rate from that reported by the inverter. For GE inverters the discharge rate is reported as the max AC rate and thus is fairly accurate. You can try computing your discharge curve and check recommendations for changing this figure in the logfile. 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.predbat_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.predbat_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.predbat_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).","title":"Scaling and weight options"},{"location":"customisation/#solar-pv-adjustment-options","text":"See also PV configuration options in apps.yaml including explanation of PV10, PV50 and PV90 terminology. input_number.predbat_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.predbat_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.","title":"Solar PV adjustment options"},{"location":"customisation/#historical-load-data","text":"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 day from the list of days to use (provided you have more than 1 day selected in days_previous). This can be used to ignore a single low usage day in your average calculation. By default is feature is enabled but can be disabled only in expert mode.","title":"Historical load data"},{"location":"customisation/#car-charging","text":"There are a number of configuration items in Home Assistant for Predbat to control your car charging. These are described in detail in Car Charging and are listed here just for completeness: switch.predbat_car_charging_hold - remove historical car charging load from the house load input_number.predbat_car_charging_threshold - power threshold above which Predbat assumes the car is being charged input_number.predbat_car_charging_energy_scale - used to scale the car_charging_energy sensor in apps.yaml input_number.predbat_car_charging_rate - car's charging rate in kW per hour input_number.predbat_car_charging_loss - percentage energy lost when charging the car switch.predbat_octopus_intelligent_charging - controls whether Octopus Intelligent (via the Octopus Energy integration) controls the car charging or Predbat plans the car charging switch.predbat_octopus_intelligent_ignore_unplugged ( expert mode ) - used with Octopus Intelligent to prevent Predbat from assuming the car will be charging when the car is unplugged binary_sensor.predbat_car_charging_slot - set to True by Predbat when the car should be charged (Predbat-led charging) select.predbat_car_charging_plan_time - the time you want the car to be charged by switch.predbat_car_charging_plan_smart - allows Predbat to allocate car charging slots to the cheapest times rather than all low rate slots input_number.predbat_car_charging_plan_max_price - maximum price per kWh to pay when charging your car switch.predbat_car_charging_from_battery - prevent the car draining the home battery when charging switch.predbat_car_charging_manual_soc - ignore the car_charging_soc car SoC sensor set in apps.yaml input_number.predbat_car_charging_manual_soc_kwh - manually maintained car SoC (used if car SoC sensor is not available)","title":"Car Charging"},{"location":"customisation/#calculation-options","text":"See the Predbat mode setting as above for basic calculation options input_number.predbat_forecast_plan_hours is the minimum length of the Predbat charge plan, and is the number of hours after the first charge slot to include in the plan. The default of 24 hours is the recommended value (to match energy rate cycles). Note that the actual length of the Predbat plan will vary depending upon when the first charge slot is. switch.predbat_calculate_export_oncharge ( expert mode ) When True calculated export slots will disable or move charge slots, allowing them to intermix. When False export slots will never be placed into charge slots. switch.predbat_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_inverter_set_charge_before - ( expert_mode ) When True charge slots will be programmed before their start time, when False they will only be configured when the charging time starts. switch.predbat_calculate_tweak_plan ( expert mode ) When True causes Predbat to perform a second pass optimisation across the next 8 charge and export windows in time order. 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 force export late. switch.predbat_calculate_second_pass ( expert mode ) When True causes Predbat to perform a second pass optimisation across all the charge and export windows in time order. 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 force export late. switch.calculate_import_low_export ( expert_mode ) When True import slots of the same value are sorted by export price. When False they are sorted just by price and then time. The default is True. By default with this option enabled if there are multiple charge slots of the same price Predbat will try to charge when the export rates are lowest thus leaving the higher export slots available. switch.calculate_export_high_import ( expert_mode ) When True export slots of the same value are sorted by import price (to avoid the low import slots for export). When False they are sorted just by price and then time. The default is False. By default with this option disabled the latest export slot of the same value will be picked, this is useful for fixed price export tariffs where you want to export as late in the day as you can.","title":"Calculation options"},{"location":"customisation/#battery-margins-and-metrics-options","text":"input_number.predbat_best_soc_keep is the minimum battery level in kWh that Predbat will to try to keep the battery above for the Predbat plan. This is a soft constraint only that's used for longer term planning and is ignored for the forthcoming first 4 hours of the plan. As this is not used for short-term planning it's possible for your SoC to drop below this - use input_number.predbat_best_soc_min if you want to force all charges to be above a set level. 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. input_number.predbat_best_soc_keep_weight ( expert_mode ) Is used to tune how strongly you want the keep metric to apply. A value of 0 would essentially ignore keep while higher values will make it more important to always stay above your keep threshold even if it costs more money to do so. The default is 0.5 - this is the recommended setting. input_number.predbat_best_soc_min ( expert mode ) sets the minimum charge level (in kWh) for charging during each slot and the minimum force export 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. input_number.predbat_best_soc_max ( expert mode ) sets the maximum charge level (in kWh) for charging during each slot. A value of 0 disables this feature. input_number.combine_rate_threshold ( expert mode ) sets a threshold (in pence) to combine charge or export slots together into a single larger average rate slot. The default is 0p which disables this feature and all rate changes result in a new slot. switch.predbat_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 disabled (False) switch.predbat_combine_export_slots ( expert mode ) Controls if export 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.predbat_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 input_number.predbat_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). input_number.predbat_metric_min_improvement_export ( expert mode ) Sets the minimum pence cost improvement it's worth doing a forced export for. A value of 5 is the default which prevents any marginal exports as they must be worth at least 5 pence for a 30 minute slot (less for shorter slots. If you increase this value (e.g. you only want to force export if definitely very profitable), then exports will become less common. The value is in pence per 30 minutes of export time. input_number.predbat_rate_low_threshold ( expert mode ) When set to 0 (the default) Predbat will automatically look at the future import rates in the plan and determine the import rate threshold below which a slot will be considered to be a potential charging slot. If rate_low_threshold is set to a non zero value this will set the threshold below future average import rates as the minimum to consider for a charge window, e.g. setting to 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. input_number.predbat_rate_high_threshold ( expert mode ) When set to 0 (the default) Predbat will automatically look at the future export rates in the plan and determine the threshold above which a slot can be considered a potential exporting slot. If rate_high_threshold is set to a non zero value this will set the threshold above future average export rates as the minimum export rate to consider exporting for, e.g. setting to 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. input_number.predbat_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. 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.predbat_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. switch.predbat_calculate_inday_adjustment ( expert mode ) Enabled by default with damping of 0.95. When enabled will calculate the difference between today's actual load and today's predicated load and adjust the rest of the days usage prediction accordingly. A scale factor can be set with input_number.predbat_metric_inday_adjust_damping ( expert mode ) to either scale up or down the impact of the in-day adjustment (lower numbers scale down its impact). The in-day adjustment factor can be seen in predbat.load_inday_adjustment and charted with the In Day Adjustment chart (template can be found in the charts template in Github). input_number.predbat_carbon_metric ( carbon enable ) When Carbon footprint tracking is enabled ( switch.predbat_carbon_enable ) you can specify a cost per Kg of CO2 used to weight the selection of plans. Values of around 10-200 will give varying outcomes to trade off cost vs carbon footprint of your system. Note: Carbon footprint tracking can only be enabled if apps.yaml is configured to point to the correct CO2 cost sensor","title":"Battery margins and metrics options"},{"location":"customisation/#inverter-control-options","text":"switch.predbat_set_status_notify Enables mobile notification about changes to the Predbat state (e.g. Charge, Export etc). On by default. switch.predbat_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 automatically determined by Predbat to be the lowest possible rate to meet the charge target. This is only really effective for charge windows >30 minutes. If this setting is turned on, its strongly recommended that you create a battery_power_charge_curve in apps.yaml as otherwise the low power charge may not reach the charge target in time. This setting is off by default. The YouTube video low power charging and charging curve explains how the low power charging works and shows how Predbat automatically creates it. input_number.predbat_charge_low_power_margin ( set_charge_low_power ) Controls how many minutes before the completion time to target finishing charging, this defaults to 10 but can be changed between 0 and 30. switch.predbat_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. switch.predbat_set_export_freeze When enabled will allow Predbat to export Solar to the grid rather than charging the battery. Enabled by default on those inverters that have this support. switch.predbat_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. switch.predbat_set_export_freeze_only ( expert mode ) When enabled forced export is prevented, but export 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 switch.predbat_inverter_hybrid set to False then if switch.predbat_inverter_soc_reset ( expert mode ) is set to True then the target SOC % will be reset to 100% outside of a charge window. This may be required for the AIO inverter to ensure it charges from solar. The default for this switch is True but it can be disabled in expert mode if need be. input_number.predbat_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. If you want to pre-prepare the battery to retain extra charge in the event of a high likelihood of a grid power outage such as storms predicted, you can increase set_reserve_min to 100%, and then change it back afterwards. (Obviously this is only any use if your inverter is wired to act as an Emergency Power Supply or whole-home backup 'island mode' on the GivEnergy AIO). switch.predbat_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.","title":"Inverter control options"},{"location":"customisation/#balance-inverters","text":"When you have two or more inverters it's possible they get out of sync so they are at different charge levels or they start to cross-charge (one discharges into another). When enabled, balance inverters tries to recover this situation by disabling either charging or discharging from one of the batteries until they re-align. The apps.yaml contains a setting balance_inverters_seconds which defines how often to run the balancing, 30 seconds is recommended if your machine is fast enough, but the default is 60 seconds. Enable the switch.predbat_balance_inverters_enable switch in Home Assistant to enable this feature. switch.predbat_balance_inverters_charge - Is used to toggle on/off balancing while the batteries are charging switch.predbat_balance_inverters_discharge - Is used to toggle on/off balancing while the batteries are discharging switch.predbat_balance_inverters_crosscharge - Is used to toggle on/off balancing when the batteries are cross charging input_number.predbat_balance_inverters_threshold_charge - Sets the minimum percentage divergence of SoC during charge before balancing, default is 1% input_number.predbat_balance_inverters_threshold_discharge - Sets the minimum percentage divergence of SoC during discharge before balancing, default is 1%","title":"Balance Inverters"},{"location":"customisation/#cloud-coverage-and-load-variance","text":"Predbat tries to model passing clouds by modulating the PV forecast data on a 5 minute interval up and down while retaining the same predicted total. The amount of modulation depends on the difference between the PV50% (default) and PV10% scenario produced by Solcast. You can disable this feature ( expert mode only ) using switch.predbat_metric_cloud_enable Predbat tries to model changes in your household load by modulating the historical data on a 5 minute interval up and down while retaining the same predicted total. The amount of modulation depends on the standard deviation of your load predictions over the coming period (currently 4 hours). You can disable this feature ( expert mode only ) using switch.metric_load_divergence_enable","title":"Cloud coverage and load variance"},{"location":"customisation/#iboost-model-options","text":"Predbat has an 'iBoost model' that can be used to model using excess solar energy to heat hot water (or similar) instead of it being exported to the grid. This model can be used to control any solar diverter device, for example an iBoost (e.g. using a Fingerbot or similar device to physically press the 'boost' button on the iBoost), a MyEnergy Eddi (using the MyEnergy integration), or it can be used with a high power smart switch to turn on the hot water cylinder immersion heater when there is excess solar. So although Predbat refers to controlling an iBoost, you are not limited to just an iBoost device when using this model within Predbat. To turn the model on, switch.predbat_iboost_enable needs to be enabled. The predicted output from the iBoost solar diverter model is returned in predbat.iboost_best and is populated in the 'iBoost' column of the Predbat plan .","title":"iBoost model options"},{"location":"customisation/#iboost-basic-configuration","text":"When you turn on predbat_iBoost_enable the following additional Home Assistant entities are created by Predbat: input_number.predbat_iboost_max_energy Sets the maximum energy in kWh that the solar diverter can consume during a day before turning off - default 3kWh. input_number.predbat_iboost_max_power Sets the maximum power in watts that the solar diverter will consume - default 2400. input_number.predbat_iboost_min_power Sets the minimum power in watts that the solar diverter will consume - default 500. input_number.predbat_iboost_value_scaling Sets how to account for the value of iBoost units of energy. The default value of 0.75 means that each kWh of energy diverted is accounted for a 0.75 x The lowest future import rate. Higher values will generate plans with more solar diversion while lower values will generate less. A value of 0 means all diverted energy should be ignored in planning (assumed to be zero value). switch.predbat_iboost_energy_subtract When enabled (default) energy reported by the iboost_energy_today sensor configured in apps.yaml will be subtracted from your historical load data to improve the accuracy of predictions. If you are using PredAI you will also need to subtract this data inside PredAI configuration. Different boost modes can be selected:","title":"iBoost basic configuration"},{"location":"customisation/#iboost-modes","text":"","title":"iBoost modes"},{"location":"customisation/#solar","text":"switch.predbat_iboost_solar When enabled assumes the diverter will use solar power to boost the hot water heating. Only excess solar will be used, this is solar that will be otherwise exported and not stored in your battery. input_number.predbat_iboost_min_soc sets the minimum home battery SoC percentage that must be in the battery before the solar diverter is turned on. The default is 0 meaning hot water heating can occur regardless of what SoC level the battery is at.","title":"Solar"},{"location":"customisation/#battery","text":"switch.predbat_iboost_charging If set to on, the diverter will operate when the battery is charging (can be combined with solar)","title":"Battery"},{"location":"customisation/#energy-rates-only","text":"If both of the above are off, but iBoost is enabled then boost will happen solely based on energy rates (see below). switch.predbat_iboost_smart Will pick the lowest import rate slots within a 24-hour period to achieve the desired energy as specified by input_number.predbat_iboost_max_energy . Only slots of at or below the rate threshold will be selected. Note this option only applies when iboost_solar and iboost battery are both off. input_number.predbat_iboost_smart_min_length Sets the minimum slot length in minutes to iBoost for (only applies for energy rate only modes). The default is 30 minutes but can be set in multiples of 30. Increasing this slot size could increase costs depending on your tariff. switch.predbat_iboost_on_export If set to on allows iBoost to run even if the battery is force exporting to the grid, otherwise it won't run in these circumstances. switch.iboost_prevent_discharge When set will stop your battery from discharging when iBoost is active and thus prevent your battery from draining to the diverter. This switch will it will work in all modes is not recommended to be used when iBoost Solar is enabled as it will prevent your battery from discharging during excess solar periods which could cause additional imports due to passing clouds.","title":"Energy rates only"},{"location":"customisation/#iboost-energy-rate-filtering","text":"input_number.predbat_iboost_rate_threshold Sets the maximum import rate (in pence) that the diverter will trigger on, defaults to 100. input_number.predbat_iboost_rate_threshold_export Sets the maximum export rate (in pence) that the diverter will trigger on, defaults to 100. switch.predbat_iboost_gas When enabled will control the diverter to only operate when import electric rates are lower than gas rates. switch.predbat_iboost_gas_export When enabled will control the diverter to only operate when export electric rates are lower than gas rates. These can be useful if you have the choice to heat your hot water by immersion heater or by gas boiler. Note: Gas rates have to be configured in apps.yaml using metric_octopus_gas . input_number.predbat_iboost_gas_scale Sets the scaling of the gas rates (set in apps.yaml )used before comparing with electric rates, to account for gas boiler losses and efficiency. It should be set to the reciprocal of the boiler efficiency, i.e. for an 80% efficient gas boiler, set to 1.25.","title":"iBoost energy rate filtering"},{"location":"customisation/#iboost-control","text":"","title":"iBoost control"},{"location":"customisation/#iboost-output-data","text":"You will see input_number.predbat_iboost_today entity which tracks the estimated kWh consumed by the solar diverter during the day, and resets at midnight every night. The binary_sensor.predbat_iboost_active entity will be enabled when the solar diverter should be active, can be used for automations to trigger the immersion heater boost. The attributes within this sensor include 'solar' which includes Solar diversion should be active and 'full' which indicates iboost should run at maximum rate (could be during a charge cycle or grid import). Example template automation for controlling the solar diverter: alias: Solar Diverter description: \"Start/stop solar diverter based on Predbat determined slots\" trigger: - platform: state entity_id: - binary_sensor.predbat_iboost_active action: - choose: - conditions: - condition: state entity_id: binary_sensor.predbat_iboost_active state: \"True\" sequence: - conditions: - condition: state entity_id: binary_sensor.predbat_iboost_active state: \"False\" sequence: mode: single If you have an incrementing sensor that tracks the solar diverter energy usage then to make your predictions more accurate you should set the iboost_energy_today sensor in apps.yaml to point to it, and optionally set iboost_energy_scaling if the sensor isn't in kWh (e.g. set to 0.001 if the sensor is in Watts). The sensor should be an incrementing sensor which can reset at midnight or not.","title":"iBoost output data"},{"location":"customisation/#holiday-mode","text":"When you go away you are likely to use less electricity and so the previous load data will be quite pessimistic. Using the Home Assistant entity input_number.predbat_holiday_days_left you can set the number of full days that you will be away for (including today). The number will count down by 1 day at midnight until it gets back to zero. Whilst holiday days left is non-zero, Predbat's 'holiday mode' is active. When Predbat's 'holiday mode' is active the historical load data will be taken from yesterday's data (1 day ago) rather than from the days_previous setting in apps.yaml . This means Predbat will adjust more quickly to the new usage pattern. If you have been away for a longer period of time (more than your normal days_previous setting) then obviously it's going to take longer for the historical data to catch up, you could then enable holiday mode for another 7 days after your return. In summary: For short holidays set holiday_days_left to the number of full days you are away, including today but excluding the return day For longer holidays set holiday_days_left to the number of days you are away plus another 7 days until the data catches back up","title":"Holiday mode"},{"location":"customisation/#manual-control","text":"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 you should then control it yourself using GivTCP or the App appropriate to your inverter. A better alternative in some cases is to tell Predbat what you want it to do using the manual force features: 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 with an upside down 'F' symbol. 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_export selector can be used to manually force an export within a 30 minute slot in the same way as the manual force charge feature. The force export takes priority over force charging. The select.predbat_manual_demand selector is used to force Predbat to demand mode during a 30 minute slot, this implies no forced grid charging or exporting of the battery. House load will be supplied from solar, or from the battery if there is insufficient solar, or grid import if there is insufficient battery charge. This is described as 'ECO' Mode for GivEnergy inverters but other inverters use different terminology. The select.predbat_manual_freeze_charge selector is used to force Predbat to freeze charge during a 30 minute slot, this implies the battery will not discharge and hold at the current level. The grid maybe used if solar is not enough to cover the load. The select.predbat_manual_freeze_export selector is used to force Predbat to freeze export during a 30 minute slot, this implies the battery will not charge but will still discharge for the house load. Any solar will be exported to the grid. When you use the manual override features you can only select times in the next 18 hours, the overrides will be removed once their time slot expires (they do not repeat). _NOTE: once you select a time slot from any of the select.predbat_manual_ selectors the selected time slot is immediately marked on the drop-down and you can then make another change. Predbat still has to update the plan which it will be doing so in the background, and this can take a few minutes to run (depending on the speed and power of the PC you are running Home Assistant on) so don't be surprised why the Predbat plan doesn't change immediately - remember you can see the date/time the plan was last updated on the first row of the plan. CAUTION: If you leave Predbat turned off for a long period of time then the override timeslots could end up repeating when you restart","title":"Manual control"},{"location":"customisation/#debug","text":"switch.predbat_debug_enable when on prints lots of debug, leave off by default switch.predbat_plan_debug ( expert mode ) when enabled adds some extra debug to the Predbat HTML plan - see Predbat Plan debug mode for more details.","title":"Debug"},{"location":"developing/","text":"Developing on Predbat Creating a fork Using GitHub, take a fork of Predbat - effectively, this creates a copy of the main repository, but in your personal space. There, you can create branches to develop on. Pull requests Once you've completed your work on your branch, you can create a pull request (PR) to merge your work back in to the main branch of Predbat. This PR should describe the work you've done in a way that makes it easy for someone to review your work, and either add comments or approve it. Unit level testing Note you will need to install python_matplotlib (e.g. brew install python_matplotlib or pip install matplotlib) Predbat now has some unit level tests, to run them on your local machine: Create a test directory somewhere Copy apps.yaml to your test area Run python3 /path/6adb4f0d_predbat/unit_test.py If the tests fail then debug them. For coverage analysis installed the 'coverage' library with Python python3 -m coverage run /path/6adb4f0d_predbat/unit_test.py python3 -m coverage html Open htmlcov/index.html in your web browser Editing the code There are at least a couple of ways of working on the code, outlined here. Using GitHub Codespaces What is GitHub Codespaces? Especially if you don't need to have a running Home Assistant system to make the changes you're interested in (e.g. for documentation, quick fixes etc.) a really easy way to work on the code is using GitHub Codespaces. GitHub Codespaces gives you a full featured development environment. This includes: A full IDE (a code editor), Visual Studio Code, which can be: Run in the browser, requiring no additional software to be installed Run in a virtual machine (VM) running in the cloud which can connect to a copy of VS Code installed on your own machine A terminal where you can run commands against your codebase e.g. running pre-commit to run the automatic code quality checks, linting files, etc. Software like mkdocs to re-generate the documentation files (and other software we may include) pre-installed in it The Codespaces environment is entirely separate from your HA installation, so does not require any modification to your HA setup to work with it. However, you are modifying code in an environment where you can't see HA running, so it's great for things like updating documentation, or writing automated tests, but not if you need to see your changes live within HA. Running GitHub Codespaces You may with to first install VS Code on your machine, which does offer some benefits compared to running Codespaces in the cloud, but this is certainly not essential, and you'll see the same code editor and terminal, and you'll have the same commands and Python packages available in the terminal. The local installation is better in a small number of scenarios e.g. if you need to connect from your browser to a specific port on the VM, such as if you're working on the documentation. Importantly, even if you do a local install of VS Code and use that to edit your code within GitHub, the terminal, the code you're editing any commands that you run, and any processes like mkdocs that you may browse to are all running in the Codespaces VM. Your local VS Code is connected to the VM through SSH. It will appear as if the code, the terminal etc. are local, but they are not. Running a local VS Code install connected to Codespaces will not install Python, Python packages or anything else on your local machine. Now, from your fork or branch, click on the Code button, and select the Codespaces tab. You can create multiple environments, or use a single environment and swap between branches in it. Once you start your Codespaces environment, it'll take a minute to create a VM for you, and to install the software we've asked it to install in there. It will also clone your repository and chosen branch into it for you, and the VM will be authenticated with GitHub so you can commit and push straight back to your fork of Predbat on GitHub. You can choose between running the IDE in the browser, or having your local installation of VS Code connect to the environment that GitHub Codespaces has created for you. The Codespaces will be already set up with Python, along with various Python packages (as defined in requirements.txt ). The environment is configured through the config in .devcontainer/devcontainer.json . Developing locally within Home Assistant To be documented later. Working on the documentation Overview of the Predbat documentation The documentation site at https://springfall2008.github.io/batpred/ is built from Markdown files in this repo. The Markdown files used to build the documentation are in the docs/ folder, with additional config for building the documentation site in mkdocs.yml . If you're making minor changes to the documentation e.g. fixing a spelling, you can just edit the Markdown files directly, and it will be pushed to the main documentation site as outlined in the documentation build process section below, once your changes are merged into main and released. However, if you're doing more than that, e.g. adding new sections, working with lists etc. we recommend you follow the instructions in working locally on the documentation below, as this will give you a live preview of what the documentation will look like once it's build and published. This will avoid any unexpected results appearing in the main documentation site. If you are adding a new file, please ensure you add that file to mkdocs.yml , so it will be linked from the menu in the sidebar. The documentation build process The documentation for the site is built using mkdocs , which will already be installed if you're using a GitHub Codespaces environment. For a detailed explanation of mkdocs features, please read the mkdocs documentation . As briefly covered above, mkdocs.yml contains the config for defining the documentation site, and the documentation is built by mkdocs reading the Markdown files in the docs/ folder, and creating HTML files from those files. mkdocs can be used locally for previewing, but is also used as part of the documentation build process that publishes the official documentation site. The publishing of the documentation is triggered by a GitHub action, as defined in .github/workflows/main.yml . In short, after configuring the build environment, mkdocs builds the site, then pushes the HTML produced to the gh-pages branch, overwriting whatever was there previously. GitHub will then detect a new commit on the gh-pages branch, and that will trigger another action to run (as defined by GitHub). This action will take the HTML files on the gh-pages branch, and will make it available at https://springfall2008.github.io/batpred/ . The documentation will be published as it is, with no further review process, so please ensure you check the documentation that will be built before merging it in. Working locally on the documentation If you are making changes to the documentation, you can see a live preview version of the documentation as it will be built and deployed. This preview version is local to your environment, is temporary, and does not impact the published version in any way. It's recommended for anything other than simple changes like fixing spellings, adding a sentence or two. Things like new sections, lists, new pages etc. are best previewed due to the complications of various Markdown standards, as what works on GitHub READMEs, for example, does not necessarily work with the published documentation site (which follows a more strict Markdown standard). There are a number of terminal commands that you can use in the Codespaces environment. Open a terminal window in Codespaces by choosing menu > Terminal > New Terminal. To run the live preview, enter mkdocs serve in the terminal window - this will cause mkdocs to build a local temporary version of the documentation site, and to temporarily publish it on port 8000 - it will show the link where you can access the documentation. Also, it will watch the docs/ folder, and any time you change the files, it will rebuild the site, allowing you to see changes to the Markdown files in your browser within a few seconds. The site will continue being served until you press CTRL-C to end the mkdocs serve command. Note, accessing the site published by mkdocs serve is not possible if you are using Codespaces to run VS Code in the browser, but it is possible if you're using it via VS Code running locally, due to the way in which ports on your environment are shared. Coding standards Expected standards This section will be enhanced following discussions as we go. However, here's a starting point: Variable names should be lower_case_with_underscores - this fits with most existing variables, is a common standard for Python code, and also allows the spell checking to check individual words within the variable name. Enforced standards Certain coding standards are enforced within the repository. Some of them can be auto-fixed, if you do a commit that fails one of those standards; other issues will need fixing first, as your pull request won't merge in GitHub until it passes. These standards are enforced by pre-commit , a tool which is able to run other tools to check, and potentially fix (for certain types of issues) any mistakes you've made. The .pre-commit-config.yaml file lists all checks that are currently carried out within the repository. Bear in mind that these checks are done according to the config within that file in the branch that you are working in, so if someone adds a new check, or changes some of the related settings, it won't apply on your branch until you've merged in their changes. Some of the tools have their own related config files: CSpell - .cspell.json and .cspell/custom-dictionary-workspace.txt Black - pyproject.toml Markdown Lint - .markdownlint.jsonc Additional notes on some of the standards: CSpell - if you have the spelling check failing due to a word which is valid but is not in the in-built dictionary, please add that word to the end of .cspell/custom-dictionary-workspace.txt and stage those changes. The spell-check should then pass. Note, the dictionary file will get re-sorted alphabetically when you run pre-commit , so you'll need to re-stage the file after it's been sorted. Running the checks locally If you are using a Codespaces environment, you'll already have pre-commit installed automatically. You can run it manually, or automatically. Running pre-commit manually: In a terminal window, running pre-commit will run all the checks against any files that you have modified and staged. Alternatively, running pre-commit run --all-files will run all the checks against all files within the repository. Note that if pre-commit makes any changes to any files when it runs, those changes will not be staged. You will need to stage those changes too before committing. You may notice pre-commit mentioning about stashing changes - this is because when it runs, any changes that aren't staged are stashed (saved away temporarily) so it runs against only the staged changes; after it has run, it pulls back those stashed changes, so they appear again (still unstaged). Running pre-commit automatically: If you run pre-commit install in a terminal window it will install a pre-commit hook - this is a file which tells git to run some code each type you do a particular action (a pre-commit hook runs at the start of processing a commit, but there are other hooks e.g. pre-push). Now, any time you perform a commit, pre-commit will run automatically on the staged files - this is a handy way of making sure that you don't accidentally commit code which will fail checks later. You can still run it manually as outlined above, in addition to the automated checks that it will do on commits. Running the checks from within GitHub When commits are done on pull requests, and in any other scenarios added to the on section of .github/workflows/linting.yml , the GitHub Actions in that file will run. In particular, the pre-commit.ci lite action will run. This uses the code here to run the same checks that get run locally (as described in the .pre-commit-config.yaml file). This will cause your commit, branch or pull request to get either a green tick or a red cross against it, to show whether the code passed the checks or not. This will happen automatically, when you push code on a branch that has a pull request. In addition, if pre-commit finds any errors that it is able to fix (e.g. a missing blank line at the end of a file, or trailing whitespace), it will do a commit of its own to fix those problems, and will push that commit back to your branch on GitHub. This will then trigger another run, which should now pass. Note : This means that pre-commit will be adding commits to your branch - this will need you to be pulling changes from GitHub so you pick up the changes that have been added by pre-commit otherwise you will hit a problem when you next try to push a commit on your branch. You can pull in those changes by running git pull , which is the equivalent of running git fetch then git merge . This is no different to working on the same branch with another developer, but it will be different to the workflow most of us have when working on Predbat.","title":"Developing on Predbat"},{"location":"developing/#developing-on-predbat","text":"","title":"Developing on Predbat"},{"location":"developing/#creating-a-fork","text":"Using GitHub, take a fork of Predbat - effectively, this creates a copy of the main repository, but in your personal space. There, you can create branches to develop on.","title":"Creating a fork"},{"location":"developing/#pull-requests","text":"Once you've completed your work on your branch, you can create a pull request (PR) to merge your work back in to the main branch of Predbat. This PR should describe the work you've done in a way that makes it easy for someone to review your work, and either add comments or approve it.","title":"Pull requests"},{"location":"developing/#unit-level-testing","text":"Note you will need to install python_matplotlib (e.g. brew install python_matplotlib or pip install matplotlib) Predbat now has some unit level tests, to run them on your local machine: Create a test directory somewhere Copy apps.yaml to your test area Run python3 /path/6adb4f0d_predbat/unit_test.py If the tests fail then debug them. For coverage analysis installed the 'coverage' library with Python python3 -m coverage run /path/6adb4f0d_predbat/unit_test.py python3 -m coverage html Open htmlcov/index.html in your web browser","title":"Unit level testing"},{"location":"developing/#editing-the-code","text":"There are at least a couple of ways of working on the code, outlined here.","title":"Editing the code"},{"location":"developing/#using-github-codespaces","text":"","title":"Using GitHub Codespaces"},{"location":"developing/#what-is-github-codespaces","text":"Especially if you don't need to have a running Home Assistant system to make the changes you're interested in (e.g. for documentation, quick fixes etc.) a really easy way to work on the code is using GitHub Codespaces. GitHub Codespaces gives you a full featured development environment. This includes: A full IDE (a code editor), Visual Studio Code, which can be: Run in the browser, requiring no additional software to be installed Run in a virtual machine (VM) running in the cloud which can connect to a copy of VS Code installed on your own machine A terminal where you can run commands against your codebase e.g. running pre-commit to run the automatic code quality checks, linting files, etc. Software like mkdocs to re-generate the documentation files (and other software we may include) pre-installed in it The Codespaces environment is entirely separate from your HA installation, so does not require any modification to your HA setup to work with it. However, you are modifying code in an environment where you can't see HA running, so it's great for things like updating documentation, or writing automated tests, but not if you need to see your changes live within HA.","title":"What is GitHub Codespaces?"},{"location":"developing/#running-github-codespaces","text":"You may with to first install VS Code on your machine, which does offer some benefits compared to running Codespaces in the cloud, but this is certainly not essential, and you'll see the same code editor and terminal, and you'll have the same commands and Python packages available in the terminal. The local installation is better in a small number of scenarios e.g. if you need to connect from your browser to a specific port on the VM, such as if you're working on the documentation. Importantly, even if you do a local install of VS Code and use that to edit your code within GitHub, the terminal, the code you're editing any commands that you run, and any processes like mkdocs that you may browse to are all running in the Codespaces VM. Your local VS Code is connected to the VM through SSH. It will appear as if the code, the terminal etc. are local, but they are not. Running a local VS Code install connected to Codespaces will not install Python, Python packages or anything else on your local machine. Now, from your fork or branch, click on the Code button, and select the Codespaces tab. You can create multiple environments, or use a single environment and swap between branches in it. Once you start your Codespaces environment, it'll take a minute to create a VM for you, and to install the software we've asked it to install in there. It will also clone your repository and chosen branch into it for you, and the VM will be authenticated with GitHub so you can commit and push straight back to your fork of Predbat on GitHub. You can choose between running the IDE in the browser, or having your local installation of VS Code connect to the environment that GitHub Codespaces has created for you. The Codespaces will be already set up with Python, along with various Python packages (as defined in requirements.txt ). The environment is configured through the config in .devcontainer/devcontainer.json .","title":"Running GitHub Codespaces"},{"location":"developing/#developing-locally-within-home-assistant","text":"To be documented later.","title":"Developing locally within Home Assistant"},{"location":"developing/#working-on-the-documentation","text":"","title":"Working on the documentation"},{"location":"developing/#overview-of-the-predbat-documentation","text":"The documentation site at https://springfall2008.github.io/batpred/ is built from Markdown files in this repo. The Markdown files used to build the documentation are in the docs/ folder, with additional config for building the documentation site in mkdocs.yml . If you're making minor changes to the documentation e.g. fixing a spelling, you can just edit the Markdown files directly, and it will be pushed to the main documentation site as outlined in the documentation build process section below, once your changes are merged into main and released. However, if you're doing more than that, e.g. adding new sections, working with lists etc. we recommend you follow the instructions in working locally on the documentation below, as this will give you a live preview of what the documentation will look like once it's build and published. This will avoid any unexpected results appearing in the main documentation site. If you are adding a new file, please ensure you add that file to mkdocs.yml , so it will be linked from the menu in the sidebar.","title":"Overview of the Predbat documentation"},{"location":"developing/#the-documentation-build-process","text":"The documentation for the site is built using mkdocs , which will already be installed if you're using a GitHub Codespaces environment. For a detailed explanation of mkdocs features, please read the mkdocs documentation . As briefly covered above, mkdocs.yml contains the config for defining the documentation site, and the documentation is built by mkdocs reading the Markdown files in the docs/ folder, and creating HTML files from those files. mkdocs can be used locally for previewing, but is also used as part of the documentation build process that publishes the official documentation site. The publishing of the documentation is triggered by a GitHub action, as defined in .github/workflows/main.yml . In short, after configuring the build environment, mkdocs builds the site, then pushes the HTML produced to the gh-pages branch, overwriting whatever was there previously. GitHub will then detect a new commit on the gh-pages branch, and that will trigger another action to run (as defined by GitHub). This action will take the HTML files on the gh-pages branch, and will make it available at https://springfall2008.github.io/batpred/ . The documentation will be published as it is, with no further review process, so please ensure you check the documentation that will be built before merging it in.","title":"The documentation build process"},{"location":"developing/#working-locally-on-the-documentation","text":"If you are making changes to the documentation, you can see a live preview version of the documentation as it will be built and deployed. This preview version is local to your environment, is temporary, and does not impact the published version in any way. It's recommended for anything other than simple changes like fixing spellings, adding a sentence or two. Things like new sections, lists, new pages etc. are best previewed due to the complications of various Markdown standards, as what works on GitHub READMEs, for example, does not necessarily work with the published documentation site (which follows a more strict Markdown standard). There are a number of terminal commands that you can use in the Codespaces environment. Open a terminal window in Codespaces by choosing menu > Terminal > New Terminal. To run the live preview, enter mkdocs serve in the terminal window - this will cause mkdocs to build a local temporary version of the documentation site, and to temporarily publish it on port 8000 - it will show the link where you can access the documentation. Also, it will watch the docs/ folder, and any time you change the files, it will rebuild the site, allowing you to see changes to the Markdown files in your browser within a few seconds. The site will continue being served until you press CTRL-C to end the mkdocs serve command. Note, accessing the site published by mkdocs serve is not possible if you are using Codespaces to run VS Code in the browser, but it is possible if you're using it via VS Code running locally, due to the way in which ports on your environment are shared.","title":"Working locally on the documentation"},{"location":"developing/#coding-standards","text":"","title":"Coding standards"},{"location":"developing/#expected-standards","text":"This section will be enhanced following discussions as we go. However, here's a starting point: Variable names should be lower_case_with_underscores - this fits with most existing variables, is a common standard for Python code, and also allows the spell checking to check individual words within the variable name.","title":"Expected standards"},{"location":"developing/#enforced-standards","text":"Certain coding standards are enforced within the repository. Some of them can be auto-fixed, if you do a commit that fails one of those standards; other issues will need fixing first, as your pull request won't merge in GitHub until it passes. These standards are enforced by pre-commit , a tool which is able to run other tools to check, and potentially fix (for certain types of issues) any mistakes you've made. The .pre-commit-config.yaml file lists all checks that are currently carried out within the repository. Bear in mind that these checks are done according to the config within that file in the branch that you are working in, so if someone adds a new check, or changes some of the related settings, it won't apply on your branch until you've merged in their changes. Some of the tools have their own related config files: CSpell - .cspell.json and .cspell/custom-dictionary-workspace.txt Black - pyproject.toml Markdown Lint - .markdownlint.jsonc Additional notes on some of the standards: CSpell - if you have the spelling check failing due to a word which is valid but is not in the in-built dictionary, please add that word to the end of .cspell/custom-dictionary-workspace.txt and stage those changes. The spell-check should then pass. Note, the dictionary file will get re-sorted alphabetically when you run pre-commit , so you'll need to re-stage the file after it's been sorted.","title":"Enforced standards"},{"location":"developing/#running-the-checks-locally","text":"If you are using a Codespaces environment, you'll already have pre-commit installed automatically. You can run it manually, or automatically. Running pre-commit manually: In a terminal window, running pre-commit will run all the checks against any files that you have modified and staged. Alternatively, running pre-commit run --all-files will run all the checks against all files within the repository. Note that if pre-commit makes any changes to any files when it runs, those changes will not be staged. You will need to stage those changes too before committing. You may notice pre-commit mentioning about stashing changes - this is because when it runs, any changes that aren't staged are stashed (saved away temporarily) so it runs against only the staged changes; after it has run, it pulls back those stashed changes, so they appear again (still unstaged). Running pre-commit automatically: If you run pre-commit install in a terminal window it will install a pre-commit hook - this is a file which tells git to run some code each type you do a particular action (a pre-commit hook runs at the start of processing a commit, but there are other hooks e.g. pre-push). Now, any time you perform a commit, pre-commit will run automatically on the staged files - this is a handy way of making sure that you don't accidentally commit code which will fail checks later. You can still run it manually as outlined above, in addition to the automated checks that it will do on commits.","title":"Running the checks locally"},{"location":"developing/#running-the-checks-from-within-github","text":"When commits are done on pull requests, and in any other scenarios added to the on section of .github/workflows/linting.yml , the GitHub Actions in that file will run. In particular, the pre-commit.ci lite action will run. This uses the code here to run the same checks that get run locally (as described in the .pre-commit-config.yaml file). This will cause your commit, branch or pull request to get either a green tick or a red cross against it, to show whether the code passed the checks or not. This will happen automatically, when you push code on a branch that has a pull request. In addition, if pre-commit finds any errors that it is able to fix (e.g. a missing blank line at the end of a file, or trailing whitespace), it will do a commit of its own to fix those problems, and will push that commit back to your branch on GitHub. This will then trigger another run, which should now pass. Note : This means that pre-commit will be adding commits to your branch - this will need you to be pulling changes from GitHub so you pick up the changes that have been added by pre-commit otherwise you will hit a problem when you next try to push a commit on your branch. You can pull in those changes by running git pull , which is the equivalent of running git fetch then git merge . This is no different to working on the same branch with another developer, but it will be different to the workflow most of us have when working on Predbat.","title":"Running the checks from within GitHub"},{"location":"devices/","text":"Support 3rd party devices/integrations Wallbox Pulsar https://www.home-assistant.io/integrations/wallbox/ Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in car_charging_energy: 're:sensor.wallbox_portal_added_energy' car_charging_planned: - 're:sensor.wallbox_portal_status_description' Wallbox works with Octopus Intelligent GO, and can be triggered via Octopus themselves or via a HA automation linked to the Predbat slot sensor Zappi https://github.com/CJNE/ha-myenergi Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in car_charging_energy: 're:sensor.myenergi_zappi_[0-9a-z]+_charge_added_session' car_charging_planned: - 're:sensor.myenergi_zappi_[0-9a-z]+_plug_status)' Tesla https://github.com/alandtse/tesla Can be used to extract the cars current SOC and Charge limit. Also can be used to control the cars charging with an automation linked to the Predbat slot sensor car_charging_limit: - 're:number.xxx_charge_limit' car_charging_soc: - 're:sensor.xxx_battery' Toyota https://github.com/DurgNomis-drol/ha_toyota - For Toyota EU cars only Can be used to extract the cars current SOC. car_charging_soc: - 'sensor.toyota_XXX_battery_level' Example sensor name for BZ4X - sensor.toyota_bz4x_battery_level Renault https://www.home-assistant.io/integrations/renault Can be used to extract the cars current SoC. car_charging_soc: - 'sensor.battery' Ohme https://github.com/dan-r/HomeAssistant-Ohme Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in. Also can be used with Octopus Intelligent GO to map out the cars charging slots into Predbat car charging energy car_charging_energy: 'sensor.ohme_session_energy' Octopus Intelligent GO octopus_intelligent_slot: 'binary_sensor.ohme_slot_active' octopus_ready_time: 'time.ohme_target_time' octopus_charge_limit: 'number.ohme_target_percent' Note: You should turn on switch.predbat_octopus_intelligent_ignore_unplugged as the Ohme charger does not clear its schedule when unplugged. Using Ohme car charging plans on other tariff's e.g. Agile octopus_intelligent_slot: 'binary_sensor.ohme_slot_active' octopus_ready_time: 'time.ohme_target_time' octopus_charge_limit: 'number.ohme_target_percent' octopus_slot_low_rate: False Note: You should turn on switch.predbat_octopus_intelligent_ignore_unplugged as the Ohme charger does not clear its schedule when unplugged. Determine if the car is charging now Normally not recommended if you are on Intelligent GO, but can be useful for ad-hoc charging not planned via Predbat car_charging_now: - 'binary_sensor.ohme_car_charging' PodPoint https://github.com/mattrayner/pod-point-home-assistant-component Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in. car_charging_energy: 're:(sensor.psl_[0-9]+_current_energy)' car_charging_planned: - 're:(sensor.psl_[0-9]+_status)' car_charging_planned_response: - 'plugged in' - 'connected-waiting-for-schedule' - 'suspended-evse' - 'pending' - 'charging' car_charging_now: - 're:(sensor.psl_[0-9]+_status)' car_charging_now_response: - 'charging' Also can be used to control the cars charging with an automation linked to the Predbat slot sensor. The device needs to be set to 'Smart' mode in the PodPoint app. Your automation trigger should then set the switch.psl_XXXXXX_charging_allowed to on. And off to stop charging. This uses the PodPoint schedule override setting to start/stop the charge. Hypervolt https://github.com/gndean/home-assistant-hypervolt-charger Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in (only V3 models). For plugged in detection on V2 models, see guidance https://springfall2008.github.io/batpred/car-charging/#example-ev-and-charger-setup . car_charging_energy: 're:(sensor.hypervolt_session_energy_total_increasing)' car_charging_planned: - 're:(binary_sensor.hypervolt_car_plugged)' car_charging_planned_response: - 'on' car_charging_now: - 're:(sensor.hypervolt_charging_readiness)' car_charging_now_response: - 'charging' Note: sensor.hypervolt_session_energy_total_increasing defaults to 'unknown' between charging sessions. Agile Tariff To automate the schedule charging with Predbat, setup the automation to detect when there is a change to binary_sensor.predbat_car_charging_slot . Ensure that select.hypervolt_charge_mode is in 'Boost', when predbat charging slot is 'on', set select.hypervolt_activation_mode to 'Plug and Charge', when it is 'off' set the 'Schedule', this is the recommended method for start/stop charging. Octopus Energy https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy Can be used for energy rates, car charging and saving sessions For energy rate metric_octopus_import: 're:(sensor.(octopus_energy_|)electricity_[0-9a-z]+_[0-9a-z]+_current_rate)' metric_octopus_export: 're:(sensor.(octopus_energy_|)electricity_[0-9a-z]+_[0-9a-z]+_export_current_rate)' For Octopus Intelligent GO octopus_intelligent_slot: 're:(binary_sensor.octopus_energy([0-9a-z_]+|)_intelligent_dispatching)' octopus_ready_time: 're:(time.octopus_energy([0-9a-z_]+|)_intelligent_ready_time)' octopus_charge_limit: 're:(number.octopus_energy([0-9a-z_]+|)_intelligent_charge_limit)' For Octopus Saving sessions octopus_saving_session: 're:(binary_sensor.octopus_energy([0-9a-z_]+|)_saving_session(s|))' octopus_saving_session_octopoints_per_penny: 8 Nordpool For adjustment to Octopus Intelligent This is built into Predbat, see the apps.yaml configuration guide As your energy rates (e.g. for those in Norway) https://github.com/custom-components/nordpool/ Can be linked to Predbat to provide energy rates in your region e.g: metric_octopus_import: 'sensor.nordpool_kwh_oslo_eur_3_10_025' Solcast https://github.com/BJReplay/ha-solcast-solar For solar forecast data pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today) pv_forecast_tomorrow: re:(sensor.(solcast_|)(pv_forecast_|)forecast_tomorrow) pv_forecast_d3: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_3|d3)) pv_forecast_d4: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_4|d4))","title":"Support 3rd party devices/integrations"},{"location":"devices/#support-3rd-party-devicesintegrations","text":"","title":"Support 3rd party devices/integrations"},{"location":"devices/#wallbox-pulsar","text":"https://www.home-assistant.io/integrations/wallbox/ Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in car_charging_energy: 're:sensor.wallbox_portal_added_energy' car_charging_planned: - 're:sensor.wallbox_portal_status_description' Wallbox works with Octopus Intelligent GO, and can be triggered via Octopus themselves or via a HA automation linked to the Predbat slot sensor","title":"Wallbox Pulsar"},{"location":"devices/#zappi","text":"https://github.com/CJNE/ha-myenergi Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in car_charging_energy: 're:sensor.myenergi_zappi_[0-9a-z]+_charge_added_session' car_charging_planned: - 're:sensor.myenergi_zappi_[0-9a-z]+_plug_status)'","title":"Zappi"},{"location":"devices/#tesla","text":"https://github.com/alandtse/tesla Can be used to extract the cars current SOC and Charge limit. Also can be used to control the cars charging with an automation linked to the Predbat slot sensor car_charging_limit: - 're:number.xxx_charge_limit' car_charging_soc: - 're:sensor.xxx_battery'","title":"Tesla"},{"location":"devices/#toyota","text":"https://github.com/DurgNomis-drol/ha_toyota - For Toyota EU cars only Can be used to extract the cars current SOC. car_charging_soc: - 'sensor.toyota_XXX_battery_level' Example sensor name for BZ4X - sensor.toyota_bz4x_battery_level","title":"Toyota"},{"location":"devices/#renault","text":"https://www.home-assistant.io/integrations/renault Can be used to extract the cars current SoC. car_charging_soc: - 'sensor.battery'","title":"Renault"},{"location":"devices/#ohme","text":"https://github.com/dan-r/HomeAssistant-Ohme Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in. Also can be used with Octopus Intelligent GO to map out the cars charging slots into Predbat car charging energy car_charging_energy: 'sensor.ohme_session_energy' Octopus Intelligent GO octopus_intelligent_slot: 'binary_sensor.ohme_slot_active' octopus_ready_time: 'time.ohme_target_time' octopus_charge_limit: 'number.ohme_target_percent' Note: You should turn on switch.predbat_octopus_intelligent_ignore_unplugged as the Ohme charger does not clear its schedule when unplugged. Using Ohme car charging plans on other tariff's e.g. Agile octopus_intelligent_slot: 'binary_sensor.ohme_slot_active' octopus_ready_time: 'time.ohme_target_time' octopus_charge_limit: 'number.ohme_target_percent' octopus_slot_low_rate: False Note: You should turn on switch.predbat_octopus_intelligent_ignore_unplugged as the Ohme charger does not clear its schedule when unplugged. Determine if the car is charging now Normally not recommended if you are on Intelligent GO, but can be useful for ad-hoc charging not planned via Predbat car_charging_now: - 'binary_sensor.ohme_car_charging'","title":"Ohme"},{"location":"devices/#podpoint","text":"https://github.com/mattrayner/pod-point-home-assistant-component Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in. car_charging_energy: 're:(sensor.psl_[0-9]+_current_energy)' car_charging_planned: - 're:(sensor.psl_[0-9]+_status)' car_charging_planned_response: - 'plugged in' - 'connected-waiting-for-schedule' - 'suspended-evse' - 'pending' - 'charging' car_charging_now: - 're:(sensor.psl_[0-9]+_status)' car_charging_now_response: - 'charging' Also can be used to control the cars charging with an automation linked to the Predbat slot sensor. The device needs to be set to 'Smart' mode in the PodPoint app. Your automation trigger should then set the switch.psl_XXXXXX_charging_allowed to on. And off to stop charging. This uses the PodPoint schedule override setting to start/stop the charge.","title":"PodPoint"},{"location":"devices/#hypervolt","text":"https://github.com/gndean/home-assistant-hypervolt-charger Can be used both for Car Charging Hold feature (to filter out previous car charging) and to determine if the car is plugged in (only V3 models). For plugged in detection on V2 models, see guidance https://springfall2008.github.io/batpred/car-charging/#example-ev-and-charger-setup . car_charging_energy: 're:(sensor.hypervolt_session_energy_total_increasing)' car_charging_planned: - 're:(binary_sensor.hypervolt_car_plugged)' car_charging_planned_response: - 'on' car_charging_now: - 're:(sensor.hypervolt_charging_readiness)' car_charging_now_response: - 'charging' Note: sensor.hypervolt_session_energy_total_increasing defaults to 'unknown' between charging sessions. Agile Tariff To automate the schedule charging with Predbat, setup the automation to detect when there is a change to binary_sensor.predbat_car_charging_slot . Ensure that select.hypervolt_charge_mode is in 'Boost', when predbat charging slot is 'on', set select.hypervolt_activation_mode to 'Plug and Charge', when it is 'off' set the 'Schedule', this is the recommended method for start/stop charging.","title":"Hypervolt"},{"location":"devices/#octopus-energy","text":"https://github.com/BottlecapDave/HomeAssistant-OctopusEnergy Can be used for energy rates, car charging and saving sessions For energy rate metric_octopus_import: 're:(sensor.(octopus_energy_|)electricity_[0-9a-z]+_[0-9a-z]+_current_rate)' metric_octopus_export: 're:(sensor.(octopus_energy_|)electricity_[0-9a-z]+_[0-9a-z]+_export_current_rate)' For Octopus Intelligent GO octopus_intelligent_slot: 're:(binary_sensor.octopus_energy([0-9a-z_]+|)_intelligent_dispatching)' octopus_ready_time: 're:(time.octopus_energy([0-9a-z_]+|)_intelligent_ready_time)' octopus_charge_limit: 're:(number.octopus_energy([0-9a-z_]+|)_intelligent_charge_limit)' For Octopus Saving sessions octopus_saving_session: 're:(binary_sensor.octopus_energy([0-9a-z_]+|)_saving_session(s|))' octopus_saving_session_octopoints_per_penny: 8","title":"Octopus Energy"},{"location":"devices/#nordpool","text":"","title":"Nordpool"},{"location":"devices/#for-adjustment-to-octopus-intelligent","text":"This is built into Predbat, see the apps.yaml configuration guide","title":"For adjustment to Octopus Intelligent"},{"location":"devices/#as-your-energy-rates-eg-for-those-in-norway","text":"https://github.com/custom-components/nordpool/ Can be linked to Predbat to provide energy rates in your region e.g: metric_octopus_import: 'sensor.nordpool_kwh_oslo_eur_3_10_025'","title":"As your energy rates (e.g. for those in Norway)"},{"location":"devices/#solcast","text":"https://github.com/BJReplay/ha-solcast-solar For solar forecast data pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today) pv_forecast_tomorrow: re:(sensor.(solcast_|)(pv_forecast_|)forecast_tomorrow) pv_forecast_d3: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_3|d3)) pv_forecast_d4: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_4|d4))","title":"Solcast"},{"location":"energy-rates/","text":"Energy rates Predbat needs to know what your Import and (optionally) Export rates are so it can plan the optimal way to use your battery. Your Import and Export rates can be simple flat rates, more complex time of day tariffs (e.g. Economy 7, Octopus Flux), or daily/half-hourly rates that track electricity market prices (e.g. Octopus Agile or Tracker). Energy rates are all configured in the apps.yaml file that's stored in either the directory /addon_configs/6adb4f0d_predbat or /config/appdaemon/apps/batpred/config/ directory depending on what type of Predbat installation method you have used . 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 edit this file - see editing configuration files within Home Assistant if you need to install an editor. There are three different ways of configuring your Energy rates in apps.yaml , using the Octopus Energy Integration , using Octopus Rates URL's , or manually defining your rates and time periods . At least one of these methods must be used to define your import and export rates. If you don't then Predbat will assume zero for your energy rates. Octopus Energy integration If your electricity supplier is Octopus Energy then the simplest way to provide Predbat with your electricity pricing information is to use the Octopus Energy integration . The Octopus Energy integration connects to your Octopus Energy account and retrieves the tariffs you are on, and the current tariff rates. If you change tariff within Octopus the integration will automatically retrieve the updated tariff information, and as tariff prices change, again they are automatically retrieved. The integration also provides support for Intelligent Octopus charging to support car charging. Follow the instructions provided in the Octopus Energy integration documentation to install and setup the integration. Once installed, you will need to configure the integration (go to Settings / Devices & Services / Integrations / Octopus Energy then click 'Configure') and provide the integration with your 'Octopus API key' (that you obtain from your Octopus account : Personal Details / API access). CAUTION To get detailed energy rates needed by Predbat you need to go into Home Assistant and manually enable the following Octopus Energy events which are disabled by default when the integration is installed: event.octopus_energy_electricity_xxxxxxxx_previous_day_rates event.octopus_energy_electricity_xxxxxxxx_current_day_rates event.octopus_energy_electricity_xxxxxxxx_next_day_rates event.octopus_energy_electricity_xxxxxxxx_export_previous_day_rates event.octopus_energy_electricity_xxxxxxxx_export_current_day_rates event.octopus_energy_electricity_xxxxxxxx_export_next_day_rates event.octopus_energy_gas_xxxxxxxx_previous_day_rates event.octopus_energy_gas_xxxxxxxx_current_day_rates event.octopus_energy_gas_xxxxxxxx_next_day_rates To enable the above events: Go to Settings / Devices & Services / Integrations, choose Octopus Energy, then xx entities You will see a list of entities (and events) supplied by the Octopus integration Click the 'Filter' symbol on the top right hand corner (a series of lines in a downwards pointing arrow) and make sure all the options are selected Then in the left hand-side search entities box, type \"current_day\" Click on the first event that comes up, check the name is the right one Click the cog wheel, then you should see the option to enable the event Click the option to enable the event and press 'Update' to make the change Repeat this for the other events. The gas rates are only required if you have a gas boiler, an iBoost, and are using Predbat to determine whether it's cheaper to heat your hot water with the iBoost or via gas. Verify that the integration is working correctly in Home Assistant by going to Developer Tools / States, and enter 'octopus' in the 'Filter entities' box. Confirm that the Octopus entities are being populated correctly. Configuring Predbat to use the Octopus Energy integration The following configuration items in apps.yaml are used to configure Predbat to use the Octopus Energy integration. They are set to a regular expression and should be auto-discovered so that Predbat automatically uses the Octopus Energy integration, but you can comment out the regular expression lines to disable, or you set them manually. metric_octopus_import - Import rates from the Octopus Energy integration, should point to the sensor sensor.octopus_energy_electricity_METER_NUMBER_current_rate metric_octopus_export - Export rates from the Octopus Energy integration, should point to the sensor sensor.octopus_energy_electricity_METER_NUMBER_export_current_rate metric_octopus_gas - Gas rates from the Octopus Energy integration, should point to the sensor sensor.octopus_energy_gas_METER_NUMBER_current_rate octopus_intelligent_slot - If you have the Octopus Intelligent Go tariff this should point to the 'slot' sensor binary_sensor.octopus_energy_ACCOUNT_ID_intelligent_dispatching metric_octopus_gas is (as above) only required to be configured if you are using Predbat to determine whether to heat your hot water via your iBoost or gas. If you do not have an export rate, or are not on the Octopus Go tariff, then the appropriate lines can be commented out in apps.yaml. Standing charge Predbat can also (optionally) include the daily standing charge in cost predictions. The following configuration item in apps.yaml defaults to obtaining the standing charge from the Octopus Energy integration: metric_standing_charge - Standing charge in pounds. By default points to the Octopus Energy integration sensor sensor.octopus_energy_electricity_METER_NUMBER_current_standing_charge You can manually change this to a standing charge in pounds, e.g. 0.50 is 50p, or delete this line from apps.yaml, or set it to zero if you don't want the standing charge (and only have consumption usage) to be included in Predbat charts and output data. Octopus Saving sessions Predbat is able to automatically join you to Octopus saving sessions and plan battery activity for the saving session period to maximise your income. For Predbat to automatically manage Octopus saving sessions the following additional configuration item in apps.yaml is used. Like the electricity rates this is set in the apps.yaml template to a regular expression that should auto-discover the Octopus Energy integration. octopus_saving_session - Indicates if a saving session is active, should point to the sensor binary_sensor.octopus_energy_ACCOUNT_ID_octoplus_saving_sessions. When a saving session is available it will be automatically joined by Predbat and should then appear as a joined session within the next 30 minutes. In the Predbat plan, for joined saving sessions the energy rates for import and export will be overridden by adding the assumed saving rate to your normal rate. The assumed rate will be taken from the Octopus Energy integration and converted into pence using the octopus_saving_session_octopoints_per_penny configuration item in apps.yaml (default is 8). If you normally cut back your house usage during a saving session then you can change input_number.predbat_load_scaling_saving to allow Predbat to assume an energy reduction in this period. E.g. setting to a value of 0.8 would indicate you will use 80% of the normal consumption in that period (a 20% reduction). As the saving session import and export rates are very high compared to normal Predbat will plan additional export during the saving session period. If necessary, a pre-charge may happen at some point during the day to maintain the battery right level for the session. Note that Predbat's operational mode select.predbat_mode must be set to either 'Control charge' or 'Control charge & discharge' for Predbat to be able to manage the battery for the saving session. If you do not have an export tariff then forced export will not apply and Predbat will just ensure you have enough battery charge to see you through the saving session period. If you do not want Predbat to automatically join Octopus saving sessions and manage your battery activity for the session, simply delete or comment out the octopus_saving_session entry in apps.yaml. Octopus free (power up) events Predbat can automatically detect Octopus free events and adjust your battery plan according. For Predbat to automatically manage Octopus free sessions the following additional configuration item in apps.yaml is used. Note: You must have signed up to Octoplus to benefit from these events Like the electricity rates this is set in the apps.yaml template to a regular expression that should auto-discover the Octopus Energy integration. octopus_free_session - Will point to the free event sensor that is exposed by the Octopus Energy Integration. This event sensor contains the dates/times of all the free events. octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)' Note: This event may need to be enabled in Home Assistant first How to Enable Octopus events If you normally increase your house usage during a free session then you can change input_number.predbat_load_scaling_free to allow Predbat to assume an energy increase in this period. E.g. setting to a value of 1.2 would indicate you will use 20% more energy that normal during this period. (Default is 1.2) If you do not want Predbat to see these sessions then comment out the octopus_free_session setting. Note: If the above is not working due to lack of data (via a 3rd party service) Predbat can scrape directly from the Octopus Web Site, this may have its own issues due to change of format. If you enable this then sessions will be considered even if you forget to sign-up so be careful! octopus_free_url: 'http://octopus.energy/free-electricity' Octopus Rates URL If you do not wish to use the Octopus Energy integration and are an Octopus Energy customer then you can configure Predbat to get the electricity rates directly online from the Octopus website. In apps.yaml configure the following lines: rates_import_octopus_url to point to the appropriate import tariff URL on the Octopus website rates_export_octopus_url to point to the export tariff URL e.g. rates_import_octopus_url : \"https://api.octopus.energy/v1/products/FLUX-IMPORT-23-02-14/electricity-tariffs/E-1R-FLUX-IMPORT-23-02-14-A/standard-unit-rates\" rates_import_octopus_url : \"https://api.octopus.energy/v1/products/AGILE-FLEX-BB-23-02-08/electricity-tariffs/E-1R-AGILE-FLEX-BB-23-02-08-A/standard-unit-rates\" rates_export_octopus_url: \"https://api.octopus.energy/v1/products/FLUX-EXPORT-BB-23-02-14/electricity-tariffs/E-1R-FLUX-EXPORT-BB-23-02-14-A/standard-unit-rates\" rates_export_octopus_url: \"https://api.octopus.energy/v1/products/AGILE-OUTGOING-BB-23-02-28/electricity-tariffs/E-1R-AGILE-OUTGOING-BB-23-02-28-A/standard-unit-rates/\" rates_export_octopus_url: \"https://api.octopus.energy/v1/products/OUTGOING-FIX-12M-BB-23-02-09/electricity-tariffs/E-1R-OUTGOING-FIX-12M-BB-23-02-09-A/standard-unit-rates/\" If you configure the rates_import_octopus_url then Predbat will use this instead of metric_octopus or rates_import. Similarly rates_export_octopus_url takes precedence over metric_octopus_export or rates_export. Configuring the Octopus rates URL is an expert feature and for most users the Octopus Energy integration is a simpler solution to use. Rate Bands to manually configure Energy Rates If you are not an Octopus Energy customer, or you are but your energy rates repeat in a simple manner, you can configure your rate bands in apps.yaml using rates_import/rates_export/rates_gas. Add the following entries to apps.yaml to define the pattern of rates over a 24-hour period: rates_import: - start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence rates_export: - start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence rates_gas: - start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence start and end are in the time format of \"HH:MM:SS\" e.g. \"12:30:00\" and should be aligned to 30 minute slots normally. rate is in pence e.g. 4.2 start and end can be omitted and Predbat will assume that you are on a single flat rate tariff. If there are any gaps in the 24-hour period then a zero rate will be assumed. The gas rates are only required if you have a gas boiler, an iBoost, and are using Predbat to determine whether it's cheaper to heat your hot water with the iBoost or via gas. Manually over-riding energy rates You can also override the import or export energy rates (regardless of whether they are set manually or via the Octopus Energy integration) by using the override feature in apps.yaml. Rate override is used to set the specific date and time period where your rates are different, e.g. an Octopus Power Up session (zero rate for an hour or two), or the British Gas half-price electricity on Sunday's. Unfortunately there aren't any API's available to feed this information automatically into Predbat so you will have to edit apps.yaml manually to set the appropriate rate over-ride dates and times: rates_import_override: - date: \"YYYY-MM-DD\" start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence rates_export_override: - date: \"YYYY-MM-DD\" start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence Optionally you can add a predicted load scaling factor for these periods using load_scaling , for example: rates_import_override: - date: '2024-01-21' start: '17:30:00' end: '18:30:00' rate: 150 load_scaling: 0.8 This instructs Predbat that during a 1 hour period at 5:30-6:30pm on 21st of Jan set the import rate to 150p and assume our load will be 80% of normal (20% lower). You can also make relative adjustments to your energy rates, e.g. if you want to avoid exporting during peak periods to improve your energy saving session results you could make a relative adjustment to your export rates using rate_increment . The reason not to just set rate is then when an energy saving session is active you do not want to ignore the higher export rate that is automatically provided by Octopus. In this example we subtract 10p from our export rate during the period that saving sessions normally fall within and thus steer Predbat away from force exporting during that time. The saving session will still work correctly as a 10p adjustment on rates >100p will have little/no impact. rates_export_override: - start: '17:00:00' end: '19:00:00' rate_increment: -10 You can also use a similar but opposite approach of setting a positive export rate_increment to encourage Predbat to discharge the battery at certain time periods. If you have a very low overnight rate (such as Octopus Go) and want to ensure your battery is discharged just before the low rate period, but you don't want to risk the battery running out too early (and importing at a higher rate), you can add a rate export override for the period you want to discharge just before the low rate period: rates_export_override: - start: '22:30:00' end: '23:30:00' rate_increment: 10 You can also use rate_increment with load_scaling, e.g. a rate_increment of 0 can be used to just apply load scaling to certain defined periods. date is optional and if specified must be in the date format of \"YYYY-MM-DD\" e.g. \"2023-09-09\". If a date is specified then the rate override applies that specific date, otherwise it applies to all dates start and end must be specified in \"HH:MM:SS\" time format e.g. \"12:30:00\" load_scaling is an optional percentage change factor in house load for the period - 1.0 would be no change, 0.8 is 80% of nominal house load, 2.0 would be a 100% increase (i.e. 2x) on normal historic house load rate is optional figure in pence to override the rate for the specific period rate_increment is optional and is the number of pence to add (or subtract) to the reported energy rates during this period Rate offsets If you are on an Agile or Tracker tariff you can tune future unknown energy rates by adjusting the entities input_number.predbat_metric_future_rate_offset_import ( expert mode ) and input_number.predbat_metric_future_rate_offset_export ( expert mode ) inside Home Assistant to set the predicted offset for future unknown rates. Future Agile energy rates In the energy market it's possible to calculate the Octopus Agile rates from around 10am UK time using public data, you can enable this in apps.yaml for Import, Export or both. This will approximate next day's rates based on the spot prices. The approximation is only used until the real Octopus Agile rates are released around 4pm. futurerate_url - URL of future energy market prices; this should not normally need to be changed futurerate_adjust_import and futurerate_adjust_export - Whether tomorrow's predicted import or export prices should be adjusted based on energy market prices or not. Set these depending upon whether you have an agile tariff for import, export or both futurerate_peak_start and futurerate_peak_end - during the peak period Octopus apply an additional peak-rate price adjustment. These configuration items enable the peak-rate hours to be adjusted CAUTION: You may violate the terms and conditions of the Nordpool site if you use this data and as such the authors of Predbat accept no responsibility for any violations: https://www.nordpoolgroup.com/en/About-us/terms-and-conditions-for-useofwebsite/ futurerate_url: 'https://dataportal-api.nordpoolgroup.com/api/DayAheadPrices?date=DATE&market=N2EX_DayAhead&deliveryArea=UK¤cy=GBP' futurerate_adjust_import: True futurerate_adjust_export: False futurerate_peak_start: \"16:00:00\" futurerate_peak_end: \"19:00:00\" Grid Carbon intensity Predbat can also track Carbon intensity by linking it to an integration which provides this data. UK Grid Carbon intensity The National Grid provides this data, please install this integration: https://github.com/jfparis/sensor.carbon_intensity_uk Once it is active update apps.yaml to link Predbat to the Sensor (if its not already in your template): # Carbon Intensity data from National grid carbon_intensity: 're:(sensor.carbon_intensity_uk)' By enabling switch.predbat_carbon_enable you can view Carbon Intensity in the predbat plan . Predbat can also optimise your grid charging based on the Carbon footprint by setting input_number.predbat_carbon_metric .","title":"Energy rates"},{"location":"energy-rates/#energy-rates","text":"Predbat needs to know what your Import and (optionally) Export rates are so it can plan the optimal way to use your battery. Your Import and Export rates can be simple flat rates, more complex time of day tariffs (e.g. Economy 7, Octopus Flux), or daily/half-hourly rates that track electricity market prices (e.g. Octopus Agile or Tracker). Energy rates are all configured in the apps.yaml file that's stored in either the directory /addon_configs/6adb4f0d_predbat or /config/appdaemon/apps/batpred/config/ directory depending on what type of Predbat installation method you have used . 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 edit this file - see editing configuration files within Home Assistant if you need to install an editor. There are three different ways of configuring your Energy rates in apps.yaml , using the Octopus Energy Integration , using Octopus Rates URL's , or manually defining your rates and time periods . At least one of these methods must be used to define your import and export rates. If you don't then Predbat will assume zero for your energy rates.","title":"Energy rates"},{"location":"energy-rates/#octopus-energy-integration","text":"If your electricity supplier is Octopus Energy then the simplest way to provide Predbat with your electricity pricing information is to use the Octopus Energy integration . The Octopus Energy integration connects to your Octopus Energy account and retrieves the tariffs you are on, and the current tariff rates. If you change tariff within Octopus the integration will automatically retrieve the updated tariff information, and as tariff prices change, again they are automatically retrieved. The integration also provides support for Intelligent Octopus charging to support car charging. Follow the instructions provided in the Octopus Energy integration documentation to install and setup the integration. Once installed, you will need to configure the integration (go to Settings / Devices & Services / Integrations / Octopus Energy then click 'Configure') and provide the integration with your 'Octopus API key' (that you obtain from your Octopus account : Personal Details / API access). CAUTION To get detailed energy rates needed by Predbat you need to go into Home Assistant and manually enable the following Octopus Energy events which are disabled by default when the integration is installed: event.octopus_energy_electricity_xxxxxxxx_previous_day_rates event.octopus_energy_electricity_xxxxxxxx_current_day_rates event.octopus_energy_electricity_xxxxxxxx_next_day_rates event.octopus_energy_electricity_xxxxxxxx_export_previous_day_rates event.octopus_energy_electricity_xxxxxxxx_export_current_day_rates event.octopus_energy_electricity_xxxxxxxx_export_next_day_rates event.octopus_energy_gas_xxxxxxxx_previous_day_rates event.octopus_energy_gas_xxxxxxxx_current_day_rates event.octopus_energy_gas_xxxxxxxx_next_day_rates To enable the above events: Go to Settings / Devices & Services / Integrations, choose Octopus Energy, then xx entities You will see a list of entities (and events) supplied by the Octopus integration Click the 'Filter' symbol on the top right hand corner (a series of lines in a downwards pointing arrow) and make sure all the options are selected Then in the left hand-side search entities box, type \"current_day\" Click on the first event that comes up, check the name is the right one Click the cog wheel, then you should see the option to enable the event Click the option to enable the event and press 'Update' to make the change Repeat this for the other events. The gas rates are only required if you have a gas boiler, an iBoost, and are using Predbat to determine whether it's cheaper to heat your hot water with the iBoost or via gas. Verify that the integration is working correctly in Home Assistant by going to Developer Tools / States, and enter 'octopus' in the 'Filter entities' box. Confirm that the Octopus entities are being populated correctly.","title":"Octopus Energy integration"},{"location":"energy-rates/#configuring-predbat-to-use-the-octopus-energy-integration","text":"The following configuration items in apps.yaml are used to configure Predbat to use the Octopus Energy integration. They are set to a regular expression and should be auto-discovered so that Predbat automatically uses the Octopus Energy integration, but you can comment out the regular expression lines to disable, or you set them manually. metric_octopus_import - Import rates from the Octopus Energy integration, should point to the sensor sensor.octopus_energy_electricity_METER_NUMBER_current_rate metric_octopus_export - Export rates from the Octopus Energy integration, should point to the sensor sensor.octopus_energy_electricity_METER_NUMBER_export_current_rate metric_octopus_gas - Gas rates from the Octopus Energy integration, should point to the sensor sensor.octopus_energy_gas_METER_NUMBER_current_rate octopus_intelligent_slot - If you have the Octopus Intelligent Go tariff this should point to the 'slot' sensor binary_sensor.octopus_energy_ACCOUNT_ID_intelligent_dispatching metric_octopus_gas is (as above) only required to be configured if you are using Predbat to determine whether to heat your hot water via your iBoost or gas. If you do not have an export rate, or are not on the Octopus Go tariff, then the appropriate lines can be commented out in apps.yaml.","title":"Configuring Predbat to use the Octopus Energy integration"},{"location":"energy-rates/#standing-charge","text":"Predbat can also (optionally) include the daily standing charge in cost predictions. The following configuration item in apps.yaml defaults to obtaining the standing charge from the Octopus Energy integration: metric_standing_charge - Standing charge in pounds. By default points to the Octopus Energy integration sensor sensor.octopus_energy_electricity_METER_NUMBER_current_standing_charge You can manually change this to a standing charge in pounds, e.g. 0.50 is 50p, or delete this line from apps.yaml, or set it to zero if you don't want the standing charge (and only have consumption usage) to be included in Predbat charts and output data.","title":"Standing charge"},{"location":"energy-rates/#octopus-saving-sessions","text":"Predbat is able to automatically join you to Octopus saving sessions and plan battery activity for the saving session period to maximise your income. For Predbat to automatically manage Octopus saving sessions the following additional configuration item in apps.yaml is used. Like the electricity rates this is set in the apps.yaml template to a regular expression that should auto-discover the Octopus Energy integration. octopus_saving_session - Indicates if a saving session is active, should point to the sensor binary_sensor.octopus_energy_ACCOUNT_ID_octoplus_saving_sessions. When a saving session is available it will be automatically joined by Predbat and should then appear as a joined session within the next 30 minutes. In the Predbat plan, for joined saving sessions the energy rates for import and export will be overridden by adding the assumed saving rate to your normal rate. The assumed rate will be taken from the Octopus Energy integration and converted into pence using the octopus_saving_session_octopoints_per_penny configuration item in apps.yaml (default is 8). If you normally cut back your house usage during a saving session then you can change input_number.predbat_load_scaling_saving to allow Predbat to assume an energy reduction in this period. E.g. setting to a value of 0.8 would indicate you will use 80% of the normal consumption in that period (a 20% reduction). As the saving session import and export rates are very high compared to normal Predbat will plan additional export during the saving session period. If necessary, a pre-charge may happen at some point during the day to maintain the battery right level for the session. Note that Predbat's operational mode select.predbat_mode must be set to either 'Control charge' or 'Control charge & discharge' for Predbat to be able to manage the battery for the saving session. If you do not have an export tariff then forced export will not apply and Predbat will just ensure you have enough battery charge to see you through the saving session period. If you do not want Predbat to automatically join Octopus saving sessions and manage your battery activity for the session, simply delete or comment out the octopus_saving_session entry in apps.yaml.","title":"Octopus Saving sessions"},{"location":"energy-rates/#octopus-free-power-up-events","text":"Predbat can automatically detect Octopus free events and adjust your battery plan according. For Predbat to automatically manage Octopus free sessions the following additional configuration item in apps.yaml is used. Note: You must have signed up to Octoplus to benefit from these events Like the electricity rates this is set in the apps.yaml template to a regular expression that should auto-discover the Octopus Energy integration. octopus_free_session - Will point to the free event sensor that is exposed by the Octopus Energy Integration. This event sensor contains the dates/times of all the free events. octopus_free_session: 're:(event.octopus_energy_([0-9a-z_]+|)_octoplus_free_electricity_session_events)' Note: This event may need to be enabled in Home Assistant first How to Enable Octopus events If you normally increase your house usage during a free session then you can change input_number.predbat_load_scaling_free to allow Predbat to assume an energy increase in this period. E.g. setting to a value of 1.2 would indicate you will use 20% more energy that normal during this period. (Default is 1.2) If you do not want Predbat to see these sessions then comment out the octopus_free_session setting. Note: If the above is not working due to lack of data (via a 3rd party service) Predbat can scrape directly from the Octopus Web Site, this may have its own issues due to change of format. If you enable this then sessions will be considered even if you forget to sign-up so be careful! octopus_free_url: 'http://octopus.energy/free-electricity'","title":"Octopus free (power up) events"},{"location":"energy-rates/#octopus-rates-url","text":"If you do not wish to use the Octopus Energy integration and are an Octopus Energy customer then you can configure Predbat to get the electricity rates directly online from the Octopus website. In apps.yaml configure the following lines: rates_import_octopus_url to point to the appropriate import tariff URL on the Octopus website rates_export_octopus_url to point to the export tariff URL e.g. rates_import_octopus_url : \"https://api.octopus.energy/v1/products/FLUX-IMPORT-23-02-14/electricity-tariffs/E-1R-FLUX-IMPORT-23-02-14-A/standard-unit-rates\" rates_import_octopus_url : \"https://api.octopus.energy/v1/products/AGILE-FLEX-BB-23-02-08/electricity-tariffs/E-1R-AGILE-FLEX-BB-23-02-08-A/standard-unit-rates\" rates_export_octopus_url: \"https://api.octopus.energy/v1/products/FLUX-EXPORT-BB-23-02-14/electricity-tariffs/E-1R-FLUX-EXPORT-BB-23-02-14-A/standard-unit-rates\" rates_export_octopus_url: \"https://api.octopus.energy/v1/products/AGILE-OUTGOING-BB-23-02-28/electricity-tariffs/E-1R-AGILE-OUTGOING-BB-23-02-28-A/standard-unit-rates/\" rates_export_octopus_url: \"https://api.octopus.energy/v1/products/OUTGOING-FIX-12M-BB-23-02-09/electricity-tariffs/E-1R-OUTGOING-FIX-12M-BB-23-02-09-A/standard-unit-rates/\" If you configure the rates_import_octopus_url then Predbat will use this instead of metric_octopus or rates_import. Similarly rates_export_octopus_url takes precedence over metric_octopus_export or rates_export. Configuring the Octopus rates URL is an expert feature and for most users the Octopus Energy integration is a simpler solution to use.","title":"Octopus Rates URL"},{"location":"energy-rates/#rate-bands-to-manually-configure-energy-rates","text":"If you are not an Octopus Energy customer, or you are but your energy rates repeat in a simple manner, you can configure your rate bands in apps.yaml using rates_import/rates_export/rates_gas. Add the following entries to apps.yaml to define the pattern of rates over a 24-hour period: rates_import: - start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence rates_export: - start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence rates_gas: - start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence start and end are in the time format of \"HH:MM:SS\" e.g. \"12:30:00\" and should be aligned to 30 minute slots normally. rate is in pence e.g. 4.2 start and end can be omitted and Predbat will assume that you are on a single flat rate tariff. If there are any gaps in the 24-hour period then a zero rate will be assumed. The gas rates are only required if you have a gas boiler, an iBoost, and are using Predbat to determine whether it's cheaper to heat your hot water with the iBoost or via gas.","title":"Rate Bands to manually configure Energy Rates"},{"location":"energy-rates/#manually-over-riding-energy-rates","text":"You can also override the import or export energy rates (regardless of whether they are set manually or via the Octopus Energy integration) by using the override feature in apps.yaml. Rate override is used to set the specific date and time period where your rates are different, e.g. an Octopus Power Up session (zero rate for an hour or two), or the British Gas half-price electricity on Sunday's. Unfortunately there aren't any API's available to feed this information automatically into Predbat so you will have to edit apps.yaml manually to set the appropriate rate over-ride dates and times: rates_import_override: - date: \"YYYY-MM-DD\" start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence rates_export_override: - date: \"YYYY-MM-DD\" start: \"HH:MM:SS\" end: \"HH:MM:SS\" rate: pence Optionally you can add a predicted load scaling factor for these periods using load_scaling , for example: rates_import_override: - date: '2024-01-21' start: '17:30:00' end: '18:30:00' rate: 150 load_scaling: 0.8 This instructs Predbat that during a 1 hour period at 5:30-6:30pm on 21st of Jan set the import rate to 150p and assume our load will be 80% of normal (20% lower). You can also make relative adjustments to your energy rates, e.g. if you want to avoid exporting during peak periods to improve your energy saving session results you could make a relative adjustment to your export rates using rate_increment . The reason not to just set rate is then when an energy saving session is active you do not want to ignore the higher export rate that is automatically provided by Octopus. In this example we subtract 10p from our export rate during the period that saving sessions normally fall within and thus steer Predbat away from force exporting during that time. The saving session will still work correctly as a 10p adjustment on rates >100p will have little/no impact. rates_export_override: - start: '17:00:00' end: '19:00:00' rate_increment: -10 You can also use a similar but opposite approach of setting a positive export rate_increment to encourage Predbat to discharge the battery at certain time periods. If you have a very low overnight rate (such as Octopus Go) and want to ensure your battery is discharged just before the low rate period, but you don't want to risk the battery running out too early (and importing at a higher rate), you can add a rate export override for the period you want to discharge just before the low rate period: rates_export_override: - start: '22:30:00' end: '23:30:00' rate_increment: 10 You can also use rate_increment with load_scaling, e.g. a rate_increment of 0 can be used to just apply load scaling to certain defined periods. date is optional and if specified must be in the date format of \"YYYY-MM-DD\" e.g. \"2023-09-09\". If a date is specified then the rate override applies that specific date, otherwise it applies to all dates start and end must be specified in \"HH:MM:SS\" time format e.g. \"12:30:00\" load_scaling is an optional percentage change factor in house load for the period - 1.0 would be no change, 0.8 is 80% of nominal house load, 2.0 would be a 100% increase (i.e. 2x) on normal historic house load rate is optional figure in pence to override the rate for the specific period rate_increment is optional and is the number of pence to add (or subtract) to the reported energy rates during this period","title":"Manually over-riding energy rates"},{"location":"energy-rates/#rate-offsets","text":"If you are on an Agile or Tracker tariff you can tune future unknown energy rates by adjusting the entities input_number.predbat_metric_future_rate_offset_import ( expert mode ) and input_number.predbat_metric_future_rate_offset_export ( expert mode ) inside Home Assistant to set the predicted offset for future unknown rates.","title":"Rate offsets"},{"location":"energy-rates/#future-agile-energy-rates","text":"In the energy market it's possible to calculate the Octopus Agile rates from around 10am UK time using public data, you can enable this in apps.yaml for Import, Export or both. This will approximate next day's rates based on the spot prices. The approximation is only used until the real Octopus Agile rates are released around 4pm. futurerate_url - URL of future energy market prices; this should not normally need to be changed futurerate_adjust_import and futurerate_adjust_export - Whether tomorrow's predicted import or export prices should be adjusted based on energy market prices or not. Set these depending upon whether you have an agile tariff for import, export or both futurerate_peak_start and futurerate_peak_end - during the peak period Octopus apply an additional peak-rate price adjustment. These configuration items enable the peak-rate hours to be adjusted CAUTION: You may violate the terms and conditions of the Nordpool site if you use this data and as such the authors of Predbat accept no responsibility for any violations: https://www.nordpoolgroup.com/en/About-us/terms-and-conditions-for-useofwebsite/ futurerate_url: 'https://dataportal-api.nordpoolgroup.com/api/DayAheadPrices?date=DATE&market=N2EX_DayAhead&deliveryArea=UK¤cy=GBP' futurerate_adjust_import: True futurerate_adjust_export: False futurerate_peak_start: \"16:00:00\" futurerate_peak_end: \"19:00:00\"","title":"Future Agile energy rates"},{"location":"energy-rates/#grid-carbon-intensity","text":"Predbat can also track Carbon intensity by linking it to an integration which provides this data.","title":"Grid Carbon intensity"},{"location":"energy-rates/#uk-grid-carbon-intensity","text":"The National Grid provides this data, please install this integration: https://github.com/jfparis/sensor.carbon_intensity_uk Once it is active update apps.yaml to link Predbat to the Sensor (if its not already in your template): # Carbon Intensity data from National grid carbon_intensity: 're:(sensor.carbon_intensity_uk)' By enabling switch.predbat_carbon_enable you can view Carbon Intensity in the predbat plan . Predbat can also optimise your grid charging based on the Carbon footprint by setting input_number.predbat_carbon_metric .","title":"UK Grid Carbon intensity"},{"location":"faq/","text":"FAQ I've installed Predbat but I don't see the correct entities First look at predbat.status in Home Assistant and the Predbat/AppDaemon add-on log (which can be found in the list of log files in the System/Log area of the GUI). See if any errors are warnings are found. If you see an error it's likely something is configured wrongly, check your entity settings are correct. Make sure Solcast is installed and it's auto-updated at least a couple of times a day (see the Solcast instructions ). The default solcast sensor names maybe wrong, you might need to update the apps.yaml config to match your own names (some people don't have the solcast_ bit in their names) Did you configure AppDaemon apps_dir correctly in appdaemon.yaml ? Why is my predicted charge % higher or lower than I might expect? Predbat is based on costing, so it will try to save you money. If you have the PV 10% option enabled it will also take into account the more worse case scenario and how often it might happen, so if the forecast is a bit unreliable it's better to charge more and not risk getting stung importing. Have you checked your energy rates for import and export are correct, maybe check the rates graph and confirm. If you do something like have export>import then Predbat will try to export as much as possible. Have you tuned Solcast to match your output accurately? Have you tuned predbat_best_soc_keep settings ? Do you have predicted car charging during the time period? You can also tune predbat_load_scaling and predbat_pv_scaling to adjust predictions up and down a bit Maybe your historical data includes car charging, you might want to filter this out using car_charging_hold in apps.yaml Why didn't the slot actually get configured? Are you in read-only mode? My plan doesn't include any charging? Do you have the predbat_mode set to Control charge (or Control charge & discharge)? The charge limit keeps increasing/decreasing in the charge window or is unstable Check you don't have any other automations running that adjust GivTCP settings during this time. Some people had a script that changes the reserve %, this will cause problems - please disable other automations and retry. I changed a config item but it made no difference? You might have to wait a few minutes until the next update cycle. Depending on the speed of the computer that Predbat is running on, it can take 1-5 minutes for Predbat to run through. You can see the date/time that Predbat last completed a run at the start of the Predbat HTML plan . It's all running but I'm not getting very good results You might want to tune input_number.predbat_best_soc_keep to set a minimum target battery level, e.g. I use 2.0 (for 2kWh, which is just over 20% on a 9.5kWh battery). If you set input_number.predbat_best_soc_keep too high then predbat could need to charge the battery in unfavourable import rates, so try to set it to a fairly low value, especially if you have a small battery. If you set it to zero then predbat may not charge at all, so use 0.1 as a minimum. Have a read of the energy rates configuration guide as depending on your tariff different settings maybe required Check your solar production is well calibrated (you can compare solcast vs actually in the Home Assistant energy tab or on the GivEnergy portal) Make sure your inverter max AC rate has been set correctly If you have an EV that you charge then you will want some sort of car charging sensor or use the basic car charging hold feature or your load predictions maybe unreliable - see Car charging Do you have a solar diverter? If so maybe you want to try using the iBoost model settings . 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) When my battery is charging to 100% is fluctuates between 98% and 100%, and/or gives an error setting reserve Some inverters e.g. GE AIO inverter won't allow the reserve to be set too 100, in which case set in apps.yaml inverter_reserve_max : 98 And this should prevent the issue The plan doesn't charge or discharge when I expect it to Predbat can only work on the information its given, although it does run every 5 minutes when it re-evaluates the plan and adjusts if necessary. The plan Predbat produces assumes that your average load and PV forecasts are accurate and Predbat will aim to give you the maximum return. Make sure you have setup your Solcast solar forecast correctly with the number of panels, orientation, output, etc. Projected daily load is determined from historical load information so make sure you have set days_previous and days_previous_weight in apps.yaml to give appropriately representative load history to Predbat, and read the longer explanation of how days_previous works . You could adjust input_number.predbat_load_scaling to 1.2 so the plan will incorporate 20% more expected load if you want to be more pessimistic about historical load, and input_number.predbat_pv_scaling to similarly adjust the PV forecast - these and other adjustment options are described in the Scaling and Weight options . It is very important to correctly set Predbat's Battery Loss Options and Battery Margins 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 to suit their needs. The SoC level that Predbat aims to keep in the battery input_number.predbat_best_soc_keep and the absolute minimum SoC level input_number.predbat_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. Conversely if you find Predbat is letting the battery exhaust too early, set predbat_best_soc_keep to 1.0 so Predbat will aim to keep 1kWh available for unexpected load. 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.predbat_battery_loss , input_number.predbat_battery_loss_discharge and input_number.predbat_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 then you can see the effective import and export rates after losses that Predbat calculates in the Predbat plan. Predbat also uses input_number.predbat_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.predbat_metric_min_improvement and input_number.predbat_metric_min_improvement_discharge (both expert mode settings) also affect Predbat's cost optimisation decisions as to whether its cost beneficial to charge or discharge the battery so could be tweaked if you feel Predbat is charging or discharging with marginal benefits. The defaults (0p and 0.1p respectively) should however give good results for most users. Finally, it could be worth considering adding import or export rate increments to apps.yaml if you want to direct Predbat to avoid or encourage charging or discharging in certain time periods - e.g. avoiding exporting in the time period saving sessions normally fall in, or to encourage discharging just before import rates fall overnight. Predbat is causing warning messages about 'exceed maximum size' in the Home Assistant Core log If you have a large input_number.predbat_forecast_plan_hours then you may see warning messages in the Home Assistant Core log about the size of a number of Predbat entities, the message will be \"State attributes for predbat. XXXX exceed maximum size of 16384 bytes\". This is just a warning, the Predbat entity attributes aren't stored in the database anyway, but you can suppress these warnings by adding the following to your configuration.yaml file: # Filter out 'message too large' warnings from Predbat entities logger: default: warning filters: homeassistant.components.recorder.db_schema: - \"State attributes for predbat.base10_export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.base10_import_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.base10_metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.base10_pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.battery_cycle exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.battery_cycle_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.battery_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.battery_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_charge_limit exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_import_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_load_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best10_export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best10_import_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best10_metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best10_pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.cost_today_export exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.cost_today_import exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.grid_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.grid_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_energy_actual exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_energy_adjusted exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_energy_predicted exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.plan_html exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.pv_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.pv_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.rates exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.soc_kw exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.soc_kw_base10 exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.soc_kw_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.soc_kw_best10 exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" Error - metric_octopus_import not set correctly or no energy rates can be read If you get this error in the Predbat log file: Check that the Octopus integration is working and that event.octopus_energy_electricity_METER_NUMBER_current_day_rates and sensor.octopus_electricity_energy_METER_NUMBER_current_rate are both populated by the integration. Ensure that you have followed the Octopus Integration Installation instructions , including enabling the Octopus Integration events. If you been using an older version of the Octopus integration and have upgraded to version 9 or above, then you may find that your energy sensors are named sensor.electricity_METER_NUMBER_current_rate (i.e. no 'octopus_energy_' prefix) but the 'event' entities have the 'octopus_energy' prefix. If the 'event' and 'sensor' entities are not consistently named then Predbat will not be able to find the event entities if the sensor names don't match what's expected. To fix this, uninstall the Octopus integration, reboot Home Assistant, delete all the old Octopus sensors, and re-install the Octopus Integration . WARN: No solar data has been configured If you get this warning message in the Predbat log file or you see that the 'PV kWh' column in the Predbat plan card is completely blank: Ensure that you have installed and configured Solcast correctly Check the Solcast integration in Home Assistant is configured and enabled (go to Settings / Integrations / Solcast ) Check that there are no errors relating to Solcast in the Home Assistant log (go to Settings / System / Logs and view the 'Home Assistant Core' log). If you see an error 429 message in the log then this is as a result of Solcast's rate limiting for Hobbyist accounts. The only fix is to re-run the 'Solcast update' automation and hope that Solcast isn't as busy when you re-run. Verify the solar forecast has been populated in Home Assistant by going to Developer Tools / States, filtering on 'solcast', and checking that you can see the half-hourly solar forecasts in the Solcast entities If you can see the solcast entities but there are no forecast PV figures, try running the 'Solcast update' automation you created, and check again the solcast entities If the solcast entities are still not populated, try reloading the Solcast integration (go to System / Devices & Services / Integrations tab, click on 'Solcast PV Forecast', click the three vertical dots beside 'Configure' and choose 'Reload' from the dropdown menu) Check sensor.solcast_pv_api_limit (it's normally 10 for new Solcast accounts) meaning you can call the Solcast API 10 times a day (but if you have two solar arrays, e.g. East/West) then retrieving the forecast will count as two API calls. Compare this to sensor.solcast_pv_api_used to see how many Solcast API calls you have made today (alternatively, you can confirm how many API calls you have made today by logging into your Solcast account). If you've run out of API calls you will have to wait until midnight GMT for the API count to reset. It's recommended that you don't include the Solcast forecast within your GivEnergy portal to avoid running out of API calls. Check the Solcast server API status is OK Note: Can not find battery charge curve If you get the message \"Note: Can not find battery charge curve, one of the required settings for soc_kw, battery_power and charge_rate are missing from apps.yaml\" in the logfile then Predbat is trying to create a battery charge curve but does not have access to the required history information in Home Assistant. Creating the battery charge curve is described in the apps.yaml document. The most likely cause of the above message appearing in the logfile is that you are controlling the inverter in REST mode but have not uncommented the following entities in apps.yaml that Predbat needs to obtain history from to create the battery charge curve: charge_rate: - number.givtcp_{geserial}_battery_charge_rate discharge_rate: - number.givtcp_{geserial}_battery_discharge_rate battery_power: - sensor.givtcp_{geserial}_battery_power soc_kw: - sensor.givtcp_{geserial}_soc_kwh WARN: Inverter is in calibration mode If you see the message \"WARN: Inverter is in calibration mode, Predbat will not function correctly and will be disabled\" in the logfile, then Predbat has identified that your inverter is currently calibrating your battery. Predbat's status will also be set to 'Calibration'. Predbat will set the inverter charge and discharge rates to maximum (if they are not already), SoC target to 100% and battery reserve to minimum (usually 4%), and will not execute the plan nor enable battery charge or discharge. Once the inverter finishes calibrating the battery, Predbat will resume normal operations. Inverter time is xxx, Predbat computer time is xxx, this is xxx minutes skewed, Predbat may not function correctly If the predbat.status gives a warning error about the inverter time: Then it indicates that there is a mis-match between the clock that Predbat is using and the inverter time clock, and clearly with a clock mis-match, charging and discharging your battery at specific times may not work as expected. There are several potential causes of this problem: Check that the inverter time is correctly set, especially that its set to GMT (even if its summer time). In the GivEnergy portal, go to My Inverters / Remote Control (cog symbol) / click SEND next to 'Set Date and Time' Check that the time_zone in appdaemon.yaml is correctly set for your location (e.g. Europe/London) The time zone for Predbat in apps.yaml needs to be set to the same value Finally, check how often your inverter integration is polling your inverter for new data. For GivTCP the Self Run Loop Timer is recommended to be set to a value of between 20 and 60 seconds. If you have checked the above and keep getting \u201ctime is skewed\u201d warnings then it means Home Assistant/predbat isn\u2019t getting the same time from the inverter as it is expecting. Either GivTCP has lost communications with the inverter or the inverter is stopped talking to the world. If you look at the Logbook in Home Assistant you should see a steady stream of entities changing in HA. In particular you will see the GivTCP inverter time entity changing every polling period, e.g. every 20 seconds. Possible fixes: restart the GivTCP add-on restart Home Assistant (although usually restarting GivTCP is enough) power the inverter off, turn off panels and battery first, then the inverter, then follow the reverse sequence to power the inverter back on again. This forces the inverter to reconnect to your wifi do a \u2018reset to defaults\u2019 in the portal If you keep getting the warning message, even sporadically, then this points to an underlying issue in your home network between Home Assistant and the inverter. You may need to add a Wi-Fi repeater or ideally a fixed Ethernet connection to your inverter to improve signal strength if this keeps happening. There is a Home Assistant automation that will alert you if GivTCP stops sending data to predbat . I have another problem not listed above If you are still having trouble feel free to raise a Github ticket for support","title":"FAQ"},{"location":"faq/#faq","text":"","title":"FAQ"},{"location":"faq/#ive-installed-predbat-but-i-dont-see-the-correct-entities","text":"First look at predbat.status in Home Assistant and the Predbat/AppDaemon add-on log (which can be found in the list of log files in the System/Log area of the GUI). See if any errors are warnings are found. If you see an error it's likely something is configured wrongly, check your entity settings are correct. Make sure Solcast is installed and it's auto-updated at least a couple of times a day (see the Solcast instructions ). The default solcast sensor names maybe wrong, you might need to update the apps.yaml config to match your own names (some people don't have the solcast_ bit in their names) Did you configure AppDaemon apps_dir correctly in appdaemon.yaml ?","title":"I've installed Predbat but I don't see the correct entities"},{"location":"faq/#why-is-my-predicted-charge-higher-or-lower-than-i-might-expect","text":"Predbat is based on costing, so it will try to save you money. If you have the PV 10% option enabled it will also take into account the more worse case scenario and how often it might happen, so if the forecast is a bit unreliable it's better to charge more and not risk getting stung importing. Have you checked your energy rates for import and export are correct, maybe check the rates graph and confirm. If you do something like have export>import then Predbat will try to export as much as possible. Have you tuned Solcast to match your output accurately? Have you tuned predbat_best_soc_keep settings ? Do you have predicted car charging during the time period? You can also tune predbat_load_scaling and predbat_pv_scaling to adjust predictions up and down a bit Maybe your historical data includes car charging, you might want to filter this out using car_charging_hold in apps.yaml","title":"Why is my predicted charge % higher or lower than I might expect?"},{"location":"faq/#why-didnt-the-slot-actually-get-configured","text":"Are you in read-only mode?","title":"Why didn't the slot actually get configured?"},{"location":"faq/#my-plan-doesnt-include-any-charging","text":"Do you have the predbat_mode set to Control charge (or Control charge & discharge)?","title":"My plan doesn't include any charging?"},{"location":"faq/#the-charge-limit-keeps-increasingdecreasing-in-the-charge-window-or-is-unstable","text":"Check you don't have any other automations running that adjust GivTCP settings during this time. Some people had a script that changes the reserve %, this will cause problems - please disable other automations and retry.","title":"The charge limit keeps increasing/decreasing in the charge window or is unstable"},{"location":"faq/#i-changed-a-config-item-but-it-made-no-difference","text":"You might have to wait a few minutes until the next update cycle. Depending on the speed of the computer that Predbat is running on, it can take 1-5 minutes for Predbat to run through. You can see the date/time that Predbat last completed a run at the start of the Predbat HTML plan .","title":"I changed a config item but it made no difference?"},{"location":"faq/#its-all-running-but-im-not-getting-very-good-results","text":"You might want to tune input_number.predbat_best_soc_keep to set a minimum target battery level, e.g. I use 2.0 (for 2kWh, which is just over 20% on a 9.5kWh battery). If you set input_number.predbat_best_soc_keep too high then predbat could need to charge the battery in unfavourable import rates, so try to set it to a fairly low value, especially if you have a small battery. If you set it to zero then predbat may not charge at all, so use 0.1 as a minimum. Have a read of the energy rates configuration guide as depending on your tariff different settings maybe required Check your solar production is well calibrated (you can compare solcast vs actually in the Home Assistant energy tab or on the GivEnergy portal) Make sure your inverter max AC rate has been set correctly If you have an EV that you charge then you will want some sort of car charging sensor or use the basic car charging hold feature or your load predictions maybe unreliable - see Car charging Do you have a solar diverter? If so maybe you want to try using the iBoost model settings . 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)","title":"It's all running but I'm not getting very good results"},{"location":"faq/#when-my-battery-is-charging-to-100-is-fluctuates-between-98-and-100-andor-gives-an-error-setting-reserve","text":"Some inverters e.g. GE AIO inverter won't allow the reserve to be set too 100, in which case set in apps.yaml inverter_reserve_max : 98 And this should prevent the issue","title":"When my battery is charging to 100% is fluctuates between 98% and 100%, and/or gives an error setting reserve"},{"location":"faq/#the-plan-doesnt-charge-or-discharge-when-i-expect-it-to","text":"Predbat can only work on the information its given, although it does run every 5 minutes when it re-evaluates the plan and adjusts if necessary. The plan Predbat produces assumes that your average load and PV forecasts are accurate and Predbat will aim to give you the maximum return. Make sure you have setup your Solcast solar forecast correctly with the number of panels, orientation, output, etc. Projected daily load is determined from historical load information so make sure you have set days_previous and days_previous_weight in apps.yaml to give appropriately representative load history to Predbat, and read the longer explanation of how days_previous works . You could adjust input_number.predbat_load_scaling to 1.2 so the plan will incorporate 20% more expected load if you want to be more pessimistic about historical load, and input_number.predbat_pv_scaling to similarly adjust the PV forecast - these and other adjustment options are described in the Scaling and Weight options . It is very important to correctly set Predbat's Battery Loss Options and Battery Margins 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 to suit their needs. The SoC level that Predbat aims to keep in the battery input_number.predbat_best_soc_keep and the absolute minimum SoC level input_number.predbat_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. Conversely if you find Predbat is letting the battery exhaust too early, set predbat_best_soc_keep to 1.0 so Predbat will aim to keep 1kWh available for unexpected load. 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.predbat_battery_loss , input_number.predbat_battery_loss_discharge and input_number.predbat_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 then you can see the effective import and export rates after losses that Predbat calculates in the Predbat plan. Predbat also uses input_number.predbat_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.predbat_metric_min_improvement and input_number.predbat_metric_min_improvement_discharge (both expert mode settings) also affect Predbat's cost optimisation decisions as to whether its cost beneficial to charge or discharge the battery so could be tweaked if you feel Predbat is charging or discharging with marginal benefits. The defaults (0p and 0.1p respectively) should however give good results for most users. Finally, it could be worth considering adding import or export rate increments to apps.yaml if you want to direct Predbat to avoid or encourage charging or discharging in certain time periods - e.g. avoiding exporting in the time period saving sessions normally fall in, or to encourage discharging just before import rates fall overnight.","title":"The plan doesn't charge or discharge when I expect it to"},{"location":"faq/#predbat-is-causing-warning-messages-about-exceed-maximum-size-in-the-home-assistant-core-log","text":"If you have a large input_number.predbat_forecast_plan_hours then you may see warning messages in the Home Assistant Core log about the size of a number of Predbat entities, the message will be \"State attributes for predbat. XXXX exceed maximum size of 16384 bytes\". This is just a warning, the Predbat entity attributes aren't stored in the database anyway, but you can suppress these warnings by adding the following to your configuration.yaml file: # Filter out 'message too large' warnings from Predbat entities logger: default: warning filters: homeassistant.components.recorder.db_schema: - \"State attributes for predbat.base10_export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.base10_import_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.base10_metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.base10_pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.battery_cycle exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.battery_cycle_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.battery_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.battery_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_charge_limit exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_import_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_load_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best_pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best10_export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best10_import_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best10_metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.best10_pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.cost_today_export exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.cost_today_import exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.export_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.grid_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.grid_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_energy_actual exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_energy_adjusted exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_energy_predicted exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.load_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.metric exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.plan_html exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.pv_energy exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.pv_power exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.pv_power_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.rates exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.soc_kw exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.soc_kw_base10 exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.soc_kw_best exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\" - \"State attributes for predbat.soc_kw_best10 exceed maximum size of 16384 bytes. This can cause database performance issues; Attributes will not be stored\"","title":"Predbat is causing warning messages about 'exceed maximum size' in the Home Assistant Core log"},{"location":"faq/#error-metric_octopus_import-not-set-correctly-or-no-energy-rates-can-be-read","text":"If you get this error in the Predbat log file: Check that the Octopus integration is working and that event.octopus_energy_electricity_METER_NUMBER_current_day_rates and sensor.octopus_electricity_energy_METER_NUMBER_current_rate are both populated by the integration. Ensure that you have followed the Octopus Integration Installation instructions , including enabling the Octopus Integration events. If you been using an older version of the Octopus integration and have upgraded to version 9 or above, then you may find that your energy sensors are named sensor.electricity_METER_NUMBER_current_rate (i.e. no 'octopus_energy_' prefix) but the 'event' entities have the 'octopus_energy' prefix. If the 'event' and 'sensor' entities are not consistently named then Predbat will not be able to find the event entities if the sensor names don't match what's expected. To fix this, uninstall the Octopus integration, reboot Home Assistant, delete all the old Octopus sensors, and re-install the Octopus Integration .","title":"Error - metric_octopus_import not set correctly or no energy rates can be read"},{"location":"faq/#warn-no-solar-data-has-been-configured","text":"If you get this warning message in the Predbat log file or you see that the 'PV kWh' column in the Predbat plan card is completely blank: Ensure that you have installed and configured Solcast correctly Check the Solcast integration in Home Assistant is configured and enabled (go to Settings / Integrations / Solcast ) Check that there are no errors relating to Solcast in the Home Assistant log (go to Settings / System / Logs and view the 'Home Assistant Core' log). If you see an error 429 message in the log then this is as a result of Solcast's rate limiting for Hobbyist accounts. The only fix is to re-run the 'Solcast update' automation and hope that Solcast isn't as busy when you re-run. Verify the solar forecast has been populated in Home Assistant by going to Developer Tools / States, filtering on 'solcast', and checking that you can see the half-hourly solar forecasts in the Solcast entities If you can see the solcast entities but there are no forecast PV figures, try running the 'Solcast update' automation you created, and check again the solcast entities If the solcast entities are still not populated, try reloading the Solcast integration (go to System / Devices & Services / Integrations tab, click on 'Solcast PV Forecast', click the three vertical dots beside 'Configure' and choose 'Reload' from the dropdown menu) Check sensor.solcast_pv_api_limit (it's normally 10 for new Solcast accounts) meaning you can call the Solcast API 10 times a day (but if you have two solar arrays, e.g. East/West) then retrieving the forecast will count as two API calls. Compare this to sensor.solcast_pv_api_used to see how many Solcast API calls you have made today (alternatively, you can confirm how many API calls you have made today by logging into your Solcast account). If you've run out of API calls you will have to wait until midnight GMT for the API count to reset. It's recommended that you don't include the Solcast forecast within your GivEnergy portal to avoid running out of API calls. Check the Solcast server API status is OK","title":"WARN: No solar data has been configured"},{"location":"faq/#note-can-not-find-battery-charge-curve","text":"If you get the message \"Note: Can not find battery charge curve, one of the required settings for soc_kw, battery_power and charge_rate are missing from apps.yaml\" in the logfile then Predbat is trying to create a battery charge curve but does not have access to the required history information in Home Assistant. Creating the battery charge curve is described in the apps.yaml document. The most likely cause of the above message appearing in the logfile is that you are controlling the inverter in REST mode but have not uncommented the following entities in apps.yaml that Predbat needs to obtain history from to create the battery charge curve: charge_rate: - number.givtcp_{geserial}_battery_charge_rate discharge_rate: - number.givtcp_{geserial}_battery_discharge_rate battery_power: - sensor.givtcp_{geserial}_battery_power soc_kw: - sensor.givtcp_{geserial}_soc_kwh","title":"Note: Can not find battery charge curve"},{"location":"faq/#warn-inverter-is-in-calibration-mode","text":"If you see the message \"WARN: Inverter is in calibration mode, Predbat will not function correctly and will be disabled\" in the logfile, then Predbat has identified that your inverter is currently calibrating your battery. Predbat's status will also be set to 'Calibration'. Predbat will set the inverter charge and discharge rates to maximum (if they are not already), SoC target to 100% and battery reserve to minimum (usually 4%), and will not execute the plan nor enable battery charge or discharge. Once the inverter finishes calibrating the battery, Predbat will resume normal operations.","title":"WARN: Inverter is in calibration mode"},{"location":"faq/#inverter-time-is-xxx-predbat-computer-time-is-xxx-this-is-xxx-minutes-skewed-predbat-may-not-function-correctly","text":"If the predbat.status gives a warning error about the inverter time: Then it indicates that there is a mis-match between the clock that Predbat is using and the inverter time clock, and clearly with a clock mis-match, charging and discharging your battery at specific times may not work as expected. There are several potential causes of this problem: Check that the inverter time is correctly set, especially that its set to GMT (even if its summer time). In the GivEnergy portal, go to My Inverters / Remote Control (cog symbol) / click SEND next to 'Set Date and Time' Check that the time_zone in appdaemon.yaml is correctly set for your location (e.g. Europe/London) The time zone for Predbat in apps.yaml needs to be set to the same value Finally, check how often your inverter integration is polling your inverter for new data. For GivTCP the Self Run Loop Timer is recommended to be set to a value of between 20 and 60 seconds. If you have checked the above and keep getting \u201ctime is skewed\u201d warnings then it means Home Assistant/predbat isn\u2019t getting the same time from the inverter as it is expecting. Either GivTCP has lost communications with the inverter or the inverter is stopped talking to the world. If you look at the Logbook in Home Assistant you should see a steady stream of entities changing in HA. In particular you will see the GivTCP inverter time entity changing every polling period, e.g. every 20 seconds. Possible fixes: restart the GivTCP add-on restart Home Assistant (although usually restarting GivTCP is enough) power the inverter off, turn off panels and battery first, then the inverter, then follow the reverse sequence to power the inverter back on again. This forces the inverter to reconnect to your wifi do a \u2018reset to defaults\u2019 in the portal If you keep getting the warning message, even sporadically, then this points to an underlying issue in your home network between Home Assistant and the inverter. You may need to add a Wi-Fi repeater or ideally a fixed Ethernet connection to your inverter to improve signal strength if this keeps happening. There is a Home Assistant automation that will alert you if GivTCP stops sending data to predbat .","title":"Inverter time is xxx, Predbat computer time is xxx, this is xxx minutes skewed, Predbat may not function correctly"},{"location":"faq/#i-have-another-problem-not-listed-above","text":"If you are still having trouble feel free to raise a Github ticket for support","title":"I have another problem not listed above"},{"location":"install/","text":"Install These instructions will take you through the process of installing and configuring Predbat for first time use. If you have a working Predbat installation using AppDaemon and are changing to use the Predbat add-on, the AppDaemon to Predbat add-on upgrade process is described below. It's recommended that you watch the Predbat Video Guides before you start. We have tried to make the documentation as comprehensive as possible but a level of familiarity with the basics of Home Assistant, Add-on's, Integrations, Entities, File Editing and YAML is assumed. There are plenty of \"Home Assistant basics\" tutorials on YouTube, but here are a few useful videos to introduce you to Home Assistant and displaying inverter data: What is Home Assistant from Smart Home Junkie YAML Basics from This Smart Home Installing HACS from Speak to the Geek Setting up the Energy dashboard for GivEnergy inverters from Speak to the Geek Power Flow Card Plus from Speak to the Geek If you get stuck, please read the FAQ's and if necessary raise a Github ticket for support. Inverter Control install You will need to install an integration to communicate with and control your inverter. The specific integration you need will depend on the brand of inverter you have: Brand Integration Github Link GivEnergy GivTCP https://github.com/britkat1980/ha-addons GivEnergy GivEnergy Cloud https://github.com/springfall2008/ge_cloud GivEnergy EMS GivEnergy Cloud https://github.com/springfall2008/ge_cloud Solis SolaX ModBus https://github.com/wills106/homeassistant-solax-modbus Solax Gen4 Solax Modbus https://github.com/wills106/homeassistant-solax-modbus Sofar Sofar MQTT https://github.com/cmcgerty/Sofar2mqtt Huawei Huawei Modbus https://github.com/wlcrs/huawei_solar SolarEdge SolarEdge Modbus https://github.com/WillCodeForCats/solaredge-modbus-multi SunSynk SunSynk Modbus https://github.com/kellerza/sunsynk Fox Fox Modbus https://github.com/nathanmarlor/foxess_modbus LuxPower LuxPython https://github.com/guybw/LuxPython_DEV Predbat was originally written for GivEnergy inverters controlled by the GivTCP add-on but has been extended for other inverter types. Please see Inverter Setup for details on installing and configuring the appropriate inverter control software so that Home Assistant is able to 'see' and manage your inverter. You will need at least 24 hours history in Home Assistant for Predbat to work correctly, the default is 7 days (but you configure this back to 1 day if you need to). NB: If you have multiple GivEnergy AIO's or a 3-phase inverter, GivTCP version 3 is required. Editing Configuration Files in Home Assistant The basic configuration for Predbat is stored in a configuration file called apps.yaml . A standard template apps.yaml file will be installed as part of the Predbat installation and you will need to edit and customise this configuration file for your own system setup. You will therefore need a method of editing configuration files within your Home Assistant environment. There are severals ways to achieve this in Home Assistant, but two of the simplest are to use either the File Editor or Studio Code Server add-on's. Whichever you use is a personal preference. File Editor is a bit simpler, Studio Code Server is more powerful but does require HACS (the Home Assistant Community Store) to be installed first. If you do not have one of these file editors already installed in Home Assistant: For Studio Code Server you will need to install HACS first if you don't currently have it installed Go to Settings / Add-ons / Add-on Store (bottom right) Scroll down the add-on store list, to find either 'File editor' or 'Studio Code Server' as appropriate, click on the add-on, click 'INSTALL' Once the editor has been installed, ensure that the 'Start on boot' option is turned on, and click 'START' to start the add-on Thereafter whenever you need to edit a configuration file in Home Assistant you can navigate to Settings / Add-on's / editor_you_chose_to_use / 'OPEN WEB UI'. You can also turn the 'Show in sidebar' option on to give a quicker way to directly access the editor. If you are using the File Editor to edit Predbat's configuration files, you will need to turn OFF the Enforce Basepath option in order to access files in different directories (i.e. within the appdaemon directory): From the File editor add-on page, click on the 'Configuration' tab to change this setting). It is set to 'On' by default: If you are using Studio Code Server it will default to showing just files and folders in the /config directory. To access the entire HA directory structure, click the three horizontal bars to the left of 'Explorer', File, Open Folder, type '/' (root) and click OK. Predbat add-on install Recommended The simplest way to install Predbat now is with the Predbat add-on. Go to settings, add-ons, select Add-on Store, three dots on the top right, Repositories, then add the following repo ' https://github.com/springfall2008/predbat_addon ' to the list and click close. Now refresh the list and find Predbat, click on it and click 'install'. Ensure 'start on boot' is enabled and click 'start'. NOTE: Throughout the rest of the Predbat documentation you will find reference to the Predbat configuration file apps.yaml and the Predbat logfile. These are located under the Home Assistant directory /addon_configs/6adb4f0d_predbat which contains: predbat.log - Predbat's active logfile that reports detail of what Predbat is doing, and details of any errors apps.yaml - Predbat's configuration file which will need to be customised to your system and requirements. This configuration process is described below. You can use your file editor (i.e. 'File editor' or 'Studio Code Server' add-on) to open the directory /addon_configs/6adb4f0d_predbat and view these files. If you have used the Predbat add-on installation method you do not need to install HACS or AppDaemon so you can skip directly to Solcast install below. The Predbat web interface will work through the Predbat add-on, you can click on the 'Web UI' button to open it once Predbat is running. If you wish to use Docker with Predbat its recommended you read the Docker installation instructions inside the Predbat add-on rather than going down the AppDaemon route listed below. Predbat installation into AppDaemon Not Recommended NOTE: The Predbat web interface will not work with the AppDaemon installation method. This is the old way of installing Predbat, to firstly install HACS (the Home Assistant Community Store), then install the AppDaemon add-on, and finally install Predbat from HACS to run within AppDaemon. NOTE: If you are using AppDaemon you now must set ha_key and ha_url in apps.yaml to point to your Home Assistant. The key can be obtained from HA by creating an access token. HACS install Predbat and AppDaemon are available through the Home Assistant Community Store (HACS). You can install Predbat manually (see below) but its usually easier to install it through HACS. Install HACS if you haven't already ( https://hacs.xyz/docs/setup/download ) Enable AppDaemon in HACS: https://hacs.xyz/docs/categories/appdaemon_apps/ AppDaemon install Predbat is written in Python and runs on a continual loop (default every 5 minutes) within the AppDaemon add-on to Home Assistant. The next task therefore is to install and configure AppDaemon. Install the AppDaemon add-on https://github.com/hassio-addons/addon-appdaemon Once AppDaemon has finished installing, ensure that the 'Start on boot' option is turned on, then click 'START' You will need to edit the appdaemon.yaml configuration file for AppDaemon and so will need to have either the File Editor or Studio Code Server add-on's installed first Find the appdaemon.yaml file in the directory /addon_configs/a0d7b954_appdaemon : Add to the appdaemon.yaml configuration file: A section app_dir which should refer to the directory /homeassistant/appdaemon/apps where Predbat will be installed Ensure that the time_zone is set correctly (e.g. Europe/London) Add thread_duration_warning_threshold: 120 in the appdaemon section It's recommended you also add a logs section and specify a new logfile location so that you can see the complete logs, I set mine to /homeassistant/appdaemon/appdaemon.log and increase the logfile maximum size and number of logfile generations to capture a few days worth of logs. Example AppDaemon config in appdaemon.yaml : appdaemon: latitude: 52.379189 longitude: 4.899431 elevation: 2 time_zone: Europe/London thread_duration_warning_threshold: 120 plugins: HASS: type: hass app_dir: /homeassistant/appdaemon/apps http: url: http://homeassistant.local:5050 admin: api: hadashboard: # write log records to a file, retaining 9 versions, rather than the standard appdaemon log logs: main_log: filename: /homeassistant/appdaemon/appdaemon.log log_generations: 9 log_size: 10000000 CAUTION: If you are upgrading AppDaemon from an older version to version 0.15.2 or above you need to follow these steps to ensure Predbat continues working. These are only required if you are upgrading AppDaemon from an old version, they're not required for new installations of AppDaemon: Make sure you have access to the HA filesystem, e.g. I use the Samba add-on and connect to the drives on my Mac, but you can use ssh also. Update AppDaemon to the latest version Go into the directory /addon_configs/a0d7b954_appdaemon and edit appdaemon.yaml . You need to add app_dir (see above) to point to the old location and update your logfile location (if you have set it). You should remove the line that points to secrets.yaml (most people don't use this file) or adjust it's path to the new location ( /homeassistant/secrets.yaml ) Move the entire 'apps' directory from /addon_configs/a0d7b954_appdaemon (new location) to /config/appdaemon (the old location) Restart AppDaemon Check it has started and confirm Predbat is running correctly again. Install Predbat through HACS If you install Predbat through HACS, once installed you will get automatic updates for each new release of Predbat! In HACS, click on Automation Click on the three dots in the top right corner, choose Custom Repositories Add https://github.com/springfall2008/batpred as a custom repository of Category 'AppDaemon' and click 'Add' Click Explore and download repositories (bottom right), type 'Predbat' in the search box, select the Predbat Repository, then click 'Download' to install the Predbat app. NOTE: Throughout the rest of the Predbat documentation you will find reference to the Predbat configuration file apps.yaml and the Predbat logfile. As you are following the 'install Predbat through HACS' installation method these are located under the Home Assistant directory /config/appdaemon/ which contains: appdaemon.log - AppDaemon and Predbat's active logfile that reports detail of what Predbat is doing, and details of any errors apps/batpred/config/apps.yaml - Predbat's configuration file which will need to be customised to your system and requirements. This configuration process is described below. Predbat manual install A manual install is suitable for those running Docker type systems where HACS does not function correctly and you had to manually install AppDaemon. Note: Not recommended if you are using HACS Copy all the .py files to the /config/appdaemon/apps/ directory in Home Assistant (or wherever you set appdaemon app_dir to) Copy apps/predbat/apps.yaml to the /config/appdaemon/apps/ directory in Home Assistant (or wherever you set appdaemon app_dir to) Edit in Home Assistant the /config/appdaemon/apps/apps.yaml file to configure Predbat If you later install with HACS then you must move the apps.yaml into /config/appdaemon/apps/predbat/config Solcast Install Predbat needs a solar forecast in order to predict solar generation and battery charging. If you do have solar panels its recommended to use the Solcast integration to retrieve your forecast solar generation. If you don't have one already, register for a free Solcast hobbyist account and enter the details of your system. You can create 2 sites maximum under one (free hobbyist) account, if you have more aspects then its suggested you average the angle based on the number of panels e.g. 7/10 240 degrees + 3/10 120 degrees. Hybrid inverters only : If your hybrid inverter capacity is smaller than your array peak capacity, tell Solcast that your AC capacity is equal to your DC capacity (both equal to your array peak kW). Otherwise, Solcast will provide forecast data clipped at your inverter capacity. Let Predbat handle any necessary clipping instead. When supplied with the unclipped Solcast forecast data, Predbat can allow in its model for PV in excess of the inverter capacity going to battery charging (bypassing the hybrid inverter). You will need your API key for the next steps: Predbat direct Solcast method Predbat can obtain the solar forecast directly from Solcast and the Solcast integration described below is not required. First get your API key from the Solcast web site, then as described in the Solcast apps.yaml documentation , uncomment the Solcast cloud interface settings in apps.yaml and set the API key correctly: solcast_host: 'https://api.solcast.com.au/' solcast_api_key: 'xxxx' solcast_poll_hours: 8 NB: If you use Predbat to obtain your solcast solar forecast then you can't include the Solar Forecast within the Home Assistant Energy dashboard as you can with the Solcast integration described below. The Solcast integration also contains a 'solar dampening' feature that may be useful to reduce the solar forecast that Predbat receives at certain times of day, e.g. if your panels are shaded by trees or buildings. Solcast Home Assistant integration method Install the Solcast integration ( https://github.com/BJReplay/ha-solcast-solar ), create a free Solcast account , configure details of your solar arrays, and request an API key that you enter into the Solcast integration in Home Assistant. Predbat is configured in apps.yaml to automatically discover the Solcast forecast entities created by the Solcast integration in Home Assistant. If you don't have any solar generation then use a file editor to comment out the following lines from the Solar forecast part of the apps.yaml configuration: pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today) pv_forecast_tomorrow: re:(sensor.(solcast_|)(pv_forecast_|)forecast_tomorrow) pv_forecast_d3: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_3|d3)) pv_forecast_d4: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_4|d4)) Note that Predbat does not update Solcast integration for you so you will need to create your own Home Assistant automation that updates the solar forecast a few times a day (e.g. dawn, dusk, and just before your nightly charge slot). Keep in mind hobbyist accounts only have 10 polls per day so the refresh period needs to be less than this. If you use the same Solcast account for other automations the total polls needs to be kept under the limit or you will experience failures. Due to the popularity of the Solcast Hobbyist service, Solcast have introduced rate limiting for Hobbyist (free) accounts. If your update gets a 429 error then this is due to rate limiting. Solcast recommend that you poll for updated solar forecasts at random times, i.e. don't poll at precisely X o'clock and zero seconds. The Solcast integration will auto-retry if it gets a 429 error, but to minimise potential rate limiting the sample Solcast automation below contains non-precise poll times for just this reason. Example Solcast update automation script: alias: Solcast update description: \"Update Solcast solar forecast\" triggers: - trigger: time at: - \"06:02:34\" - \"12:07:47\" - \"18:09:56\" - \"23:11:18\" conditions: [] actions: - action: solcast_solar.update_forecasts data: {} mode: single Manually run the automation and then make sure the Solcast integration is working in Home Assistant by going to Developer Tools / States, filtering on 'solcast', and checking that you can see the half-hourly solar forecasts in the Solcast entities. Energy Rates Predbat needs to know what your electricity import and export rates are in order to optimise battery charging and discharging to minimise your expenditure. These rates are configured in Predbat's apps.yaml configuration file. Follow the instructions in the Energy Rates document. Note: that if you are using the Octopus integration the 'sensor.octopus_xxx' and 'event.octopus_xxx' entities must have a similar pattern of names for Predbat to work correctly - see the FAQ's if they are not. Configuring Predbat You will need to use a file editor (either the File editor or Studio Code Server add-on) to edit the apps.yaml file in Home Assistant to configure Predbat - see Configuring apps.yaml . When Predbat starts up initially it will perform a sanity check of itself and the configuration and confirm the right files are present. You will see this check in the log, should it fail a warning will be issued and predbat.status will also reflect the warning. While the above warning might not prevent Predbat from starting up, you should fix the issue ASAP as it may cause future problems. Note: if you are running the Predbat through the Predbat add-on or via Docker you will get a logfile warning message \"Warn: unable to find /addon_configs/6adb4f0d_predbat/appdaemon.yaml skipping checks as Predbat maybe running outside of AppDaemon\" - this is normal and can be ignored. Predbat Output and Configuration Controls As described above, the basic configuration of Predbat is held in the apps.yaml configuration file. 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 section describes these points in more detail including using the auto-generated predbat_dashboard.yaml dashboard file. 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 . The Predbat Configuration Guide 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 detailed Predbat Customisation Guide 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 and the other components it is dependent upon (e.g. an inverter controller such as GivTCP, Solcast solar forecast, Octopus Energy integration, etc). You have checked the Predbat log file 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 some dashboard pages to control and monitor Predbat , and are ready to start Predbat generating your plan. You may initially want to set select.predbat_mode to Monitor to see how Predbat operates, e.g. by studying the Predbat Plan . 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. NB: In Monitor mode Predbat will NOT plan any battery charge or discharge activity of its own, it will report on the predicted battery charge level based on the current inverter charge & discharge settings, predicted house load and predicted solar generation. In order to enable Predbat to start generating your plan you must delete the 'template: True' line in apps.yaml once you are happy with your configuration. Predbat will automatically run, analyse your house load, battery status, solar prediction, etc and produce a plan based upon the current battery settings. Check the Predbat logfile again for errors. Voluminous output is quite normal but any errors or warnings should be investigated. Read the Predbat FAQ's for answers to common questions you may have. Also check the Predbat status predbat.status - major errors will also be flagged here. Once Predbat is running successfully 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 further customise Predbat's settings to meet your needs. Set select.predbat_mode to the correct mode of operation for your system - usually 'Control charge' or 'Control charge & discharge'. ALSO you should set switch.predbat_set_read_only to True to stop Predbat making any changes to your inverter. You can see the planned solar and grid charging and discharging activity in the Predbat Plan . Another set of views can be seen in the detailed Apex Charts showing Predbat's predictions . 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. Updating Predbat Note that any future updates to Predbat will not overwrite the apps.yaml configuration file that you have tailored to your setup. If new Predbat releases introduce new features to apps.yaml you may therefore need to manually copy across the new apps.yaml settings from the Template apps.yaml . Update via Home Assistant Recommended Predbat can now be updated using the Home Assistant update feature. When a new release is available you should see it in the Home Assistant settings: Click on the update and select install: Predbat built-in update Recommended for manual selection of versions or automatic updates Predbat can now update itself, just select the version of Predbat you want to install from the select.predbat_update drop down menu, the latest version will be at the top of the list. Predbat will update itself and automatically restart. Alternatively, if you turn on switch.predbat_auto_update , Predbat will automatically update itself as new releases are published on Github. Once Predbat has been installed and configured you should update Predbat to the latest version by selecting the latest version in the select.predbat_update selector, or by enabling the switch.predbat_auto_update to auto-update Predbat. Please note that using the internal update mechanism of Predbat will not inform HACS that Predbat has been updated. If you used HACS to install Predbat you do not need to use it again unless your system is in need of repair. HACS Update Not Recommended HACS checks for updates and new releases only once a day by default, you can however force it to check again, or download a specific version by using the 'Redownload' option from the top-right three dots menu for Predbat in the HACS Automation section. NOTE: If you update Predbat through HACS you may need to restart AppDaemon as it sometimes reads the config wrongly during the update. (If this happens you will get a template configuration error in the entity predbat.status ). Go to Settings, Add-ons, AppDaemon, and click 'Restart'. If you update Predbat via Home Assistant or via Predbat's build-in update then HACS will not know about this and you'll continue to get messages in HACS about updating Predbat. Manual update of Predbat Expert only You can go to Github and download all the .py files from the releases tab and then manually copy these files over the existing version in /config/appdaemon/apps/batpred/ manually. Upgrading from AppDaemon to Predbat add-on These steps assume you already have a working Predbat system and want to upgrade to using the Predbat add-on instead of using either the AppDaemon or the AppDaemon-predbat add-on. Using the Predbat add-on is the strategic direction for Predbat and resolves some performance and data load issues that can occur with AppDaemon. The Predbat code that runs is exactly the same and the configuration is exactly the same, its just changing the 'container' that Predbat runs within. Before starting, watch the installing Predbat add-on video Although the upgrade steps are low risk, take a full backup of Home Assistant before starting Install the Predbat add-on : Add the Predbat add-on to the list of Repositories in the add-on store Install the Predbat add-on But do not start it - yet Install a file editor if you don't have one already installed - either File Editor or Studio Code Server, it doesn't matter Shutdown your existing AppDaemon or AppDaemon-predbat add-on: Go to Settings/Add-ons Click on the existing AppDaemon/AppDaemon-predbat add-on Click STOP, and untick 'Start on boot' Briefly start the new Predbat add-on so that it creates the addon_config folder and the template apps.yaml file: Go to Settings/Add-ons Click on the Predbat add-on Click START, wait a minute for the add-on to initialise itself, then click STOP. A predbat status warning that you have a template apps.yaml file is normal and can be ignored Open your file editor and open your existing apps.yaml file: If you are using the old 'combined AppDaemon/Predbat add-on installation method' it's in the directory /addon_configs/46f69597_appdaemon-predbat/apps , or with the HACS, Appdaemon add-on then Predbat installation method , it's in /config/appdaemon/apps/batpred/config/ Select all the contents of the apps.yaml file and 'copy' (control-C, command-C, etc as appropriate) Now open the template apps.yaml file that's supplied with the Predbat add-on and has been created in the directory /addon_configs/6adb4f0d_predbat , select all the contents of the template apps.yaml file, and paste in the contents of your existing apps.yaml, overwriting the template with your specific configuration Now you are ready to swap from running the AppDaemon or AppDaemon-predbat add-on to the Predbat add-on: Go to Settings/Add-ons Click on the existing AppDaemon/AppDaemon-predbat add-on Make sure it is not running and 'Start on boot' is not ticked Click the back arrow Click on the Predbat add-on Click START, and tick 'Start on boot' If you are using the Predbat automatic monitor then you will need to enable the predbat_running binary sensor and change the automation, replacing the AppDaemon add-on id (a0d7b954_appdaemon) with 'a06adb4f0d_predbat', and 'binary_sensor.appdaemon_running' with 'binary_sensor.predbat_running'. And that's it. You should check the Log tab to ensure it all starts properly, but it should do as you've copied over your existing configuration. Note that if you are using the Predbat direct connection to Solcast then the Predbat add-on will need to download your solar forecast so will use up one or two of your daily API calls (hobbyist accounts have a 10 API a day limit). If you are using the Solcast integration then this won't be required. You may find that the Predbat add-on installed with an older version of Predbat than you were previously using, which might require you to update Predbat to the correct version . When you are happy running the Predbat add-on you can delete the AppDaemon or AppDaemon-predbat add-on. Backing up Home Assistant and Predbat It's strongly recommended that you implement an automatic mechanism to backup your Home Assistant and Predbat system. There are several ways of backing up Home Assistant but one of the simplest is the Home Assistant Google Drive Backup which is an add-on that runs every night, automatically makes a backup of Home Assistant (including Predbat), and copies that backup to a Google Drive for safe keeping. If you create a new Google account specifically for your Home Assistant backups you will automatically get 15Gb of free Google Drive storage, enough for a couple of weeks of backups. As well as the full Home Assistant backup you manually copy the contents of Predbat's apps.yaml configuration file to somewhere safe so that if you accidentally mis-edit it, you can get Predbat working quickly again by copying it back again.","title":"Install details"},{"location":"install/#install","text":"These instructions will take you through the process of installing and configuring Predbat for first time use. If you have a working Predbat installation using AppDaemon and are changing to use the Predbat add-on, the AppDaemon to Predbat add-on upgrade process is described below. It's recommended that you watch the Predbat Video Guides before you start. We have tried to make the documentation as comprehensive as possible but a level of familiarity with the basics of Home Assistant, Add-on's, Integrations, Entities, File Editing and YAML is assumed. There are plenty of \"Home Assistant basics\" tutorials on YouTube, but here are a few useful videos to introduce you to Home Assistant and displaying inverter data: What is Home Assistant from Smart Home Junkie YAML Basics from This Smart Home Installing HACS from Speak to the Geek Setting up the Energy dashboard for GivEnergy inverters from Speak to the Geek Power Flow Card Plus from Speak to the Geek If you get stuck, please read the FAQ's and if necessary raise a Github ticket for support.","title":"Install"},{"location":"install/#inverter-control-install","text":"You will need to install an integration to communicate with and control your inverter. The specific integration you need will depend on the brand of inverter you have: Brand Integration Github Link GivEnergy GivTCP https://github.com/britkat1980/ha-addons GivEnergy GivEnergy Cloud https://github.com/springfall2008/ge_cloud GivEnergy EMS GivEnergy Cloud https://github.com/springfall2008/ge_cloud Solis SolaX ModBus https://github.com/wills106/homeassistant-solax-modbus Solax Gen4 Solax Modbus https://github.com/wills106/homeassistant-solax-modbus Sofar Sofar MQTT https://github.com/cmcgerty/Sofar2mqtt Huawei Huawei Modbus https://github.com/wlcrs/huawei_solar SolarEdge SolarEdge Modbus https://github.com/WillCodeForCats/solaredge-modbus-multi SunSynk SunSynk Modbus https://github.com/kellerza/sunsynk Fox Fox Modbus https://github.com/nathanmarlor/foxess_modbus LuxPower LuxPython https://github.com/guybw/LuxPython_DEV Predbat was originally written for GivEnergy inverters controlled by the GivTCP add-on but has been extended for other inverter types. Please see Inverter Setup for details on installing and configuring the appropriate inverter control software so that Home Assistant is able to 'see' and manage your inverter. You will need at least 24 hours history in Home Assistant for Predbat to work correctly, the default is 7 days (but you configure this back to 1 day if you need to). NB: If you have multiple GivEnergy AIO's or a 3-phase inverter, GivTCP version 3 is required.","title":"Inverter Control install"},{"location":"install/#editing-configuration-files-in-home-assistant","text":"The basic configuration for Predbat is stored in a configuration file called apps.yaml . A standard template apps.yaml file will be installed as part of the Predbat installation and you will need to edit and customise this configuration file for your own system setup. You will therefore need a method of editing configuration files within your Home Assistant environment. There are severals ways to achieve this in Home Assistant, but two of the simplest are to use either the File Editor or Studio Code Server add-on's. Whichever you use is a personal preference. File Editor is a bit simpler, Studio Code Server is more powerful but does require HACS (the Home Assistant Community Store) to be installed first. If you do not have one of these file editors already installed in Home Assistant: For Studio Code Server you will need to install HACS first if you don't currently have it installed Go to Settings / Add-ons / Add-on Store (bottom right) Scroll down the add-on store list, to find either 'File editor' or 'Studio Code Server' as appropriate, click on the add-on, click 'INSTALL' Once the editor has been installed, ensure that the 'Start on boot' option is turned on, and click 'START' to start the add-on Thereafter whenever you need to edit a configuration file in Home Assistant you can navigate to Settings / Add-on's / editor_you_chose_to_use / 'OPEN WEB UI'. You can also turn the 'Show in sidebar' option on to give a quicker way to directly access the editor. If you are using the File Editor to edit Predbat's configuration files, you will need to turn OFF the Enforce Basepath option in order to access files in different directories (i.e. within the appdaemon directory): From the File editor add-on page, click on the 'Configuration' tab to change this setting). It is set to 'On' by default: If you are using Studio Code Server it will default to showing just files and folders in the /config directory. To access the entire HA directory structure, click the three horizontal bars to the left of 'Explorer', File, Open Folder, type '/' (root) and click OK.","title":"Editing Configuration Files in Home Assistant"},{"location":"install/#predbat-add-on-install","text":"Recommended The simplest way to install Predbat now is with the Predbat add-on. Go to settings, add-ons, select Add-on Store, three dots on the top right, Repositories, then add the following repo ' https://github.com/springfall2008/predbat_addon ' to the list and click close. Now refresh the list and find Predbat, click on it and click 'install'. Ensure 'start on boot' is enabled and click 'start'. NOTE: Throughout the rest of the Predbat documentation you will find reference to the Predbat configuration file apps.yaml and the Predbat logfile. These are located under the Home Assistant directory /addon_configs/6adb4f0d_predbat which contains: predbat.log - Predbat's active logfile that reports detail of what Predbat is doing, and details of any errors apps.yaml - Predbat's configuration file which will need to be customised to your system and requirements. This configuration process is described below. You can use your file editor (i.e. 'File editor' or 'Studio Code Server' add-on) to open the directory /addon_configs/6adb4f0d_predbat and view these files. If you have used the Predbat add-on installation method you do not need to install HACS or AppDaemon so you can skip directly to Solcast install below. The Predbat web interface will work through the Predbat add-on, you can click on the 'Web UI' button to open it once Predbat is running. If you wish to use Docker with Predbat its recommended you read the Docker installation instructions inside the Predbat add-on rather than going down the AppDaemon route listed below.","title":"Predbat add-on install"},{"location":"install/#predbat-installation-into-appdaemon","text":"Not Recommended NOTE: The Predbat web interface will not work with the AppDaemon installation method. This is the old way of installing Predbat, to firstly install HACS (the Home Assistant Community Store), then install the AppDaemon add-on, and finally install Predbat from HACS to run within AppDaemon. NOTE: If you are using AppDaemon you now must set ha_key and ha_url in apps.yaml to point to your Home Assistant. The key can be obtained from HA by creating an access token.","title":"Predbat installation into AppDaemon"},{"location":"install/#hacs-install","text":"Predbat and AppDaemon are available through the Home Assistant Community Store (HACS). You can install Predbat manually (see below) but its usually easier to install it through HACS. Install HACS if you haven't already ( https://hacs.xyz/docs/setup/download ) Enable AppDaemon in HACS: https://hacs.xyz/docs/categories/appdaemon_apps/","title":"HACS install"},{"location":"install/#appdaemon-install","text":"Predbat is written in Python and runs on a continual loop (default every 5 minutes) within the AppDaemon add-on to Home Assistant. The next task therefore is to install and configure AppDaemon. Install the AppDaemon add-on https://github.com/hassio-addons/addon-appdaemon Once AppDaemon has finished installing, ensure that the 'Start on boot' option is turned on, then click 'START' You will need to edit the appdaemon.yaml configuration file for AppDaemon and so will need to have either the File Editor or Studio Code Server add-on's installed first Find the appdaemon.yaml file in the directory /addon_configs/a0d7b954_appdaemon : Add to the appdaemon.yaml configuration file: A section app_dir which should refer to the directory /homeassistant/appdaemon/apps where Predbat will be installed Ensure that the time_zone is set correctly (e.g. Europe/London) Add thread_duration_warning_threshold: 120 in the appdaemon section It's recommended you also add a logs section and specify a new logfile location so that you can see the complete logs, I set mine to /homeassistant/appdaemon/appdaemon.log and increase the logfile maximum size and number of logfile generations to capture a few days worth of logs. Example AppDaemon config in appdaemon.yaml : appdaemon: latitude: 52.379189 longitude: 4.899431 elevation: 2 time_zone: Europe/London thread_duration_warning_threshold: 120 plugins: HASS: type: hass app_dir: /homeassistant/appdaemon/apps http: url: http://homeassistant.local:5050 admin: api: hadashboard: # write log records to a file, retaining 9 versions, rather than the standard appdaemon log logs: main_log: filename: /homeassistant/appdaemon/appdaemon.log log_generations: 9 log_size: 10000000 CAUTION: If you are upgrading AppDaemon from an older version to version 0.15.2 or above you need to follow these steps to ensure Predbat continues working. These are only required if you are upgrading AppDaemon from an old version, they're not required for new installations of AppDaemon: Make sure you have access to the HA filesystem, e.g. I use the Samba add-on and connect to the drives on my Mac, but you can use ssh also. Update AppDaemon to the latest version Go into the directory /addon_configs/a0d7b954_appdaemon and edit appdaemon.yaml . You need to add app_dir (see above) to point to the old location and update your logfile location (if you have set it). You should remove the line that points to secrets.yaml (most people don't use this file) or adjust it's path to the new location ( /homeassistant/secrets.yaml ) Move the entire 'apps' directory from /addon_configs/a0d7b954_appdaemon (new location) to /config/appdaemon (the old location) Restart AppDaemon Check it has started and confirm Predbat is running correctly again.","title":"AppDaemon install"},{"location":"install/#install-predbat-through-hacs","text":"If you install Predbat through HACS, once installed you will get automatic updates for each new release of Predbat! In HACS, click on Automation Click on the three dots in the top right corner, choose Custom Repositories Add https://github.com/springfall2008/batpred as a custom repository of Category 'AppDaemon' and click 'Add' Click Explore and download repositories (bottom right), type 'Predbat' in the search box, select the Predbat Repository, then click 'Download' to install the Predbat app. NOTE: Throughout the rest of the Predbat documentation you will find reference to the Predbat configuration file apps.yaml and the Predbat logfile. As you are following the 'install Predbat through HACS' installation method these are located under the Home Assistant directory /config/appdaemon/ which contains: appdaemon.log - AppDaemon and Predbat's active logfile that reports detail of what Predbat is doing, and details of any errors apps/batpred/config/apps.yaml - Predbat's configuration file which will need to be customised to your system and requirements. This configuration process is described below.","title":"Install Predbat through HACS"},{"location":"install/#predbat-manual-install","text":"A manual install is suitable for those running Docker type systems where HACS does not function correctly and you had to manually install AppDaemon. Note: Not recommended if you are using HACS Copy all the .py files to the /config/appdaemon/apps/ directory in Home Assistant (or wherever you set appdaemon app_dir to) Copy apps/predbat/apps.yaml to the /config/appdaemon/apps/ directory in Home Assistant (or wherever you set appdaemon app_dir to) Edit in Home Assistant the /config/appdaemon/apps/apps.yaml file to configure Predbat If you later install with HACS then you must move the apps.yaml into /config/appdaemon/apps/predbat/config","title":"Predbat manual install"},{"location":"install/#solcast-install","text":"Predbat needs a solar forecast in order to predict solar generation and battery charging. If you do have solar panels its recommended to use the Solcast integration to retrieve your forecast solar generation. If you don't have one already, register for a free Solcast hobbyist account and enter the details of your system. You can create 2 sites maximum under one (free hobbyist) account, if you have more aspects then its suggested you average the angle based on the number of panels e.g. 7/10 240 degrees + 3/10 120 degrees. Hybrid inverters only : If your hybrid inverter capacity is smaller than your array peak capacity, tell Solcast that your AC capacity is equal to your DC capacity (both equal to your array peak kW). Otherwise, Solcast will provide forecast data clipped at your inverter capacity. Let Predbat handle any necessary clipping instead. When supplied with the unclipped Solcast forecast data, Predbat can allow in its model for PV in excess of the inverter capacity going to battery charging (bypassing the hybrid inverter). You will need your API key for the next steps:","title":"Solcast Install"},{"location":"install/#predbat-direct-solcast-method","text":"Predbat can obtain the solar forecast directly from Solcast and the Solcast integration described below is not required. First get your API key from the Solcast web site, then as described in the Solcast apps.yaml documentation , uncomment the Solcast cloud interface settings in apps.yaml and set the API key correctly: solcast_host: 'https://api.solcast.com.au/' solcast_api_key: 'xxxx' solcast_poll_hours: 8 NB: If you use Predbat to obtain your solcast solar forecast then you can't include the Solar Forecast within the Home Assistant Energy dashboard as you can with the Solcast integration described below. The Solcast integration also contains a 'solar dampening' feature that may be useful to reduce the solar forecast that Predbat receives at certain times of day, e.g. if your panels are shaded by trees or buildings.","title":"Predbat direct Solcast method"},{"location":"install/#solcast-home-assistant-integration-method","text":"Install the Solcast integration ( https://github.com/BJReplay/ha-solcast-solar ), create a free Solcast account , configure details of your solar arrays, and request an API key that you enter into the Solcast integration in Home Assistant. Predbat is configured in apps.yaml to automatically discover the Solcast forecast entities created by the Solcast integration in Home Assistant. If you don't have any solar generation then use a file editor to comment out the following lines from the Solar forecast part of the apps.yaml configuration: pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today) pv_forecast_tomorrow: re:(sensor.(solcast_|)(pv_forecast_|)forecast_tomorrow) pv_forecast_d3: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_3|d3)) pv_forecast_d4: re:(sensor.(solcast_|)(pv_forecast_|)forecast_(day_4|d4)) Note that Predbat does not update Solcast integration for you so you will need to create your own Home Assistant automation that updates the solar forecast a few times a day (e.g. dawn, dusk, and just before your nightly charge slot). Keep in mind hobbyist accounts only have 10 polls per day so the refresh period needs to be less than this. If you use the same Solcast account for other automations the total polls needs to be kept under the limit or you will experience failures. Due to the popularity of the Solcast Hobbyist service, Solcast have introduced rate limiting for Hobbyist (free) accounts. If your update gets a 429 error then this is due to rate limiting. Solcast recommend that you poll for updated solar forecasts at random times, i.e. don't poll at precisely X o'clock and zero seconds. The Solcast integration will auto-retry if it gets a 429 error, but to minimise potential rate limiting the sample Solcast automation below contains non-precise poll times for just this reason. Example Solcast update automation script: alias: Solcast update description: \"Update Solcast solar forecast\" triggers: - trigger: time at: - \"06:02:34\" - \"12:07:47\" - \"18:09:56\" - \"23:11:18\" conditions: [] actions: - action: solcast_solar.update_forecasts data: {} mode: single Manually run the automation and then make sure the Solcast integration is working in Home Assistant by going to Developer Tools / States, filtering on 'solcast', and checking that you can see the half-hourly solar forecasts in the Solcast entities.","title":"Solcast Home Assistant integration method"},{"location":"install/#energy-rates","text":"Predbat needs to know what your electricity import and export rates are in order to optimise battery charging and discharging to minimise your expenditure. These rates are configured in Predbat's apps.yaml configuration file. Follow the instructions in the Energy Rates document. Note: that if you are using the Octopus integration the 'sensor.octopus_xxx' and 'event.octopus_xxx' entities must have a similar pattern of names for Predbat to work correctly - see the FAQ's if they are not.","title":"Energy Rates"},{"location":"install/#configuring-predbat","text":"You will need to use a file editor (either the File editor or Studio Code Server add-on) to edit the apps.yaml file in Home Assistant to configure Predbat - see Configuring apps.yaml . When Predbat starts up initially it will perform a sanity check of itself and the configuration and confirm the right files are present. You will see this check in the log, should it fail a warning will be issued and predbat.status will also reflect the warning. While the above warning might not prevent Predbat from starting up, you should fix the issue ASAP as it may cause future problems. Note: if you are running the Predbat through the Predbat add-on or via Docker you will get a logfile warning message \"Warn: unable to find /addon_configs/6adb4f0d_predbat/appdaemon.yaml skipping checks as Predbat maybe running outside of AppDaemon\" - this is normal and can be ignored.","title":"Configuring Predbat"},{"location":"install/#predbat-output-and-configuration-controls","text":"As described above, the basic configuration of Predbat is held in the apps.yaml configuration file. 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 section describes these points in more detail including using the auto-generated predbat_dashboard.yaml dashboard file. 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 . The Predbat Configuration Guide 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 detailed Predbat Customisation Guide details all the Predbat configuration items (switches, input numbers, etc) in Home Assistant, and what each of them does.","title":"Predbat Output and Configuration Controls"},{"location":"install/#ready-to-light-the-touch-paper","text":"By now you should have successfully installed and configured Predbat and the other components it is dependent upon (e.g. an inverter controller such as GivTCP, Solcast solar forecast, Octopus Energy integration, etc). You have checked the Predbat log file 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 some dashboard pages to control and monitor Predbat , and are ready to start Predbat generating your plan. You may initially want to set select.predbat_mode to Monitor to see how Predbat operates, e.g. by studying the Predbat Plan . 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. NB: In Monitor mode Predbat will NOT plan any battery charge or discharge activity of its own, it will report on the predicted battery charge level based on the current inverter charge & discharge settings, predicted house load and predicted solar generation. In order to enable Predbat to start generating your plan you must delete the 'template: True' line in apps.yaml once you are happy with your configuration. Predbat will automatically run, analyse your house load, battery status, solar prediction, etc and produce a plan based upon the current battery settings. Check the Predbat logfile again for errors. Voluminous output is quite normal but any errors or warnings should be investigated. Read the Predbat FAQ's for answers to common questions you may have. Also check the Predbat status predbat.status - major errors will also be flagged here. Once Predbat is running successfully 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 further customise Predbat's settings to meet your needs. Set select.predbat_mode to the correct mode of operation for your system - usually 'Control charge' or 'Control charge & discharge'. ALSO you should set switch.predbat_set_read_only to True to stop Predbat making any changes to your inverter. You can see the planned solar and grid charging and discharging activity in the Predbat Plan . Another set of views can be seen in the detailed Apex Charts showing Predbat's predictions . 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.","title":"Ready to light the touch-paper"},{"location":"install/#updating-predbat","text":"Note that any future updates to Predbat will not overwrite the apps.yaml configuration file that you have tailored to your setup. If new Predbat releases introduce new features to apps.yaml you may therefore need to manually copy across the new apps.yaml settings from the Template apps.yaml .","title":"Updating Predbat"},{"location":"install/#update-via-home-assistant","text":"Recommended Predbat can now be updated using the Home Assistant update feature. When a new release is available you should see it in the Home Assistant settings: Click on the update and select install:","title":"Update via Home Assistant"},{"location":"install/#predbat-built-in-update","text":"Recommended for manual selection of versions or automatic updates Predbat can now update itself, just select the version of Predbat you want to install from the select.predbat_update drop down menu, the latest version will be at the top of the list. Predbat will update itself and automatically restart. Alternatively, if you turn on switch.predbat_auto_update , Predbat will automatically update itself as new releases are published on Github. Once Predbat has been installed and configured you should update Predbat to the latest version by selecting the latest version in the select.predbat_update selector, or by enabling the switch.predbat_auto_update to auto-update Predbat. Please note that using the internal update mechanism of Predbat will not inform HACS that Predbat has been updated. If you used HACS to install Predbat you do not need to use it again unless your system is in need of repair.","title":"Predbat built-in update"},{"location":"install/#hacs-update","text":"Not Recommended HACS checks for updates and new releases only once a day by default, you can however force it to check again, or download a specific version by using the 'Redownload' option from the top-right three dots menu for Predbat in the HACS Automation section. NOTE: If you update Predbat through HACS you may need to restart AppDaemon as it sometimes reads the config wrongly during the update. (If this happens you will get a template configuration error in the entity predbat.status ). Go to Settings, Add-ons, AppDaemon, and click 'Restart'. If you update Predbat via Home Assistant or via Predbat's build-in update then HACS will not know about this and you'll continue to get messages in HACS about updating Predbat.","title":"HACS Update"},{"location":"install/#manual-update-of-predbat","text":"Expert only You can go to Github and download all the .py files from the releases tab and then manually copy these files over the existing version in /config/appdaemon/apps/batpred/ manually.","title":"Manual update of Predbat"},{"location":"install/#upgrading-from-appdaemon-to-predbat-add-on","text":"These steps assume you already have a working Predbat system and want to upgrade to using the Predbat add-on instead of using either the AppDaemon or the AppDaemon-predbat add-on. Using the Predbat add-on is the strategic direction for Predbat and resolves some performance and data load issues that can occur with AppDaemon. The Predbat code that runs is exactly the same and the configuration is exactly the same, its just changing the 'container' that Predbat runs within. Before starting, watch the installing Predbat add-on video Although the upgrade steps are low risk, take a full backup of Home Assistant before starting Install the Predbat add-on : Add the Predbat add-on to the list of Repositories in the add-on store Install the Predbat add-on But do not start it - yet Install a file editor if you don't have one already installed - either File Editor or Studio Code Server, it doesn't matter Shutdown your existing AppDaemon or AppDaemon-predbat add-on: Go to Settings/Add-ons Click on the existing AppDaemon/AppDaemon-predbat add-on Click STOP, and untick 'Start on boot' Briefly start the new Predbat add-on so that it creates the addon_config folder and the template apps.yaml file: Go to Settings/Add-ons Click on the Predbat add-on Click START, wait a minute for the add-on to initialise itself, then click STOP. A predbat status warning that you have a template apps.yaml file is normal and can be ignored Open your file editor and open your existing apps.yaml file: If you are using the old 'combined AppDaemon/Predbat add-on installation method' it's in the directory /addon_configs/46f69597_appdaemon-predbat/apps , or with the HACS, Appdaemon add-on then Predbat installation method , it's in /config/appdaemon/apps/batpred/config/ Select all the contents of the apps.yaml file and 'copy' (control-C, command-C, etc as appropriate) Now open the template apps.yaml file that's supplied with the Predbat add-on and has been created in the directory /addon_configs/6adb4f0d_predbat , select all the contents of the template apps.yaml file, and paste in the contents of your existing apps.yaml, overwriting the template with your specific configuration Now you are ready to swap from running the AppDaemon or AppDaemon-predbat add-on to the Predbat add-on: Go to Settings/Add-ons Click on the existing AppDaemon/AppDaemon-predbat add-on Make sure it is not running and 'Start on boot' is not ticked Click the back arrow Click on the Predbat add-on Click START, and tick 'Start on boot' If you are using the Predbat automatic monitor then you will need to enable the predbat_running binary sensor and change the automation, replacing the AppDaemon add-on id (a0d7b954_appdaemon) with 'a06adb4f0d_predbat', and 'binary_sensor.appdaemon_running' with 'binary_sensor.predbat_running'. And that's it. You should check the Log tab to ensure it all starts properly, but it should do as you've copied over your existing configuration. Note that if you are using the Predbat direct connection to Solcast then the Predbat add-on will need to download your solar forecast so will use up one or two of your daily API calls (hobbyist accounts have a 10 API a day limit). If you are using the Solcast integration then this won't be required. You may find that the Predbat add-on installed with an older version of Predbat than you were previously using, which might require you to update Predbat to the correct version . When you are happy running the Predbat add-on you can delete the AppDaemon or AppDaemon-predbat add-on.","title":"Upgrading from AppDaemon to Predbat add-on"},{"location":"install/#backing-up-home-assistant-and-predbat","text":"It's strongly recommended that you implement an automatic mechanism to backup your Home Assistant and Predbat system. There are several ways of backing up Home Assistant but one of the simplest is the Home Assistant Google Drive Backup which is an add-on that runs every night, automatically makes a backup of Home Assistant (including Predbat), and copies that backup to a Google Drive for safe keeping. If you create a new Google account specifically for your Home Assistant backups you will automatically get 15Gb of free Google Drive storage, enough for a couple of weeks of backups. As well as the full Home Assistant backup you manually copy the contents of Predbat's apps.yaml configuration file to somewhere safe so that if you accidentally mis-edit it, you can get Predbat working quickly again by copying it back again.","title":"Backing up Home Assistant and Predbat"},{"location":"installation-summary/","text":"Installation summary Please see the sections below for how to achieve each step. This is just a checklist of things: Before you start, its recommended that you watch the step by step installation videos, see the video guides section for those and other videos Make sure the right inverter control module is installed and running Install a file editor (either the File editor or Studio Code Server add-on) to enable you to edit configuration files if you haven't already - Editing configuration files Install Predbat, either: a) Install the Predbat add-on - Predbat add-on install , or b) Complete the separate installation steps: i) Install HACS if you haven't already - HACS install ii) Install AppDaemon if you haven't already - AppDaemon install iii) Install Predbat using HACS - Predbat install Register for a Solcast hobbyist account if you haven't already Solcast install and either: a) Configure Predbat to call Solcast for the Solar forecast, or b) Install and configure the Solcast integration , create an automation to update Solcast a times a day, and check that you see the Solcast data in Home Assistant Follow the Energy Rates 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 Edit Predbat's apps.yaml configuration file to to match your system - apps.yaml settings The apps.yaml file will be in either the directory /addon_configs/6adb4f0d_predbat 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 You have your energy rates set correctly either using Octopus Energy integration or entered manually That the Solcast integration (if being used) is matching the configuration correctly - should be automatic If you have an electric car you have setup the Car Charging configuration Add the Predbat entities to your dashboard - Output data Follow the Configuration Guide to set 'standard' Predbat configuration settings depending on your import and export tariffs The detailed Customisation Guide lists all Predbat's controls and settings in Home Assistant that can be tuned for your system Set up the Predbat Plan card so you can check what Predbat is planning to do - Create the Predbat Plan card Set up the Apex Charts for other views on what Predbat is doing - Creating the charts 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 Comment out or delete the 'template: True' line in apps.yaml 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 Look at the FAQ for help Overview of the key configuration elements:","title":"Install summary"},{"location":"installation-summary/#installation-summary","text":"Please see the sections below for how to achieve each step. This is just a checklist of things: Before you start, its recommended that you watch the step by step installation videos, see the video guides section for those and other videos Make sure the right inverter control module is installed and running Install a file editor (either the File editor or Studio Code Server add-on) to enable you to edit configuration files if you haven't already - Editing configuration files Install Predbat, either: a) Install the Predbat add-on - Predbat add-on install , or b) Complete the separate installation steps: i) Install HACS if you haven't already - HACS install ii) Install AppDaemon if you haven't already - AppDaemon install iii) Install Predbat using HACS - Predbat install Register for a Solcast hobbyist account if you haven't already Solcast install and either: a) Configure Predbat to call Solcast for the Solar forecast, or b) Install and configure the Solcast integration , create an automation to update Solcast a times a day, and check that you see the Solcast data in Home Assistant Follow the Energy Rates 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 Edit Predbat's apps.yaml configuration file to to match your system - apps.yaml settings The apps.yaml file will be in either the directory /addon_configs/6adb4f0d_predbat 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 You have your energy rates set correctly either using Octopus Energy integration or entered manually That the Solcast integration (if being used) is matching the configuration correctly - should be automatic If you have an electric car you have setup the Car Charging configuration Add the Predbat entities to your dashboard - Output data Follow the Configuration Guide to set 'standard' Predbat configuration settings depending on your import and export tariffs The detailed Customisation Guide lists all Predbat's controls and settings in Home Assistant that can be tuned for your system Set up the Predbat Plan card so you can check what Predbat is planning to do - Create the Predbat Plan card Set up the Apex Charts for other views on what Predbat is doing - Creating the charts 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 Comment out or delete the 'template: True' line in apps.yaml 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 Look at the FAQ for help Overview of the key configuration elements:","title":"Installation summary"},{"location":"inverter-setup/","text":"Inverter setup PredBat was originally written for GivEnergy inverters using the GivTCP integration but this is now being extended to other inverter models: Name Integration Template GivEnergy with GivTCP GivTCP givenergy_givtcp.yaml Solis Hybrid inverters Solax Modbus integration ginlong_solis.yaml Solax Gen4 inverters Solax Modbus integration in Modbus Power Control Mode solax_sx4.yaml Sofar inverters Sofar MQTT integration sofar.yaml Huawei inverters Huawei Solar huawei.yaml SolarEdge inverters Solaredge Modbus Multi solaredge.yaml Givenergy with GE Cloud ge_cloud givenergy_cloud.yaml Givenergy with GE Cloud EMC ge_cloud givenergy_ems.yaml SunSynk Sunsynk sunsynk.yaml Fox Foxess fox.yaml LuxPower LuxPython luxpower.yaml Growatt with Solar Assistant Solar Assistant solar_assistant_growatt.yaml Note that support for all these inverters is in various stages of development. Please expect things to fail and report them as Issues on Github. NB: By default the apps.yaml template for GivTCP is installed with Predbat. If you are using a different inverter then you will need to copy the appropriate apps.yaml template from the above list and use it to replace the GivTCP apps.yaml - if you copy but don't replace the standard template then Predbat will not function correctly. GivEnergy with GivTCP Its recommended that you firstly watch the Installing GivTCP and Mosquitto Add-on's video from Speak to the Geek . Although the video covers GivTCP v2 and v3 has been recently released, the install and setup process is very similar. The below instructions assume you are installing GivTCP v3, with changes highlighted against GivTCP v2 as covered in the video. Install Mosquitto Broker add-on: Go to Settings / Add-ons / Add-on Store (bottom right) Scroll down the add-on store list, to find 'Mosquitto broker', click on the add-on, then click 'INSTALL' Once the Mosquitto broker has been installed, ensure that the 'Start on boot' and 'Watchdog' options are turned on, and click 'START' to start the add-on Next, configure Mosquitto broker by going to Settings / Devices and Services / Integrations. Mosquitto broker should appear as a Discovered integration so click the blue 'CONFIGURE' button, then SUBMIT to complete configuring Mosquitto broker With GivTCP v3 you no longer need to create a dedicated Home Assistant user for MQTT so this part of the video can be skipped over Install the GivTCP add-on: Go to Settings / Add-ons / Add-on Store Click the three dots in the top right corner, then Repositories You'll need to add the GivTCP repository as an additional custom repository so paste/type ' https://github.com/britkat1980/ha-addons ' into the text box and click 'Add' the 'Close' NB: this URL is for GivTCP v3, not v2 as covered in the video. Click the back button and then re-navigate to Settings / Add-ons / Add-on Store so Home Assistant picks up the GivTCP add-on from the custom repository Scroll down the add-on store list, to find 'GivTCP-V3', you should see the three addon's; the production version, the latest beta and the latest dev versions. Click on the 'GivTCP' add-on, then click 'INSTALL' Once GivTCP has been installed, ensure that the 'Start on boot' and 'Watchdog' options are turned on Configure GivTCP: The configuration process for GivTCP in v3 has changed from that shown in the video, the Configuration tab is now no longer used and all configuration is now done via the add-on's Web interface On the GivTCP add-on, click 'START' to start the add-on Once the add-on has started, click 'Open Web UI' or go to http://homeassistant.local:8099/ , then click 'Go to Config Page' to configure GivTCP GivTCP will auto-discover your inverters and batteries so you shouldn't need to manually enter these, but check the IP address(s) it finds are correct If you have multiple inverters you may wish to change the default device prefixes that GivTCP assigns ('givtcp', 'givtcp2', 'givtcp3', etc) to make it easier to identify your devices within Home Assistant. For example if you have a gateway and two AIO's you could use the prefixes 'GW', 'AIO-1' and 'AIO-2'. The prefixes should be set before you start using GivTCP in anger as changing the prefixes later on will result in both the old and new sensor names appearing in Home Assistant with the 'old' sensors being \"unavailable\". Note that if you do change the givtcp prefixes then you will also have to edit the apps.yaml configuration file to match, and change the sensor names that predbat is looking for (by default prefixed 'givtcp_xxx') to your new sensor naming structure Click Next and Next to get to the Selfrun page, and turn on Self run. The Self Run Loop Timer is how often GivTCP will retrieve data from your inverters - it's recommended that set this to a value between 20 and 60, but not less than 15 seconds as otherwise the inverter will then spend all its time talking to GivTCP and won't communicate with the GivEnergy portal and app GivTCP now auto-populates the MQTT page so as long as you're using Mosquitto broker within Home Assistant; you won't need to create a dedicated MQTT user or enter the details on the MQTT page You don't need to configure the Influx page. Tariff and Palm pages can also be skipped as these functions are done by Predbat (Optional) On the Web page, you can turn the Dashboard on to see a simple power flow diagram for your inverters (similar to the GivEnergy mobile app) On the 'Misc' page check that 'Print Raw' is set to on for added monitoring Finally click 'Save and Restart' and GivTCP should start communicating with your inverters and will automatically create a set of 'givtcp_xxx' entities in Home Assistant for your inverter data, inverter controls and battery data Check the GivTCP Log tab that there aren't any errors; it should end with 'Publishing Home Assistant Discovery messages' Specific Predbat configuration requirements for certain GivEnergy equipment The rest of the Predbat installation instructions should now be followed, but its worth highlighting that there are a few specific settings that should be set for certain GivEnergy equipment. These settings are documented in the appropriate place in the documentation, but for ease of identification, are repeated here: If you are using GivTCP v3 and have an AIO or 3 phase inverter then you will need to manually set geserial in apps.yaml to your inverter serial number If you have a single AIO then control is directly to the AIO. Ensure geserial in apps.yaml is correctly picking the AIO and comment out geserial2 lines If you have multiple AIO's then all control of the AIO's is done through the Gateway so geserial in apps.yaml should be set to the Gateway serial number If you have multiple AIO's you might want to consider setting inverter charge and discharge limits unless you want to charge and discharge at the full 12kWh! If you have a 2.6kWh, 5.2kWh or AIO battery then you will need to set battery_scaling in apps.yaml as the battery size is incorrectly reported to GivTCP If you have a Gen 2, Gen 3 or AIO then you may need to set inverter_reserve_max in apps.yaml to 98. If you have a Gen 1 or a firmware version that allows reserve being set to 100 then you can change the default from 98 to 100 If your inverter has been wired as an EPS (Emergency Power Supply) or AIO 'whole home backup', consider setting input_number.predbat_set_reserve_min to reserve some battery power for use in emergencies. NB: GivTCP and Predbat do not currently yet work together for 3 phase inverters . This is being worked on by the author of GivTCP, e.g. see GivTCP issue: unable to charge or discharge 3 phase inverters with predbat Solis Inverters To run PredBat with Solis hybrid inverters, follow the following steps: Install PredBat as per the Installation Summary Ensure that you have the Solax Modbus integration running. There are a number of entities which this integration disables by default that you will need to enable via the Home Assistant GUI: Name Description sensor.solisx_rtc Real Time Clock sensor.solisx_battery_power Battery Power Instead of apps.yaml use ginlong_solis.yaml from this Repo as your starting template. The majority of settings should be correct but please check. You will need to un-comment the template line to enable it. Save it to the appropriate Predbat software directory . Set solax_modbus_new in apps.yaml to True if you have integration version 2024.03.2 or greater Ensure that the inverter is set Control Mode 35 - on the Solax integration this is Timed Charge/Discharge . If you want to use the Reserve functionality within PredBat you will need to select Backup/Reserve (code 51) instead but be aware that this is not fully tested. In due course these mode settings will be incorporated into the code. Solax Gen4 Inverters Use the template configuration from: solax.sx4.yaml Set solax_modbus_new in apps.yaml to True if you have integration version 2024.03.2 or greater Please see this ticket in Github for ongoing discussion: https://github.com/springfall2008/batpred/issues/259 Sofar Inverters For this integration the key elements are: Hardware - sofar2mqtt EPS board - Relatively easy to solder and flash, or can be bought pre-made. Software - Sofar MQTT integration - MQTT integration Home Assistant configuration - sofar_inverter.yaml package (in templates directory) with the MQTT sensors. This is the default with a couple of additional inputs to support battery capacity. This should be installed in Home Assistant. Predbat configuration - sofar.yaml template for Predbat (in templates directory). This file should be copied to apps.yaml Please note that the inverter needs to be put into \"Passive Mode\" for the sofar2mqtt to control the inverter. This integration has various limitations, it can charge and discharge the battery but does not have finer control over reserve and target SOC% Note: You will need to change the min reserve in Home Assistant to match your minimum battery level ( input_number.predbat_set_reserve_min ). Please see this ticket in Github for ongoing discussions: https://github.com/springfall2008/batpred/issues/395 Huawei Inverters Discussion ticket is here: https://github.com/springfall2008/batpred/issues/684 Please copy the template apps.yaml from https://github.com/springfall2008/batpred/blob/main/templates/huawei.yaml and modify for your system Ensure you set input_number.predbat_set_reserve_min to the minimum value for your system which maybe 12% SolarEdge Inverters Discussion ticket is here: https://github.com/springfall2008/batpred/issues/181 Please copy the template apps.yaml from https://github.com/springfall2008/batpred/blob/main/templates/solaredge.yaml and modify for your system Ensure that number.solaredge_i1_storage_command_timeout is set to reasonably high value e.g. 3600 seconds to avoid the commands issued being cancelled Power Control Options, as well as Enable Battery Control, must be enabled in the Solaredge Modbus Multi integration configuration, and switch.solaredge_i1_advanced_power_control must be on. For pv_today , pv_power and load_power sensors to work you need to create this as a template within your Home Assistant configuration.yml Please see: https://gist.github.com/Ashpork/f80fb0d3cb22356a12ed24734065061c . These sensors are not critical so you can just comment it out in apps.yaml if you can't get it to work template: - sensor: - name: \"Solar Panel Production W\" unique_id: solar_panel_production_w unit_of_measurement: \"W\" icon: mdi:solar-power state: > {% set i1_dc_power = states('sensor.solaredge_i1_dc_power') | float(0) %} {% set b1_dc_power = states('sensor.solaredge_b1_dc_power') | float(0) %} {% if (i1_dc_power + b1_dc_power <= 0) %} 0 {% else %} {{ (i1_dc_power + b1_dc_power) }} {% endif %} availability: > {{ states('sensor.solaredge_i1_dc_power') | is_number and states('sensor.solaredge_b1_dc_power') | is_number }} - name: \"Solar House Consumption W\" unique_id: solar_house_consumption_w unit_of_measurement: \"W\" icon: mdi:home state: > {% set i1_ac_power = states('sensor.solaredge_i1_ac_power') | float(0) %} {% set m1_ac_power = states('sensor.solaredge_m1_ac_power') | float(0) %} {% if (i1_ac_power - m1_ac_power <= 0) %} 0 {% else %} {{ (i1_ac_power - m1_ac_power) }} {% endif %} availability: > {{ states('sensor.solaredge_i1_ac_power') | is_number and states('sensor.solaredge_m1_ac_power') | is_number }} sensor: - platform: integration source: sensor.solar_panel_production_w method: left unit_prefix: k name: solar_panel_production_kwh Givenergy with ge_cloud This is experimental system, please discuss on the ticket: https://github.com/springfall2008/batpred/issues/905 First set up ge_cloud integration using your API key https://github.com/springfall2008/ge_cloud Now copy the template givenergy_cloud.yaml from templates into your apps.yaml and edit Set geserial to your inverter serial Make sure discharge down to registers are set to 4% and slots 2, 3 and 4 for charge and discharge are disabled (if you have them) Givenergy with EMC First set up ge_cloud integration using your API key https://github.com/springfall2008/ge_cloud Now copy the template givenergy_emc.yaml from templates into your apps.yaml and edit Set geserial to your first inverter serial and geserial2 to the second (look in HA for entity names) Set geseriale to the EMS inverter serial number (look in HA for entity names) Turn off slots 2, 3 and 4 for charge, export and discharge as Predbat will only use 1 slot (set the start and end times to 00:00) Fox Experimental I've managed to get Batpred working on my Fox ESS inverter, connected via an Elfin EW11 modbus and using Nathan's Fox ESS Modbus tool. See: https://github.com/springfall2008/batpred/issues/1401 Template is in the templates area, give it a try Lux Power This requires the LuxPython component which integrates with your Lux Power inverter Copy the template luxpower.yaml from templates into your apps.yaml and edit inverter and battery settings as required Growatt with Solar Assistant You need to have a Solar Assistant installation https://solar-assistant.io Copy the template solar_assistant_growatt.yaml from templates into your apps.yaml and edit inverter and battery settings as required (the template has growatt, yours might/will have different entity ids on Home Assistant) Sunsynk Copy the Sunsynk apps.yaml template and edit for your system. Create the automations below Create the value templates below See: https://github.com/springfall2008/batpred/issues/1331 SunSynk automations Copy into your HA automations Predbat Charge/Discharge Control alias: Predbat Charge / Discharge Control description: \"\" trigger: - platform: state entity_id: - binary_sensor.predbat_charging to: \"on\" id: predbat_charge_on - platform: state entity_id: - binary_sensor.predbat_charging to: \"off\" id: predbat_charge_off - platform: state entity_id: - binary_sensor.predbat_exporting to: \"on\" id: predbat_discharge_on - platform: state entity_id: - binary_sensor.predbat_exporting to: \"off\" id: predbat_discharge_off condition: [] action: - choose: - conditions: - condition: trigger id: - predbat_charge_on sequence: - service: switch.turn_on metadata: {} data: {} target: entity_id: switch.sunsynk_grid_charge_timezone1 - conditions: - condition: trigger id: - predbat_charge_off sequence: - service: switch.turn_off target: entity_id: - switch.sunsynk_grid_charge_timezone1 data: {} - conditions: - condition: trigger id: - predbat_discharge_on sequence: - service: switch.turn_on metadata: {} data: {} target: entity_id: switch.sunsynk_solar_sell - conditions: - condition: trigger id: - predbat_discharge_off sequence: - service: switch.turn_off target: entity_id: - switch.sunsynk_solar_sell data: {} mode: single Update the charge limits across all timezone's alias: PredBat - Copy Charge Limit description: Copy Battery SOC to all time slots trigger: - platform: state entity_id: - number.sunsynk_set_soc_timezone1 to: null condition: [] action: - service: number.set_value data_template: entity_id: - number.sunsynk_set_soc_timezone2 - number.sunsynk_set_soc_timezone3 - number.sunsynk_set_soc_timezone4 - number.sunsynk_set_soc_timezone5 - number.sunsynk_set_soc_timezone6 value: \"{{ states('number.sunsynk_set_soc_timezone1')|int(20) }}\" mode: single SunSynk Value templates Copy into your template/sensor area of configuration.yaml template: sensor: xxxxx Sunsynk Battery Max Charge Rate - name: \"sunsynk_max_battery_charge_rate\" unit_of_measurement: \"w\" state_class: measurement state: > {{ [8000,[states('input_number.sunsynk_battery_max_charge_current_limit')|int,states('sensor.sunsynk_battery_charge_limit_current')|int]|min * states('sensor.sunsynk_battery_voltage')|float]|min }} Sunsynk Battery Max DisCharge Rate - name: \"sunsynk_max_battery_discharge_rate\" unit_of_measurement: \"w\" state_class: measurement state: > {{ [8000,[states('input_number.sunsynk_battery_max_discharge_current_limit')|int,states('sensor.sunsynk_battery_discharge_limit_current')|int]|min * states('sensor.sunsynk_battery_voltage')|float]|min }} Sunsynk Charge Rate Calc - name: \"sunsynk_charge_rate_calc\" unit_of_measurement: \"w\" state_class: measurement state: > {{ [8000,[states('input_number.test_sunsynk_battery_max_charge_current')|int,states('sensor.sunsynk_battery_charge_limit_current')|int]|min * states('sensor.sunsynk_battery_voltage')|float]|min }} Sunsynk Discharge Rate Calc - name: \"sunsynk_discharge_rate_calc\" unit_of_measurement: \"w\" state_class: measurement state: > {{ [8000,[states('input_number.test_sunsynk_battery_max_discharge_current')|int,states('sensor.sunsynk_battery_discharge_limit_current')|int]|min * states('sensor.sunsynk_battery_voltage')|float]|min }} I want to add an unsupported inverter to Predbat First copy one of the template configurations that is close to your system and try to configure it to match the sensors you have Create a github ticket for support and add in what you know to the ticket Then find out how to control your inverter inside Home Assistant, ideally share any automation you have to control the inverter You can create a new inverter type in apps.yaml and change the options as to which controls it has The easy way to integrate is to use a HA service to start charges and discharges, edit the template below inverter_type: MINE inverter: name : \"My Shiny new Inverter\" has_rest_api: False has_mqtt_api: False output_charge_control: \"power\" has_charge_enable_time: False has_discharge_enable_time: False has_target_soc: False has_reserve_soc: False charge_time_format: \"S\" charge_time_entity_is_option: False soc_units: \"%\" num_load_entities: 1 has_ge_inverter_mode\": False time_button_press: False clock_time_format: \"%Y-%m-%d %H:%M:%S\" write_and_poll_sleep: 2 has_time_window: False support_charge_freeze: False support_discharge_freeze\": False # Services to control charging/discharging charge_start_service: service: select.select_option entity_id: \"select.solaredge_i1_storage_command_mode\" option: \"Charge from Solar Power and Grid\" charge_stop_service: service: select.select_option entity_id: \"select.solaredge_i1_storage_command_mode\" option: \"Charge from Solar Power\" discharge_start_service: service: select.select_option entity_id: \"select.solaredge_i1_storage_command_mode\" option: \"Maximize Self Consumption\" Inverter control option The follow options are supported per inverter: has_rest_api When True the REST API will be used to fetch data/control the inverter. This is currently only for GivEnergy inverters with GivTCP and givtcp_rest must be set in apps.yaml has_mqtt_api When True the MQTT API to Home Assistant will be used to issue control messages for the inverter The mqtt/publish service is used with the topic as defined by mqtt_topic in apps.yaml Messages will be sent these controls: Values that are updated: topic /set/reserve - payload=reserve topic /set/charge_rate - payload=new_rate topic /set/discharge_rate - payload=new_rate topic /set/target_soc - payload=target_soc These three change between battery charge/discharge and auto (idle) mode: topic /set/charge - payload=charge_rate topic /set/discharge - payload=discharge_rate topic /set/auto - payload=true Service API When True a Home Assistant service will be used to issue control messages for the inverter For each service you wish to use it must be defined in apps.yaml. There are two ways to define a service, the basic mode: charge_start_service: my_service_name_charge Will call my_service_name_charge for the charge start service. Or the custom method: charge_start_service: - service: my_charge_start_service device_id: {device_id} power: {power} soc: {target_soc} Here you can define all the values passed to the service and use the default values from the template or define your own. You can also call more than one service e.g: charge_start_service: - service: my_charge_start_service device_id: {device_id} power: {power} soc: {target_soc} - service: switch.turn_off entity_id: switch.tsunami_charger charge_start_service Called to start a charge The default options passed in are: device_id - as defined in apps.yaml by device_id target_soc - The SOC to charge to power - The charge power to use charge_freeze_service If defined will be called for freeze charge, otherwise charge_start_service is used for freeze charge also. discharge_start_service Called to start a discharge The default options passed in are: device_id - as defined in apps.yaml by device_id target_soc - The SOC to discharge to power - The discharge power to use discharge_freeze_service If defined will be called for Discharge freeze, otherwise discharge_start_service is used for freeze discharge also. charge_stop_service Called to stop a charge device_id - as defined in apps.yaml by device_id discharge_stop_service Called to stop a discharge, if not set then charge_stop_service will be used instead device_id - as defined in apps.yaml by device_id output_charge_control Set to power, current or none When power the inverter has a charge_rate and discharge_rate setting in watts defined in apps.yaml When current the inverter has timed_charge_current and timed_discharge_current setting in amps defined in apps.yaml charge_control_immediate When True the inverter timed_charge_current or timed_discharge_current is used to control charging or discharging as/when it starts and stops rather than using a timed method. current_dp Sets the number of decimal places when setting the current in Amps, should be 0 or 1 has_charge_enable_time When True the inverter has a setting defined in apps.yaml called scheduled_charge_enable when can be used to enable/disable timed charging. has_discharge_enable_time When True the inverter has a setting defined in apps.yaml called scheduled_discharge_enable when can be used to enable/disable timed discharging. has_target_soc When True the inverter has a target soc setting in apps.yaml called charge_limit , when False charging must be turned on and off by Predbat rather than the inverter doing it based on the target % has_reserve_soc When True the inverter has a reserve soc setting in apps.yaml called reserve has_timed_pause When True the inverter has a setting in apps.yaml called pause_mode and settings pause_start_time and pause_end_time which can be used to pause the inverter from charging and discharging the battery - this is for GivEnergy systems only right now. charge_time_format When set to \"HH:MM:SS\" the inverter has: charge_start_time charge_end_time discharge_start_time discharge_end_time Which are option selectors in the format HH:MM:SS (e.g. 12:23:00) where seconds are always 00. When set to \"H M\" the inverter has: charge_start_hour charge_end_hour charge_start_minute charge_end_minute discharge_start_hour discharge_end_hour discharge_start_minute discharge_end_minute Settings in apps.yaml which can be used to set the start and end times of charges and discharges charge_time_entity_is_option When True charge_start_time charge_end_time discharge_start_time and discharge_end_time are all Options, when false they are number values. clock_time_format Defines the time format of the inverter clock setting inverter_time in apps.yaml soc_units Defines the units of the SOC setting (currently not used) time_button_press When true the inverter has a button press which is needed to update the inverter registers from the Home Assistant values. The apps.yaml setting charge_discharge_update_button is the entity name of the button that must be pressed and polled until it updates after each inverter register change. support_charge_freeze When True the inverter supports charge freeze modes support_discharge_freeze When True the inverter supports discharge freeze modes has_ge_inverter_mode When True the inverter as the GivEnergy inverter modes (ECO, Timed Export etc). num_load_entities Sets the number of load_power_n settings in apps.yaml are present in addition to load_power (the default) write_and_poll_sleep Sets the number of seconds between polls of inverter settings has_idle_time When True the inverter has an idle time register which must be set to the start and end times for ECO mode (GivEnergy EMC) can_span_midnight When True start and end times for charge and discharge can span midnight e.g. 23:00:00 - 01:00:00 is a 2 hour slot. charge_discharge_with_rate When True when charging discharge rate must be 0 and visa-versa. When false the rate does not have to change.","title":"Inverter setup"},{"location":"inverter-setup/#inverter-setup","text":"PredBat was originally written for GivEnergy inverters using the GivTCP integration but this is now being extended to other inverter models: Name Integration Template GivEnergy with GivTCP GivTCP givenergy_givtcp.yaml Solis Hybrid inverters Solax Modbus integration ginlong_solis.yaml Solax Gen4 inverters Solax Modbus integration in Modbus Power Control Mode solax_sx4.yaml Sofar inverters Sofar MQTT integration sofar.yaml Huawei inverters Huawei Solar huawei.yaml SolarEdge inverters Solaredge Modbus Multi solaredge.yaml Givenergy with GE Cloud ge_cloud givenergy_cloud.yaml Givenergy with GE Cloud EMC ge_cloud givenergy_ems.yaml SunSynk Sunsynk sunsynk.yaml Fox Foxess fox.yaml LuxPower LuxPython luxpower.yaml Growatt with Solar Assistant Solar Assistant solar_assistant_growatt.yaml Note that support for all these inverters is in various stages of development. Please expect things to fail and report them as Issues on Github. NB: By default the apps.yaml template for GivTCP is installed with Predbat. If you are using a different inverter then you will need to copy the appropriate apps.yaml template from the above list and use it to replace the GivTCP apps.yaml - if you copy but don't replace the standard template then Predbat will not function correctly.","title":"Inverter setup"},{"location":"inverter-setup/#givenergy-with-givtcp","text":"Its recommended that you firstly watch the Installing GivTCP and Mosquitto Add-on's video from Speak to the Geek . Although the video covers GivTCP v2 and v3 has been recently released, the install and setup process is very similar. The below instructions assume you are installing GivTCP v3, with changes highlighted against GivTCP v2 as covered in the video. Install Mosquitto Broker add-on: Go to Settings / Add-ons / Add-on Store (bottom right) Scroll down the add-on store list, to find 'Mosquitto broker', click on the add-on, then click 'INSTALL' Once the Mosquitto broker has been installed, ensure that the 'Start on boot' and 'Watchdog' options are turned on, and click 'START' to start the add-on Next, configure Mosquitto broker by going to Settings / Devices and Services / Integrations. Mosquitto broker should appear as a Discovered integration so click the blue 'CONFIGURE' button, then SUBMIT to complete configuring Mosquitto broker With GivTCP v3 you no longer need to create a dedicated Home Assistant user for MQTT so this part of the video can be skipped over Install the GivTCP add-on: Go to Settings / Add-ons / Add-on Store Click the three dots in the top right corner, then Repositories You'll need to add the GivTCP repository as an additional custom repository so paste/type ' https://github.com/britkat1980/ha-addons ' into the text box and click 'Add' the 'Close' NB: this URL is for GivTCP v3, not v2 as covered in the video. Click the back button and then re-navigate to Settings / Add-ons / Add-on Store so Home Assistant picks up the GivTCP add-on from the custom repository Scroll down the add-on store list, to find 'GivTCP-V3', you should see the three addon's; the production version, the latest beta and the latest dev versions. Click on the 'GivTCP' add-on, then click 'INSTALL' Once GivTCP has been installed, ensure that the 'Start on boot' and 'Watchdog' options are turned on Configure GivTCP: The configuration process for GivTCP in v3 has changed from that shown in the video, the Configuration tab is now no longer used and all configuration is now done via the add-on's Web interface On the GivTCP add-on, click 'START' to start the add-on Once the add-on has started, click 'Open Web UI' or go to http://homeassistant.local:8099/ , then click 'Go to Config Page' to configure GivTCP GivTCP will auto-discover your inverters and batteries so you shouldn't need to manually enter these, but check the IP address(s) it finds are correct If you have multiple inverters you may wish to change the default device prefixes that GivTCP assigns ('givtcp', 'givtcp2', 'givtcp3', etc) to make it easier to identify your devices within Home Assistant. For example if you have a gateway and two AIO's you could use the prefixes 'GW', 'AIO-1' and 'AIO-2'. The prefixes should be set before you start using GivTCP in anger as changing the prefixes later on will result in both the old and new sensor names appearing in Home Assistant with the 'old' sensors being \"unavailable\". Note that if you do change the givtcp prefixes then you will also have to edit the apps.yaml configuration file to match, and change the sensor names that predbat is looking for (by default prefixed 'givtcp_xxx') to your new sensor naming structure Click Next and Next to get to the Selfrun page, and turn on Self run. The Self Run Loop Timer is how often GivTCP will retrieve data from your inverters - it's recommended that set this to a value between 20 and 60, but not less than 15 seconds as otherwise the inverter will then spend all its time talking to GivTCP and won't communicate with the GivEnergy portal and app GivTCP now auto-populates the MQTT page so as long as you're using Mosquitto broker within Home Assistant; you won't need to create a dedicated MQTT user or enter the details on the MQTT page You don't need to configure the Influx page. Tariff and Palm pages can also be skipped as these functions are done by Predbat (Optional) On the Web page, you can turn the Dashboard on to see a simple power flow diagram for your inverters (similar to the GivEnergy mobile app) On the 'Misc' page check that 'Print Raw' is set to on for added monitoring Finally click 'Save and Restart' and GivTCP should start communicating with your inverters and will automatically create a set of 'givtcp_xxx' entities in Home Assistant for your inverter data, inverter controls and battery data Check the GivTCP Log tab that there aren't any errors; it should end with 'Publishing Home Assistant Discovery messages' Specific Predbat configuration requirements for certain GivEnergy equipment The rest of the Predbat installation instructions should now be followed, but its worth highlighting that there are a few specific settings that should be set for certain GivEnergy equipment. These settings are documented in the appropriate place in the documentation, but for ease of identification, are repeated here: If you are using GivTCP v3 and have an AIO or 3 phase inverter then you will need to manually set geserial in apps.yaml to your inverter serial number If you have a single AIO then control is directly to the AIO. Ensure geserial in apps.yaml is correctly picking the AIO and comment out geserial2 lines If you have multiple AIO's then all control of the AIO's is done through the Gateway so geserial in apps.yaml should be set to the Gateway serial number If you have multiple AIO's you might want to consider setting inverter charge and discharge limits unless you want to charge and discharge at the full 12kWh! If you have a 2.6kWh, 5.2kWh or AIO battery then you will need to set battery_scaling in apps.yaml as the battery size is incorrectly reported to GivTCP If you have a Gen 2, Gen 3 or AIO then you may need to set inverter_reserve_max in apps.yaml to 98. If you have a Gen 1 or a firmware version that allows reserve being set to 100 then you can change the default from 98 to 100 If your inverter has been wired as an EPS (Emergency Power Supply) or AIO 'whole home backup', consider setting input_number.predbat_set_reserve_min to reserve some battery power for use in emergencies. NB: GivTCP and Predbat do not currently yet work together for 3 phase inverters . This is being worked on by the author of GivTCP, e.g. see GivTCP issue: unable to charge or discharge 3 phase inverters with predbat","title":"GivEnergy with GivTCP"},{"location":"inverter-setup/#solis-inverters","text":"To run PredBat with Solis hybrid inverters, follow the following steps: Install PredBat as per the Installation Summary Ensure that you have the Solax Modbus integration running. There are a number of entities which this integration disables by default that you will need to enable via the Home Assistant GUI: Name Description sensor.solisx_rtc Real Time Clock sensor.solisx_battery_power Battery Power Instead of apps.yaml use ginlong_solis.yaml from this Repo as your starting template. The majority of settings should be correct but please check. You will need to un-comment the template line to enable it. Save it to the appropriate Predbat software directory . Set solax_modbus_new in apps.yaml to True if you have integration version 2024.03.2 or greater Ensure that the inverter is set Control Mode 35 - on the Solax integration this is Timed Charge/Discharge . If you want to use the Reserve functionality within PredBat you will need to select Backup/Reserve (code 51) instead but be aware that this is not fully tested. In due course these mode settings will be incorporated into the code.","title":"Solis Inverters"},{"location":"inverter-setup/#solax-gen4-inverters","text":"Use the template configuration from: solax.sx4.yaml Set solax_modbus_new in apps.yaml to True if you have integration version 2024.03.2 or greater Please see this ticket in Github for ongoing discussion: https://github.com/springfall2008/batpred/issues/259","title":"Solax Gen4 Inverters"},{"location":"inverter-setup/#sofar-inverters","text":"For this integration the key elements are: Hardware - sofar2mqtt EPS board - Relatively easy to solder and flash, or can be bought pre-made. Software - Sofar MQTT integration - MQTT integration Home Assistant configuration - sofar_inverter.yaml package (in templates directory) with the MQTT sensors. This is the default with a couple of additional inputs to support battery capacity. This should be installed in Home Assistant. Predbat configuration - sofar.yaml template for Predbat (in templates directory). This file should be copied to apps.yaml Please note that the inverter needs to be put into \"Passive Mode\" for the sofar2mqtt to control the inverter. This integration has various limitations, it can charge and discharge the battery but does not have finer control over reserve and target SOC% Note: You will need to change the min reserve in Home Assistant to match your minimum battery level ( input_number.predbat_set_reserve_min ). Please see this ticket in Github for ongoing discussions: https://github.com/springfall2008/batpred/issues/395","title":"Sofar Inverters"},{"location":"inverter-setup/#huawei-inverters","text":"Discussion ticket is here: https://github.com/springfall2008/batpred/issues/684 Please copy the template apps.yaml from https://github.com/springfall2008/batpred/blob/main/templates/huawei.yaml and modify for your system Ensure you set input_number.predbat_set_reserve_min to the minimum value for your system which maybe 12%","title":"Huawei Inverters"},{"location":"inverter-setup/#solaredge-inverters","text":"Discussion ticket is here: https://github.com/springfall2008/batpred/issues/181 Please copy the template apps.yaml from https://github.com/springfall2008/batpred/blob/main/templates/solaredge.yaml and modify for your system Ensure that number.solaredge_i1_storage_command_timeout is set to reasonably high value e.g. 3600 seconds to avoid the commands issued being cancelled Power Control Options, as well as Enable Battery Control, must be enabled in the Solaredge Modbus Multi integration configuration, and switch.solaredge_i1_advanced_power_control must be on. For pv_today , pv_power and load_power sensors to work you need to create this as a template within your Home Assistant configuration.yml Please see: https://gist.github.com/Ashpork/f80fb0d3cb22356a12ed24734065061c . These sensors are not critical so you can just comment it out in apps.yaml if you can't get it to work template: - sensor: - name: \"Solar Panel Production W\" unique_id: solar_panel_production_w unit_of_measurement: \"W\" icon: mdi:solar-power state: > {% set i1_dc_power = states('sensor.solaredge_i1_dc_power') | float(0) %} {% set b1_dc_power = states('sensor.solaredge_b1_dc_power') | float(0) %} {% if (i1_dc_power + b1_dc_power <= 0) %} 0 {% else %} {{ (i1_dc_power + b1_dc_power) }} {% endif %} availability: > {{ states('sensor.solaredge_i1_dc_power') | is_number and states('sensor.solaredge_b1_dc_power') | is_number }} - name: \"Solar House Consumption W\" unique_id: solar_house_consumption_w unit_of_measurement: \"W\" icon: mdi:home state: > {% set i1_ac_power = states('sensor.solaredge_i1_ac_power') | float(0) %} {% set m1_ac_power = states('sensor.solaredge_m1_ac_power') | float(0) %} {% if (i1_ac_power - m1_ac_power <= 0) %} 0 {% else %} {{ (i1_ac_power - m1_ac_power) }} {% endif %} availability: > {{ states('sensor.solaredge_i1_ac_power') | is_number and states('sensor.solaredge_m1_ac_power') | is_number }} sensor: - platform: integration source: sensor.solar_panel_production_w method: left unit_prefix: k name: solar_panel_production_kwh","title":"SolarEdge Inverters"},{"location":"inverter-setup/#givenergy-with-ge_cloud","text":"This is experimental system, please discuss on the ticket: https://github.com/springfall2008/batpred/issues/905 First set up ge_cloud integration using your API key https://github.com/springfall2008/ge_cloud Now copy the template givenergy_cloud.yaml from templates into your apps.yaml and edit Set geserial to your inverter serial Make sure discharge down to registers are set to 4% and slots 2, 3 and 4 for charge and discharge are disabled (if you have them)","title":"Givenergy with ge_cloud"},{"location":"inverter-setup/#givenergy-with-emc","text":"First set up ge_cloud integration using your API key https://github.com/springfall2008/ge_cloud Now copy the template givenergy_emc.yaml from templates into your apps.yaml and edit Set geserial to your first inverter serial and geserial2 to the second (look in HA for entity names) Set geseriale to the EMS inverter serial number (look in HA for entity names) Turn off slots 2, 3 and 4 for charge, export and discharge as Predbat will only use 1 slot (set the start and end times to 00:00)","title":"Givenergy with EMC"},{"location":"inverter-setup/#fox","text":"Experimental I've managed to get Batpred working on my Fox ESS inverter, connected via an Elfin EW11 modbus and using Nathan's Fox ESS Modbus tool. See: https://github.com/springfall2008/batpred/issues/1401 Template is in the templates area, give it a try","title":"Fox"},{"location":"inverter-setup/#lux-power","text":"This requires the LuxPython component which integrates with your Lux Power inverter Copy the template luxpower.yaml from templates into your apps.yaml and edit inverter and battery settings as required","title":"Lux Power"},{"location":"inverter-setup/#growatt-with-solar-assistant","text":"You need to have a Solar Assistant installation https://solar-assistant.io Copy the template solar_assistant_growatt.yaml from templates into your apps.yaml and edit inverter and battery settings as required (the template has growatt, yours might/will have different entity ids on Home Assistant)","title":"Growatt with Solar Assistant"},{"location":"inverter-setup/#sunsynk","text":"Copy the Sunsynk apps.yaml template and edit for your system. Create the automations below Create the value templates below See: https://github.com/springfall2008/batpred/issues/1331","title":"Sunsynk"},{"location":"inverter-setup/#sunsynk-automations","text":"Copy into your HA automations","title":"SunSynk automations"},{"location":"inverter-setup/#predbat-chargedischarge-control","text":"alias: Predbat Charge / Discharge Control description: \"\" trigger: - platform: state entity_id: - binary_sensor.predbat_charging to: \"on\" id: predbat_charge_on - platform: state entity_id: - binary_sensor.predbat_charging to: \"off\" id: predbat_charge_off - platform: state entity_id: - binary_sensor.predbat_exporting to: \"on\" id: predbat_discharge_on - platform: state entity_id: - binary_sensor.predbat_exporting to: \"off\" id: predbat_discharge_off condition: [] action: - choose: - conditions: - condition: trigger id: - predbat_charge_on sequence: - service: switch.turn_on metadata: {} data: {} target: entity_id: switch.sunsynk_grid_charge_timezone1 - conditions: - condition: trigger id: - predbat_charge_off sequence: - service: switch.turn_off target: entity_id: - switch.sunsynk_grid_charge_timezone1 data: {} - conditions: - condition: trigger id: - predbat_discharge_on sequence: - service: switch.turn_on metadata: {} data: {} target: entity_id: switch.sunsynk_solar_sell - conditions: - condition: trigger id: - predbat_discharge_off sequence: - service: switch.turn_off target: entity_id: - switch.sunsynk_solar_sell data: {} mode: single","title":"Predbat Charge/Discharge Control"},{"location":"inverter-setup/#update-the-charge-limits-across-all-timezones","text":"alias: PredBat - Copy Charge Limit description: Copy Battery SOC to all time slots trigger: - platform: state entity_id: - number.sunsynk_set_soc_timezone1 to: null condition: [] action: - service: number.set_value data_template: entity_id: - number.sunsynk_set_soc_timezone2 - number.sunsynk_set_soc_timezone3 - number.sunsynk_set_soc_timezone4 - number.sunsynk_set_soc_timezone5 - number.sunsynk_set_soc_timezone6 value: \"{{ states('number.sunsynk_set_soc_timezone1')|int(20) }}\" mode: single","title":"Update the charge limits across all timezone's"},{"location":"inverter-setup/#sunsynk-value-templates","text":"Copy into your template/sensor area of configuration.yaml template: sensor: xxxxx","title":"SunSynk Value templates"},{"location":"inverter-setup/#sunsynk-battery-max-charge-rate","text":"- name: \"sunsynk_max_battery_charge_rate\" unit_of_measurement: \"w\" state_class: measurement state: > {{ [8000,[states('input_number.sunsynk_battery_max_charge_current_limit')|int,states('sensor.sunsynk_battery_charge_limit_current')|int]|min * states('sensor.sunsynk_battery_voltage')|float]|min }}","title":"Sunsynk Battery Max Charge Rate"},{"location":"inverter-setup/#sunsynk-battery-max-discharge-rate","text":"- name: \"sunsynk_max_battery_discharge_rate\" unit_of_measurement: \"w\" state_class: measurement state: > {{ [8000,[states('input_number.sunsynk_battery_max_discharge_current_limit')|int,states('sensor.sunsynk_battery_discharge_limit_current')|int]|min * states('sensor.sunsynk_battery_voltage')|float]|min }}","title":"Sunsynk Battery Max DisCharge Rate"},{"location":"inverter-setup/#sunsynk-charge-rate-calc","text":"- name: \"sunsynk_charge_rate_calc\" unit_of_measurement: \"w\" state_class: measurement state: > {{ [8000,[states('input_number.test_sunsynk_battery_max_charge_current')|int,states('sensor.sunsynk_battery_charge_limit_current')|int]|min * states('sensor.sunsynk_battery_voltage')|float]|min }}","title":"Sunsynk Charge Rate Calc"},{"location":"inverter-setup/#sunsynk-discharge-rate-calc","text":"- name: \"sunsynk_discharge_rate_calc\" unit_of_measurement: \"w\" state_class: measurement state: > {{ [8000,[states('input_number.test_sunsynk_battery_max_discharge_current')|int,states('sensor.sunsynk_battery_discharge_limit_current')|int]|min * states('sensor.sunsynk_battery_voltage')|float]|min }}","title":"Sunsynk Discharge Rate Calc"},{"location":"inverter-setup/#i-want-to-add-an-unsupported-inverter-to-predbat","text":"First copy one of the template configurations that is close to your system and try to configure it to match the sensors you have Create a github ticket for support and add in what you know to the ticket Then find out how to control your inverter inside Home Assistant, ideally share any automation you have to control the inverter You can create a new inverter type in apps.yaml and change the options as to which controls it has The easy way to integrate is to use a HA service to start charges and discharges, edit the template below inverter_type: MINE inverter: name : \"My Shiny new Inverter\" has_rest_api: False has_mqtt_api: False output_charge_control: \"power\" has_charge_enable_time: False has_discharge_enable_time: False has_target_soc: False has_reserve_soc: False charge_time_format: \"S\" charge_time_entity_is_option: False soc_units: \"%\" num_load_entities: 1 has_ge_inverter_mode\": False time_button_press: False clock_time_format: \"%Y-%m-%d %H:%M:%S\" write_and_poll_sleep: 2 has_time_window: False support_charge_freeze: False support_discharge_freeze\": False # Services to control charging/discharging charge_start_service: service: select.select_option entity_id: \"select.solaredge_i1_storage_command_mode\" option: \"Charge from Solar Power and Grid\" charge_stop_service: service: select.select_option entity_id: \"select.solaredge_i1_storage_command_mode\" option: \"Charge from Solar Power\" discharge_start_service: service: select.select_option entity_id: \"select.solaredge_i1_storage_command_mode\" option: \"Maximize Self Consumption\"","title":"I want to add an unsupported inverter to Predbat"},{"location":"inverter-setup/#inverter-control-option","text":"The follow options are supported per inverter:","title":"Inverter control option"},{"location":"inverter-setup/#has_rest_api","text":"When True the REST API will be used to fetch data/control the inverter. This is currently only for GivEnergy inverters with GivTCP and givtcp_rest must be set in apps.yaml","title":"has_rest_api"},{"location":"inverter-setup/#has_mqtt_api","text":"When True the MQTT API to Home Assistant will be used to issue control messages for the inverter The mqtt/publish service is used with the topic as defined by mqtt_topic in apps.yaml Messages will be sent these controls: Values that are updated: topic /set/reserve - payload=reserve topic /set/charge_rate - payload=new_rate topic /set/discharge_rate - payload=new_rate topic /set/target_soc - payload=target_soc These three change between battery charge/discharge and auto (idle) mode: topic /set/charge - payload=charge_rate topic /set/discharge - payload=discharge_rate topic /set/auto - payload=true","title":"has_mqtt_api"},{"location":"inverter-setup/#service-api","text":"When True a Home Assistant service will be used to issue control messages for the inverter For each service you wish to use it must be defined in apps.yaml. There are two ways to define a service, the basic mode: charge_start_service: my_service_name_charge Will call my_service_name_charge for the charge start service. Or the custom method: charge_start_service: - service: my_charge_start_service device_id: {device_id} power: {power} soc: {target_soc} Here you can define all the values passed to the service and use the default values from the template or define your own. You can also call more than one service e.g: charge_start_service: - service: my_charge_start_service device_id: {device_id} power: {power} soc: {target_soc} - service: switch.turn_off entity_id: switch.tsunami_charger","title":"Service API"},{"location":"inverter-setup/#charge_start_service","text":"Called to start a charge The default options passed in are: device_id - as defined in apps.yaml by device_id target_soc - The SOC to charge to power - The charge power to use","title":"charge_start_service"},{"location":"inverter-setup/#charge_freeze_service","text":"If defined will be called for freeze charge, otherwise charge_start_service is used for freeze charge also.","title":"charge_freeze_service"},{"location":"inverter-setup/#discharge_start_service","text":"Called to start a discharge The default options passed in are: device_id - as defined in apps.yaml by device_id target_soc - The SOC to discharge to power - The discharge power to use","title":"discharge_start_service"},{"location":"inverter-setup/#discharge_freeze_service","text":"If defined will be called for Discharge freeze, otherwise discharge_start_service is used for freeze discharge also.","title":"discharge_freeze_service"},{"location":"inverter-setup/#charge_stop_service","text":"Called to stop a charge device_id - as defined in apps.yaml by device_id","title":"charge_stop_service"},{"location":"inverter-setup/#discharge_stop_service","text":"Called to stop a discharge, if not set then charge_stop_service will be used instead device_id - as defined in apps.yaml by device_id","title":"discharge_stop_service"},{"location":"inverter-setup/#output_charge_control","text":"Set to power, current or none When power the inverter has a charge_rate and discharge_rate setting in watts defined in apps.yaml When current the inverter has timed_charge_current and timed_discharge_current setting in amps defined in apps.yaml","title":"output_charge_control"},{"location":"inverter-setup/#charge_control_immediate","text":"When True the inverter timed_charge_current or timed_discharge_current is used to control charging or discharging as/when it starts and stops rather than using a timed method.","title":"charge_control_immediate"},{"location":"inverter-setup/#current_dp","text":"Sets the number of decimal places when setting the current in Amps, should be 0 or 1","title":"current_dp"},{"location":"inverter-setup/#has_charge_enable_time","text":"When True the inverter has a setting defined in apps.yaml called scheduled_charge_enable when can be used to enable/disable timed charging.","title":"has_charge_enable_time"},{"location":"inverter-setup/#has_discharge_enable_time","text":"When True the inverter has a setting defined in apps.yaml called scheduled_discharge_enable when can be used to enable/disable timed discharging.","title":"has_discharge_enable_time"},{"location":"inverter-setup/#has_target_soc","text":"When True the inverter has a target soc setting in apps.yaml called charge_limit , when False charging must be turned on and off by Predbat rather than the inverter doing it based on the target %","title":"has_target_soc"},{"location":"inverter-setup/#has_reserve_soc","text":"When True the inverter has a reserve soc setting in apps.yaml called reserve","title":"has_reserve_soc"},{"location":"inverter-setup/#has_timed_pause","text":"When True the inverter has a setting in apps.yaml called pause_mode and settings pause_start_time and pause_end_time which can be used to pause the inverter from charging and discharging the battery - this is for GivEnergy systems only right now.","title":"has_timed_pause"},{"location":"inverter-setup/#charge_time_format","text":"When set to \"HH:MM:SS\" the inverter has: charge_start_time charge_end_time discharge_start_time discharge_end_time Which are option selectors in the format HH:MM:SS (e.g. 12:23:00) where seconds are always 00. When set to \"H M\" the inverter has: charge_start_hour charge_end_hour charge_start_minute charge_end_minute discharge_start_hour discharge_end_hour discharge_start_minute discharge_end_minute Settings in apps.yaml which can be used to set the start and end times of charges and discharges","title":"charge_time_format"},{"location":"inverter-setup/#charge_time_entity_is_option","text":"When True charge_start_time charge_end_time discharge_start_time and discharge_end_time are all Options, when false they are number values.","title":"charge_time_entity_is_option"},{"location":"inverter-setup/#clock_time_format","text":"Defines the time format of the inverter clock setting inverter_time in apps.yaml","title":"clock_time_format"},{"location":"inverter-setup/#soc_units","text":"Defines the units of the SOC setting (currently not used)","title":"soc_units"},{"location":"inverter-setup/#time_button_press","text":"When true the inverter has a button press which is needed to update the inverter registers from the Home Assistant values. The apps.yaml setting charge_discharge_update_button is the entity name of the button that must be pressed and polled until it updates after each inverter register change.","title":"time_button_press"},{"location":"inverter-setup/#support_charge_freeze","text":"When True the inverter supports charge freeze modes","title":"support_charge_freeze"},{"location":"inverter-setup/#support_discharge_freeze","text":"When True the inverter supports discharge freeze modes","title":"support_discharge_freeze"},{"location":"inverter-setup/#has_ge_inverter_mode","text":"When True the inverter as the GivEnergy inverter modes (ECO, Timed Export etc).","title":"has_ge_inverter_mode"},{"location":"inverter-setup/#num_load_entities","text":"Sets the number of load_power_n settings in apps.yaml are present in addition to load_power (the default)","title":"num_load_entities"},{"location":"inverter-setup/#write_and_poll_sleep","text":"Sets the number of seconds between polls of inverter settings","title":"write_and_poll_sleep"},{"location":"inverter-setup/#has_idle_time","text":"When True the inverter has an idle time register which must be set to the start and end times for ECO mode (GivEnergy EMC)","title":"has_idle_time"},{"location":"inverter-setup/#can_span_midnight","text":"When True start and end times for charge and discharge can span midnight e.g. 23:00:00 - 01:00:00 is a 2 hour slot.","title":"can_span_midnight"},{"location":"inverter-setup/#charge_discharge_with_rate","text":"When True when charging discharge rate must be 0 and visa-versa. When false the rate does not have to change.","title":"charge_discharge_with_rate"},{"location":"manual-api/","text":"Predbat automation API CAUTION This is an expert feature only, you can break Predbat if you set the wrong things here. While for most people Predbat will do what you want without any adjustments there are some special cases where users wish to write some more complex automations which override Predbat settings For settings inside Home Assistant e.g. switch.predbat_ , select.predbat_ and input_number.predbat_* you can already use an automation to change these values For settings in apps.yaml its very difficult or impossible to update them via an automation. For this reasons there is a selector called select.predbat_manual_api which works a bit like the manual override ones but this can have new values added using the select API in Home Assistant. The only function the selector itself serves is to store override commands, you can clear from the selector but you have to set them using a service call. Certain settings from apps.yaml maybe overridden using this method. Each override is in a string format and works a bit like a web URL, setting the command and the values. Data retention The data for overrides is kept inside the Home Assistant selector itself and so will survive a reboot. There is likely a limit to the size of this data so be sure to remove old overrides when you are done with them. Keep in mind its easy to lose all of the overrides with the 'off' option so do not keep important data here only use it for short term automations. Supported command formats The supported formats are: off = (index)= ?= (index)?= ?=&= (index)?=&= Commands are disabled again by putting them in square brackets e.g: [?=&=] ```` Below is an example of setting a rate override, you can clear all overrides by calling 'off' or this specific one only by calling the same thing again but in square brackets [] For the rates you can use **rates_export_override** or **rates_import_override** with all the same options as apps.yaml but in a URL type format ```text rates_export_override?start=17:00:00&end=19:00:00&rate=0 If you override a single value item in a list with something like: inverter_limit(0)=4000 To disable this override again: [inverter_limit(0)=4000] If you omit the index then all entries in the list will be overridden. To disable all overrides off Supported overrides The following settings can be overridden with this method: rates_export_override rates_import_override inverter_limit export_limit days_previous days_previous_weight inverter_battery_rate_min inverter_reserve_max battery_rate_max car_charging_soc car_charging_limit car_charging_battery_size battery_scaling forecast_hours import_export_scaling inverter_limit_charge inverter_limit_discharge","title":"Predbat automation API"},{"location":"manual-api/#predbat-automation-api","text":"CAUTION This is an expert feature only, you can break Predbat if you set the wrong things here. While for most people Predbat will do what you want without any adjustments there are some special cases where users wish to write some more complex automations which override Predbat settings For settings inside Home Assistant e.g. switch.predbat_ , select.predbat_ and input_number.predbat_* you can already use an automation to change these values For settings in apps.yaml its very difficult or impossible to update them via an automation. For this reasons there is a selector called select.predbat_manual_api which works a bit like the manual override ones but this can have new values added using the select API in Home Assistant. The only function the selector itself serves is to store override commands, you can clear from the selector but you have to set them using a service call. Certain settings from apps.yaml maybe overridden using this method. Each override is in a string format and works a bit like a web URL, setting the command and the values.","title":"Predbat automation API"},{"location":"manual-api/#data-retention","text":"The data for overrides is kept inside the Home Assistant selector itself and so will survive a reboot. There is likely a limit to the size of this data so be sure to remove old overrides when you are done with them. Keep in mind its easy to lose all of the overrides with the 'off' option so do not keep important data here only use it for short term automations.","title":"Data retention"},{"location":"manual-api/#supported-command-formats","text":"The supported formats are: off = (index)= ?= (index)?= ?=&= (index)?=&= Commands are disabled again by putting them in square brackets e.g: [?=&=] ```` Below is an example of setting a rate override, you can clear all overrides by calling 'off' or this specific one only by calling the same thing again but in square brackets [] For the rates you can use **rates_export_override** or **rates_import_override** with all the same options as apps.yaml but in a URL type format ```text rates_export_override?start=17:00:00&end=19:00:00&rate=0 If you override a single value item in a list with something like: inverter_limit(0)=4000 To disable this override again: [inverter_limit(0)=4000] If you omit the index then all entries in the list will be overridden. To disable all overrides off","title":"Supported command formats"},{"location":"manual-api/#supported-overrides","text":"The following settings can be overridden with this method: rates_export_override rates_import_override inverter_limit export_limit days_previous days_previous_weight inverter_battery_rate_min inverter_reserve_max battery_rate_max car_charging_soc car_charging_limit car_charging_battery_size battery_scaling forecast_hours import_export_scaling inverter_limit_charge inverter_limit_discharge","title":"Supported overrides"},{"location":"output-data/","text":"Output data Each time Predbat runs it outputs a lot of information about the current performance of your solar/battery system and the predicted load, PV, cost, CO2, car charging, etc. This section of the documentation explains the different output and logging data that Predbat produces and gives an overview of how to display that information within Home Assistant. There can never be a single Predbat dashboard that suits every user, so instead Predbat gives a starter-set of displays that can be adapted to your individual needs. Web interface NOTE: The Predbat web interface will not work with the AppDaemon or the Predbat-appdaemon installation methods. Predbat has a Web interface active can be opened via the Predbat Add on by clicking on 'Web UI'. The web interface can be added to your sidebar by turning on the 'Show in Sidebar' toggle. If you are not using the Predbat Add on then you may be able to access the Web Interface directly on port 5052 (e.g. with a Docker Container or Native on your Linux/MAC). The Web interface can allow you to view the current plan, adjust the configuration, view the charts, check your apps.yaml and view the logfiles. You can change your view using the top menu bar. Displaying output data Each Predbat configuration item is named input_number.predbat_xxx , switch.predbat_yyy or select.predbat_zzz depending on the control type. Creating a simple Predbat dashboard Each time Predbat runs it auto-generates a dashboard with the filename predbat_dashboard.yaml that can be used as a starter for your own Predbat dashboard. Depending on how you installed Predbat this predbat_dashboard.yaml file will be held in one of three different directories in Home Assistant: if you have used the Predbat add-on installation method , it will be in the directory /addon_configs/6adb4f0d_predbat/ , if the combined AppDaemon/Predbat add-on installation method was used, it's in /addon_configs/46f69597_appdaemon-predbat/ , or with the HACS, Appdaemon add-on then Predbat installation method , it's /config/appdaemon/apps/batpred/config/ . 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 open the predbat_dashboard.yaml file - see editing configuration files within Home Assistant if you need to install an editor. Once opened, select and copy all the contents of the predbat_dashboard.yaml file and add the contents into a new dashboard page: Go to System/Dashboards, click 'Open' against an existing dashboard or 'Add Dashboard'/'New dashboard from scratch'/enter a name/click Create, then click 'Open' Click the pencil icon in the top right corner, click the blue 'Add card', scroll down the list of cards to the bottom and click 'Manual', delete the template card configuration and paste the contents of the predbat_dashboard.yaml file copied earlier, then 'Save'. This will give you a simple Predbat control and output dashboard that you can then resequence and customise as you wish. Creating a compact Predbat control dashboard You can also create a dashboard page that's dynamically generated to automatically include all the Predbat control and output entities, so when new entities are added in future Predbat releases, you don't have to edit the dashboard. Firstly you need to install HACS if it isn't already installed, and then install two HACS front end components: Auto Entities ( https://github.com/thomasloven/lovelace-auto-entities ) automatically generates a list of entities that match a wildcard expression Lovelace Collapsable Cards ( https://github.com/RossMcMillan92/lovelace-collapsable-cards ) wraps the entity lists within a drop-down toggle Installation steps: Click the HACS icon on the left-hand side panel Click 'Frontend' Click the three dots in the top right corner then 'Custom Repositories' Paste (or type) in the following repository name https://github.com/RossMcMillan92/lovelace-collapsable-cards , choose Category of 'Lovelace', and click Add Close the Custom repositories dialogue Click 'Explore & Download Repositories' Search for 'collapsable cards', click the name of it, check it's the right one, click 'Download', 'Download' again, then 'Reload' Click 'Explore & Download Repositories' again, search for 'auto-entities', then 'Download', 'Download', 'Reload' Now create the dynamic dashboard: Go to Settings/Dashboards, click 'Open' against an existing dashboard or 'Add Dashboard'/'New dashboard from scratch'/enter a name/click Create, then click 'Open' Click the pencil icon in the top right corner, then the plus symbol on the far right of the next row to create a new View Enter a title of the View, then Save Click the blue 'Add card', scroll down the list of cards to the bottom and click 'Manual', delete the template card configuration and copy/paste the following YAML into the dashboard and click 'Save': type: vertical-stack title: Predbat \ud83e\udd87 cards: - type: entities entities: - entity: predbat.status - type: weblink name: Predbat Web Console url: /hassio/ingress/6adb4f0d_predbat - entity: update.predbat_version - entity: select.predbat_update - entity: select.predbat_mode - entity: select.predbat_saverestore - entity: switch.predbat_active - type: custom:collapsable-cards title: \ud83d\udd00 Control defaultOpen: false cards: - type: custom:collapsable-cards title: \ud83d\udd22 Input Variables defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: input_number.predbat* exclude: [] unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \ud83d\udd00 Switches defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: switch.predbat* exclude: [] unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \ud83d\udd22 Selectors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: select.predbat* exclude: [] unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: '#\ufe0f\u20e3 Sensors' defaultOpen: false cards: - type: custom:collapsable-cards title: \ud83d\udcb7 Cost Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: predbat.*cost* - entity_id: predbat.*rate* - entity_id: predbat.*metric* exclude: - entity_id: predbat.*start* - entity_id: predbat.*end* - entity_id: predbat.*duration* unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \ud83d\udcb7 Saving Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: predbat.*saving* exclude: - entity_id: predbat.*start* - entity_id: predbat.*end* - entity_id: predbat.*duration* unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \ud83d\udd5b Time/Duration Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: predbat.*start* - entity_id: predbat.*end* - entity_id: predbat.*duration* - entity_id: predbat.*record* exclude: [] unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \u26a1 Power Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: predbat.*soc* - entity_id: predbat.*energy* - entity_id: predbat.*load* - entity_id: predbat.*battery* - entity_id: predbat.*kw* - entity_id: predbat.*power* - entity_id: predbat.*charge* - entity_id: predbat.*iboost* - entity_id: predbat.*grid* - entity_id: sensor.predbat_pv* exclude: - entity_id: predbat.*savings* - entity_id: predbat.*start* - entity_id: predbat.*end* - entity_id: predbat.*duration* - entity_id: predbat.*record* unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: 1\ufe0f\u20e3 Binary Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: binary_sensor.predbat* exclude: [] unique: true sort: method: friendly_name numeric: false This will give you a compact dynamically created list of all Predbat entities which groups the entities by type and is collapsed by default to prevent screen clutter. Credit @DJBenson for the code. Viewing the Predbat plan predbat.plan_html - A sensor that contains a HTML render of the Predbat predicted best plan, detailing import and export rates, predicted house load, solar generation, battery SoC, car and iBoost charging, and Predbat's planned charging and discharging activities. Its recommended to Create the Predbat Plan card as an easy way to see the plan that Predbat has created. If you are using the Predbat add-on then the predbat plan can also be viewed via the 'Plan' tab of the Predbat web console . Graphing the Predbat predictions A set of Apex Charts can also be created to see graphically what Predbat plans to do - Creating the charts . Basic status switch.predbat_active - Automatically set by Predbat to On when Predbat is busy calculating or controlling your inverter, or Off when Predbat is waiting for the next time it needs to perform a plan calculation update. If you toggle this switch in Home Assistant it will force Predbat to perform an update now (useful for automations). predbat.status - Gives the current status & errors and logs any changes that Predbat makes to your inverter. The different Predbat status values and their meanings are detailed in what does Predbat do . predbat.status additionally has the following attributes that are automatically populated: Last updated - date and time that Predbat last updated the plan Debug - A set of arrays containing Predbat's planned charging and discharging time windows and battery limits (in kWh) Version - version of Predbat that's running Error - binary value true or false depending upon whether Predbat is in an error status or nor Baseline data Predbat outputs the following sensors to predict what your battery is expected to do over the forecast_hours duration of the plan with no changes made by Predbat. This is considered to be the 'baseline' plan: NB: All of Predbat's forecasts are from midnight today to the forecast_hours duration (set in apps.yaml) into the future and shouldn't be confused with 'today' figures. e.g. predbat.pv_energy is the actual PV energy from midnight today, and for the predicted forecast_hours (typically 48) ahead so will be much larger than sensor.solcast_pv_forecast_today which is today's Solcast PV forecast. predbat.battery_cycle - Predicted baseline battery cycle in kWh (total kWh processed) with attributes of the prediction every 5 minutes to end of plan predbat.battery_hours_left - The number of hours left until your home battery is predicted to run out under the baseline plan (stops at the maximum prediction time) predbat.battery_power - The sensor is always zero; attributes contain the predicted remaining battery power under the baseline plan, in 5 minute slots, for charting predbat.car_soc - The expected charge level of your car at the end of the baseline plan. Can also be charted predbat.charge_end - Predicted end time of the next forced battery charging under the baseline plan predbat.charge_limit - Predicted baseline battery charge limit for the next charge in percent with attributes of all future battery charging times & limits predbat.charge_limit_kw - Predicted baseline battery charge limit for the next charge in kWh with attributes of future charging times & limits predbat.charge_start - Predicted start time of the next forced battery charging under the baseline plan predbat.duration - The duration of the prediction maximum in hours predbat.export_energy - Total kWh of predicted exports under the baseline plan with attributes of the predicted export kWh and their time slots predbat.grid_power - The sensor is always zero; attributes contain the predicted Grid power (positive or negative for import or export) in kW per 5 minute slots to the end of the baseline plan for charting predbat.import_energy - Total kWh of predicted imports under baseline plan with attributes of the predicted import kWh and their time slots predbat.import_energy_battery - Total kWh of predicted import energy used to charge the home battery under the baseline plan predbat.import_energy_house - Predicted import energy used by the home under the baseline plan that is not provided by your home battery (e.g. due to a flat battery or load is above maximum discharge rate) predbat.load_energy - Total kWh of predicted house load under the baseline plan with attributes of the predicted load kWh in 5 minute slots to the end of the plan predbat.load_power - Total kW of predicted house load power to the end of the baseline plan, with attributes of the average instantaneous house load power in kW in 5 minute slots to the end of the plan predbat.metric - Total predicted cost for the baseline plan, taking account of predicted solar generation, house load, import and export rates. Attributes contain data for charting the cost prediction in 5 minute slots to the end of the plan predbat.pv_energy - Predicted PV energy in kWh under the baseline plan with attributes of the predicted PV generation in kWh with time slots predbat.pv_power - Predicted PV power now with attributes that contain the predicted PV power in kW per 5 minute slots to the end of the baseline plan for charting predbat.soc_kw - Predicted state of charge (in kWh) at the end of the baseline plan prediction, not very useful in itself, but the attributes hold prediction data in 5 minute intervals which can be charted with Apex Charts (or similar) predbat.soc_min_kwh - Predicted lowest battery SoC value in kWh under the baseline plan with attribute of the date/time that that lowest SoC occurs at PV 10% Baseline data Predbat outputs the following baseline results under the PV 10% scenario for the forecast_hours duration of the plan, these are known as the 'base10' predictions: predbat.base10_export_energy- Total predicted export energy in kWh for the PV 10% scenario, with attributes of the predicted export kWh and their time slots predbat.base10_import_energy- Total predicted import energy in kWh for the PV 10% scenario, with attributes of the predicted import kWh and their time slots predbat.base10_load_energy - Total predicted house load in kWh for the PV 10% scenario predbat.base10_metric - Total predicted cost for the PV 10% scenario, with attributes of the cost prediction in 5 minute slots to the end of the plan for charting predbat.base10_pv_energy - Predicted PV 10% energy in kWh with attributes of the predicted PV generation in kWh with time slots predbat.soc_kw_base10 - Predicted final state of charge (in kWh) of the battery, with attributes of the predicted SoC in 5 minute time slots to the end of the plan under the PV 10% scenario, for charting Best Prediction data Predbat outputs the following 'best' entities from the forecast (for the forecast_hours duration) based on the lowest cost consumption plan. The 'best' plan in Predbat parlance is simply Predbat's lowest cost predicted plan: predbat.battery_cycle_best - Predicted best battery cycle in kWh (total kWh processed) with attributes of the prediction every 5 minutes to end of plan predbat.battery_power_best - Predicted remaining battery power in kW with attributes of the future prediction in 5 minute slots predbat.best_battery_hours_left - Predicted total number of hours of battery capacity left under the best plan predbat.best_charge_end - Predicted end time of the next forced battery charging under the best plan predbat.best_charge_limit - Predicted best battery charge limit for the next charge in percent with attributes of all future battery charging times & limits predbat.best_charge_limit_kw - Predicted best battery charge limit for the next charge in kWh with attributes of future charging times & limits predbat.best_charge_start - Predicted start time of the next forced battery charging under the best plan predbat.best_export_end - Predicted end time of the next forced battery export under the best plan predbat.best_export_limit - Predicted best battery export limit in percent (will be 0% when discharging or 100% when not) with attributes of all future battery exports (kWh and time slots) predbat.best_export_limit_kw - Predicted best battery export limit in kWh predbat.best_export_start - Predicted start time of the next forced battery export under the best plan predbat.best_export_energy - Total kWh of predicted exports under the best plan, with attributes of the predicted export kWh and their time slots predbat.best_import_energy - Total kWh of predicted imports under best plan, with attributes of the predicted import kWh and their time slots predbat.best_import_energy_battery - Total kWh of predicted import energy to charge the home battery under the best plan predbat.best_import_energy_house - Total kWh of predicted import energy used directly by the house under the best plan (e.g. due to a flat battery or the house load is greater than the max discharge rate) predbat.best_load_energy - Total kWh of predicted house load energy in kWh under the best plan with attributes of the predicted load kWh in 5 minute slots to the end of the plan predbat.best_metric - Total predicted cost for the best plan, taking account of predicted solar generation, house load, import and export rates. Attributes contain data for charting the cost prediction in 5 minute slots to the end of the plan predbat.best_pv_energy - Predicted PV energy in kWh under the best plan with attributes of the predicted PV generation in kWh with time slots predbat.best_soc_min_kwh - Predicted lowest battery SoC value in kWh under the best plan with attribute of the date/time that that lowest SoC occurs at predbat.car_soc_best - See Car data below predbat.carbon_best - See Carbon data below predbat.grid_power_best - The sensor is always zero; attributes contain the predicted Grid power (positive or negative for import or export), in kW per 5 minute slots to the end of the best plan for charting predbat.iboost_best - See iBoost data below predbat.load_power_best - Total kW of predicted house load power to the end the best plan, with attributes of the average instantaneous house load power in kW in 5 minute slots to the end of the plan predbat.pv_power_best - The sensor is always zero; attributes contain the predicted PV power in kW per 5 minute slots to the end of the best plan for charting predbat.soc_kw_best - Predicted final state of charge (in kWh) with attributes of the predicted SoC in 5 minute time slots to the end of the best plan, for charting predbat.soc_kw_best_h1 - Single data point for the predicted state of charge in 1 hours time (useful for calibration charts, predicted vs actual) predbat.soc_kw_best_h8 - Single data point for the predicted state of charge in 8 hours time (useful for calibration charts, predicted vs actual) predbat.soc_kw_best_h12 - Single data point for the predicted state of charge in 12 hours time (useful for calibration charts, predicted vs actual) Best PV 10% Prediction data Predbat outputs the following best results under the PV 10% scenario for the forecast_hours duration, these are known as the 'best10' prediction: predbat.best10_metric - Predicted best cost in pence using the PV 10% solar forecast predbat.best10_export_energy- Predicted best export energy in kWh for PV 10% predbat.best10_import_energy- Predicted best import energy in kWH for PV 10% predbat.best10_load_energy - Predicted best load energy in kWh for PV 10% predbat.best10_pv_energy - Predicted best PV 10% energy in kWh predbat.soc_kw_best10 - As soc_kw_best but using the PV 10%, also holds minute by minute data (in attributes) to be charted In-day load adjustment data The following sensors are used in the in-day adjustment chart - see creating the Predbat charts and in day load adjustment : predbat.load_energy_actual - Total kWh of house load to end of plan, energy up to 'now' taken from today's actual energy, energy after 'now' from Predbat's prediction. Attributes of this actual/predicted energy in 5 minute slots from midnight today to the end of the plan for charting predbat.load_energy_adjusted - Total kWh of predicted house load to end of plan, adjusted based on variance of today's actual load to the predicted load (based on historical data), dampened according to input_number.predbat_metric_inday_adjust_damping. Attributes contain the 5 minute slot forecasts to end of plan for charting predbat.load_energy_predicted - Total predicted kWh of house load to end of plan, attributes of predicted load in 5 minute slots from midnight today to the end of the plan for charting predbat.load_inday_adjustment - the % in-day adjustment factor used to adjust Predbat's predicted load by actual load today 'Today' energy data The following sensors output by Predbat give the 'today' energy readings. They mirror input sensors fed into Predbat in apps.yaml and are used in the data prediction chart - see creating the Predbat charts : predbat.export_energy_h0 - Mirrors the export_today sensor configured in apps.yaml and gives today's total kWh of export energy predbat.import_energy_h0 - Mirrors the import_today sensor configured in apps.yaml and gives today's total kWh of import energy predbat.load_energy_h0 - Mirrors the load_today sensor configured in apps.yaml and gives today's total kWh of house load energy predbat.pv_energy_h0 - Mirrors the pv_today sensor configured in apps.yaml and gives today's total kWh of generated PV energy predbat.soc_kw_h0 - Mirrors the soc_kwh sensor configured in apps.yaml and gives today's total kWh of battery state of charge (SoC). Note that if you have configured battery scaling then soc_kw_h0 will have been scaled by the configured scaling factor Battery status The following sensors are set based upon what Predbat is currently controlling the battery to do: binary_sensor.predbat_charging - Set to 'on' when Predbat is force charging the battery (from solar, or if that is insufficient, from grid import), or 'off' otherwise binary_sensor.predbat_exporting - Set to 'on' when Predbat is force discharging the battery for export income, 'off' otherwise. These are useful for automations if for example you want to turn off car charging when the battery is being exported. Export trigger binary_sensor.predbat_export_trigger_NAME - custom binary sensors that are set to On by Predbat when more than a specified amount of energy is being exported - see Triggers in apps.yaml Prediction window predbat.record - The sensor is always zero; attributes contain the time window for the current predicted plan Energy rate data Low rate import entities predbat.low_rate_cost - The lowest import rate cost in Pence predbat.low_rate_duration - The time duration in minutes of the next low rate slot predbat.low_rate_end - End time of the next low import rate slot predbat.low_rate_start - Start time of the next low import rate slot predbat.low_rate_cost_2, predbat.low_rate_end_2, predbat.low_rate_start_2 - The cost and times of the following low import rate slot binary_sensor.predbat_low_rate_slot - A sensor that is 'on' to indicate when there is a low energy rate import slot active, 'off' otherwise High rate export entities predbat.high_rate_export_cost - The highest export rate cost in Pence predbat.high_rate_export_duration - The time duration in minutes of the next high rate slot predbat.high_rate_export_end - End time of the next high export rate slot predbat.high_rate_export_start - Start time of the next high export rate slot predbat.high_rate_export_cost_2, predbat.high_rate_export_end_2, predbat.high_rate_export_start_2 - The cost and times of the following high export rate slot binary_sensor.predbat_high_rate_export_slot - A sensor that is 'on' to indicate when there is a high export rate slot active, 'off' otherwise Other rate entities predbat.rates - The current energy import rate in Pence with attributes of yesterday's, todays and tomorrow's rates which can be charted predbat.rates_export - The current energy export rates in Pence (also can be charted) predbat.rates_gas - The current gas rates in Pence (also can be charted) predbat.cost_today - The total cost of energy so far today (since midnight) with attributes of the total cost every 5 minutes since midnight today predbat.cost_today_export - Same as predbat.cost_today, but for all export income since midnight today predbat.cost_today_import - Same as predbat.cost_today, but for all import costs since midnight today predbat.cost_hour - The total cost of energy averaged over the last hour predbat.cost_today_export - Same as predbat.cost_hour, but for export predbat.cost_today_import - Same as predbat.cost_hour, but for import predbat.ppkwh_today - The cost in pence/kWh of the house load today accounting for the change in battery level predbat.ppkwh_hour - The cost in pence/kWh of the house load averaged over the last hour, accounting for the change in battery level Car data binary_sensor.predbat_car_charging_slot - A binary sensor indicating when to charge your car (if car planning is enabled) - which can be used in an automation as described in Predbat led car charging predbat.car_charging_start - The time that car charging is planned to start at, in HH:MM:SS format predbat.car_soc_best - Predicted charge level of your car in the best plan at the end of the plan using the proposed car charging SoC% and charge window. Can also be charted predbat.cost_today_car - Current cost in pence so far today of charging the car, with attribute of the projected future car charging costs and slots predbat.cost_total_car - A running total in pence of the below cost_yesterday_car sensor, with attribute of the total in pounds predbat.cost_yesterday_car - A sensor that gives the total energy costs in pence of charging the car for yesterday (00:00-23:59 on the previous day) iBoost Solar Diverter data binary_sensor.predbat_iboost_active - A binary sensor indicating when there is excess solar and the solar diverter (e.g. iBoost, Eddi or just plain immersion heater) should be active, can be used for automations to trigger the immersion heater boost input_number.predbat_iboost_today - Gives the amount of energy modelled that will be sent to the solar diverter today, increments during the day and is reset to zero at 11:30pm each night predbat.iboost_best - Predicted energy in kWh going into the iBoost solar diverter under the best plan Carbon data The following sensors output by Predbat give historic and predicted carbon data. They are used in the carbon chart - see creating the Predbat charts : predbat.carbon - Predicted Carbon energy in g at the end of the plan with attributes giving the breakdown of predicted Carbon impact by half hour time slots predbat.carbon_best - Predicted Carbon intensity in g for your home under the best plan based on grid imports, grid exports and the grid's projected carbon intensity predbat.carbon_now - A sensor that gives the current Grid Carbon intensity in g/kWh predbat.carbon_today - A sensor that tracks your home's Carbon impact today in g based on your grid import minus your grid export Energy saving data The following sensors output by Predbat give cost saving data that Predbat achieved, i.e. the financial benefits of using Predbat. They are used in the daily cost saving and total cost savings charts - see creating the Predbat charts : predbat.cost_yesterday - A sensor that gives the total energy costs in pence for yesterday (00:00-23:59 on the previous day) predbat.savings_total_actual - A running total in pence of the above cost_yesterday sensor, with attribute of the total in pounds predbat.savings_total_predbat - A running total in pence of the below savings_yesterday_predbat sensor, with attribute of the total in pounds predbat.savings_total_pvbat - A running total of the below savings_yesterday_pvbat sensor, with attribute of the total in pounds predbat.savings_total_soc - A running total of what the final SoC in kWh would have been at the end of each day if you were not using Predbat predbat.savings_yesterday_predbat - A sensor which tells you how much money Predbat saved you yesterday compared to not using Predbat, and only charging at the lowest import rate in the 24 hour period predbat.savings_yesterday_pvbat - A sensor which tells you how much money you saved from using Predbat vs not having a PV and battery system at all and all house load being met from grid import Solar forecast data The following sensors give the forecast Solar data from Solcast. Predbat populates these sensors irrespective of whether you are using the Predbat direct Solcast or Solcast integration method to get your Solar forecast, but if you are using the Solcast integration then the Predbat sensors mirror the similarly named Solcast integration sensors so could be disabled if you so wish. sensor.predbat_pv_today - Tracks the PV forecast in kWh for today, attributes give the remaining amount today and the half hourly data sensor.predbat_pv_tomorrow - Tracks the PV forecast in kWh for tomorrow, attributes give the remaining amount today and the half hourly data sensor.predbat_pv_d2 - Similar to the above, but tracking the PV forecast for the day after tomorrow sensor.predbat_pv_d3 - PV forecast for two days after tomorrow sensor.predbat_pv_forecast_h0 - Tracks the PV 'power now' forecast in Watts, attributes give the 10% and 90% power now forecast 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! If you are using the Predbat add-on then the logfile can easily be viewed via the 'Log' tab of the Predbat web console . To directly view the physical logfile, it can be found in one of three different directories in Home Assistant with slightly different filenames depending on how you installed Predbat: if you have used the Predbat add-on installation method , the logfile will be /addon_configs/6adb4f0d_predbat/predbat.log , if the HACS, Appdaemon add-on then Predbat installation method , it's /homeassistant/appdaemon/appdaemon.log , or if the combined AppDaemon/Predbat add-on installation method was used, it's /addon_configs/46f69597_appdaemon-predbat/predbat.log . 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 if you are not using the Predbat add-on. See editing configuration files within 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 running the Home Assistant Companion app. To create a new automation: Settings / Automations & Scenes Create Automation / Create new Automation Three dots (top right corner) / Edit in YAML Delete the existing (template) automation code and copy/paste the supplied automation code below GivTCP activity monitor This automation will raise an alert if any of the following occur: The inverter goes offline for more than 15 minutes No last_updated_time received from the inverter for more than 15 minutes Inverter temperature less than 5 degrees for more than 15 minutes (should never happen) The battery goes offline to the inverter for more than 15 minutes GivTCP add-on is not running Mosquitto broker add-on is not running Predbat/AppDaemon-predbat or AppDaemon add-on (as appropriate) is not running The script will need to be customised for your inverter id, battery id and mobile details, and can be extended for multiple inverters and batteries by duplicating the triggers and adding appropriate battery and inverter id's. alias: GivTCP activity monitor description: Alert when communications to GivTCP have ceased for 15 minutes triggers: - trigger: state entity_id: sensor.givtcp__last_updated_time to: \"null\" for: minutes: 15 variables: alert_text: No GivTCP update received from inverter restart_app: GivTCP - trigger: state entity_id: - sensor.givtcp__status from: online for: minutes: 15 variables: alert_text: No GivTCP update received from inverter restart_app: GivTCP - trigger: numeric_state entity_id: - sensor.givtcp__invertor_temperature for: minutes: 15 below: 10 variables: alert_text: No GivTCP update received from inverter restart_app: GivTCP - trigger: state entity_id: - sensor.givtcp__battery_cells to: unknown for: minutes: 15 variables: alert_text: Battery is offline to GivTCP restart_app: GivTCP - trigger: state entity_id: - binary_sensor.givtcp_running to: \"off\" for: minutes: 15 variables: alert_text: GivTCP add-on is not running restart_app: GivTCP - trigger: state entity_id: - binary_sensor.mosquitto_broker_running to: \"off\" for: minutes: 15 variables: alert_text: Mosquitto Broker add-on is not running restart_app: Mosquitto actions: - action: notify.mobile_app_ alias: Send a notification data: title: GivTCP communication issue message: | {{now().strftime('%-d %b %H:%M')}} ISSUE: {{ alert_text }} for the past 15 minutes, restarting {{ restart_app }} data: visibility: public persistent: true push: sound: name: default critical: 1 volume: 0.8 sticky: true color: red - choose: - conditions: - condition: template value_template: \"{{ restart_app == 'GivTCP' }}\" sequence: - alias: Restart GivTCP add-on action: hassio.addon_restart data: addon: 533ea71a_givtcp - conditions: - condition: template value_template: \"{{ restart_app == 'Mosquitto' }}\" sequence: - alias: Restart Mosquitto add-on action: hassio.addon_restart data: addon: core_mosquitto trace: stored_traces: 20 mode: single The last two triggers (GivTCP and Mosquitto running) trigger if any of these add-ons that Predbat is dependent upon are not running. You will need to enable a binary sensor for each add-on to be able to use these triggers in the automation: Navigate to Settings / Devices and Services / Devices and search for 'GivTCP' Click on the GivTCP add-on, and under 'Sensors', click 'XX entities not shown' Click the 'Running' sensor, then the cogwheel, and Enable the sensor Repeat these steps for the 'Mosquitto' add-on. As an extension to the above, if you don't want the automation to restart the failing add-on and instead just send an alert that there is a problem, delete the 'choose' code above. Restarting GivTCP does however lose the current GivTCP log in Home Assistant. NB: If you are using GivTCP v2 rather than v3, replace the '533ea71a_givtcp' with 'a6a2857d_givtcp'. Predbat error monitor This automation will raise an alert if Predbat's status turns to Error for more than 5 minutes. In normal operation Predbat will automatically run and update its forecast every 5 minutes. If the automation detects that Predbat has not done this for 20 minutes, then an alert will be raised and the automation will restart the Predbat add-on to try to resolve a 'hung Predbat' issue. In the same way for the GivTCP and Mosquitto add-on's above, the last trigger requires you to enable a binary sensor that detects that the Predbat/AppDaemon add-on is running. Follow the same steps to enable the binary sensor for either the 'Predbat', 'AppDaemon' or 'AppDaemon-predbat' add-on depending on which Predbat installation method you followed. The script will need to be customised for your mobile details. alias: Predbat error monitor description: Alert when Predbat has raised an exception trace: stored_traces: 20 triggers: - trigger: template alias: Predbat status contains 'Error' for 5 minutes value_template: \"{{ 'Error' in states('predbat.status') }}\" for: minutes: 5 variables: alert_text: >- predbat status is {{ states('predbat.status') }}, error={{ state_attr('predbat.status', 'error') }} - trigger: state alias: Predbat is in error status for 5 minutes entity_id: predbat.status attribute: error to: \"true\" for: minutes: 5 variables: alert_text: >- predbat status is {{ states('predbat.status') }}, error={{ state_attr('predbat.status', 'error') }} - trigger: state alias: Predbat status.last_updated has not changed for 20 minutes entity_id: predbat.status attribute: last_updated for: minutes: 20 variables: alert_text: >- Predbat stalled? Restarting. last_updated=' {{ state_attr('predbat.status','last_updated')|as_timestamp|timestamp_custom('%a %H:%M') }}', unchanged for 20 mins; Status='{{ states('predbat.status') }}' restart_predbat: \"Y\" - trigger: state entity_id: binary_sensor.predbat_running to: \"off\" for: minutes: 15 variables: alert_text: Predbat add-on is not running restart_predbat: \"Y\" actions: - action: notify.mobile_app_ alias: Send alert message data: title: Predbat status issue message: | {{now().strftime('%-d %b %H:%M')}} ISSUE: {{ alert_text }} data: visibility: public persistent: true push: sound: name: default critical: 1 volume: 0.8 sticky: true color: red - if: - condition: template value_template: \"{{ restart_predbat == 'Y' }}\" then: - action: hassio.addon_restart data: addon: 6adb4f0d_predbat alias: Restart Predbat add-on mode: single NB: If you are using AppDaemon rather than the Predbat add-on, replace '6adb4f0d_predbat' with 'a0d7b954_appdaemon' and change 'binary_sensor.predbat_running' to 'binary_sensor.appdaemon_running'. An error alert looks like this:","title":"Output data"},{"location":"output-data/#output-data","text":"Each time Predbat runs it outputs a lot of information about the current performance of your solar/battery system and the predicted load, PV, cost, CO2, car charging, etc. This section of the documentation explains the different output and logging data that Predbat produces and gives an overview of how to display that information within Home Assistant. There can never be a single Predbat dashboard that suits every user, so instead Predbat gives a starter-set of displays that can be adapted to your individual needs.","title":"Output data"},{"location":"output-data/#web-interface","text":"NOTE: The Predbat web interface will not work with the AppDaemon or the Predbat-appdaemon installation methods. Predbat has a Web interface active can be opened via the Predbat Add on by clicking on 'Web UI'. The web interface can be added to your sidebar by turning on the 'Show in Sidebar' toggle. If you are not using the Predbat Add on then you may be able to access the Web Interface directly on port 5052 (e.g. with a Docker Container or Native on your Linux/MAC). The Web interface can allow you to view the current plan, adjust the configuration, view the charts, check your apps.yaml and view the logfiles. You can change your view using the top menu bar.","title":"Web interface"},{"location":"output-data/#displaying-output-data","text":"Each Predbat configuration item is named input_number.predbat_xxx , switch.predbat_yyy or select.predbat_zzz depending on the control type.","title":"Displaying output data"},{"location":"output-data/#creating-a-simple-predbat-dashboard","text":"Each time Predbat runs it auto-generates a dashboard with the filename predbat_dashboard.yaml that can be used as a starter for your own Predbat dashboard. Depending on how you installed Predbat this predbat_dashboard.yaml file will be held in one of three different directories in Home Assistant: if you have used the Predbat add-on installation method , it will be in the directory /addon_configs/6adb4f0d_predbat/ , if the combined AppDaemon/Predbat add-on installation method was used, it's in /addon_configs/46f69597_appdaemon-predbat/ , or with the HACS, Appdaemon add-on then Predbat installation method , it's /config/appdaemon/apps/batpred/config/ . 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 open the predbat_dashboard.yaml file - see editing configuration files within Home Assistant if you need to install an editor. Once opened, select and copy all the contents of the predbat_dashboard.yaml file and add the contents into a new dashboard page: Go to System/Dashboards, click 'Open' against an existing dashboard or 'Add Dashboard'/'New dashboard from scratch'/enter a name/click Create, then click 'Open' Click the pencil icon in the top right corner, click the blue 'Add card', scroll down the list of cards to the bottom and click 'Manual', delete the template card configuration and paste the contents of the predbat_dashboard.yaml file copied earlier, then 'Save'. This will give you a simple Predbat control and output dashboard that you can then resequence and customise as you wish.","title":"Creating a simple Predbat dashboard"},{"location":"output-data/#creating-a-compact-predbat-control-dashboard","text":"You can also create a dashboard page that's dynamically generated to automatically include all the Predbat control and output entities, so when new entities are added in future Predbat releases, you don't have to edit the dashboard. Firstly you need to install HACS if it isn't already installed, and then install two HACS front end components: Auto Entities ( https://github.com/thomasloven/lovelace-auto-entities ) automatically generates a list of entities that match a wildcard expression Lovelace Collapsable Cards ( https://github.com/RossMcMillan92/lovelace-collapsable-cards ) wraps the entity lists within a drop-down toggle Installation steps: Click the HACS icon on the left-hand side panel Click 'Frontend' Click the three dots in the top right corner then 'Custom Repositories' Paste (or type) in the following repository name https://github.com/RossMcMillan92/lovelace-collapsable-cards , choose Category of 'Lovelace', and click Add Close the Custom repositories dialogue Click 'Explore & Download Repositories' Search for 'collapsable cards', click the name of it, check it's the right one, click 'Download', 'Download' again, then 'Reload' Click 'Explore & Download Repositories' again, search for 'auto-entities', then 'Download', 'Download', 'Reload' Now create the dynamic dashboard: Go to Settings/Dashboards, click 'Open' against an existing dashboard or 'Add Dashboard'/'New dashboard from scratch'/enter a name/click Create, then click 'Open' Click the pencil icon in the top right corner, then the plus symbol on the far right of the next row to create a new View Enter a title of the View, then Save Click the blue 'Add card', scroll down the list of cards to the bottom and click 'Manual', delete the template card configuration and copy/paste the following YAML into the dashboard and click 'Save': type: vertical-stack title: Predbat \ud83e\udd87 cards: - type: entities entities: - entity: predbat.status - type: weblink name: Predbat Web Console url: /hassio/ingress/6adb4f0d_predbat - entity: update.predbat_version - entity: select.predbat_update - entity: select.predbat_mode - entity: select.predbat_saverestore - entity: switch.predbat_active - type: custom:collapsable-cards title: \ud83d\udd00 Control defaultOpen: false cards: - type: custom:collapsable-cards title: \ud83d\udd22 Input Variables defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: input_number.predbat* exclude: [] unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \ud83d\udd00 Switches defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: switch.predbat* exclude: [] unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \ud83d\udd22 Selectors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: select.predbat* exclude: [] unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: '#\ufe0f\u20e3 Sensors' defaultOpen: false cards: - type: custom:collapsable-cards title: \ud83d\udcb7 Cost Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: predbat.*cost* - entity_id: predbat.*rate* - entity_id: predbat.*metric* exclude: - entity_id: predbat.*start* - entity_id: predbat.*end* - entity_id: predbat.*duration* unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \ud83d\udcb7 Saving Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: predbat.*saving* exclude: - entity_id: predbat.*start* - entity_id: predbat.*end* - entity_id: predbat.*duration* unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \ud83d\udd5b Time/Duration Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: predbat.*start* - entity_id: predbat.*end* - entity_id: predbat.*duration* - entity_id: predbat.*record* exclude: [] unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: \u26a1 Power Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: predbat.*soc* - entity_id: predbat.*energy* - entity_id: predbat.*load* - entity_id: predbat.*battery* - entity_id: predbat.*kw* - entity_id: predbat.*power* - entity_id: predbat.*charge* - entity_id: predbat.*iboost* - entity_id: predbat.*grid* - entity_id: sensor.predbat_pv* exclude: - entity_id: predbat.*savings* - entity_id: predbat.*start* - entity_id: predbat.*end* - entity_id: predbat.*duration* - entity_id: predbat.*record* unique: true sort: method: friendly_name numeric: false - type: custom:collapsable-cards title: 1\ufe0f\u20e3 Binary Sensors defaultOpen: false cards: - type: custom:auto-entities card: type: entities filter: include: - entity_id: binary_sensor.predbat* exclude: [] unique: true sort: method: friendly_name numeric: false This will give you a compact dynamically created list of all Predbat entities which groups the entities by type and is collapsed by default to prevent screen clutter. Credit @DJBenson for the code.","title":"Creating a compact Predbat control dashboard"},{"location":"output-data/#viewing-the-predbat-plan","text":"predbat.plan_html - A sensor that contains a HTML render of the Predbat predicted best plan, detailing import and export rates, predicted house load, solar generation, battery SoC, car and iBoost charging, and Predbat's planned charging and discharging activities. Its recommended to Create the Predbat Plan card as an easy way to see the plan that Predbat has created. If you are using the Predbat add-on then the predbat plan can also be viewed via the 'Plan' tab of the Predbat web console .","title":"Viewing the Predbat plan"},{"location":"output-data/#graphing-the-predbat-predictions","text":"A set of Apex Charts can also be created to see graphically what Predbat plans to do - Creating the charts .","title":"Graphing the Predbat predictions"},{"location":"output-data/#basic-status","text":"switch.predbat_active - Automatically set by Predbat to On when Predbat is busy calculating or controlling your inverter, or Off when Predbat is waiting for the next time it needs to perform a plan calculation update. If you toggle this switch in Home Assistant it will force Predbat to perform an update now (useful for automations). predbat.status - Gives the current status & errors and logs any changes that Predbat makes to your inverter. The different Predbat status values and their meanings are detailed in what does Predbat do . predbat.status additionally has the following attributes that are automatically populated: Last updated - date and time that Predbat last updated the plan Debug - A set of arrays containing Predbat's planned charging and discharging time windows and battery limits (in kWh) Version - version of Predbat that's running Error - binary value true or false depending upon whether Predbat is in an error status or nor","title":"Basic status"},{"location":"output-data/#baseline-data","text":"Predbat outputs the following sensors to predict what your battery is expected to do over the forecast_hours duration of the plan with no changes made by Predbat. This is considered to be the 'baseline' plan: NB: All of Predbat's forecasts are from midnight today to the forecast_hours duration (set in apps.yaml) into the future and shouldn't be confused with 'today' figures. e.g. predbat.pv_energy is the actual PV energy from midnight today, and for the predicted forecast_hours (typically 48) ahead so will be much larger than sensor.solcast_pv_forecast_today which is today's Solcast PV forecast. predbat.battery_cycle - Predicted baseline battery cycle in kWh (total kWh processed) with attributes of the prediction every 5 minutes to end of plan predbat.battery_hours_left - The number of hours left until your home battery is predicted to run out under the baseline plan (stops at the maximum prediction time) predbat.battery_power - The sensor is always zero; attributes contain the predicted remaining battery power under the baseline plan, in 5 minute slots, for charting predbat.car_soc - The expected charge level of your car at the end of the baseline plan. Can also be charted predbat.charge_end - Predicted end time of the next forced battery charging under the baseline plan predbat.charge_limit - Predicted baseline battery charge limit for the next charge in percent with attributes of all future battery charging times & limits predbat.charge_limit_kw - Predicted baseline battery charge limit for the next charge in kWh with attributes of future charging times & limits predbat.charge_start - Predicted start time of the next forced battery charging under the baseline plan predbat.duration - The duration of the prediction maximum in hours predbat.export_energy - Total kWh of predicted exports under the baseline plan with attributes of the predicted export kWh and their time slots predbat.grid_power - The sensor is always zero; attributes contain the predicted Grid power (positive or negative for import or export) in kW per 5 minute slots to the end of the baseline plan for charting predbat.import_energy - Total kWh of predicted imports under baseline plan with attributes of the predicted import kWh and their time slots predbat.import_energy_battery - Total kWh of predicted import energy used to charge the home battery under the baseline plan predbat.import_energy_house - Predicted import energy used by the home under the baseline plan that is not provided by your home battery (e.g. due to a flat battery or load is above maximum discharge rate) predbat.load_energy - Total kWh of predicted house load under the baseline plan with attributes of the predicted load kWh in 5 minute slots to the end of the plan predbat.load_power - Total kW of predicted house load power to the end of the baseline plan, with attributes of the average instantaneous house load power in kW in 5 minute slots to the end of the plan predbat.metric - Total predicted cost for the baseline plan, taking account of predicted solar generation, house load, import and export rates. Attributes contain data for charting the cost prediction in 5 minute slots to the end of the plan predbat.pv_energy - Predicted PV energy in kWh under the baseline plan with attributes of the predicted PV generation in kWh with time slots predbat.pv_power - Predicted PV power now with attributes that contain the predicted PV power in kW per 5 minute slots to the end of the baseline plan for charting predbat.soc_kw - Predicted state of charge (in kWh) at the end of the baseline plan prediction, not very useful in itself, but the attributes hold prediction data in 5 minute intervals which can be charted with Apex Charts (or similar) predbat.soc_min_kwh - Predicted lowest battery SoC value in kWh under the baseline plan with attribute of the date/time that that lowest SoC occurs at","title":"Baseline data"},{"location":"output-data/#pv-10-baseline-data","text":"Predbat outputs the following baseline results under the PV 10% scenario for the forecast_hours duration of the plan, these are known as the 'base10' predictions: predbat.base10_export_energy- Total predicted export energy in kWh for the PV 10% scenario, with attributes of the predicted export kWh and their time slots predbat.base10_import_energy- Total predicted import energy in kWh for the PV 10% scenario, with attributes of the predicted import kWh and their time slots predbat.base10_load_energy - Total predicted house load in kWh for the PV 10% scenario predbat.base10_metric - Total predicted cost for the PV 10% scenario, with attributes of the cost prediction in 5 minute slots to the end of the plan for charting predbat.base10_pv_energy - Predicted PV 10% energy in kWh with attributes of the predicted PV generation in kWh with time slots predbat.soc_kw_base10 - Predicted final state of charge (in kWh) of the battery, with attributes of the predicted SoC in 5 minute time slots to the end of the plan under the PV 10% scenario, for charting","title":"PV 10% Baseline data"},{"location":"output-data/#best-prediction-data","text":"Predbat outputs the following 'best' entities from the forecast (for the forecast_hours duration) based on the lowest cost consumption plan. The 'best' plan in Predbat parlance is simply Predbat's lowest cost predicted plan: predbat.battery_cycle_best - Predicted best battery cycle in kWh (total kWh processed) with attributes of the prediction every 5 minutes to end of plan predbat.battery_power_best - Predicted remaining battery power in kW with attributes of the future prediction in 5 minute slots predbat.best_battery_hours_left - Predicted total number of hours of battery capacity left under the best plan predbat.best_charge_end - Predicted end time of the next forced battery charging under the best plan predbat.best_charge_limit - Predicted best battery charge limit for the next charge in percent with attributes of all future battery charging times & limits predbat.best_charge_limit_kw - Predicted best battery charge limit for the next charge in kWh with attributes of future charging times & limits predbat.best_charge_start - Predicted start time of the next forced battery charging under the best plan predbat.best_export_end - Predicted end time of the next forced battery export under the best plan predbat.best_export_limit - Predicted best battery export limit in percent (will be 0% when discharging or 100% when not) with attributes of all future battery exports (kWh and time slots) predbat.best_export_limit_kw - Predicted best battery export limit in kWh predbat.best_export_start - Predicted start time of the next forced battery export under the best plan predbat.best_export_energy - Total kWh of predicted exports under the best plan, with attributes of the predicted export kWh and their time slots predbat.best_import_energy - Total kWh of predicted imports under best plan, with attributes of the predicted import kWh and their time slots predbat.best_import_energy_battery - Total kWh of predicted import energy to charge the home battery under the best plan predbat.best_import_energy_house - Total kWh of predicted import energy used directly by the house under the best plan (e.g. due to a flat battery or the house load is greater than the max discharge rate) predbat.best_load_energy - Total kWh of predicted house load energy in kWh under the best plan with attributes of the predicted load kWh in 5 minute slots to the end of the plan predbat.best_metric - Total predicted cost for the best plan, taking account of predicted solar generation, house load, import and export rates. Attributes contain data for charting the cost prediction in 5 minute slots to the end of the plan predbat.best_pv_energy - Predicted PV energy in kWh under the best plan with attributes of the predicted PV generation in kWh with time slots predbat.best_soc_min_kwh - Predicted lowest battery SoC value in kWh under the best plan with attribute of the date/time that that lowest SoC occurs at predbat.car_soc_best - See Car data below predbat.carbon_best - See Carbon data below predbat.grid_power_best - The sensor is always zero; attributes contain the predicted Grid power (positive or negative for import or export), in kW per 5 minute slots to the end of the best plan for charting predbat.iboost_best - See iBoost data below predbat.load_power_best - Total kW of predicted house load power to the end the best plan, with attributes of the average instantaneous house load power in kW in 5 minute slots to the end of the plan predbat.pv_power_best - The sensor is always zero; attributes contain the predicted PV power in kW per 5 minute slots to the end of the best plan for charting predbat.soc_kw_best - Predicted final state of charge (in kWh) with attributes of the predicted SoC in 5 minute time slots to the end of the best plan, for charting predbat.soc_kw_best_h1 - Single data point for the predicted state of charge in 1 hours time (useful for calibration charts, predicted vs actual) predbat.soc_kw_best_h8 - Single data point for the predicted state of charge in 8 hours time (useful for calibration charts, predicted vs actual) predbat.soc_kw_best_h12 - Single data point for the predicted state of charge in 12 hours time (useful for calibration charts, predicted vs actual)","title":"Best Prediction data"},{"location":"output-data/#best-pv-10-prediction-data","text":"Predbat outputs the following best results under the PV 10% scenario for the forecast_hours duration, these are known as the 'best10' prediction: predbat.best10_metric - Predicted best cost in pence using the PV 10% solar forecast predbat.best10_export_energy- Predicted best export energy in kWh for PV 10% predbat.best10_import_energy- Predicted best import energy in kWH for PV 10% predbat.best10_load_energy - Predicted best load energy in kWh for PV 10% predbat.best10_pv_energy - Predicted best PV 10% energy in kWh predbat.soc_kw_best10 - As soc_kw_best but using the PV 10%, also holds minute by minute data (in attributes) to be charted","title":"Best PV 10% Prediction data"},{"location":"output-data/#in-day-load-adjustment-data","text":"The following sensors are used in the in-day adjustment chart - see creating the Predbat charts and in day load adjustment : predbat.load_energy_actual - Total kWh of house load to end of plan, energy up to 'now' taken from today's actual energy, energy after 'now' from Predbat's prediction. Attributes of this actual/predicted energy in 5 minute slots from midnight today to the end of the plan for charting predbat.load_energy_adjusted - Total kWh of predicted house load to end of plan, adjusted based on variance of today's actual load to the predicted load (based on historical data), dampened according to input_number.predbat_metric_inday_adjust_damping. Attributes contain the 5 minute slot forecasts to end of plan for charting predbat.load_energy_predicted - Total predicted kWh of house load to end of plan, attributes of predicted load in 5 minute slots from midnight today to the end of the plan for charting predbat.load_inday_adjustment - the % in-day adjustment factor used to adjust Predbat's predicted load by actual load today","title":"In-day load adjustment data"},{"location":"output-data/#today-energy-data","text":"The following sensors output by Predbat give the 'today' energy readings. They mirror input sensors fed into Predbat in apps.yaml and are used in the data prediction chart - see creating the Predbat charts : predbat.export_energy_h0 - Mirrors the export_today sensor configured in apps.yaml and gives today's total kWh of export energy predbat.import_energy_h0 - Mirrors the import_today sensor configured in apps.yaml and gives today's total kWh of import energy predbat.load_energy_h0 - Mirrors the load_today sensor configured in apps.yaml and gives today's total kWh of house load energy predbat.pv_energy_h0 - Mirrors the pv_today sensor configured in apps.yaml and gives today's total kWh of generated PV energy predbat.soc_kw_h0 - Mirrors the soc_kwh sensor configured in apps.yaml and gives today's total kWh of battery state of charge (SoC). Note that if you have configured battery scaling then soc_kw_h0 will have been scaled by the configured scaling factor","title":"'Today' energy data"},{"location":"output-data/#battery-status","text":"The following sensors are set based upon what Predbat is currently controlling the battery to do: binary_sensor.predbat_charging - Set to 'on' when Predbat is force charging the battery (from solar, or if that is insufficient, from grid import), or 'off' otherwise binary_sensor.predbat_exporting - Set to 'on' when Predbat is force discharging the battery for export income, 'off' otherwise. These are useful for automations if for example you want to turn off car charging when the battery is being exported.","title":"Battery status"},{"location":"output-data/#export-trigger","text":"binary_sensor.predbat_export_trigger_NAME - custom binary sensors that are set to On by Predbat when more than a specified amount of energy is being exported - see Triggers in apps.yaml","title":"Export trigger"},{"location":"output-data/#prediction-window","text":"predbat.record - The sensor is always zero; attributes contain the time window for the current predicted plan","title":"Prediction window"},{"location":"output-data/#energy-rate-data","text":"","title":"Energy rate data"},{"location":"output-data/#low-rate-import-entities","text":"predbat.low_rate_cost - The lowest import rate cost in Pence predbat.low_rate_duration - The time duration in minutes of the next low rate slot predbat.low_rate_end - End time of the next low import rate slot predbat.low_rate_start - Start time of the next low import rate slot predbat.low_rate_cost_2, predbat.low_rate_end_2, predbat.low_rate_start_2 - The cost and times of the following low import rate slot binary_sensor.predbat_low_rate_slot - A sensor that is 'on' to indicate when there is a low energy rate import slot active, 'off' otherwise","title":"Low rate import entities"},{"location":"output-data/#high-rate-export-entities","text":"predbat.high_rate_export_cost - The highest export rate cost in Pence predbat.high_rate_export_duration - The time duration in minutes of the next high rate slot predbat.high_rate_export_end - End time of the next high export rate slot predbat.high_rate_export_start - Start time of the next high export rate slot predbat.high_rate_export_cost_2, predbat.high_rate_export_end_2, predbat.high_rate_export_start_2 - The cost and times of the following high export rate slot binary_sensor.predbat_high_rate_export_slot - A sensor that is 'on' to indicate when there is a high export rate slot active, 'off' otherwise","title":"High rate export entities"},{"location":"output-data/#other-rate-entities","text":"predbat.rates - The current energy import rate in Pence with attributes of yesterday's, todays and tomorrow's rates which can be charted predbat.rates_export - The current energy export rates in Pence (also can be charted) predbat.rates_gas - The current gas rates in Pence (also can be charted) predbat.cost_today - The total cost of energy so far today (since midnight) with attributes of the total cost every 5 minutes since midnight today predbat.cost_today_export - Same as predbat.cost_today, but for all export income since midnight today predbat.cost_today_import - Same as predbat.cost_today, but for all import costs since midnight today predbat.cost_hour - The total cost of energy averaged over the last hour predbat.cost_today_export - Same as predbat.cost_hour, but for export predbat.cost_today_import - Same as predbat.cost_hour, but for import predbat.ppkwh_today - The cost in pence/kWh of the house load today accounting for the change in battery level predbat.ppkwh_hour - The cost in pence/kWh of the house load averaged over the last hour, accounting for the change in battery level","title":"Other rate entities"},{"location":"output-data/#car-data","text":"binary_sensor.predbat_car_charging_slot - A binary sensor indicating when to charge your car (if car planning is enabled) - which can be used in an automation as described in Predbat led car charging predbat.car_charging_start - The time that car charging is planned to start at, in HH:MM:SS format predbat.car_soc_best - Predicted charge level of your car in the best plan at the end of the plan using the proposed car charging SoC% and charge window. Can also be charted predbat.cost_today_car - Current cost in pence so far today of charging the car, with attribute of the projected future car charging costs and slots predbat.cost_total_car - A running total in pence of the below cost_yesterday_car sensor, with attribute of the total in pounds predbat.cost_yesterday_car - A sensor that gives the total energy costs in pence of charging the car for yesterday (00:00-23:59 on the previous day)","title":"Car data"},{"location":"output-data/#iboost-solar-diverter-data","text":"binary_sensor.predbat_iboost_active - A binary sensor indicating when there is excess solar and the solar diverter (e.g. iBoost, Eddi or just plain immersion heater) should be active, can be used for automations to trigger the immersion heater boost input_number.predbat_iboost_today - Gives the amount of energy modelled that will be sent to the solar diverter today, increments during the day and is reset to zero at 11:30pm each night predbat.iboost_best - Predicted energy in kWh going into the iBoost solar diverter under the best plan","title":"iBoost Solar Diverter data"},{"location":"output-data/#carbon-data","text":"The following sensors output by Predbat give historic and predicted carbon data. They are used in the carbon chart - see creating the Predbat charts : predbat.carbon - Predicted Carbon energy in g at the end of the plan with attributes giving the breakdown of predicted Carbon impact by half hour time slots predbat.carbon_best - Predicted Carbon intensity in g for your home under the best plan based on grid imports, grid exports and the grid's projected carbon intensity predbat.carbon_now - A sensor that gives the current Grid Carbon intensity in g/kWh predbat.carbon_today - A sensor that tracks your home's Carbon impact today in g based on your grid import minus your grid export","title":"Carbon data"},{"location":"output-data/#energy-saving-data","text":"The following sensors output by Predbat give cost saving data that Predbat achieved, i.e. the financial benefits of using Predbat. They are used in the daily cost saving and total cost savings charts - see creating the Predbat charts : predbat.cost_yesterday - A sensor that gives the total energy costs in pence for yesterday (00:00-23:59 on the previous day) predbat.savings_total_actual - A running total in pence of the above cost_yesterday sensor, with attribute of the total in pounds predbat.savings_total_predbat - A running total in pence of the below savings_yesterday_predbat sensor, with attribute of the total in pounds predbat.savings_total_pvbat - A running total of the below savings_yesterday_pvbat sensor, with attribute of the total in pounds predbat.savings_total_soc - A running total of what the final SoC in kWh would have been at the end of each day if you were not using Predbat predbat.savings_yesterday_predbat - A sensor which tells you how much money Predbat saved you yesterday compared to not using Predbat, and only charging at the lowest import rate in the 24 hour period predbat.savings_yesterday_pvbat - A sensor which tells you how much money you saved from using Predbat vs not having a PV and battery system at all and all house load being met from grid import","title":"Energy saving data"},{"location":"output-data/#solar-forecast-data","text":"The following sensors give the forecast Solar data from Solcast. Predbat populates these sensors irrespective of whether you are using the Predbat direct Solcast or Solcast integration method to get your Solar forecast, but if you are using the Solcast integration then the Predbat sensors mirror the similarly named Solcast integration sensors so could be disabled if you so wish. sensor.predbat_pv_today - Tracks the PV forecast in kWh for today, attributes give the remaining amount today and the half hourly data sensor.predbat_pv_tomorrow - Tracks the PV forecast in kWh for tomorrow, attributes give the remaining amount today and the half hourly data sensor.predbat_pv_d2 - Similar to the above, but tracking the PV forecast for the day after tomorrow sensor.predbat_pv_d3 - PV forecast for two days after tomorrow sensor.predbat_pv_forecast_h0 - Tracks the PV 'power now' forecast in Watts, attributes give the 10% and 90% power now forecast","title":"Solar forecast data"},{"location":"output-data/#predbat-logfile","text":"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! If you are using the Predbat add-on then the logfile can easily be viewed via the 'Log' tab of the Predbat web console . To directly view the physical logfile, it can be found in one of three different directories in Home Assistant with slightly different filenames depending on how you installed Predbat: if you have used the Predbat add-on installation method , the logfile will be /addon_configs/6adb4f0d_predbat/predbat.log , if the HACS, Appdaemon add-on then Predbat installation method , it's /homeassistant/appdaemon/appdaemon.log , or if the combined AppDaemon/Predbat add-on installation method was used, it's /addon_configs/46f69597_appdaemon-predbat/predbat.log . 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 if you are not using the Predbat add-on. See editing configuration files within Home Assistant if you need to install an editor.","title":"Predbat Logfile"},{"location":"output-data/#automated-monitoring-that-predbat-and-givtcp-are-running-ok","text":"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 running the Home Assistant Companion app. To create a new automation: Settings / Automations & Scenes Create Automation / Create new Automation Three dots (top right corner) / Edit in YAML Delete the existing (template) automation code and copy/paste the supplied automation code below","title":"Automated monitoring that Predbat and GivTCP are running OK"},{"location":"output-data/#givtcp-activity-monitor","text":"This automation will raise an alert if any of the following occur: The inverter goes offline for more than 15 minutes No last_updated_time received from the inverter for more than 15 minutes Inverter temperature less than 5 degrees for more than 15 minutes (should never happen) The battery goes offline to the inverter for more than 15 minutes GivTCP add-on is not running Mosquitto broker add-on is not running Predbat/AppDaemon-predbat or AppDaemon add-on (as appropriate) is not running The script will need to be customised for your inverter id, battery id and mobile details, and can be extended for multiple inverters and batteries by duplicating the triggers and adding appropriate battery and inverter id's. alias: GivTCP activity monitor description: Alert when communications to GivTCP have ceased for 15 minutes triggers: - trigger: state entity_id: sensor.givtcp__last_updated_time to: \"null\" for: minutes: 15 variables: alert_text: No GivTCP update received from inverter restart_app: GivTCP - trigger: state entity_id: - sensor.givtcp__status from: online for: minutes: 15 variables: alert_text: No GivTCP update received from inverter restart_app: GivTCP - trigger: numeric_state entity_id: - sensor.givtcp__invertor_temperature for: minutes: 15 below: 10 variables: alert_text: No GivTCP update received from inverter restart_app: GivTCP - trigger: state entity_id: - sensor.givtcp__battery_cells to: unknown for: minutes: 15 variables: alert_text: Battery is offline to GivTCP restart_app: GivTCP - trigger: state entity_id: - binary_sensor.givtcp_running to: \"off\" for: minutes: 15 variables: alert_text: GivTCP add-on is not running restart_app: GivTCP - trigger: state entity_id: - binary_sensor.mosquitto_broker_running to: \"off\" for: minutes: 15 variables: alert_text: Mosquitto Broker add-on is not running restart_app: Mosquitto actions: - action: notify.mobile_app_ alias: Send a notification data: title: GivTCP communication issue message: | {{now().strftime('%-d %b %H:%M')}} ISSUE: {{ alert_text }} for the past 15 minutes, restarting {{ restart_app }} data: visibility: public persistent: true push: sound: name: default critical: 1 volume: 0.8 sticky: true color: red - choose: - conditions: - condition: template value_template: \"{{ restart_app == 'GivTCP' }}\" sequence: - alias: Restart GivTCP add-on action: hassio.addon_restart data: addon: 533ea71a_givtcp - conditions: - condition: template value_template: \"{{ restart_app == 'Mosquitto' }}\" sequence: - alias: Restart Mosquitto add-on action: hassio.addon_restart data: addon: core_mosquitto trace: stored_traces: 20 mode: single The last two triggers (GivTCP and Mosquitto running) trigger if any of these add-ons that Predbat is dependent upon are not running. You will need to enable a binary sensor for each add-on to be able to use these triggers in the automation: Navigate to Settings / Devices and Services / Devices and search for 'GivTCP' Click on the GivTCP add-on, and under 'Sensors', click 'XX entities not shown' Click the 'Running' sensor, then the cogwheel, and Enable the sensor Repeat these steps for the 'Mosquitto' add-on. As an extension to the above, if you don't want the automation to restart the failing add-on and instead just send an alert that there is a problem, delete the 'choose' code above. Restarting GivTCP does however lose the current GivTCP log in Home Assistant. NB: If you are using GivTCP v2 rather than v3, replace the '533ea71a_givtcp' with 'a6a2857d_givtcp'.","title":"GivTCP activity monitor"},{"location":"output-data/#predbat-error-monitor","text":"This automation will raise an alert if Predbat's status turns to Error for more than 5 minutes. In normal operation Predbat will automatically run and update its forecast every 5 minutes. If the automation detects that Predbat has not done this for 20 minutes, then an alert will be raised and the automation will restart the Predbat add-on to try to resolve a 'hung Predbat' issue. In the same way for the GivTCP and Mosquitto add-on's above, the last trigger requires you to enable a binary sensor that detects that the Predbat/AppDaemon add-on is running. Follow the same steps to enable the binary sensor for either the 'Predbat', 'AppDaemon' or 'AppDaemon-predbat' add-on depending on which Predbat installation method you followed. The script will need to be customised for your mobile details. alias: Predbat error monitor description: Alert when Predbat has raised an exception trace: stored_traces: 20 triggers: - trigger: template alias: Predbat status contains 'Error' for 5 minutes value_template: \"{{ 'Error' in states('predbat.status') }}\" for: minutes: 5 variables: alert_text: >- predbat status is {{ states('predbat.status') }}, error={{ state_attr('predbat.status', 'error') }} - trigger: state alias: Predbat is in error status for 5 minutes entity_id: predbat.status attribute: error to: \"true\" for: minutes: 5 variables: alert_text: >- predbat status is {{ states('predbat.status') }}, error={{ state_attr('predbat.status', 'error') }} - trigger: state alias: Predbat status.last_updated has not changed for 20 minutes entity_id: predbat.status attribute: last_updated for: minutes: 20 variables: alert_text: >- Predbat stalled? Restarting. last_updated=' {{ state_attr('predbat.status','last_updated')|as_timestamp|timestamp_custom('%a %H:%M') }}', unchanged for 20 mins; Status='{{ states('predbat.status') }}' restart_predbat: \"Y\" - trigger: state entity_id: binary_sensor.predbat_running to: \"off\" for: minutes: 15 variables: alert_text: Predbat add-on is not running restart_predbat: \"Y\" actions: - action: notify.mobile_app_ alias: Send alert message data: title: Predbat status issue message: | {{now().strftime('%-d %b %H:%M')}} ISSUE: {{ alert_text }} data: visibility: public persistent: true push: sound: name: default critical: 1 volume: 0.8 sticky: true color: red - if: - condition: template value_template: \"{{ restart_predbat == 'Y' }}\" then: - action: hassio.addon_restart data: addon: 6adb4f0d_predbat alias: Restart Predbat add-on mode: single NB: If you are using AppDaemon rather than the Predbat add-on, replace '6adb4f0d_predbat' with 'a0d7b954_appdaemon' and change 'binary_sensor.predbat_running' to 'binary_sensor.appdaemon_running'. An error alert looks like this:","title":"Predbat error monitor"},{"location":"predbat-plan-card/","text":"Predbat Plan card Predbat can create its own plan card which can be added to your Home Assistant dashboard. At a glance the Predbat plan shows you the plan going forward of home demand, EV charging, iBoost and for your battery, and any actions that Predbat plans to take. Displaying the Predbat plan Firstly install the HTML template card in HACS: In HACS, click on Frontend Click the blue Explore and download repositories button and type 'HTML' Click on 'HTML Jinja2 Template card', then click the blue 'Download', then 'Download' again to install it When prompted to 'reload your browser', click 'Reload' NB: Do not install the very similarly named 'Lovelace Html card', it won't work! You must install 'HTML Jinja2 Template card'. Next, on a Home Assistant dashboard, click the blue 'Add card', scroll down the list of cards to the bottom and click 'Manual', delete the template card configuration and copy/paste the following to display the Predbat plan: type: custom:html-template-card title: Predbat plan ignore_line_breaks: true content: | {{ state_attr('predbat.plan_html', 'html') }} You should see something like this: If you get an error 'Custom element doesn't exist: html-template-card' then you've not installed the Jinja2 template card correctly from HACS. Understanding the Predbat plan For every half hour period (slot) that Predbat has planned for (the forecast_hours setting in apps.yaml ), the Predbat plan shows: The import rate in pence for that slot The export rate in pence for that slot What 'status' Predbat will be in (e.g. Charging, Discharging) Any limit applied (e.g. charging to 70%) Forecast Solar generation (from Solcast) Forecast house load (from your historical load data) Planned car charging (if car charging is configured in Predbat) Planned iBoost immersion heating (if iBoost is configured) What the battery SoC will be at the start of the 30 minute slot The forecast cost for the half hour slot A running total cost Forecast CO2 Carbon intensity and Carbon footprint emitted by the grid's electricity generation, and the direction of travel over the slot (if carbon forecasting is enabled) Rate symbols (import and export): ? \u2146 - Rate that has been modified based on input_number.predbat_metric_future_rate_offset_import or input_number.predbat_metric_future_rate_offset_export ? \u2696 - Rate that has been estimated using future rate estimation data (e.g. Nordpool) = - Rate that has been overridden by the users apps.yaml \u00b1 - Rate that has been adjusted with a rate offset in the users apps.yaml $ - Rate that has been adjusted for an Octopus Saving session ? - Rate that has not yet been defined and the previous days data was used instead Battery SoC symbols: \u2192 - Current SoC expected to remain level \u2198 - Current SoC expected to fall \u2197 - Current SoC expected to rise Cost symbols: \u2192 - Current cost expected to remain level \u2198 - Current cost expected to fall (due to export) \u2197 - Current cost expected to rise (due to import or standing charge) Explaining each column in the Predbat plan in more detail: Time - Predbat plans your home, solar and battery load in 30 minute slots, on the :00 and :30 minutes past each hour. The Predbat slots are therefore aligned to Octopus Agile slots or rate change times on any other tariff. Import - The import rate for that time slot in pence. The rate will be coloured Blue if the price is zero pence or negative, Green if the rate is less than the import rate threshold, Red if the rate is more than 1.5 times the import rate threshold, and Yellow if the rate is between 1 and 1.5 times the import rate threshold. See the Predbat customisation guide for explanation of the import rate threshold (and over-riding it), but in essence Predbat will consider blue and green-coloured slots as preferred candidates for importing, yellow and red (higher rates) will not. If battery charging is planned by Predbat for a particular slot, the import rate for that slot will be highlighted in bold text. Export - Similarly, the export rate for that time slot in pence. The rate will be coloured White if the price is less than the export rate threshold, Yellow if it is more than the export rate threshold, and pale Red if the rate is more than 1.5 times the export rate threshold. So in essence, Yellow and Red coloured export rates will be considered as priorities for exporting, White will not. If battery discharging is planned by Predbat for a particular slot, the export rate for that slot will be highlighted in bold text. State - Predbat's status controls whether the battery is charging, discharging to support house load (Demand mode), 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 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, Dark Grey for Freeze Discharging, 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_export_oncharge is set to True, then within a 30 minute slot (and depending on import and export rates) Predbat could potentially plan for there to be both charging and discharging activity - if Predbat plans this, state will show as both Charging and Exporting in the same slot. Limit % - Alongside any battery activity (charging, discharging, etc) there will be a SoC limit. This limit is what the SoC is planned to be at the end of the 30 minute time slot. e.g. 'Charge\u2197 70%' is charge to 70% SoC, and 'Exp\u2198 4%' is force exporting the battery to the 4% reserve level. PV kWh - The predicted solar forecast for the half hour slot, estimated from the Solcast Forecast . If the PV forecast is above 0.2kWh for the slot it will be coloured Melon Red with a little sun symbol, above 0.1kWh it will be Yellow with a sun symbol, otherwise it will be Silver Grey. Load kWh - The predicted house load for the half hour slot, estimated as a weighted average of the number of days_previous Historical data from your inverter or other house load sensor. If the load forecast is 0.5kWh or above for the slot it will be coloured Orangey-Red, from 0.25kWh to 0.5 it will be coloured Yellow, above 0 to 0.25 it will be Light Green, and if zero, it will be coloured White. Car kWh - The total predicted car charging for the half hour slot. This column will only be shown if num_cars in apps.yaml is 1 or more. If the car is planned to be charged in that slot then the kWh will be coloured Yellow, otherwise it will be White. iBoost kWh - The energy planned for solar diverter immersion heating such as iBoost or MyEnergi Eddi. This column will only be shown if switch.predbat_iboost_enable is set to True. If the solar diverter is planned to be on in that slot then the kWh will be coloured Yellow, otherwise it will be White. SoC % - The estimate of battery State of Charge percentage at the start of the time slot together with an arrow pointing up, to the right or downwards to indicate whether the battery SoC is increasing, remaining constant or decreasing during the time slot. The 'SoC %' can be read in conjunction with the 'Limit %'; the SoC column gives the estimated SoC at the beginning of the slot, the Limit column the estimated SoC at the end of the slot. If the SoC is 50% or greater it will be coloured Green, 20% or greater, Yellow, and if less than 20%, Orangey-Red. Cost - The estimated cost in pence for the time slot together with an arrow indicating whether the total cost today is increasing, staying flat or decreasing. If the cost for the slot is 10p or more it will be coloured Orangey-Red, \u00bdp or more it will be coloured Yellow, -\u00bdp or less it will be coloured Green, otherwise it will be coloured White. Total - The total cumulative cost so far for 'today' at the start of the slot, including the standing charge. At midnight tonight this cumulative cost will be reset to the daily standing charge (or zero if metric_standing_charge wasn't set in apps.yaml ). Due to the way Predbat works, total cost is always reported (in Predbat output entities, this HTML plan, in the Apex charts , etc) as starting from midnight today and adding on from there. Looking at the sample Predbat plan above as an example, the plan starts at 10:00 with total cost today already being \u00a33.13. The house load is then fully met through the day and evening by the battery (with some PV top-up charging) so total cost remains constant at \u00a33.13. In the 22:30 and 23:00 slots there is a little grid import, and then at 23:30 there's grid import and the battery starts to be charged. As you can see the Total continues to increase in the plan past midnight with each Total being the Total from the preceding slot plus the Cost estimate from the preceding slot - reminder that Total gives the running total at the start of the slot. Total cost is always coloured White. CO2 (g/kWh) - The estimated CO2 Carbon intensity emitted by the grid when generating electricity at the start of the 30 minute slot. This column will only be shown if switch.predbat_carbon_enable is set to True. The CO2 value will be coloured according to how high the carbon footprint intensity is: greater or equal to 450g/kWh it will be deep red; greater or equal to 290, dark red; then golden orange from 200 upwards; yellow from 120; green from 40 and light green if less than 40. CO2 (kg) - The estimated CO2 Carbon footprint that the grid will emit generating electricity at the start of the slot and the direction of travel over the slot. This column will only be shown if switch.predbat_carbon_enable is set to True. The carbon amount in kg will be coloured according to the direction of travel over the slot; if the carbon value is rising by 10kg or more it will be orange with an upwards arrow; if falling by 10kg or more it will green with a downwards arrow, and in the middle, white with a horizontal arrow. Debug mode for Predbat Plan If Predbat expert mode is turned on then a number of additional controls and switches are made available in Home Assistant. If switch.predbat_plan_debug is then turned on then the Predbat plan shows additional 'debugging' information for the import rate, export rate, load and PV columns. The Predbat plan will now look like this with plan_debug turned on: Import and Export rate will now show the actual rate (according to how you have setup the energy rates ) and also in brackets the effective import or export rate. The effective rate takes into account battery and inverter energy losses for charging and discharging and converting from DC to AC and vice-versa. Note that the Cost and Total columns are always based upon the actual Import and Export rate. Using the above debug plan as an example: At 22:30 the battery is being charged. The actual import rate is 14.07p, but after conversion losses to store the grid AC into the DC battery, the energy being put into the battery has effectively cost 14.81p - for every 1kWh of AC grid import you don't get 1kWh of DC stored in the battery, so 1kWh of battery charge has effectively cost slightly more than the import rate. At 00:30 the battery is being force exported and excess energy (above the estimated house load of 0.47kWh) will be exported. The actual export rate is 18.22p, but after losses converting the stored DC battery charge into AC to supply the home and export it, the energy being exported has effectively only earned 17.31p - it will take slightly more than 1kWh of stored DC battery charge to get 1kWh of AC to use or export so each discharged and exported kWh actually earns slightly less. Putting these together, at 00:00, the effective import rate (after losses) is 13.93p, the effective export rate is 17.31p, so even though battery and inverter conversion losses have been incurred, there is still a 3.38p profit per kWh and Predbat plans to charge and then exports the battery in the same slot to generate that profit. With debug mode turned on, the Load column shows the predicted load in kWh for the half hour slot and in brackets the modelled load variance value using the load variance model . The PV column in debug mode changes shows the predicted PV generation in kWh for the half hour slot and the Solcast 10% forecast in brackets. Note that Predbat's forecasted PV generation already contains a input_number.predbat_pv_metric10_weight weighted value of the Solcast 10% forecast . Note that the values in brackets in the load and PV columns are each only shown if they are non-zero. The debug mode on the Predbat plan can be quite useful to understand from the import and export rates after conversion losses , why Predbat plans to charge or force export the battery. There's a further explanation of the Predbat forecast and plan in the FAQ's. Customising and Reformatting the Predbat Plan An additional independent front-end Home Assistant component the 'Predbat Table Card' is available on HACS that gives a number of additional customisation and configuration options to tailor how the Predbat plan looks: Change the sequence of columns and which columns are shown in the plan Restyle the columns, or retain the Predbat original colour scheme Apply custom light/dark themes See the Predbat Table Card repository for more details.","title":"Predbat Plan card"},{"location":"predbat-plan-card/#predbat-plan-card","text":"Predbat can create its own plan card which can be added to your Home Assistant dashboard. At a glance the Predbat plan shows you the plan going forward of home demand, EV charging, iBoost and for your battery, and any actions that Predbat plans to take.","title":"Predbat Plan card"},{"location":"predbat-plan-card/#displaying-the-predbat-plan","text":"Firstly install the HTML template card in HACS: In HACS, click on Frontend Click the blue Explore and download repositories button and type 'HTML' Click on 'HTML Jinja2 Template card', then click the blue 'Download', then 'Download' again to install it When prompted to 'reload your browser', click 'Reload' NB: Do not install the very similarly named 'Lovelace Html card', it won't work! You must install 'HTML Jinja2 Template card'. Next, on a Home Assistant dashboard, click the blue 'Add card', scroll down the list of cards to the bottom and click 'Manual', delete the template card configuration and copy/paste the following to display the Predbat plan: type: custom:html-template-card title: Predbat plan ignore_line_breaks: true content: | {{ state_attr('predbat.plan_html', 'html') }} You should see something like this: If you get an error 'Custom element doesn't exist: html-template-card' then you've not installed the Jinja2 template card correctly from HACS.","title":"Displaying the Predbat plan"},{"location":"predbat-plan-card/#understanding-the-predbat-plan","text":"For every half hour period (slot) that Predbat has planned for (the forecast_hours setting in apps.yaml ), the Predbat plan shows: The import rate in pence for that slot The export rate in pence for that slot What 'status' Predbat will be in (e.g. Charging, Discharging) Any limit applied (e.g. charging to 70%) Forecast Solar generation (from Solcast) Forecast house load (from your historical load data) Planned car charging (if car charging is configured in Predbat) Planned iBoost immersion heating (if iBoost is configured) What the battery SoC will be at the start of the 30 minute slot The forecast cost for the half hour slot A running total cost Forecast CO2 Carbon intensity and Carbon footprint emitted by the grid's electricity generation, and the direction of travel over the slot (if carbon forecasting is enabled) Rate symbols (import and export): ? \u2146 - Rate that has been modified based on input_number.predbat_metric_future_rate_offset_import or input_number.predbat_metric_future_rate_offset_export ? \u2696 - Rate that has been estimated using future rate estimation data (e.g. Nordpool) = - Rate that has been overridden by the users apps.yaml \u00b1 - Rate that has been adjusted with a rate offset in the users apps.yaml $ - Rate that has been adjusted for an Octopus Saving session ? - Rate that has not yet been defined and the previous days data was used instead Battery SoC symbols: \u2192 - Current SoC expected to remain level \u2198 - Current SoC expected to fall \u2197 - Current SoC expected to rise Cost symbols: \u2192 - Current cost expected to remain level \u2198 - Current cost expected to fall (due to export) \u2197 - Current cost expected to rise (due to import or standing charge) Explaining each column in the Predbat plan in more detail: Time - Predbat plans your home, solar and battery load in 30 minute slots, on the :00 and :30 minutes past each hour. The Predbat slots are therefore aligned to Octopus Agile slots or rate change times on any other tariff. Import - The import rate for that time slot in pence. The rate will be coloured Blue if the price is zero pence or negative, Green if the rate is less than the import rate threshold, Red if the rate is more than 1.5 times the import rate threshold, and Yellow if the rate is between 1 and 1.5 times the import rate threshold. See the Predbat customisation guide for explanation of the import rate threshold (and over-riding it), but in essence Predbat will consider blue and green-coloured slots as preferred candidates for importing, yellow and red (higher rates) will not. If battery charging is planned by Predbat for a particular slot, the import rate for that slot will be highlighted in bold text. Export - Similarly, the export rate for that time slot in pence. The rate will be coloured White if the price is less than the export rate threshold, Yellow if it is more than the export rate threshold, and pale Red if the rate is more than 1.5 times the export rate threshold. So in essence, Yellow and Red coloured export rates will be considered as priorities for exporting, White will not. If battery discharging is planned by Predbat for a particular slot, the export rate for that slot will be highlighted in bold text. State - Predbat's status controls whether the battery is charging, discharging to support house load (Demand mode), 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 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, Dark Grey for Freeze Discharging, 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_export_oncharge is set to True, then within a 30 minute slot (and depending on import and export rates) Predbat could potentially plan for there to be both charging and discharging activity - if Predbat plans this, state will show as both Charging and Exporting in the same slot. Limit % - Alongside any battery activity (charging, discharging, etc) there will be a SoC limit. This limit is what the SoC is planned to be at the end of the 30 minute time slot. e.g. 'Charge\u2197 70%' is charge to 70% SoC, and 'Exp\u2198 4%' is force exporting the battery to the 4% reserve level. PV kWh - The predicted solar forecast for the half hour slot, estimated from the Solcast Forecast . If the PV forecast is above 0.2kWh for the slot it will be coloured Melon Red with a little sun symbol, above 0.1kWh it will be Yellow with a sun symbol, otherwise it will be Silver Grey. Load kWh - The predicted house load for the half hour slot, estimated as a weighted average of the number of days_previous Historical data from your inverter or other house load sensor. If the load forecast is 0.5kWh or above for the slot it will be coloured Orangey-Red, from 0.25kWh to 0.5 it will be coloured Yellow, above 0 to 0.25 it will be Light Green, and if zero, it will be coloured White. Car kWh - The total predicted car charging for the half hour slot. This column will only be shown if num_cars in apps.yaml is 1 or more. If the car is planned to be charged in that slot then the kWh will be coloured Yellow, otherwise it will be White. iBoost kWh - The energy planned for solar diverter immersion heating such as iBoost or MyEnergi Eddi. This column will only be shown if switch.predbat_iboost_enable is set to True. If the solar diverter is planned to be on in that slot then the kWh will be coloured Yellow, otherwise it will be White. SoC % - The estimate of battery State of Charge percentage at the start of the time slot together with an arrow pointing up, to the right or downwards to indicate whether the battery SoC is increasing, remaining constant or decreasing during the time slot. The 'SoC %' can be read in conjunction with the 'Limit %'; the SoC column gives the estimated SoC at the beginning of the slot, the Limit column the estimated SoC at the end of the slot. If the SoC is 50% or greater it will be coloured Green, 20% or greater, Yellow, and if less than 20%, Orangey-Red. Cost - The estimated cost in pence for the time slot together with an arrow indicating whether the total cost today is increasing, staying flat or decreasing. If the cost for the slot is 10p or more it will be coloured Orangey-Red, \u00bdp or more it will be coloured Yellow, -\u00bdp or less it will be coloured Green, otherwise it will be coloured White. Total - The total cumulative cost so far for 'today' at the start of the slot, including the standing charge. At midnight tonight this cumulative cost will be reset to the daily standing charge (or zero if metric_standing_charge wasn't set in apps.yaml ). Due to the way Predbat works, total cost is always reported (in Predbat output entities, this HTML plan, in the Apex charts , etc) as starting from midnight today and adding on from there. Looking at the sample Predbat plan above as an example, the plan starts at 10:00 with total cost today already being \u00a33.13. The house load is then fully met through the day and evening by the battery (with some PV top-up charging) so total cost remains constant at \u00a33.13. In the 22:30 and 23:00 slots there is a little grid import, and then at 23:30 there's grid import and the battery starts to be charged. As you can see the Total continues to increase in the plan past midnight with each Total being the Total from the preceding slot plus the Cost estimate from the preceding slot - reminder that Total gives the running total at the start of the slot. Total cost is always coloured White. CO2 (g/kWh) - The estimated CO2 Carbon intensity emitted by the grid when generating electricity at the start of the 30 minute slot. This column will only be shown if switch.predbat_carbon_enable is set to True. The CO2 value will be coloured according to how high the carbon footprint intensity is: greater or equal to 450g/kWh it will be deep red; greater or equal to 290, dark red; then golden orange from 200 upwards; yellow from 120; green from 40 and light green if less than 40. CO2 (kg) - The estimated CO2 Carbon footprint that the grid will emit generating electricity at the start of the slot and the direction of travel over the slot. This column will only be shown if switch.predbat_carbon_enable is set to True. The carbon amount in kg will be coloured according to the direction of travel over the slot; if the carbon value is rising by 10kg or more it will be orange with an upwards arrow; if falling by 10kg or more it will green with a downwards arrow, and in the middle, white with a horizontal arrow.","title":"Understanding the Predbat plan"},{"location":"predbat-plan-card/#debug-mode-for-predbat-plan","text":"If Predbat expert mode is turned on then a number of additional controls and switches are made available in Home Assistant. If switch.predbat_plan_debug is then turned on then the Predbat plan shows additional 'debugging' information for the import rate, export rate, load and PV columns. The Predbat plan will now look like this with plan_debug turned on: Import and Export rate will now show the actual rate (according to how you have setup the energy rates ) and also in brackets the effective import or export rate. The effective rate takes into account battery and inverter energy losses for charging and discharging and converting from DC to AC and vice-versa. Note that the Cost and Total columns are always based upon the actual Import and Export rate. Using the above debug plan as an example: At 22:30 the battery is being charged. The actual import rate is 14.07p, but after conversion losses to store the grid AC into the DC battery, the energy being put into the battery has effectively cost 14.81p - for every 1kWh of AC grid import you don't get 1kWh of DC stored in the battery, so 1kWh of battery charge has effectively cost slightly more than the import rate. At 00:30 the battery is being force exported and excess energy (above the estimated house load of 0.47kWh) will be exported. The actual export rate is 18.22p, but after losses converting the stored DC battery charge into AC to supply the home and export it, the energy being exported has effectively only earned 17.31p - it will take slightly more than 1kWh of stored DC battery charge to get 1kWh of AC to use or export so each discharged and exported kWh actually earns slightly less. Putting these together, at 00:00, the effective import rate (after losses) is 13.93p, the effective export rate is 17.31p, so even though battery and inverter conversion losses have been incurred, there is still a 3.38p profit per kWh and Predbat plans to charge and then exports the battery in the same slot to generate that profit. With debug mode turned on, the Load column shows the predicted load in kWh for the half hour slot and in brackets the modelled load variance value using the load variance model . The PV column in debug mode changes shows the predicted PV generation in kWh for the half hour slot and the Solcast 10% forecast in brackets. Note that Predbat's forecasted PV generation already contains a input_number.predbat_pv_metric10_weight weighted value of the Solcast 10% forecast . Note that the values in brackets in the load and PV columns are each only shown if they are non-zero. The debug mode on the Predbat plan can be quite useful to understand from the import and export rates after conversion losses , why Predbat plans to charge or force export the battery. There's a further explanation of the Predbat forecast and plan in the FAQ's.","title":"Debug mode for Predbat Plan"},{"location":"predbat-plan-card/#customising-and-reformatting-the-predbat-plan","text":"An additional independent front-end Home Assistant component the 'Predbat Table Card' is available on HACS that gives a number of additional customisation and configuration options to tailor how the Predbat plan looks: Change the sequence of columns and which columns are shown in the plan Restyle the columns, or retain the Predbat original colour scheme Apply custom light/dark themes See the Predbat Table Card repository for more details.","title":"Customising and Reformatting the Predbat Plan"},{"location":"predheat/","text":"predheat Predheat attempts to model water based central heating systems based on a boiler or a heat pump. Operation The app runs every 5 minutes and it will automatically update its prediction for the heating system for the next period, up to a maximum of 48 hours. The inputs are as follows An external temperature sensor, can be a real one or one created by an Internet service An internal temperature sensor, ideally from your home thermostat. The target temperature sensor, this is what your home thermostat is set to. A heating energy sensor in kWh (not strictly required but needed to plot historical usage and calibrate) The flow temperature setting of your heating, can be static or a sensor Your current energy rates, either from the Octopus Energy plugin or hand typed into the configuration Some data about your home that you have to figure out for yourself and calibrate The outputs are: Prediction of the internal house temperature going forward, including times when the heating will be active. Your predicted energy usage and costs. The energy usage, if electric, can also be connected into Predbat to help you project your home battery usage. Future versions will also offer Predbat to run in master mode, controlling your homes heating in the same way as a smart thermostat (e.g. Nest) Installation guide Predheat is now part of Predbat, first you will need to configure it using apps.yaml and then enable it by turning on switch.predbat_predheat_enable Openweather install See: https://www.home-assistant.io/integrations/openweathermap First create an OpenWeather account and then register for a \"One Call by Call\" subscription plan. This does need a credit/debit card but won't cost anything. You get 1000 API calls a day for free, so edit your limit in the account to 1000 to avoid ever being charged. Then add in the Home Assistant service and connect up your API key to obtain hourly weather data. Use the v3.0 API and ensure you have a 2024 version of Home Assistant. Apex Charts install Use HACS to install Apex Charts (Lovelace frontend add-on) - https://github.com/RomRider/apexcharts-card There is a template for the Predheat charts in: https://raw.githubusercontent.com/springfall2008/batpred/refs/heads/main/templates/example_chart_predbat.yaml_template Create a new Apex chart for each chart in this template and copy the YAML code into the chart. Configuration guide First you need to edit apps.yaml to configure your system. Copy the following template into The Predbat apps.yaml and edit the settings: predheat.yaml Set the mode ( mode ) to 'gas' or 'pump' depending on if you have a gas boiler or heat pump Set the external temperature sensor ( external_temperature ) either to a real sensor or create one from the open weather map by adding this sensor to your configuration.yaml file for HA: template: - sensor: - name: \"external_temperature\" unit_of_measurement: 'c' state_class: measurement state: > {{ state_attr('weather.openweathermap', 'temperature') }} Set internal_temperature to point to one or more internal temperature sensors, if you have a heating thermostat then ideally link it to this or to a sensor at least in a similar area of the house. The weather configuration points to the Open Weather Map sensor by default so should work as-is. Set the target_temperature to point to a sensor that indicates what your boiler thermostat is set to, or manually enter the temperature setting here. Set smart_thermostat to True if your thermostat starts the boiler ahead of time for the new target temperature or False for regular options. Set heating_energy To point to a sensor that indicates the energy consumed by your boiler/heat-pump in kWh. If the sensor isn't accurate then using heating_energy_scaling to adjust it to the actually energy consumed. You can also comment this line out if you don't have a sensor, but no historical cost information will be produced. Now you need to make a list of all your radiators in the house, measure them and look up their BTU output at Delta 50 and their volume in Litres. The links below maybe useful for various standard radiators: https://www.bestheating.com/milano-kent-straight-chrome-heated-towel-rail-various-sizes-91119 https://www.bestheating.com/milano-compact-type-11-single-panel-radiator-multi-sizes-available-74174 https://www.bestheating.com/milano-compact-type-22-double-panel-radiator-multi-sizes-available-74176 https://www.bestheating.com/milano-compact-type-21-double-panel-plus-radiator-multi-sizes-available-74175 Add up all the BTUs and divide by 3.41 to gain the heat output in Watts and set that in heat_output configuration option. Add up all the litres of water, add in some extra for the piping and an expansion vessel if present (e.g. 5-10 litres) and set heat_volume accordingly. Set the heat_max_power and heat_min_power to the minimum and maximum power output of your boiler/heat-pump in watts. This should be specified as the maximum output power and not the maximum input energy. E.g. a heat pump with a COP of 4 might output 7kW but could only consume 1.7kW. Set heating_cop to the nominal COP of your system. For a gas boiler use 1.0 (as the efficiency will be based on flow temperature) or for a heat pump set it to the best value which is likely around 4.0 (it will be scaled down for cold weather). Set flow_temp To the target flow temperature of your system, either via a sensor or as a fixed value. E.g. gas boilers are often set to say 60 or 70 degrees while heat pumps are much lower e.g. 30 or 40. Set flow_difference_target to be the difference in flow temperature (in vs out) where your heating system will run at full power if it is above. e.g. for gas boilers this maybe something around 40 while on a heat pump it could be much lower e.g. 10. Set volume_temp If you have a sensor on your radiators which can confirm the water temperature, this must not be near the heat pump/boiler but instead as close to the interior temperature sensor as possible. If you do not have a sensor then instead PredHeat will calculate the next temperature and store it in next_volume_temp for use in the next calculation cycle. For energy rates, they will come from the Predbat configuration, ensure you have your electric or gas rates set correctly. Note you can also change the tables for gas_efficiency , heat_pump_efficiency and delta_correction in the Predheat configuration but the defaults should be fine to get going. Now comes the tricky part, we need to calculate the heat loss for your house: What will help here is historical temperature data, find a time period in the last few weeks when your heating was turned off (for a few hours beforehand) and the house is cooling down. Measure the number of degrees the house drops by in a given time period. Divide that figure (e.g. 1.5 degrees) by the time period e.g. (3 hours) and then again divide it by the average difference between the inside and outside temperature (e.g. 19 degrees inside, 9 degrees outside, so a temperature difference of 4 degrees) = 1.5 degrees / 3 hours / 10 degrees difference = 0.05. Set that figure to heat_loss_degrees . It maybe best to compute this when it's cold out and if you have your heating turned off overnight. Note in future versions of Predheat I might make this calculation automatic. Next we need to work out the number of watts of heat loss in the house, this can be done by looking at the energy consumed when the heating comes on. Pick a period of heating, ideally from the time the temperature starts increasing for a complete hour of increase, looking at the increase in temperature in degrees, add to that static heat loss which is heat_loss_degrees (internal temp - external temp) 1 hours to get the total degrees accounted for. Now divide that by the external temperature difference again / (internal_temp - external_temp) and multiply the final figure by the energy your system consumed in Watts during that period (can be found either from your sensor or just by looking at your energy bill for the same 1 hour period). The final figure should be the number of watts your house loses per 1 degree of external temperature difference and be set to heat_loss_watts Then you can set heat_gain_static to be the static heat output of other things in your house eg. computers and people. You can figure this out by looking at how many degrees of temperature difference your house can maintain without any heating and multiply up your heat loss watts figure by this. Weather Compensation If your heat source makes use of weather compensation then add the following to the configuration to map out your heat curve. The example has a flow temp of 45C at -3C outside and 25C at 15C outside: yaml weather_compensation: -20: 45.0 -3: 45.0 15: 25.0 20: 25.0 Predheat will fill in the gaps between the points provided.","title":"predheat"},{"location":"predheat/#predheat","text":"Predheat attempts to model water based central heating systems based on a boiler or a heat pump.","title":"predheat"},{"location":"predheat/#operation","text":"The app runs every 5 minutes and it will automatically update its prediction for the heating system for the next period, up to a maximum of 48 hours. The inputs are as follows An external temperature sensor, can be a real one or one created by an Internet service An internal temperature sensor, ideally from your home thermostat. The target temperature sensor, this is what your home thermostat is set to. A heating energy sensor in kWh (not strictly required but needed to plot historical usage and calibrate) The flow temperature setting of your heating, can be static or a sensor Your current energy rates, either from the Octopus Energy plugin or hand typed into the configuration Some data about your home that you have to figure out for yourself and calibrate The outputs are: Prediction of the internal house temperature going forward, including times when the heating will be active. Your predicted energy usage and costs. The energy usage, if electric, can also be connected into Predbat to help you project your home battery usage. Future versions will also offer Predbat to run in master mode, controlling your homes heating in the same way as a smart thermostat (e.g. Nest)","title":"Operation"},{"location":"predheat/#installation-guide","text":"Predheat is now part of Predbat, first you will need to configure it using apps.yaml and then enable it by turning on switch.predbat_predheat_enable","title":"Installation guide"},{"location":"predheat/#openweather-install","text":"See: https://www.home-assistant.io/integrations/openweathermap First create an OpenWeather account and then register for a \"One Call by Call\" subscription plan. This does need a credit/debit card but won't cost anything. You get 1000 API calls a day for free, so edit your limit in the account to 1000 to avoid ever being charged. Then add in the Home Assistant service and connect up your API key to obtain hourly weather data. Use the v3.0 API and ensure you have a 2024 version of Home Assistant.","title":"Openweather install"},{"location":"predheat/#apex-charts-install","text":"Use HACS to install Apex Charts (Lovelace frontend add-on) - https://github.com/RomRider/apexcharts-card There is a template for the Predheat charts in: https://raw.githubusercontent.com/springfall2008/batpred/refs/heads/main/templates/example_chart_predbat.yaml_template Create a new Apex chart for each chart in this template and copy the YAML code into the chart.","title":"Apex Charts install"},{"location":"predheat/#configuration-guide","text":"First you need to edit apps.yaml to configure your system. Copy the following template into The Predbat apps.yaml and edit the settings: predheat.yaml Set the mode ( mode ) to 'gas' or 'pump' depending on if you have a gas boiler or heat pump Set the external temperature sensor ( external_temperature ) either to a real sensor or create one from the open weather map by adding this sensor to your configuration.yaml file for HA: template: - sensor: - name: \"external_temperature\" unit_of_measurement: 'c' state_class: measurement state: > {{ state_attr('weather.openweathermap', 'temperature') }} Set internal_temperature to point to one or more internal temperature sensors, if you have a heating thermostat then ideally link it to this or to a sensor at least in a similar area of the house. The weather configuration points to the Open Weather Map sensor by default so should work as-is. Set the target_temperature to point to a sensor that indicates what your boiler thermostat is set to, or manually enter the temperature setting here. Set smart_thermostat to True if your thermostat starts the boiler ahead of time for the new target temperature or False for regular options. Set heating_energy To point to a sensor that indicates the energy consumed by your boiler/heat-pump in kWh. If the sensor isn't accurate then using heating_energy_scaling to adjust it to the actually energy consumed. You can also comment this line out if you don't have a sensor, but no historical cost information will be produced. Now you need to make a list of all your radiators in the house, measure them and look up their BTU output at Delta 50 and their volume in Litres. The links below maybe useful for various standard radiators: https://www.bestheating.com/milano-kent-straight-chrome-heated-towel-rail-various-sizes-91119 https://www.bestheating.com/milano-compact-type-11-single-panel-radiator-multi-sizes-available-74174 https://www.bestheating.com/milano-compact-type-22-double-panel-radiator-multi-sizes-available-74176 https://www.bestheating.com/milano-compact-type-21-double-panel-plus-radiator-multi-sizes-available-74175 Add up all the BTUs and divide by 3.41 to gain the heat output in Watts and set that in heat_output configuration option. Add up all the litres of water, add in some extra for the piping and an expansion vessel if present (e.g. 5-10 litres) and set heat_volume accordingly. Set the heat_max_power and heat_min_power to the minimum and maximum power output of your boiler/heat-pump in watts. This should be specified as the maximum output power and not the maximum input energy. E.g. a heat pump with a COP of 4 might output 7kW but could only consume 1.7kW. Set heating_cop to the nominal COP of your system. For a gas boiler use 1.0 (as the efficiency will be based on flow temperature) or for a heat pump set it to the best value which is likely around 4.0 (it will be scaled down for cold weather). Set flow_temp To the target flow temperature of your system, either via a sensor or as a fixed value. E.g. gas boilers are often set to say 60 or 70 degrees while heat pumps are much lower e.g. 30 or 40. Set flow_difference_target to be the difference in flow temperature (in vs out) where your heating system will run at full power if it is above. e.g. for gas boilers this maybe something around 40 while on a heat pump it could be much lower e.g. 10. Set volume_temp If you have a sensor on your radiators which can confirm the water temperature, this must not be near the heat pump/boiler but instead as close to the interior temperature sensor as possible. If you do not have a sensor then instead PredHeat will calculate the next temperature and store it in next_volume_temp for use in the next calculation cycle. For energy rates, they will come from the Predbat configuration, ensure you have your electric or gas rates set correctly. Note you can also change the tables for gas_efficiency , heat_pump_efficiency and delta_correction in the Predheat configuration but the defaults should be fine to get going. Now comes the tricky part, we need to calculate the heat loss for your house: What will help here is historical temperature data, find a time period in the last few weeks when your heating was turned off (for a few hours beforehand) and the house is cooling down. Measure the number of degrees the house drops by in a given time period. Divide that figure (e.g. 1.5 degrees) by the time period e.g. (3 hours) and then again divide it by the average difference between the inside and outside temperature (e.g. 19 degrees inside, 9 degrees outside, so a temperature difference of 4 degrees) = 1.5 degrees / 3 hours / 10 degrees difference = 0.05. Set that figure to heat_loss_degrees . It maybe best to compute this when it's cold out and if you have your heating turned off overnight. Note in future versions of Predheat I might make this calculation automatic. Next we need to work out the number of watts of heat loss in the house, this can be done by looking at the energy consumed when the heating comes on. Pick a period of heating, ideally from the time the temperature starts increasing for a complete hour of increase, looking at the increase in temperature in degrees, add to that static heat loss which is heat_loss_degrees (internal temp - external temp) 1 hours to get the total degrees accounted for. Now divide that by the external temperature difference again / (internal_temp - external_temp) and multiply the final figure by the energy your system consumed in Watts during that period (can be found either from your sensor or just by looking at your energy bill for the same 1 hour period). The final figure should be the number of watts your house loses per 1 degree of external temperature difference and be set to heat_loss_watts Then you can set heat_gain_static to be the static heat output of other things in your house eg. computers and people. You can figure this out by looking at how many degrees of temperature difference your house can maintain without any heating and multiply up your heat loss watts figure by this.","title":"Configuration guide"},{"location":"predheat/#weather-compensation","text":"If your heat source makes use of weather compensation then add the following to the configuration to map out your heat curve. The example has a flow temp of 45C at -3C outside and 25C at 15C outside: yaml weather_compensation: -20: 45.0 -3: 45.0 15: 25.0 20: 25.0 Predheat will fill in the gaps between the points provided.","title":"Weather Compensation"},{"location":"todo-list/","text":"To-do list See Github issues","title":"To-do list"},{"location":"todo-list/#to-do-list","text":"See Github issues","title":"To-do list"},{"location":"video-guides/","text":"Video Guides All the video guides are now available on my YouTube channel: Springfall2008 Basic installation Playlist of Predbat installation videos Setting Up HomeAssistant Basics, File Editor, SSH, HACS, Octopus, eWelink Installing MQTT and GivTCP on Home Assistant Predbat installation - Predbat, Solcast, Dashboard, Charts and Plans - Add On Method Configuration of apps.yaml Configuration of Predbat inside Home Assistant Understanding historical data Understanding the charts How to understand Predbat plans AppDaemon log files Documentation overview Other configuration videos Playlist of other Predbat configuration videos Multiple cars How to Tune your system for better performance Issues with Solcast free accounts and Home Assistant How to Install Predbat with the new Add On Features Playlist of Predbat feature videos Intelligent Octopus car charging Saving sessions and power ups How to update Predbat Predbat mode and read-only mode Creating a dashboard Saving and restoring settings Manual plan override Charging curve and low power charging Controlling my car based on Predbat Slot Manual plan overrides for force charge/discharge/idle GivTCP auto restart feature GivEnergy Inverter Pause, Manual Freeze Charge/Discharge Optimising for Carbon Footprint Calculating your cost savings Energy Tariffs Playlist of Tariff configuration videos Intelligent Octopus import + Agile export Intelligent Octopus import + Fixed export Octopus Agile import + Agile export Octopus Flux","title":"Video Guides"},{"location":"video-guides/#video-guides","text":"All the video guides are now available on my YouTube channel: Springfall2008","title":"Video Guides"},{"location":"video-guides/#basic-installation","text":"Playlist of Predbat installation videos Setting Up HomeAssistant Basics, File Editor, SSH, HACS, Octopus, eWelink Installing MQTT and GivTCP on Home Assistant Predbat installation - Predbat, Solcast, Dashboard, Charts and Plans - Add On Method Configuration of apps.yaml Configuration of Predbat inside Home Assistant Understanding historical data Understanding the charts How to understand Predbat plans AppDaemon log files Documentation overview","title":"Basic installation"},{"location":"video-guides/#other-configuration-videos","text":"Playlist of other Predbat configuration videos Multiple cars How to Tune your system for better performance Issues with Solcast free accounts and Home Assistant How to Install Predbat with the new Add On","title":"Other configuration videos"},{"location":"video-guides/#features","text":"Playlist of Predbat feature videos Intelligent Octopus car charging Saving sessions and power ups How to update Predbat Predbat mode and read-only mode Creating a dashboard Saving and restoring settings Manual plan override Charging curve and low power charging Controlling my car based on Predbat Slot Manual plan overrides for force charge/discharge/idle GivTCP auto restart feature GivEnergy Inverter Pause, Manual Freeze Charge/Discharge Optimising for Carbon Footprint Calculating your cost savings","title":"Features"},{"location":"video-guides/#energy-tariffs","text":"Playlist of Tariff configuration videos Intelligent Octopus import + Agile export Intelligent Octopus import + Fixed export Octopus Agile import + Agile export Octopus Flux","title":"Energy Tariffs"},{"location":"what-does-predbat-do/","text":"What does Predbat do? 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, solar generation, house load, charging activity, discharging activity, costs and import and export amounts based on 30 minute slots. 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 configurable weighting towards the more pessimistic (10%) scenario. Predbat automatically programs your inverter with the appropriate charging and discharging controls. Both Hybrid inverters and AC Coupled inverters are supported by Predbat. 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 or to use a Solar Diverter, and take into account of these loads on the house during these periods. Multiple inverter support is included but depends on all inverters running in lockstep. Terminology Basic terminology SoC - State of Charge - the % or kWh level of charge of your battery Target SoC - The target level that the battery is being charged to, e.g. we target 100% SoC means the battery is being charged to full Charge Limit - Another word for Target SoC Load - The energy your home is using to power your equipment e.g. oven, lights or electric car charging Grid - Your electric supply outside the house 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 Demand - Demand Mode is when the battery covers the house load and charges from solar, to avoid importing or exporting (some systems call this ECO Mode). Charging - When your battery is charging, in Predbat this refers to force charge (from the grid). Discharge - The opposite of charge, when the battery is discharging. Exporting - When your battery is force discharging to create an export, in Predbat this refers to force export. Export Limit - When your battery is being force exported the export limit is the % battery level where the discharge will stop if reached. PV - Solar power that is generated in your home. Can also refer to a prediction of the solar for the day, by default is the 50% scenario (most likely generation). 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 charged or discharged with AC (using an internal inverter) Micro Inverters - Small inverters that are fitted in-line with the DC solar panels and produce AC power on a per-panel basis. Typically used with an AC Coupled battery. 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 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. Loss - Refers to energy lost in your system due to heat or other factors. PV10 - A prediction of the 10% scenario for solar, this is like a worst case, occurs 1 in 10 days PV90 - A prediction of the 90% scenario for solar, this is like a best case, occurs 1 in 10 days Base - Usually refers to the expected outcome if Predbat takes no further action, meaning just what is currently configured on your inverter. Best - The best plan that Predbat could come up with, as in what it will do (assuming Read only is off) Actual - Used to refer to what has already happened in the past. Base10 - The base scenario but with the 10% outcome for Solar and Load (worst case) Charge Limit Base - This is the target charge % in the Base plan (what is currently set on your inverter) Best10 - The best plan but with the 10% outcome for Solar and Load (worst case) Charge Limit Best - This is the target charge % in the Best plan (what is currently set on your inverter) Export Limit Best - This is the target to force export to in % in the Best plan. Best SOC Keep - The amount of battery you want to keep in the plan that Predbat has made Predbat modes When you first install Predbat it will be in '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 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 the Home Assistant entity predbat.status : Demand - 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 is described as 'Eco' Mode for GivEnergy inverters but other inverters use different terminology. 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 battery is charging but the current battery level (SoC) is is frozen (held). Think of it as a charge to the current battery level. The grid or solar covers any house load. If there is a shortfall of Solar power to meet house load, the excess house load is met from grid import, but if there is excess Solar power above house load, the excess solar will 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. Exporting - 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 exporting - The battery is in demand mode, but with charging disabled. The battery or solar covers the house load. As charging is disabled, if there is excess solar generated, the current SoC level will be held and the excess solar will be exported. If there is a shortfall of generated solar power to meet house load, the battery will discharge to meet the extra load. Hold exporting - The plan was to force export but the minimum battery level was reached and thus the battery is kept in Demand mode. If the battery level again gets above the threshold it will be changed back to Export mode. Calibration - The inverter is calibrating the batteries. On GivEnergy systems the battery state of charge (SoC) level has to be calibrated by performing a full battery discharge then a full charge so that the voltage levels associated with empty and full SoC can be determined. Predbat will pause executing the plan until the calibration automatically finishes - see Calibration FAQ . Error - There is a configuration error or other problem, you should check the Predbat log file for more details.","title":"What does Predbat do?"},{"location":"what-does-predbat-do/#what-does-predbat-do","text":"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, solar generation, house load, charging activity, discharging activity, costs and import and export amounts based on 30 minute slots. 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 configurable weighting towards the more pessimistic (10%) scenario. Predbat automatically programs your inverter with the appropriate charging and discharging controls. Both Hybrid inverters and AC Coupled inverters are supported by Predbat. 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 or to use a Solar Diverter, and take into account of these loads on the house during these periods. Multiple inverter support is included but depends on all inverters running in lockstep.","title":"What does Predbat do?"},{"location":"what-does-predbat-do/#terminology","text":"","title":"Terminology"},{"location":"what-does-predbat-do/#basic-terminology","text":"SoC - State of Charge - the % or kWh level of charge of your battery Target SoC - The target level that the battery is being charged to, e.g. we target 100% SoC means the battery is being charged to full Charge Limit - Another word for Target SoC Load - The energy your home is using to power your equipment e.g. oven, lights or electric car charging Grid - Your electric supply outside the house 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 Demand - Demand Mode is when the battery covers the house load and charges from solar, to avoid importing or exporting (some systems call this ECO Mode). Charging - When your battery is charging, in Predbat this refers to force charge (from the grid). Discharge - The opposite of charge, when the battery is discharging. Exporting - When your battery is force discharging to create an export, in Predbat this refers to force export. Export Limit - When your battery is being force exported the export limit is the % battery level where the discharge will stop if reached. PV - Solar power that is generated in your home. Can also refer to a prediction of the solar for the day, by default is the 50% scenario (most likely generation). 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 charged or discharged with AC (using an internal inverter) Micro Inverters - Small inverters that are fitted in-line with the DC solar panels and produce AC power on a per-panel basis. Typically used with an AC Coupled battery. 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 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. Loss - Refers to energy lost in your system due to heat or other factors. PV10 - A prediction of the 10% scenario for solar, this is like a worst case, occurs 1 in 10 days PV90 - A prediction of the 90% scenario for solar, this is like a best case, occurs 1 in 10 days Base - Usually refers to the expected outcome if Predbat takes no further action, meaning just what is currently configured on your inverter. Best - The best plan that Predbat could come up with, as in what it will do (assuming Read only is off) Actual - Used to refer to what has already happened in the past. Base10 - The base scenario but with the 10% outcome for Solar and Load (worst case) Charge Limit Base - This is the target charge % in the Base plan (what is currently set on your inverter) Best10 - The best plan but with the 10% outcome for Solar and Load (worst case) Charge Limit Best - This is the target charge % in the Best plan (what is currently set on your inverter) Export Limit Best - This is the target to force export to in % in the Best plan. Best SOC Keep - The amount of battery you want to keep in the plan that Predbat has made","title":"Basic terminology"},{"location":"what-does-predbat-do/#predbat-modes","text":"When you first install Predbat it will be in '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 in the Customisation Guide. Once you are ready for Predbat to take control move this setting to one of the active control modes.","title":"Predbat modes"},{"location":"what-does-predbat-do/#predbat-status","text":"The current Predbat status is reported in the Home Assistant entity predbat.status : Demand - 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 is described as 'Eco' Mode for GivEnergy inverters but other inverters use different terminology. 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 battery is charging but the current battery level (SoC) is is frozen (held). Think of it as a charge to the current battery level. The grid or solar covers any house load. If there is a shortfall of Solar power to meet house load, the excess house load is met from grid import, but if there is excess Solar power above house load, the excess solar will 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. Exporting - 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 exporting - The battery is in demand mode, but with charging disabled. The battery or solar covers the house load. As charging is disabled, if there is excess solar generated, the current SoC level will be held and the excess solar will be exported. If there is a shortfall of generated solar power to meet house load, the battery will discharge to meet the extra load. Hold exporting - The plan was to force export but the minimum battery level was reached and thus the battery is kept in Demand mode. If the battery level again gets above the threshold it will be changed back to Export mode. Calibration - The inverter is calibrating the batteries. On GivEnergy systems the battery state of charge (SoC) level has to be calibrated by performing a full battery discharge then a full charge so that the voltage levels associated with empty and full SoC can be determined. Predbat will pause executing the plan until the calibration automatically finishes - see Calibration FAQ . Error - There is a configuration error or other problem, you should check the Predbat log file for more details.","title":"Predbat status"}]} \ No newline at end of file diff --git a/search/worker.js b/search/worker.js new file mode 100644 index 000000000..8628dbce9 --- /dev/null +++ b/search/worker.js @@ -0,0 +1,133 @@ +var base_path = 'function' === typeof importScripts ? '.' : '/search/'; +var allowSearch = false; +var index; +var documents = {}; +var lang = ['en']; +var data; + +function getScript(script, callback) { + console.log('Loading script: ' + script); + $.getScript(base_path + script).done(function () { + callback(); + }).fail(function (jqxhr, settings, exception) { + console.log('Error: ' + exception); + }); +} + +function getScriptsInOrder(scripts, callback) { + if (scripts.length === 0) { + callback(); + return; + } + getScript(scripts[0], function() { + getScriptsInOrder(scripts.slice(1), callback); + }); +} + +function loadScripts(urls, callback) { + if( 'function' === typeof importScripts ) { + importScripts.apply(null, urls); + callback(); + } else { + getScriptsInOrder(urls, callback); + } +} + +function onJSONLoaded () { + data = JSON.parse(this.responseText); + var scriptsToLoad = ['lunr.js']; + if (data.config && data.config.lang && data.config.lang.length) { + lang = data.config.lang; + } + if (lang.length > 1 || lang[0] !== "en") { + scriptsToLoad.push('lunr.stemmer.support.js'); + if (lang.length > 1) { + scriptsToLoad.push('lunr.multi.js'); + } + if (lang.includes("ja") || lang.includes("jp")) { + scriptsToLoad.push('tinyseg.js'); + } + for (var i=0; i < lang.length; i++) { + if (lang[i] != 'en') { + scriptsToLoad.push(['lunr', lang[i], 'js'].join('.')); + } + } + } + loadScripts(scriptsToLoad, onScriptsLoaded); +} + +function onScriptsLoaded () { + console.log('All search scripts loaded, building Lunr index...'); + if (data.config && data.config.separator && data.config.separator.length) { + lunr.tokenizer.separator = new RegExp(data.config.separator); + } + + if (data.index) { + index = lunr.Index.load(data.index); + data.docs.forEach(function (doc) { + documents[doc.location] = doc; + }); + console.log('Lunr pre-built index loaded, search ready'); + } else { + index = lunr(function () { + if (lang.length === 1 && lang[0] !== "en" && lunr[lang[0]]) { + this.use(lunr[lang[0]]); + } else if (lang.length > 1) { + this.use(lunr.multiLanguage.apply(null, lang)); // spread operator not supported in all browsers: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Browser_compatibility + } + this.field('title'); + this.field('text'); + this.ref('location'); + + for (var i=0; i < data.docs.length; i++) { + var doc = data.docs[i]; + this.add(doc); + documents[doc.location] = doc; + } + }); + console.log('Lunr index built, search ready'); + } + allowSearch = true; + postMessage({config: data.config}); + postMessage({allowSearch: allowSearch}); +} + +function init () { + var oReq = new XMLHttpRequest(); + oReq.addEventListener("load", onJSONLoaded); + var index_path = base_path + '/search_index.json'; + if( 'function' === typeof importScripts ){ + index_path = 'search_index.json'; + } + oReq.open("GET", index_path); + oReq.send(); +} + +function search (query) { + if (!allowSearch) { + console.error('Assets for search still loading'); + return; + } + + var resultDocuments = []; + var results = index.search(query); + for (var i=0; i < results.length; i++){ + var result = results[i]; + doc = documents[result.ref]; + doc.summary = doc.text.substring(0, 200); + resultDocuments.push(doc); + } + return resultDocuments; +} + +if( 'function' === typeof importScripts ) { + onmessage = function (e) { + if (e.data.init) { + init(); + } else if (e.data.query) { + postMessage({ results: search(e.data.query) }); + } else { + console.error("Worker - Unrecognized message: " + e); + } + }; +} diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 000000000..0f8724efd --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz new file mode 100644 index 000000000..089c8d598 Binary files /dev/null and b/sitemap.xml.gz differ diff --git a/todo-list/index.html b/todo-list/index.html new file mode 100644 index 000000000..9b9059723 --- /dev/null +++ b/todo-list/index.html @@ -0,0 +1,179 @@ + + + + + + + + To-do list - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Predbat development
    • +
  • To-do list
    • +
  • +
    • +
+
+
+
+
+ +

To-do list

+ + +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/video-guides/index.html b/video-guides/index.html new file mode 100644 index 000000000..c622bb0f3 --- /dev/null +++ b/video-guides/index.html @@ -0,0 +1,237 @@ + + + + + + + + Video Guides - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • Installing & configuring Predbat
    • +
  • Video Guides
    • +
  • +
    • +
+
+
+
+
+ +

Video Guides

+

All the video guides are now available on my YouTube channel: Springfall2008

+

Basic installation

+

Playlist of Predbat installation videos

+ +

Other configuration videos

+

Playlist of other Predbat configuration videos

+ +

Features

+

Playlist of Predbat feature videos

+ +

Energy Tariffs

+

Playlist of Tariff configuration videos

+ + +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/what-does-predbat-do/index.html b/what-does-predbat-do/index.html new file mode 100644 index 000000000..a56f0a55e --- /dev/null +++ b/what-does-predbat-do/index.html @@ -0,0 +1,294 @@ + + + + + + + + What does Predbat do? - Predbat Documentation + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • What does Predbat do?
    • +
  • +
    • +
+
+
+
+
+ +

What does Predbat do?

+

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, solar generation, house load, charging activity, discharging activity, costs and import and export amounts based on 30 minute slots.
    • +
  • 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 configurable weighting towards the more pessimistic (10%) scenario.
    • +
  • Predbat automatically programs your inverter with the appropriate charging and discharging controls. Both Hybrid inverters and AC Coupled inverters are supported by Predbat.
    • +
  • 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 or to use a Solar Diverter, and take into account of these loads on the house during these periods.
    • +
  • Multiple inverter support is included but depends on all inverters running in lockstep.
    • +
+

Terminology

+

Basic terminology

+
    +
  • SoC - State of Charge - the % or kWh level of charge of your battery
    • +
  • Target SoC - The target level that the battery is being charged to, e.g. we target 100% SoC means the battery is being charged to full
    • +
  • Charge Limit - Another word for Target SoC
    • +
  • Load - The energy your home is using to power your equipment e.g. oven, lights or electric car charging
    • +
  • Grid - Your electric supply outside the house
    • +
  • 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
    • +
  • Demand - Demand Mode is when the battery covers the house load and charges from solar, to avoid importing or exporting (some systems call this ECO Mode).
    • +
  • Charging - When your battery is charging, in Predbat this refers to force charge (from the grid).
    • +
  • Discharge - The opposite of charge, when the battery is discharging.
    • +
  • Exporting - When your battery is force discharging to create an export, in Predbat this refers to force export.
    • +
  • Export Limit - When your battery is being force exported the export limit is the % battery level where the discharge will stop if reached.
    • +
  • PV - Solar power that is generated in your home. Can also refer to a prediction of the solar for the day, by default is the 50% scenario (most likely generation).
    • +
  • 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 charged or discharged with AC (using an internal inverter)
    • +
  • Micro Inverters - Small inverters that are fitted in-line with the DC solar panels and produce AC power on a per-panel basis. Typically used with an AC Coupled battery.
    • +
  • 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 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.
      • +
    +
    • +
  • +

    Loss - Refers to energy lost in your system due to heat or other factors.

    +
    • +
  • +

    PV10 - A prediction of the 10% scenario for solar, this is like a worst case, occurs 1 in 10 days

    +
    • +
  • PV90 - A prediction of the 90% scenario for solar, this is like a best case, occurs 1 in 10 days
    • +
  • Base - Usually refers to the expected outcome if Predbat takes no further action, meaning just what is currently configured on your inverter.
    • +
  • Best - The best plan that Predbat could come up with, as in what it will do (assuming Read only is off)
    • +
  • Actual - Used to refer to what has already happened in the past.
    • +
  • Base10 - The base scenario but with the 10% outcome for Solar and Load (worst case)
    • +
  • Charge Limit Base - This is the target charge % in the Base plan (what is currently set on your inverter)
    • +
  • Best10 - The best plan but with the 10% outcome for Solar and Load (worst case)
    • +
  • Charge Limit Best - This is the target charge % in the Best plan (what is currently set on your inverter)
    • +
  • Export Limit Best - This is the target to force export to in % in the Best plan.
    • +
  • Best SOC Keep - The amount of battery you want to keep in the plan that Predbat has made
    • +
+

Predbat modes

+

When you first install Predbat it will be in '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 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 the Home Assistant entity predbat.status:

+
    +
  • +

    Demand - 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 is described as 'Eco' Mode for GivEnergy inverters but other inverters use different terminology.

    +
    • +
  • +

    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 battery is charging but the current battery level (SoC) is is frozen (held). Think of it as a charge to the current battery level. +The grid or solar covers any house load. If there is a shortfall of Solar power to meet house load, the excess house load is met from grid import, +but if there is excess Solar power above house load, the excess solar will 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.

    +
    • +
  • +

    Exporting - 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 exporting - The battery is in demand mode, but with charging disabled. +The battery or solar covers the house load. As charging is disabled, if there is excess solar generated, the current SoC level will be held and the excess solar will be exported. +If there is a shortfall of generated solar power to meet house load, the battery will discharge to meet the extra load.

    +
    • +
  • +

    Hold exporting - The plan was to force export but the minimum battery level was reached and thus the battery is kept in Demand mode. +If the battery level again gets above the threshold it will be changed back to Export mode.

    +
    • +
  • +

    Calibration - The inverter is calibrating the batteries. +On GivEnergy systems the battery state of charge (SoC) level has to be calibrated by performing a full battery discharge then a full charge +so that the voltage levels associated with empty and full SoC can be determined. +Predbat will pause executing the plan until the calibration automatically finishes - see Calibration FAQ.

    +
    • +
  • +

    Error - There is a configuration error or other problem, you should check the Predbat log file for more details.

    +
    • +
+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + +