Documentation updates for Solcast and Sunsynk (#1157)

* Update apps.yaml

* Update ginlong_solis.yaml

* Update givenergy_cloud.yaml

* Update givenergy_ems.yaml

* Update givenergy_givtcp.yaml

* Update huawei.yaml

* Update sofar.yaml

* Update solaredge.yaml

* Update solax_sx4.yaml

* Update sunsynk.yaml

* Update install.md

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

* Update install.md

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

* Update installation-summary.md

* Update install.md

* Update output-data.md

* Update other-inverters.md

* Update install.md

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

* Update install.md

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

---------

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

apps/predbat/config/apps.yaml

@@ -219,7 +219,12 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
   # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
   pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)

docs/install.md

@@ -31,6 +31,7 @@ You will need to install an integration to communicate with and control your inv
 | 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> |
 
 Predbat was originally written for GivEnergy inverters controlled by the GivTCP add-on but has been extended for other inverter types.
 Please see [Other Inverters](other-inverters.md) for details on the install details.
@@ -68,15 +69,35 @@ in order to access files in different directories (i.e. within the appdaemon dir
 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.
 
-## AppDaemon-Predbat combined install
+## Predbat add-on install
 
 **Recommended**
 
-The simplest way to install Predbat now is with a combined AppDaemon/Predbat add-on.
+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/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](#solcast-install) below.
+
+## AppDaemon-Predbat combined install
+
+Another way to install Predbat now is with a combined AppDaemon/Predbat add-on.
 This is a fork of AppDaemon which automatically includes an install of Predbat.
 
 Installing the combined AppDaemon-predbat add-on is thus simpler for new users as they do not need to install HACS, AppDaemon and Predbat as three separate installation steps.
-If you are already running AppDaemon then the original installation method for Predbat still exists, is still supported, and is described below in [Predbat Installation into AppDaemon](#predbat-installation-into-appdaemon).
+If you are already running AppDaemon then the original installation method for Predbat still exists, is still supported, and is described below
+in [Predbat Installation into AppDaemon](#predbat-installation-into-appdaemon).
 
 To install the combined AppDaemon-predbat add-on:
 
@@ -198,28 +219,50 @@ Note: **Not recommended if you are using HACS**
 ## 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 solar then use a file editor to comment out the following lines from the Solar forecast part of the `apps.yaml` configuration:
+If you don't have one already register for a hobbyist account on [Solcast account](https://solcast.com/) and enter the details of your system.
+You can create 2 sites maximum under one 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).
+
+### Predbat direct method
+
+Predbat can talk to Solcast directly, first get your API key from the Solcast web site, then uncomment the solcast settings in apps.yaml and set the key correctly.
+
+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:
 
 ```yaml
-  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))
+solcast_host: 'https://api.solcast.com.au/'
+solcast_api_key: 'xxxx'
+solcast_poll_hours: 8
 ```
 
-If you do have solar panels its recommended to use the Solcast integration to retrieve your forecast solar generation.
+### Solcast Home Assistant integration method
+
 Predbat is configured in `apps.yaml` to automatically discover the Solcast forecast entities in Home Assistant.
 
-Install the Solcast integration (<https://github.com/oziee/ha-solcast-solar>), create a free [Solcast account](https://solcast.com/),
+Install the Solcast integration (<https://github.com/BJReplay/ha-solcast-solar>), create a free [Solcast account](https://solcast.com/),
 configure details of your solar arrays, and request an API key that you enter into the Solcast integration in Home Assistant.
 
-**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).
+If you don't have solar then use a file editor to comment out the following lines from the Solar forecast part of the `apps.yaml` configuration:
+
+```yaml
+  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 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).
+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.
 
 Example Solcast update automation script:
 

docs/installation-summary.md

@@ -6,14 +6,15 @@ Please see the sections below for how to achieve each step. This is just a check
 see the [video guides](video-guides.md) section for those and other videos
 2. Make sure the right inverter control module is installed and running - [GivTCP or Solax install](install.md#inverter-control-integration-install-givtcpsolax-modbus)
 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](install.md#editing-configuration-files-in-home-assistant)
-4. Install Predbat and AppDaemon, either:
-    - a) Install the AppDaemon-Predbat combined add-on - [AppDaemon-Predbat combined install](install.md#appdaemon-predbat-combined-install)
-    - b) Complete the separate installation steps:
+4. Install Predbat, either:
+    - a) Install the Predbat add-on - [Predbat add-on install](install.md#predbat-add-on-install)
+    - b) Install the AppDaemon-Predbat combined add-on - [AppDaemon-Predbat combined install](install.md#appdaemon-predbat-combined-install)
+    - c) Complete the separate installation steps:
         - i) Install HACS if you haven't already - [HACS install](install.md#hacs-install)
         - ii) Install AppDaemon if you haven't already - [AppDaemon install](install.md#appdaemon-install)
         - iii) Install Predbat using HACS - [Predbat install](install.md#install-predbat-through-hacs)
 5. Install Solcast if you haven't already [Solcast install](install.md#solcast-install).
-Create an automation to update Solcast a times a day, and check that you see the Solcast data in Home Assistant
+If using the Solcast integration then create an automation to update Solcast a times a day, and check that you see the Solcast data in Home Assistant
 6. Follow the [Energy Rates](energy-rates.md) instructions to tell Predbat what your import and export energy rates are.
 If you use Octopus Energy then this includes installing the Octopus Energy integration (if you haven't already) - [Octopus Energy](energy-rates.md#octopus-energy-integration)
 7. Edit Predbat's `apps.yaml` configuration file to to match your system - [apps.yaml settings](apps-yaml.md)<BR>

docs/other-inverters.md

@@ -12,6 +12,7 @@ PredBat was originally written for GivEnergy inverters using the GivTCP integrat
    | SolarEdge inverters | [Solaredge Modbus Multi](https://github.com/WillCodeForCats/solaredge-modbus-multi) | [solaredge.yaml](https://raw.githubusercontent.com/springfall2008/batpred/main/templates/solaredge.yaml) |
    | Givenergy with GE Cloud | [ge_cloud](https://github.com/springfall2008/ge_cloud) | [givenergy_cloud.yaml](https://raw.githubusercontent.com/springfall2008/batpred/main/templates/givenergy_cloud.yaml) |
    | Givenergy with GE Cloud EMC | [ge_cloud](https://github.com/springfall2008/ge_cloud) | [givenergy_ems.yaml](https://raw.githubusercontent.com/springfall2008/batpred/main/templates/givenergy_ems.yaml) |
+   | SunSynk | [Sunsynk](https://github.com/kellerza/sunsynk) | [sunsynk.yaml](https://raw.githubusercontent.com/springfall2008/batpred/main/templates/sunsynk.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.
 Please also ensure you have set up enhanced logging in AppDaemon as described here.
@@ -138,14 +139,16 @@ This is experimental system, please discuss on the ticket: <https://github.com/s
 
 ## Givenergy with EMC
 
-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_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)
 
+## Sunsynk
+
+This is experimental system, please discuss on the ticket: <https://github.com/springfall2008/batpred/issues/1060>
+
 ## 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

docs/output-data.md

@@ -163,6 +163,11 @@ import rate in the 24 hour Period
 - predbat.savings_yesterday_pvbat - A sensor which tells you have much money you saved vs not having a PV and battery system at all (this includes in the Predbat savings).
 - predbat.savings_total_pvbat - A running total of the above
 
+## Solar forecast data
+
+- sensor.predbat_pv_today - Tracks the PV forecast for today, attributes give the remaining amount today and the half hourly data.
+- sensor.predbat_pv_tomorrow - Tracks the PV forecast for tomorrow, attributes give the remaining amount today and the half hourly data.
+
 ## Sample Predbat data out dashboard
 
 ![image](images/predbat-data_out_dashboard_sample.png)

templates/ginlong_solis.yaml

@@ -159,7 +159,12 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
   # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
   pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)

templates/givenergy_cloud.yaml

@@ -205,7 +205,12 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
   # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
   pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)

templates/givenergy_ems.yaml

@@ -208,7 +208,12 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
   # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
   pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)

templates/givenergy_givtcp.yaml

@@ -220,7 +220,12 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
   # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
   pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)

templates/huawei.yaml

@@ -155,11 +155,14 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
-  # The regular [removed]re:) makes the solcast bit optional
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
+  # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
-  # sensor.solcast_pv_forecast_forecast_today
-  # sensor.solcast_pv_forecast_forecast_tomorrow
   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))

templates/sofar.yaml

@@ -139,7 +139,12 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
   # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
   pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)

templates/solaredge.yaml

@@ -148,7 +148,12 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
   # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
   pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)

templates/solax_sx4.yaml

@@ -166,7 +166,12 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
   # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
   pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)

templates/sunsynk.yaml

@@ -208,7 +208,12 @@ pred_bat:
   # 1 means add 1 minute to AppDaemon time, -1 takes it away
   clock_skew: 0
 
-  # Set these to match solcast sensor names
+  # Solcast cloud interface, set this or the local interface below
+  #solcast_host: 'https://api.solcast.com.au/'
+  #solcast_api_key: 'xxxx'
+  #solcast_poll_hours: 8
+
+  # Set these to match solcast sensor names if not using the cloud interface
   # The regular expression (re:) makes the solcast bit optional
   # If these don't match find your own names in Home Assistant
   pv_forecast_today: re:(sensor.(solcast_|)(pv_forecast_|)forecast_today)