OpenAPI FoxESS cloud version released

[FozzieUK]

The OpenAPI version of the FoxESS cloud is now released.

The original access to the FoxESS cloud was made directly to their servers but because of internal changes, FoxESS have confirmed that direct 3rd party access will be disabled, however they have released an OpenAPI that developers can use to interface their applications to FoxESS servers.

Main Changes -

This integration communicates directly with the FoxESS OpenAPI servers, as its name suggests this is an open api that allows developers to write 3rd party applications to access the data on solar installations, more information can be found here FoxESS OpenAPI Documentation

The old cloud required username and password access, the OpenAPI has changed this and now requires a personal_api_key that has to be generated in the user profile of your FoxESS web account (see readme for more details).
EDIT: The username and password are now optional parameters as some users have these stored in their secrets file, the integration will not complain if they are, or are not specified as it no longer requires them

The access to the FoxESS api is limited to 1,440 api calls a day with certain limits on the timing of reads and writes, and the integration has to accomodate this - it now schedules variable data reads every 5 minutes (as per the old application and in-line with FoxESS cloud update interval), the report data (totals) is gathered every 15 minutes and daily generation every 30 minutes.

The error checking is more robust and in the event of a cloud timeout or loss of connection, it will schedule a retry after 1 minute and keep trying each minute until a connection is established.

This integration provides the following additional variables -

Residual Energy (the total amount of power reported to be available by the battery BMS - this includes minsoc)
MinSoC (the minimum state of charge of the battery - if battery fitted)
MinSoC on Grid (the minimum state of charge of the battery whilst on grid power - if battery fitted)

ADDITIONAL NOTES

The OpenAPI version of this integration was expected to be released towards the end of February when FoxESS were to close down the old cloud access, however FoxESS unexpectedly removed private access to their servers as of 20th February 2024, we do not know if this is temporary or whether it just happened early (I will update with more information when we know).
Either way access via the OpenAPI is their prescribed route going forwards.

The OpenAPI requires a 'personal_api_key' which you can get from your account at the FoxESS website in the user profile (see readme for more details).

As of the time of writing this, the 'personal_api_key' request feature has also gone off-line (it reports an http '500') and we are chasing them to re-instate it urgently - if you had already requested a personal_api_key the OpenAPI continues to work fine.
EDIT: 11:48am 20/2/2024 the personal_api_key request feature is working again

Again I will update here when I have more information about the status of this.

If you have any comments or issues regarding the openapi version please add them below.

[virusgt]

If I understood correctly, to connect now I need to modify the entry and it should look like this?

sensor:

• platform: foxess
  username: xxxx
  password: xxxxx
  deviceID: xxxxxx
  personal_api_key: xxxx
  logger:
  default: warning
  logs:
  custom_components.foxess: debug

[FozzieUK]

Like this -

sensor:
  - platform: foxess
    username: xxxxx
    password: xxxxx
    deviceID: enter_your_inverter_id
    deviceSN: enter_your_inverter_serial_number
    apiKey: enter_your_personal_api_key

It doesn't need your username / password anymore but it expects to find the text so they must be left in (for now)

and a little further down in your config

logger:
  default: warn
  logs:
    custom_components.foxess: warning

[virusgt]

Great, thanks, I'll test it soon :)

[virusgt]

Something went wrong
Invalid config for 'sensor' from integration 'foxess' at configuration.yaml, line 24: 'deviceSN' is an invalid option for 'foxess.sensor', check: deviceSN, please check the docs at https://github.com/macxq/foxess-ha Invalid config for 'sensor' from integration 'foxess' at configuration.yaml, line 25: 'apiKey' is an invalid option for 'foxess.sensor', check: apiKey, please check the docs at https://github.com/macxq/foxess-ha

[FozzieUK]

Have you downloaded the new release in HACS - if you go into HACS, find FOXESS CLOUD and click on it, it should say 'UPDATE' if it doesn't click on the 3 dots in the right hand corner and select 'Update Information' - it should then say 'UPDATE' which will download the new version and you'll need to restart HA

