Retrieves data from FoxESS Cloud API for solar inverters (e.g., used in Enpal systems) and exposes ioBroker states for home automation:
- Monitor solar power production
- Track battery state of charge (SoC)
- Analyze grid consumption and feed-in power
- Automate based on power generation
- Visualize energy flows in ioBroker dashboards
pvPower: Current PV power generation (kW)pv1Power…pv24Power: Individual PV string powers (kW) — only strings present on the device are created automaticallygenerationPower: Total generation/output power (kW)load: Current load/consumption power (kW)gridConsumption: Power imported from grid (kW)feedinPower: Power exported to grid (kW)
soc: Battery state of charge (%)batCharge: Battery charging power (kW)batDischarge: Battery discharging power (kW)batTemperature: Battery temperature (°C) — created automatically when the device reports a value
invTemperature: Inverter internal temperature (°C) — created automatically when the device reports a value; warns in the log at ≥ 65 °C and ≥ 80 °CrunningState: Current inverter running state (string)
info.connection: Connection status
When enabled in the Reporting tab, the adapter derives period totals from the lifetime cumulative values returned by the API:
report.day.*: Today's generation, feed-in and grid consumption (kWh)report.week.*: This week's totals (kWh)report.month.*: This month's totals (kWh)report.year.*: This year's totals (kWh)
When enabled in the Statistics tab, the adapter tracks accumulated PV energy and publishes JSON tables for use in VIS dashboards — see PV Power JSON Statistics for VIS Dashboards below.
The FoxESS Open API allows 1440 calls per day per API key (not per adapter instance). Usage in the FoxESS app or web portal does not count toward this Open API quota.
| Setup | API calls per day (24 h) |
|---|---|
| 1 instance @ 60 s interval | 1440 (full quota) |
| 2 instances @ 60 s (same API key) | ~2880 → limit often exceeded after ~12 h |
| 1 instance @ 120 s interval | 720 |
With the recommended 60 s interval, a single instance uses the full daily quota (1440 minutes = 24 hours).
Important: All Open API clients sharing the same API key share one quota — for example multiple ioBroker instances, Home Assistant integrations, or scripts. Exceeding the limit can cause intermittent API errors (e.g. 40400, 40402). Check remaining calls in the FoxESS portal under Profile → API Management.
For additional inverters, create one adapter instance per device (one serial number per instance) and plan the poll interval accordingly, or use separate API keys if your account allows it.
The adapter creates the following data points:
foxesscloud.0.pvPower- PV Power (kW)foxesscloud.0.generationPower- Generation Power/Output (kW)foxesscloud.0.soc- Battery State of Charge (%)foxesscloud.0.load- Load Power (kW)foxesscloud.0.gridConsumption- Grid Consumption/Import (kW)foxesscloud.0.feedinPower- Feed-in/Export Power (kW)foxesscloud.0.batCharge- Battery Charge Power (kW)foxesscloud.0.batDischarge- Battery Discharge Power (kW)foxesscloud.0.runningState- Inverter Running Statefoxesscloud.0.info.connection- Connection status
foxesscloud.0.pv1Power…foxesscloud.0.pv24Power- PV String 1–24 Power (kW)foxesscloud.0.invTemperature- Inverter Internal Temperature (°C)foxesscloud.0.batTemperature- Battery Temperature (°C)
foxesscloud.0.report.day.generation- Today's PV Generation (kWh)foxesscloud.0.report.day.feedin- Today's Feed-in Energy (kWh)foxesscloud.0.report.day.gridConsumption- Today's Grid Consumption (kWh)foxesscloud.0.report.week.generation- This Week's PV Generation (kWh)foxesscloud.0.report.week.feedin- This Week's Feed-in Energy (kWh)foxesscloud.0.report.week.gridConsumption- This Week's Grid Consumption (kWh)foxesscloud.0.report.month.generation- This Month's PV Generation (kWh)foxesscloud.0.report.month.feedin- This Month's Feed-in Energy (kWh)foxesscloud.0.report.month.gridConsumption- This Month's Grid Consumption (kWh)foxesscloud.0.report.year.generation- This Year's PV Generation (kWh)foxesscloud.0.report.year.feedin- This Year's Feed-in Energy (kWh)foxesscloud.0.report.year.gridConsumption- This Year's Grid Consumption (kWh)
foxesscloud.0.pvPowerJSON.daily- Daily energy statistics (JSON format) - current week from Monday to Sundayfoxesscloud.0.pvPowerJSON.weekly- Weekly energy statistics (JSON format) - all weeks of the current monthfoxesscloud.0.pvPowerJSON.monthly- Monthly energy statistics (JSON format) - all 12 months of the current year
- Install the adapter from the ioBroker admin interface
- Create a new instance
- Configure the General tab:
- API Token: Your API key from the FoxESS Cloud portal
- Serial Number (SN): The serial number of your inverter
- Update Interval: Data refresh interval in seconds (default: 60, minimum: 60)
- Optionally configure the Statistics tab:
- Enable PV Power JSON generation: Activate JSON table generation for VIS widgets
- Daily statistics: Generate daily energy data for the current week (Monday-Sunday)
- Weekly statistics: Generate weekly energy data for all weeks of the current month
- Monthly statistics: Generate monthly energy data for all 12 months of the current year
- Price per kWh: Optional — enter your electricity price per kWh for cost calculations in the JSON tables
- Daily / Weekly / Monthly start value: Optional initial kWh values for the running periods if the adapter is enabled after production already started
- Optionally configure the Reporting tab:
- Enable energy reporting: Activate period-based energy reporting (day / week / month / year)
- Save and start the instance
- Log in to FoxESS Cloud
- Go to your profile/settings
- Generate an API key (token)
- Find your inverter serial number in the device list
When enabled in the configuration, the adapter generates JSON tables with energy statistics that can be displayed in ioBroker VIS using widgets like the inventwo JSON Widget.
The JSON tables contain energy data with the following structure:
[
{"date": "Monday", "value": "1.904", "price": "0.58"},
{"date": "Tuesday", "value": "4.653", "price": "1.42"},
{"date": "Wednesday", "value": "0.417", "price": "0.13"},
{"date": "Thursday", "value": "0", "price": "0"},
{"date": "Friday", "value": "0", "price": "0"},
{"date": "Saturday", "value": "0", "price": "0"},
{"date": "Sunday", "value": "0", "price": "0"},
{"date": "Total", "value": "6.843", "price": "2.09"}
]- date: Day name (localized), week number (KW XX), or month name
- value: Energy generated in kWh (3 decimal places)
- price: Costs in € (only if price per kWh is configured, 2 decimal places)
- Daily: Shows the current calendar week from Monday to Sunday and updates the current day live
- Weekly: Accumulates weekly data (Monday-Sunday), shows all weeks of the current month, and includes the running week
- Monthly: Accumulates monthly data (1st–last day), shows all 12 months of the current year, and includes the running month
If the adapter is enabled while production is already running, you can configure optional start values for the current day, current week, and current month. These values are added once at the beginning of the respective running period.
The language of date labels (day/week/month names) automatically adapts to your ioBroker system language:
- German (de): Montag, Dienstag, January, Februar, etc.
- English (en): Monday, Tuesday, Januar, Februar, etc.
- Enable PV Power JSON generation in adapter configuration
- Add a JSON widget to your VIS dashboard
- Bind the widget to one of these states:
foxesscloud.0.pvPowerJSON.dailyfor daily statisticsfoxesscloud.0.pvPowerJSON.weeklyfor weekly statisticsfoxesscloud.0.pvPowerJSON.monthlyfor monthly statistics
- Configure the widget to display the energy/price data in a table format
When Enable energy reporting is activated in the Reporting tab, the adapter derives period totals (day / week / month / year) from the lifetime cumulative values returned by the FoxESS Cloud API. No additional API calls are required — the values are piggy-backed on the regular real-time query.
On each poll the adapter reads three lifetime values from the API:
generation— total energy generated since installation (kWh)feedin— total energy fed into the grid since installation (kWh)gridConsumption— total energy consumed from the grid since installation (kWh)
At the start of each period (new day / new ISO week / new calendar month / new year) the current lifetime values are stored as a baseline. The reported state value is always current lifetime value − baseline.
Baselines are persisted in report._baselines so they survive adapter restarts.
| State | Description |
|---|---|
foxesscloud.0.report.day.generation |
PV generation today (kWh) |
foxesscloud.0.report.day.feedin |
Energy fed into the grid today (kWh) |
foxesscloud.0.report.day.gridConsumption |
Energy consumed from the grid today (kWh) |
foxesscloud.0.report.week.generation |
PV generation this ISO week (kWh) |
foxesscloud.0.report.week.feedin |
Feed-in this ISO week (kWh) |
foxesscloud.0.report.week.gridConsumption |
Grid consumption this ISO week (kWh) |
foxesscloud.0.report.month.generation |
PV generation this month (kWh) |
foxesscloud.0.report.month.feedin |
Feed-in this month (kWh) |
foxesscloud.0.report.month.gridConsumption |
Grid consumption this month (kWh) |
foxesscloud.0.report.year.generation |
PV generation this year (kWh) |
foxesscloud.0.report.year.feedin |
Feed-in this year (kWh) |
foxesscloud.0.report.year.gridConsumption |
Grid consumption this year (kWh) |
- This adapter only reads data from FoxESS Cloud API using your personal API token
- Your API token is stored encrypted in the ioBroker database
- (skvarel) Added meta object types for adapter and instance namespace
- (skvarel) Fixed repository checker error E0036
- (skvarel) Documented Open API rate limit (per API key, multiple instances) in README and admin General tab
- (skvarel) Migrated project rules from GitHub Copilot to Cursor rules
- (skvarel) Revised config and i18n
- (StephanBeutel) Added support for up to 24 PV strings with dynamic state creation on first occurrence
- (StephanBeutel) Added report states for daily, weekly, monthly, and yearly energy totals derived from lifetime API values
- (StephanBeutel) Fixed null value handling for inverter and battery temperature states
- (StephanBeutel) Extracted reusable makeApiRequest() method for cleaner API communication
- (StephanBeutel) Centralized all state name translations into a single STATE_NAMES constant
- (skvarel) Fixed report states not updating during current period (values were only written at period rollover)
- (skvarel) Made energy reporting configurable via a new Reporting tab in the admin UI
MIT License
Copyright (c) 2026 skvarel skvarel@inventwo.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.