Crate foxess 

Foxess API client library

The foxess crate implements a subset of available FoxESS Cloud APIs.

Its purpose is mainly focused on APIs that help in executing automatic scheduling of battery charging and battery discharging (self-use) given external data such as tariffs from e.g.:

• Nordpool in the Nordic European region or some other supplier of daily tariffs.
• Weather temperature forecast data to estimate household power consumption
• Weather cloud forecast data and sun incidence calculations to estimate PV power production
• Etc. depending on level of ambition/precision in estimates

The APIs are tested for a Fox H3 model SK-HWR-12, and although the FoxESS Cloud APIs are general, settings and variables are not guaranteed to be fully supported by all inverters.

License

This library comes with a standard MIT license

Features

• async (default) - Enables async requests using reqwest
• blocking - Enables blocking requests using reqwest

async and blocking features are mutually exclusive, and since async is default, one must declare default-features = false when enabling blocking

Blocking mode (alternative)

This crate defaults to the async feature, and the documentation on docs.rs is generated for the async API.

If you prefer a blocking API, disable default features and enable blocking instead:

[dependencies]
foxess = { version = "0.x.y", default-features = false, features = ["blocking"] }

The blocking API uses the same Fox type name, but methods are synchronous (no .await).

Usage Overview

Note down your inverter serial number, can be found from within the FoxCloud2.0 app or the FoxESS Cloud V2 site web site.

Get an API key, it can be retrieved from the FoxESS Cloud V1 site under User Profile/API Management.

Decide whether to use the blocking or non-blocking feature in cargo.toml dependencies

[dependencies]
# Non-blocking (async)
foxess = "0.x.y"

# Non-blocking (async) if you want clarity
foxess = { version = "0.x.y", features = ["async"] }

# Blocking
foxess = { version = "0.x.y", default-features = false, features = ["blocking"] }

Examples

Non-blocking request for battery State of Charge

use foxess::Fox;
use foxess::fox_variables::SoC;

let api_key = "my_api_key";
let sn = "my_inverter_sn";

let fox = Fox::new(api_key, sn, 30).unwrap();
let soc = fox.get_variable_typed::<SoC>().await.unwrap();

println!("Current battery State of Charge: {}%", soc);

Non-blocking request for one-day PV power (Photo Voltaic), loads power (household load) and battery SoC

use std::ops::Add;
use chrono::{TimeZone, Utc, Local, Duration};
use foxess::{Fox, FoxVariables};

let api_key = "my_api_key";
let sn = "my_inverter_sn";

let start = Local.with_ymd_and_hms(2026, 2, 1, 0, 0, 0).unwrap().with_timezone(&Utc);
let end = start.add(Duration::days(1));
let variables = vec![FoxVariables::PvPower, FoxVariables::LoadsPower, FoxVariables::SoC];

let fox = Fox::new(api_key, sn, 30).unwrap();
let history = fox.get_variables_history(start, end, variables).await.unwrap();

let pv_history = history.get(FoxVariables::PvPower);
let loads_history = history.get(FoxVariables::LoadsPower);
let soc_history = history.get_u8_percent(FoxVariables::SoC);
let soh_history = history.get_u8_percent(FoxVariables::SOH);

// Expect these to have values
assert!(pv_history.is_some());
assert!(loads_history.is_some());
assert!(soc_history.is_some());

// Expect this to be None
assert!(soh_history.is_none());

if let Some(first) = pv_history.unwrap().first() {
    println!("PV power: {} W at {:?}", first.data, first.date_time);
}

Adding own marker structs for variables and settings

This is handy if an available variable or setting hasn’t got a builtin marker struct yet for typed operations. Or if an available builtin marker struct hasn’t sufficient guards for a settable setting.

Be aware, though, that not all available variables and settings work with all inverters. Fox will throw an error if FoxESS Cloud doesn’t support the requested variable or setting.

use foxess::{Fox, FoxError, FoxVariables, FoxSettings};
use foxess::fox_variables::VariableSpec;
use foxess::fox_settings::{SettingSpec, SettableSettingSpec};

let api_key = "my_api_key";
let sn = "my_inverter_sn";

let fox = Fox::new(&api_key, &sn, 30).unwrap();
let rf = fox.get_variable_typed::<RFreq>().await.unwrap();
println!("Current R frequency state: {}", rf);

let apl = fox.get_setting_typed::<MaxSetDischargeCurrent>().await.unwrap();
println!("Current max discharge current: {} A", apl);

let _ = fox.set_setting_typed::<MaxSetDischargeCurrent>(20.0).await.unwrap();


struct RFreq;
impl VariableSpec for RFreq {
    type Value = String;

    const VARIABLE: FoxVariables = FoxVariables::RFreq;

    fn into(raw: f64) -> Result<Self::Value, FoxError> {
        Ok(format!("{} Hz", raw))
    }
}

struct MaxSetDischargeCurrent;
impl SettingSpec for MaxSetDischargeCurrent {
    type Value = f64;

    const SETTING: FoxSettings = FoxSettings::MaxSetDischargeCurrent;

    fn parse(raw: String) -> Result<Self::Value, FoxError> {
        Ok(raw.parse::<f64>().unwrap())
    }
}

impl SettableSettingSpec for MaxSetDischargeCurrent {
    fn format(value: &Self::Value) -> String {
        value.clamp(3.0, 26.0).to_string()
    }
}

Modules

fox_settings

This module re-exports the fox_settings module from the models module.

fox_variables

This module re-exports the fox_variables module from the models module.

Structs

AvailableVariables

A collection of available variables.

ExtraParam

Additional parameters for specific work modes or settings.

Fox

A client for interacting with the FoxESS Open API.

Group

A scheduled task group defining a work mode for a specific time window.

MainSwitchStatus

Represents the Main Switch Status state in the API.

MetaData

Detailed structure for a parameter including unit, precision, and range.

Properties

Metadata properties defining the constraints for scheduler parameters.

Range

A numeric range with minimum and maximum values.

SettingsData

A structure that maintains the current state of settings data.

SettingsDataPoint

A struct representing a single data point for a setting.

TimeSegmentsData

Information about a time-segments based scheduler configuration.

TimeSegmentsDataRequest

Data to set as time-segments for the scheduler

VariableDataPoint

A struct representing a single data point for a variable.

VariableDataSet

A struct representing a dataset with associated historical timestamp information.

VariablesData

A structure that maintains the current state of variable data.

VariablesDataHistory

A structure that maintains a historical record of variable data.

WorkMode

Work mode information including available modes and their units.

Enums

FoxError

Custom error types for the FoxESS client.

FoxSettings

An enumeration representing implemented settings from FoxESS cloud, i.e., a subset from available settings.

FoxVariables

An enumeration representing the available real-time variables from FoxESS cloud.

FoxWorkModes

An enumeration representing the available scheduler work modes from FoxESS cloud.