[virusgt]

Oh yes :), work after the update, I didn't notice the update. Thank you so much for help.

[FozzieUK]

Note - username and password are now optional parameters in v0.34, they no longer need to be added as the integration does not use them, but they can be left in your platform configuration or if stored in your secrets file.

[Bishbosh02]

Thanks for releasing this fast, only lost a few hours of generation data....

[Phoenix17785]

Works like a charm. Thanks for the update !

[FozzieUK]

@Phoenix17785 as you've got 3 inverters - I can't remember if you have 3 accounts (with 3 api_keys) or 1 account with 3 inverters sharing 1 api_key.
If it's only 1 account, keep an eye on the api limit of 1,440 calls per day - you will burn through that if it is being shared between your 3 inverters. If you have more 3 separate user accounts for each inverter then you should have no problems.
I am trying to reduce the number / pace of api_calls the integration makes but Fox don't make it easy with only 1,440 calls per day.

[Phoenix17785]

I have one account with 3 inverters. In the File Editor I have the API key on all three platform. Or is one enough? Von meinem iPhone gesendetAm 26.02.2024 um 16:21 schrieb Dave Foster ***@***.***>: @Phoenix17785 as you've got 3 inverters - I can't remember if you have 3 accounts (with 3 api_keys) or 1 account with 3 inverters sharing 1 api_key. If it's only 1 account, keep an eye on the api limit of 1,440 calls per day - you will burn through that if it is being shared between your 3 inverters. If you have more 3 separate user accounts for each inverter then you should have no problems. I am trying to reduce the number / pace of api_calls the integration makes but Fox don't make it easy with only 1,440 calls per day. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[FozzieUK]

@Phoenix17785 This is the biggest limitation with the openapi, it's a hard limit of 1,440 calls per account per day - which isn't good for multiple inverters in 1 account.

The current version of integration uses 35 api calls per hour (per inverter) = 840 calls per inverter so 3 inverters would need 2,520 calls - and you would run out of calls after 14 hours.

I am about to release another version that is better on resources, and uses 24 api calls per hour = 576 calls per inverter but even that would run out after approx 20 hours.

I'll send a request to FoxESS and see if I can get them to increase the limit, it really doesn't work well for multiple inverter sites (unless you can separate out each inverter in it's own account)

[FozzieUK]

@Phoenix17785 scratch what I have said so far - if I am reading their api release notes correctly you should be getting 1,440 api calls per day per inverter in your account in which case it will be just fine.

Can you keep close eye on your data and if you see the integration keeps gathering data and doesn't report access limitations, any problems let me know and i'll get on to Foxess to sort it.

[Phoenix17785]

Ah that’s why I see 4320 calls in my account.Von meinem iPhone gesendetAm 26.02.2024 um 16:49 schrieb Dave Foster ***@***.***>: @Phoenix17785 scratch what I have said so far - if I am reading their api release notes correctly you should be getting 1,440 api calls per day per inverter in your account in which case it will be just fine. Can you keep close eye on your data and if you see the integration keeps gathering data and doesn't report access limitations, any problems let me know and i'll get on to Foxess to sort it. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[virusgt]

Hey, I have had trouble downloading data for about 1 hour, I did a HA restart, I have all the updates, and I don't know if it's something to do with me or is something wrong with the API again?

[FozzieUK]

If it doesn’t have any timeouts the entities should be available again approx 5 or 6 minutes after a restart, i’m monitoring the openapi responses and it’s ridiculously slow and erratic.

[Bishbosh02]

Just updated my timeout to 75 and its now working after a re-start

[Dommify01]

Where do I change the time? I can't find this option!!

[FozzieUK]

@Dommify01 just update to the latest version in HACS v0.36, you might have to go to HACS click on Foxess Cloud, the three dots in the right corner and ‘update information’, then it will tell you there’s an up date.
It’s done for you in this update.

[Dommify01]

hi, thanks, but I just had to wait one more time and the data has been updated in real time and is correct. cheers