FOX ESS Cloud CLI

A command-line utility for managing FOX ESS solar inverters via the FOX Cloud API. Query real-time data, view generation statistics, manage battery settings, and control charging schedules.

Built for FOX ESS KH series inverters with battery storage (tested on KH10).

Features

• Real-time monitoring - View live power flows, battery state, PV generation
• Generation statistics - Daily, monthly, yearly, and cumulative totals
• Battery management - View module details, set minimum SoC levels
• Schedule control - View and disable charging schedules
• Historical data - Query past performance with peak values and SoC ranges
• Monthly reports - Generation, feed-in, and grid consumption summaries

Installation

Prerequisites

• Python 3.7+
• A FOX ESS inverter registered on FOX ESS Cloud

Setup

1. Clone the repository:

   git clone https://github.com/yourusername/fox-cloud.git
   cd fox-cloud

2. Install dependencies:

   pip install requests

3. Create a .env file with your API key (see Getting an API Key):

   echo 'FOX_API_KEY="your-api-key-here"' > .env

Getting an API Key

1. Log in to FOX ESS Cloud
2. Click your username in the top-right corner
3. Select Personal Centre (or API Management)
4. Navigate to the API Management section
5. Click Generate API Key
6. Copy the generated key and add it to your .env file

Note: Keep your API key secure. Never commit it to version control.

Usage

python fox_utility.py <command> [options]

Commands

Command	Description
status	Show scheduler configuration and battery settings
realtime	Display live power data (PV, battery, grid, loads)
generation	Show generation statistics (today/month/year/total)
battery	Display battery modules, heating settings, SoC config
history	Show historical data with peaks and SoC range
report	Display monthly generation report
peakshaving	Show peak shaving configuration
variables	List all available data variables
faults	Show current fault status
disable	Disable all scheduling (with confirmation)
setsoc N	Set minimum battery SoC to N%

Options

Option	Description
-d, --device SN	Specify device serial number (auto-detected if omitted)
--date YYYY-MM-DD	Date for history command
--year YYYY	Year for report command
--month MM	Month for report command
--ongrid N	On-grid SoC for setsoc (defaults to same as main value)

Examples

# View current status and schedules
python fox_utility.py status

# Check real-time power flows
python fox_utility.py realtime

# View generation statistics
python fox_utility.py generation

# View yesterday's data
python fox_utility.py history --date 2025-12-18

# View last month's report
python fox_utility.py report --year 2025 --month 11

# Set minimum battery SoC to 20%
python fox_utility.py setsoc 20

# Set different SoC for on-grid (15%) vs off-grid (20%)
python fox_utility.py setsoc 20 --ongrid 15

# Emergency: disable all schedules
python fox_utility.py disable

API Rate Limits

The FOX ESS API has the following limits:

• Query endpoints: 1 request per second
• Update endpoints: 1 request per 2 seconds
• Per device: 1,440 calls per day

Background

This utility was created to investigate and resolve an issue where a third-party application had set a forced charging schedule that couldn't be disabled through the official FOX ESS iOS app. See API_FINDINGS.md for detailed documentation of the schedule management API endpoints.

API Documentation

Official FOX ESS Cloud API documentation: https://www.foxesscloud.com/public/i18n/en/OpenApiDocument.html

Licence

MIT License - see LICENCE for details.

Contributing

Contributions welcome! Please ensure you don't commit any API keys or personal data.