Using Jupyter Notebook - TonyM1958/FoxESS-Cloud GitHub Wiki

This page explains how you can get data from Fox ESS Cloud and process it using Google Drive and Google Colaboratory. All you will need is a Google account with access to Google Drive.

If you have access to any other Jupyter Lab runtime environment, the same code will work there. This includes using the JupyterLab Lite add-on for Home Assistant. With this, you can run the battery charging predictions regardless of the integration or other add-ons you have installed. The notebook accesses all the data and changes settings on your inverter just using the Fox ESS Cloud.

You can play about with the code interactively using the information this page. If you create a setup you want to use regularly, you can schedule it to run automatically using Saturn Cloud (see Wiki page for more details).

Setting up Colaboratory

A number of example notebooks are available here. These include:

  • battery.ipynb: get information on your battery including cell voltage and temperatures
  • pvoutput.ipynb: upload PV history data to pvoutput.org, or use pvoutput_tou.ipynb to upload data with tariff based time of use for grid import / export
  • daily.ipynb: run daily to configure battery charging based on forecast PV generation and also upload data to pvoutput.org
  • pv_daily.ipynb: extracts your PV production data as a starting point for building your own analysis.

Click on the notebook(s) you wish to use, download the file (click the button in the top right hand corner of the page, shown below) and press your browser back button to return here.

Now, open your Downloads folder and drag and drop the notebook(s) into your Google Drive

Right click on a notebook in Google Drive or click the 3 dots shown on the left and select Open With, Google Colaboratory

image

(You can also drop the file into Jupyter Lab, if you have this available)

You see a screen similar to this:

Edit the file to add your details. Make sure you keep the double quotes around each item or you will get a syntax error. Newer notebooks use your Fox account API key, while some older notebooks use your Fox username and password. Add the relevant details:

  • replace my.fox_username with the username of your Fox account (if required)
  • replace my.fox_password with the password of your Fox account (if required)
  • replace my.api_key with your Open API key (if required)
  • replace my.fox_device_sn with the serial number of the inverter you want to connect to

Save your file using the Colaboratory menu: File, Save or Ctrl+S

Run the code in the first cell by clicking the 'play' button or clicking on the cell and pressing Shift+Enter. If there are no errors, you now have a working environment that can access your Fox Cloud data. If there are errors, see the trouble shooting information below.

The subsequent cells are specific to the different notebooks and actions you might want to take. Review the following sections, where they are relevant and then run the cell to perform the action.

If you have more than 1 inverter and use Meter2/CT2 to monitor the second inverter, the load energy values provided by Fox may be wrong. If this is the case, uncomment this line and the script will re-integrate your load power to give more accurate load energy values:

f.integrate_load_power = 1

Getting Battery Information

Relevant to : battery.ipynb

Simply run the cell to get your battery information. For example:

Generate CSV upload data for PV Output

Relevant to: pvoutput.ipynb, pvoutput_tou.ipynb

This cell will generate data in CSV format that you can upload to PV output:

Edit the start date. The day your inverter was installed is a good place to start. The format of the date must be 'YYYY-MM-DD'. If you run this cell, it should return data for each day from the start date.

By default, the limit in the file is 10 days. If you want to get more data, change the line that says limit = 10 to a higher value. If you set limit = None, it will produce data for a month. You can alter the start_date, limit or span and run the cell to get data for up to 200 days if you wish - although this will take some time.

Before you upload data, you need to setup your account on pvoutput.org and configure your PV system. This is described here.

Before uploading data, go to the PV Output CSV Upload tool and enter these settings to match the CSVdata format:

Once the format is setup, CSV data can be copied out of Colaboratory (select the lines you want from the cell output and press ctrl+C) and pasted into the CSV Upload tool text window (click in the window and press ctrl+V). Press Load to process the data.

You can generate and upload up to 200 days at a time by changing or removing the parameters. After you copy and upload some data, you can edit the date and run it again to generate more CSV data for upload. PV Output has a limit of 1 CSV upload every 5 minutes so, if you try to upload again, you may be told to try again in a few minutes.

If you have a solar inverter (such as T series) that does not provide energy stats, set tou=2. This will generate energy stats by integrating the grid consumption and feed in power values.

Set Tariff

Relevant to: daily.ipynb, pvoutput_tou.ipynb

Running this cell will configure your tariff and, for Agile, will fetch pricing data and calculate your best charging period:

More information on configuring tariffs and how they work is provided here

Charge Needed

Relevant to: daily.ipynb

Running this cell in the notebook will check for data from your inverter and get information about your battery, generation and consumption and work out if you need to enable charging from grid:

There are various parameters you can set in this cell to adjust how it works (that are described here). To start with, just run it with the default parameters and it will try to analyse your system, your battery state, your generation and consumption and advise whether you need to charge, as shown in the example above.

If you wish, you can allow the charge time settings on your inverter to be updated: change 'update_settings=0' to 'update_settings=1' to allow this.

Once you get used to how things work, you can configure a forecast, using Solcast to get more accurate data. Setting this up is described below.

Using Solcast for forecasting (daily.ipynb)

If you setup a Solcast hobby account and configure your PV system (described here), you can add your credentials to your notebook in the first cell. Once this is done, when you run charge_needed, it will try to get your forecast from Solcast.

To setup Solcast, you need to do the following:

  • Register a hobbyist account on the Solcast web site
  • Create and configure a solar array for each string (by default, the hobbyist account is limited to 2 arrays)
  • Under your account details, take a copy of your API key

Now edit the first cell in your notebook:

  • remove # from the start of the line and replace my.solcast_api_key with your Solcast API key

The first cell should now look like this:

Re-run the first cell to update your settings.

Now, when you run the cell with charge_needed beteen 22:00 and 23:59, it should get a forecast from Solcast in addition to the other data. By default, the script will use your forecast to determine whether you need to charge your battery.

image

charge_needed only gets your forecast after 22:00 so you don't run out of API calls if you run it at other times in the day. When run earlier, it forecasts your generation using your history for the last 3 days.

Upload Daily data to PV Output

Relevant to: pvoutputipynb and daily.ipynb

Before uploading data, you should add your PV Output credentials to the first cell:

  • replace pv_api_key with the API key you download from the PV Output Settings, API
  • replace pv_system_id with the System Id shown under PV Output, Settings, Registered Systems

Re-run the first cell to update your settings.

This cell generates PV Ouptut data for yesterday and today and uploads it directly to PV Output. For this to work, your PV Output API credentials need to be entered into the first cell and then run.

If you run this cell as is, it will upload complete data for yesterday and partial data for today. You can also set a specific date using d = 'YYYY-MM-DD'.

There is a rate limit, so you can only do around 10 days at a time before the PV Output API starts to reject your uploads.

Analyse daily PV Production

Relevant to: pv_daily.ipynb

This cell get your PV production data for yesterday and displays the amount generated by each PV string and when the peak power was generated.

If you have more than 2 PV strings, you can amend the list of PV Power variables that are fetched to include additional strings. For example, if you have 4 PV strings:

v=['pv1Power', 'pv2Power', 'pv3Power', 'pv4Power']

Troubleshooting

  • If there is a problem logging in to Fox Cloud, PV Output or Solcast, check your have the correct API keys
  • If there is a python error running the scripts (such as name 'f' is not defined), restart Colaboratory from the top menu: Runtine, Restart session and then re-run the first cell to re-initialise the environment