foxesscloud 2.9.1__tar.gz → 2.9.3__tar.gz

{foxesscloud-2.9.1 → foxesscloud-2.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: foxesscloud
-Version: 2.9.1
+Version: 2.9.3
 Summary: library for accessing Fox ESS cloud data using Open API
 Author-email: Tony Matthews <tony@quasair.co.uk>
 Project-URL: Homepage, https://github.com/TonyM1958/FoxESS-Cloud
@@ -61,6 +61,7 @@ You don't have to configure all of the settings. Your Fox ESS Cloud api key is t
 For example, replace _my.fox_api_key_ with the API key. Add you inverter serial number if you have more than 1 inverter linked to your account. Be sure to keep the double quotes around the values you enter or you will get a syntax error.
 
 Residual handling configures how battery residual energy reported by Fox is handled:
++ 0: Use rated capacity, SoH and SoC to calculate residual energy (default)
 + 1: Fox returns the current battery residual energy and battery capacity is calculated using soc
 + 2: Fox returns the current battery capacity and battery residual is calculated using soc
 + 3: Fox returns the residual capacity per battery (Mira)
@@ -108,8 +109,8 @@ Once an inverter is selected, you can make other calls to get information:
 
 ```
 f.get_generation()
-f.get_battery(info, rated, count)
-f.get_batteries(info, rated, count)
+f.get_battery()
+f.get_batteries(info)
 f.get_settings()
 f.get_charge()
 f.get_min()
@@ -117,17 +118,15 @@ f.get_peakshaving()
 f.get_flag()
 f.get_schedule()
 f.get_named_settings(name)
+f.get_battery_heating()
 
 ```
 Each of these calls will return a dictionary or list containing the relevant information.
 
 get_generation() will return the latest generation information for the device. The results are also stored in f.device as 'generationToday', 'generationMonth' and 'generationTotal'.
 
-get_battery() / get_batteries() returns the current battery status, including 'soc', 'volt', 'current', 'power', 'temperature' and 'residual'. The result also updates f.battery / f.batteries.
-get_batteries() returns multiple batteries (if available) as a list. get_battery() returns the first battery. Parameters:
-+ 'info': get battery serial number info, if available. Default 0 (not available via Open API)
-+ 'rated': optional rated capacity for the battery in Wh to work out SoH. If not provided, it will try to work this out.
-+ 'count': optional battery count. If not provided, it will try to work this out.
+get_battery() / get_batteries() returns the current battery status, including 'soc', 'volt', 'current', 'power', 'temperature', 'residual' and 'throughput'. The result also updates f.battery / f.batteries.
+get_batteries() returns multiple batteries (if available) as a list. get_battery() returns the first battery.
 
 Additional battery attributes provided include:
 + 'capacity': the estimated battery capacity, derrived from 'residual' and 'soc'
@@ -146,8 +145,9 @@ get_schedule() returns the current work mode / soc schedule settings. The result
 
 get_named_settings() returns the value of a named setting. If 'name' is a list, it returns a list of values.
 + f.named_settings is updated. This is dictionary of information and current value, indexed by 'name'.
-+ named_settings currently supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode, WorkMode
++ named_settings currently available are stored in f.name_list. The settings supported depends on the inverter model and firmware version. An error will be returned if an unsupported variable is used.
 
+get_battery_heating returns the current battery heating parameters and store these in f.battery_heating
 
 ## Inverter Settings
 You can change inverter settings using:
@@ -158,6 +158,7 @@ f.set_charge(ch1, st1, en1, ch2, st2, en2, enable)
 f.set_period(start, end, mode, min_soc, max_soc, fdsoc, fdpwr, price, segment)
 f.set_schedule(periods, enable)
 f.set_named_settings(name, value, force)
+f.set_battery_heating(enable, start, end, time1, time2, time3)
 ```
 
 set_min() applies new SoC settings to the inverter. The parameters update battery_settings:
@@ -180,12 +181,16 @@ set_period() returns a period structure that can be used to build a list for set
 + max_soc: optional, default is 100
 + fdsoc: optional, default is 10. Used when setting a period with ForceDischarge mode
 + fdpwr: optional, default is 0. Used when setting a period with ForceDischarge mode
++ import_limit: optional, default is None (not set). Used when setting a period with ForceCharge mode
++ export_limit: optional, default is None (not set). Used when setting a period with ForceDischarge mode
 + price: optional, default None. Used to display plunge pricing for time period.
 + enable: sets whether this time segment is enable (1) or disabled (0). The default is enabled.
 + segment: optional, allows the parameters for the period to be passed as a dictionary instead of individual values.
 
 Before calling set_period(), do at least one call to get_schedule(). This will inspect the schedule result to check if max_soc is supported and set the flag f.schedule['maxsoc'] to enable or disable this field as appropriate.
 
+The variable f.max_periods is used to check the number of time periods allowed. The default is 8.
+
 set_schedule() configures a list of scheduled work mode / soc changes with enable=1. If called with enable=0, any existing schedules are disabled. To enable a schedule, you must provide a list of time segments
 + periods: a time segment or list of time segments created using f.set_period().
 + enable: 1 to enable schedules, 0 to disable schedules. The default is 1.
@@ -194,8 +199,12 @@ set_named_settings() sets the 'name' setting to 'value'.
 + 'name' may also be a list of (name, value) pairs.
 + force: setting to 1 will disable Mode Scheduler, if enabled. Default is 0.
 + a return value of 1 is success. 0 means setting failed. None is another error e.g. device not found, invalid name or value.
-+ named_settings currently supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode, WorkMode
++ named_settings currently available are stored in f.name_list. The settings supported depend on the inverter model and firmware version. An error will be returned if an unsupported varaible is used.
 
+set_battery_heating() set the heating parameters as follows:
++ enable: optional, 0 or 1, default is 1
++ start, end: optional start and end temperatures. The defaults are start at 9C and end at 12C.
++ time1, time2, time3: optional times when the battery can heat from the grid time. The structure is {'enable': 1, 'start': '00:30', 'end': '05:30'}. The time slot is disabled by default.
 
 ## Real Time Data
 Real time data reports the latest values for inverter variables, collected every 5 minutes:
@@ -821,6 +830,19 @@ This setting can be:
 
 # Version Info
 
+2.9.3 - 2026/01/18<br>
+Update get_device() to use v1 API call.
+Update get_battery() to work out battery count and rated capacity from device battery list.
+Update default residual_handling to option 0 (residual is calculated from rated capacity, SoH and SoC).
+Added get_battery_real() for testing (Fox does not currently populate most of the data).
+Added 'throughput' to battery variables returned.
+Add f.name_list to hold the list of setting variables and update the list.
+Added get_battery_heating() and set_battery_heating().
+
+2.9.2 - 2025/11/30<br>
+Update get_schedule(), set_period() and set_schedule() to use v2 interface and add setting import_limit and export_limit.
+Added f.max_periods to allow for more time periods in schedules (default is 8).
+
 2.9.1 - 2025/10/25<br>
 Change default contingency for charge_needed() to [25,15,10,20] and special contingency to 35.
 Update info shown around contingency.

foxesscloud-2.9.1/src/foxesscloud.egg-info/PKG-INFO → foxesscloud-2.9.3/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.1
-Name: foxesscloud
-Version: 2.9.1
-Summary: library for accessing Fox ESS cloud data using Open API
-Author-email: Tony Matthews <tony@quasair.co.uk>
-Project-URL: Homepage, https://github.com/TonyM1958/FoxESS-Cloud
-Project-URL: Bug Tracker, https://github.com/TonyM1958/FoxESS-Cloud/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENCE
-
 # FoxESS-Cloud
 
 <a href="https://www.buymeacoffee.com/tonym1958" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174" align="right"></a>
@@ -61,6 +47,7 @@ You don't have to configure all of the settings. Your Fox ESS Cloud api key is t
 For example, replace _my.fox_api_key_ with the API key. Add you inverter serial number if you have more than 1 inverter linked to your account. Be sure to keep the double quotes around the values you enter or you will get a syntax error.
 
 Residual handling configures how battery residual energy reported by Fox is handled:
++ 0: Use rated capacity, SoH and SoC to calculate residual energy (default)
 + 1: Fox returns the current battery residual energy and battery capacity is calculated using soc
 + 2: Fox returns the current battery capacity and battery residual is calculated using soc
 + 3: Fox returns the residual capacity per battery (Mira)
@@ -108,8 +95,8 @@ Once an inverter is selected, you can make other calls to get information:
 
 ```
 f.get_generation()
-f.get_battery(info, rated, count)
-f.get_batteries(info, rated, count)
+f.get_battery()
+f.get_batteries(info)
 f.get_settings()
 f.get_charge()
 f.get_min()
@@ -117,17 +104,15 @@ f.get_peakshaving()
 f.get_flag()
 f.get_schedule()
 f.get_named_settings(name)
+f.get_battery_heating()
 
 ```
 Each of these calls will return a dictionary or list containing the relevant information.
 
 get_generation() will return the latest generation information for the device. The results are also stored in f.device as 'generationToday', 'generationMonth' and 'generationTotal'.
 
-get_battery() / get_batteries() returns the current battery status, including 'soc', 'volt', 'current', 'power', 'temperature' and 'residual'. The result also updates f.battery / f.batteries.
-get_batteries() returns multiple batteries (if available) as a list. get_battery() returns the first battery. Parameters:
-+ 'info': get battery serial number info, if available. Default 0 (not available via Open API)
-+ 'rated': optional rated capacity for the battery in Wh to work out SoH. If not provided, it will try to work this out.
-+ 'count': optional battery count. If not provided, it will try to work this out.
+get_battery() / get_batteries() returns the current battery status, including 'soc', 'volt', 'current', 'power', 'temperature', 'residual' and 'throughput'. The result also updates f.battery / f.batteries.
+get_batteries() returns multiple batteries (if available) as a list. get_battery() returns the first battery.
 
 Additional battery attributes provided include:
 + 'capacity': the estimated battery capacity, derrived from 'residual' and 'soc'
@@ -146,8 +131,9 @@ get_schedule() returns the current work mode / soc schedule settings. The result
 
 get_named_settings() returns the value of a named setting. If 'name' is a list, it returns a list of values.
 + f.named_settings is updated. This is dictionary of information and current value, indexed by 'name'.
-+ named_settings currently supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode, WorkMode
++ named_settings currently available are stored in f.name_list. The settings supported depends on the inverter model and firmware version. An error will be returned if an unsupported variable is used.
 
+get_battery_heating returns the current battery heating parameters and store these in f.battery_heating
 
 ## Inverter Settings
 You can change inverter settings using:
@@ -158,6 +144,7 @@ f.set_charge(ch1, st1, en1, ch2, st2, en2, enable)
 f.set_period(start, end, mode, min_soc, max_soc, fdsoc, fdpwr, price, segment)
 f.set_schedule(periods, enable)
 f.set_named_settings(name, value, force)
+f.set_battery_heating(enable, start, end, time1, time2, time3)
 ```
 
 set_min() applies new SoC settings to the inverter. The parameters update battery_settings:
@@ -180,12 +167,16 @@ set_period() returns a period structure that can be used to build a list for set
 + max_soc: optional, default is 100
 + fdsoc: optional, default is 10. Used when setting a period with ForceDischarge mode
 + fdpwr: optional, default is 0. Used when setting a period with ForceDischarge mode
++ import_limit: optional, default is None (not set). Used when setting a period with ForceCharge mode
++ export_limit: optional, default is None (not set). Used when setting a period with ForceDischarge mode
 + price: optional, default None. Used to display plunge pricing for time period.
 + enable: sets whether this time segment is enable (1) or disabled (0). The default is enabled.
 + segment: optional, allows the parameters for the period to be passed as a dictionary instead of individual values.
 
 Before calling set_period(), do at least one call to get_schedule(). This will inspect the schedule result to check if max_soc is supported and set the flag f.schedule['maxsoc'] to enable or disable this field as appropriate.
 
+The variable f.max_periods is used to check the number of time periods allowed. The default is 8.
+
 set_schedule() configures a list of scheduled work mode / soc changes with enable=1. If called with enable=0, any existing schedules are disabled. To enable a schedule, you must provide a list of time segments
 + periods: a time segment or list of time segments created using f.set_period().
 + enable: 1 to enable schedules, 0 to disable schedules. The default is 1.
@@ -194,8 +185,12 @@ set_named_settings() sets the 'name' setting to 'value'.
 + 'name' may also be a list of (name, value) pairs.
 + force: setting to 1 will disable Mode Scheduler, if enabled. Default is 0.
 + a return value of 1 is success. 0 means setting failed. None is another error e.g. device not found, invalid name or value.
-+ named_settings currently supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode, WorkMode
++ named_settings currently available are stored in f.name_list. The settings supported depend on the inverter model and firmware version. An error will be returned if an unsupported varaible is used.
 
+set_battery_heating() set the heating parameters as follows:
++ enable: optional, 0 or 1, default is 1
++ start, end: optional start and end temperatures. The defaults are start at 9C and end at 12C.
++ time1, time2, time3: optional times when the battery can heat from the grid time. The structure is {'enable': 1, 'start': '00:30', 'end': '05:30'}. The time slot is disabled by default.
 
 ## Real Time Data
 Real time data reports the latest values for inverter variables, collected every 5 minutes:
@@ -821,6 +816,19 @@ This setting can be:
 
 # Version Info
 
+2.9.3 - 2026/01/18<br>
+Update get_device() to use v1 API call.
+Update get_battery() to work out battery count and rated capacity from device battery list.
+Update default residual_handling to option 0 (residual is calculated from rated capacity, SoH and SoC).
+Added get_battery_real() for testing (Fox does not currently populate most of the data).
+Added 'throughput' to battery variables returned.
+Add f.name_list to hold the list of setting variables and update the list.
+Added get_battery_heating() and set_battery_heating().
+
+2.9.2 - 2025/11/30<br>
+Update get_schedule(), set_period() and set_schedule() to use v2 interface and add setting import_limit and export_limit.
+Added f.max_periods to allow for more time periods in schedules (default is 8).
+
 2.9.1 - 2025/10/25<br>
 Change default contingency for charge_needed() to [25,15,10,20] and special contingency to 35.
 Update info shown around contingency.

{foxesscloud-2.9.1 → foxesscloud-2.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "foxesscloud"
-version = "2.9.1"
+version = "2.9.3"
 authors = [
   {name="Tony Matthews", email="tony@quasair.co.uk"},
 ]

{foxesscloud-2.9.1 → foxesscloud-2.9.3}/src/foxesscloud/foxesscloud.py

@@ -1,7 +1,7 @@
 ##################################################################################################
 """
 Module:   Fox ESS Cloud
-Updated:  25 October 2025
+Updated:  18 January 2026
 By:       Tony Matthews
 """
 ##################################################################################################
@@ -10,7 +10,7 @@ By:       Tony Matthews
 # ALL RIGHTS ARE RESERVED © Tony Matthews 2023
 ##################################################################################################
 
-version = "1.10.0"
+version = "1.11.0"
 print(f"FoxESS-Cloud version {version}")
 
 debug_setting = 1
@@ -1862,8 +1862,8 @@ def rescale_history(data, steps):
 # station = 0: use device_id, 1 = use station_id
 ##################################################################################################
 
-report_vars = ['PVEnergyTotal', 'input','generation', 'feedin', 'loads', 'gridConsumption', 'chargeEnergyToTal', 'dischargeEnergyToTal']
-report_names = ['PV Yield', 'Input', 'Generation', 'Grid Export', 'Consumption', 'Grid Import', 'Battery Charge', 'Battery Discharge']
+report_vars = ['PVEnergyTotal', 'generation', 'feedin', 'loads', 'gridConsumption', 'chargeEnergyToTal', 'dischargeEnergyToTal']
+report_names = ['PV Yield', 'Generation', 'Grid Export', 'Consumption', 'Grid Import', 'Battery Charge', 'Battery Discharge']
 
 # fix power values after fox corrupts high word of 32-bit energy total
 fix_values = 1

{foxesscloud-2.9.1 → foxesscloud-2.9.3}/src/foxesscloud/openapi.py

@@ -1,7 +1,7 @@
 ##################################################################################################
 """
 Module:   Fox ESS Cloud using Open API
-Updated:  25 October 2025
+Updated:  18 January 2025
 By:       Tony Matthews
 """
 ##################################################################################################
@@ -10,7 +10,7 @@ By:       Tony Matthews
 # ALL RIGHTS ARE RESERVED © Tony Matthews 2024
 ##################################################################################################
 
-version = "2.9.1"
+version = "2.9.3"
 print(f"FoxESS-Cloud Open API version {version}")
 
 debug_setting = 1
@@ -486,7 +486,7 @@ def get_device(sn=None, device_type=None):
     # load information for the device
     device_sn = device_list[n].get('deviceSN')
     params = {'sn': device_sn }
-    response = signed_get(path="/op/v0/device/detail", params=params)
+    response = signed_get(path="/op/v1/device/detail", params=params)
     if response.status_code != 200:
         output(f"** get_device() got detail response code {response.status_code}: {response.reason}")
         return None
@@ -574,11 +574,11 @@ def get_generation(update=1):
 battery = None
 batteries = None
 battery_settings = None
-battery_vars = ['SoC', 'invBatVolt', 'invBatCurrent', 'invBatPower', 'batTemperature', 'ResidualEnergy','SOH' ]
-battery_data = ['soc', 'volt', 'current', 'power', 'temperature', 'residual', 'soh']
+battery_vars = ['SoC', 'invBatVolt', 'invBatCurrent', 'invBatPower', 'batTemperature', 'ResidualEnergy','SOH','energyThroughput' ]
+battery_data = ['soc', 'volt', 'current', 'power', 'temperature', 'residual', 'soh', 'throughput']
 
 # 1 = Residual Energy, 2 = Residual Capacity (HV), 3 = Residual Capacity per battery (Mira)
-residual_handling = 1
+residual_handling = 0
 
 # charge rates based on residual_handling. Index is bms temperature
 battery_params = {
@@ -611,57 +611,53 @@ def get_battery(info=0, v=None, rated=None, count=None):
     global device_sn, battery, debug_setting, residual_handling, battery_params
     if get_device() is None:
         return None
+    battery = {}
+    rated = 0
+    count = 0
+    for b in device['batteryList']:
+        if b.get('type') == 'bmu' and b.get('capacity') is not None:
+            rated += b['capacity']
+            count += 1
+    if count > 0:
+        battery['count'] = count
+        battery['ratedCapacity'] = rated
+    else:
+        output(f"** get_battery(): battery capacity not available")
+        return None
     output(f"getting battery", 2)
     if v is None:
         v = battery_vars
     result = get_real(v)
-    battery = {}
     for i in range(0, len(battery_vars)):
         battery[battery_data[i]] = result[i].get('value')
     if debug_setting > 1:
         print(f"raw battery = {battery}")
-    battery['residual_handling'] = residual_handling
-    battery['soh'] = None
-    battery['soh_supported'] = False
     if battery.get('status') is None:
         battery['status'] = 0 if battery.get('volt') is None or battery['volt'] <= 10 else 1
     if battery['status'] == 0:
         output(f"** get_battery(): battery status not available")
         return None
-    if battery['residual_handling'] == 2:
+    capacity = battery['ratedCapacity'] / 1000 * (battery['soh'] if battery.get('soh') is not None else 100) / 100
+    soc = battery.get('soc')
+    battery['residual_handling'] = residual_handling
+    if battery['residual_handling'] == 1:
+        capacity = battery['residual'] / soc * 100
+        battery['soh'] = round(capacity * 1000 / battery['ratedCapacity'] * 100, 1)
+    elif battery['residual_handling'] == 2:
         capacity = battery.get('residual')
-        soc = battery.get('soc')
-        residual = capacity * soc / 100 if capacity is not None and soc is not None else capacity
-        if battery.get('count') is None:
-            battery['count'] = int(battery['volt'] / 49) if count is None else count
-        if battery.get('ratedCapacity') is None:
-            battery['ratedCapacity'] = 2560 * battery['count'] if rated is None else rated
+        battery['soh'] = round(capacity * 1000 / battery['ratedCapacity'] * 100, 1)
     elif battery['residual_handling'] == 3:
-        if battery.get('count') is None:
-            battery['count'] = int(battery['volt'] / 49) if count is None else count
         capacity = (battery['residual'] * battery['count']) if battery.get('residual') is not None else None
-        soc = battery.get('soc')
-        residual = capacity * soc / 100 if capacity is not None and soc is not None else capacity
-        if battery.get('ratedCapacity') is None:
-            battery['ratedCapacity'] = 2450 * battery['count'] if rated is None else rated
-    else:
-        residual = battery.get('residual')
-        soc = battery.get('soc')
-        capacity = residual / soc * 100 if residual is not None and soc is not None and soc > 0 else None 
-        if battery.get('count') is None or battery['count'] < 1:
-            battery['count'] = count
-        if battery.get('ratedCapacity') is None or battery['ratedCapacity'] < 100:
-            battery['ratedCapacity'] = rated
+        battery['soh'] = round(capacity / battery['ratedCapacity'] * 100, 1)
+    residual = capacity * soc / 100
     battery['capacity'] = round(capacity, 3)
     battery['residual'] = round(residual, 3)
-    battery['charge_rate'] = None
-    params = battery_params[battery['residual_handling']]
-    battery['charge_loss'] = params['charge_loss']
-    battery['discharge_loss'] = params['discharge_loss']
-    if battery.get('ratedCapacity') is not None and battery.get('capacity') is not None:
-        battery['soh'] = round(battery['capacity'] * 1000 / battery['ratedCapacity'] * 100, 1) if battery['ratedCapacity'] > 0.0 else None
-    if battery.get('temperature') is not None:
-        battery['charge_rate'] = interpolate((battery['temperature'] - params['offset']) / params['step'], params['table'])
+    if battery['residual_handling'] > 0:
+        params = battery_params[battery['residual_handling']]
+        battery['charge_loss'] = params['charge_loss']
+        battery['discharge_loss'] = params['discharge_loss']
+        if battery.get('temperature') is not None:
+            battery['charge_rate'] = interpolate((battery['temperature'] - params['offset']) / params['step'], params['table'])
     return battery
 
 def get_batteries(info=0, rated=None, count=None):
@@ -676,6 +672,91 @@ def get_batteries(info=0, rated=None, count=None):
     batteries = [battery]
     return batteries
 
+def get_battery_real():
+    global device_sn, device
+    if get_device() is None:
+        return None
+    output(f"getting battery real", 2)
+    params = {'sn': device_sn}
+    response = signed_get(path="/op/v0/device/battery/real/query", params=params)
+    if response.status_code != 200:
+        output(f"** get_battery_real() got response code {response.status_code}: {response.reason}")
+        return None
+    result = response.json().get('result')
+    if result is None:
+        output(f"** get_battery_real(), no result data, {errno_message(response)}")
+        return None
+    return result
+
+##################################################################################################
+# battery heating settings
+##################################################################################################
+
+battery_heating = None
+
+def get_battery_heating():
+    global device_sn, device, battery_heating
+    if get_device() is None:
+        return None
+    output(f"getting battery heating", 2)
+    body = {'sn': device_sn}
+    response = signed_post(path="/op/v0/device/batteryHeating/get", body=body)
+    if response.status_code != 200:
+        output(f"** get_battery_heating() got response code {response.status_code}: {response.reason}")
+        return None
+    errno = response.json().get('errno')
+    if errno != 0:
+        if errno == 41200:
+            output(f"** get_battery_heating(): not supported")
+        else:
+            output(f"** get_battery_heating(): {errno_message(response)}")
+        return None
+    result = response.json().get('result')
+    battery_heating = result
+    return result
+
+def set_time(body, s, time):
+    if time is None:
+        body[s + 'Enable'] = 0
+        body[s + 'StartHour'] = 0
+        body[s + 'StartMinute'] = 0
+        body[s + 'EndHour'] = 0
+        body[s + 'EndMinute'] = 0
+    else:
+        body[s + 'Enable'] = time['enable']
+        t = time_hours(time['start'])
+        body[s + 'StartHour'] = int(t)
+        body[s + 'StartMinute'] = int(60 * (t - int(t)) + 0.5)
+        t = time_hours(time['end'])
+        body[s + 'EndHour'] = int(t)
+        body[s + 'EndMinute'] = int(60 * (t - int(t)) + 0.5)
+    return
+
+def set_battery_heating(enable=None, start=None, end=None, time1=None, time2=None, time3=None):
+    global device_sn, device
+    if get_device() is None:
+        return None
+    output(f"setting battery heating", 2)
+    body = {'sn': device_sn}
+    body['batteryWarmUpEnable'] = enable if enable is not None else 1
+    body['startTemperature'] = start if start is not None else 9
+    body['endTemperature'] = end if end is not None else 12
+    set_time(body, 'time1', time1)
+    set_time(body, 'time2', time2)
+    set_time(body, 'time3', time3)
+    response = signed_post(path="/op/v0/device/batteryHeating/set", body=body)
+    if response.status_code != 200:
+        output(f"** set_battery_heating() got response code {response.status_code}: {response.reason}")
+        return None
+    errno = response.json().get('errno')
+    if errno != 0:
+        if errno == 41200:
+            output(f"** set_battery_heating(): not supported")
+        else:
+            output(f"** set_battery_heating(): {errno_message(response)}")
+        return None
+    return 1
+
 ##################################################################################################
 # get charge times and save to battery_settings
 ##################################################################################################
@@ -896,6 +977,8 @@ def get_peakshaving():
 ##################################################################################################
 
 # store for named settings info
+name_list = ['ExportLimit','MinSoc','MinSocOnGrid','MaxSoc','GridCode','WorkMode','ExportLimitPower',
+    'EpsOutPut','MaxSetChargeCurrent','MaxSetDischargeCurrent','ECOMode','Meter1Enable','Meter2Enable','SysSwitch','GroundProtection']
 named_settings = {}
 
 def get_remote_settings(name):
@@ -911,8 +994,7 @@ def get_remote_settings(name):
             v = get_remote_settings(n)
             if v is None:
                 continue
-            for x in v.keys():
-                values[x] = v[x]
+            values[n] = v
         return values
     body = {'sn': device_sn, 'key': name}
     setting_delay()
@@ -923,7 +1005,7 @@ def get_remote_settings(name):
     result = response.json().get('result')
     if result is None:
         errno = response.json().get('errno')
-        output(f"** get_remote_settings(), no result data, {errno_message(response)}")
+        output(f"** get_remote_settings(), no result data for {name}, {errno_message(response)}")
         return None
     named_settings[name] = result
     value = result.get('value')
@@ -1053,6 +1135,7 @@ def set_work_mode(mode, force = 0):
 ##################################################################################################
 
 schedule = None
+max_periods = 8
 
 # get the current switch status
 def get_flag():
@@ -1069,7 +1152,7 @@ def get_flag():
     if result is None:
         return None
     if schedule is None:
-        schedule = {'enable': None, 'support': None, 'periods': None, 'maxsoc': False}
+        schedule = {'enable': None, 'support': None, 'periods': None, 'maxsoc': None}
     schedule['enable'] = result.get('enable')
     schedule['support'] = result.get('support')
     if device.get('function') is not None and device['function'].get('scheduler') is not None:
@@ -1090,7 +1173,7 @@ def get_schedule():
         return None
     output(f"getting schedule", 2)
     body = {'deviceSN': device_sn}
-    response = signed_post(path="/op/v1/device/scheduler/get", body=body)
+    response = signed_post(path="/op/v2/device/scheduler/get", body=body)
     if response.status_code != 200:
         output(f"** get_schedule() got response code {response.status_code}: {response.reason}")
         return None
@@ -1103,11 +1186,12 @@ def get_schedule():
         enable = True if enable == 1 else False
     schedule['enable'] = enable
     schedule['periods'] = []
+    schedule['maxsoc'] = False
     # remove invalid work mode from periods
     for g in result['groups']:
         if g['enable'] == 1 and g['workMode'] in work_modes:
             schedule['periods'].append(g)
-            if g.get('maxSoc') is not None:
+            if g.get('extraParam') is not None and g['extraParam'].get('maxSoc') is not None:
                 schedule['maxsoc'] = True
     return schedule
 
@@ -1126,6 +1210,8 @@ def build_strategy_from_schedule():
         period['max_soc'] = p.get('maxSoc')
         period['fdsoc'] = p.get('fdsoc')
         period['fdpwr'] = p.get('fdpwr')
+        period['import_limit'] = p.get('importLimit')
+        period['export_limit'] = p.get('exportLimit')
         strategy.append(period)
     return strategy
 
@@ -1134,9 +1220,9 @@ def build_strategy_from_schedule():
 ##################################################################################################
 
 # create time segment structure. Note: end time is exclusive.
-def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdsoc=None, fdpwr=None, price=None, segment=None, enable=1, quiet=1):
+def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdsoc=None, fdpwr=None, import_limit=None, export_limit=None, price=None, segment=None, enable=1, quiet=1):
     global schedule, device
-    if schedule is None:
+    if schedule is None or schedule.get('maxsoc') is None:
         get_schedule()
     if segment is not None and type(segment) is dict:
         start = segment.get('start')
@@ -1146,6 +1232,8 @@ def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdso
         max_soc = segment.get('max_soc')
         fdsoc = segment.get('fdSoc')
         fdpwr = segment.get('fdPwr')
+        import_limit = segment.get('import_limit')
+        export_limit = segment.get('export_limit')
         price = segment.get('price')
     start = time_hours(start)
     # adjust exclusive time to inclusive
@@ -1166,8 +1254,8 @@ def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdso
     power = (device['power'] * 1000) if device.get('power') is not None else None
     fdpwr = power if fdpwr is None and device.get('power') is not None and ('ForceCharge' in mode or 'ForceDischarge' in mode) else fdpwr
     fdpwr = 0 if fdpwr is None else fdpwr
-    if min_soc < 10 or min_soc > 100:
-        output(f"set_period(): ** min_soc must be between 10 and 100")
+    if min_soc < 0 or min_soc > 100:
+        output(f"set_period(): ** min_soc must be between 0 and 100")
         return None
     if max_soc is not None and (max_soc < 10 or max_soc > 100):
         output(f"set_period(): ** max_soc must be between 10 and 100")
@@ -1187,14 +1275,13 @@ def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdso
     start_hour, start_minute = split_hours(start)
     end_hour, end_minute = split_hours(end)
     period = {'enable': enable, 'startHour': start_hour, 'startMinute': start_minute, 'endHour': end_hour, 'endMinute': end_minute, 'workMode': mode,
-        'minSocOnGrid': int(min_soc), 'fdSoc': int(fdsoc), 'fdPwr': int(fdpwr)}
-    if max_soc is not None:
-        period['maxSoc'] = int(max_soc)
+        'extraParam': {'minSocOnGrid': int(min_soc), 'fdSoc': int(fdsoc), 'fdPwr': int(fdpwr), 'maxSoc': max_soc, 'importLimit': import_limit,
+        'exportLimit': export_limit }}
     return period
 
 # set a schedule from a period or list of time segment periods
 def set_schedule(periods=None, enable=True):
-    global device_sn, debug_setting, schedule
+    global device_sn, debug_setting, schedule, max_periods
     if get_flag() is None:
         return None
     if schedule.get('support') == False:
@@ -1202,6 +1289,7 @@ def set_schedule(periods=None, enable=True):
         return None
     output(f"set_schedule(): enable = {enable}, periods = {periods}", 2)
     if debug_setting > 2:
+        print(f"** schedule not set (debug_setting={debug_setting})")
         return None
     if type(enable) is int:
         enable = True if enable == 1 else False
@@ -1212,11 +1300,11 @@ def set_schedule(periods=None, enable=True):
     if periods is not None:
         if type(periods) is not list:
             periods = [periods]
-        if len(periods) > 8:
-            output(f"** set_schedule(): maximum of 8 periods allowed, {len(periods)} provided")
-        body = {'deviceSN': device_sn, 'groups': periods[-8:]}
+        if len(periods) > max_periods:
+            output(f"** set_schedule(): maximum of {max_periods} periods allowed, {len(periods)} provided")
+        body = {'deviceSN': device_sn, 'groups': periods[-max_periods:]}
         setting_delay()
-        response = signed_post(path="/op/v1/device/scheduler/enable", body=body)
+        response = signed_post(path="/op/v2/device/scheduler/enable", body=body)
         if response.status_code != 200:
             output(f"** set_schedule() periods response code {response.status_code}: {response.reason}")
             return None
@@ -3437,7 +3525,8 @@ def battery_info(log=0, plot=1, rated=None, count=None, info=1, bat=None):
     output(f"Cell Volts:          {avg(cell_volts):.3f}V average, {max(cell_volts):.3f}V maximum, {min(cell_volts):.3f}V minimum")
     output(f"Cell Imbalance:      {imbalance(cell_volts):.2f}%:")
     output(f"BMS Temperature:     {bms_temperature:.1f}°C")
-    output(f"BMS Charge Rate:     {bat.get('charge_rate'):.1f}A (estimated)")
+    if bat.get('charge_rate') is not None:
+        output(f"BMS Charge Rate:     {bat['charge_rate']:.1f}A (estimated)")
     output(f"Battery Temperature: {avg(cell_temps):.1f}°C average, {max(cell_temps):.1f}°C maximum, {min(cell_temps):.1f}°C minimum")
     output(f"\nInfo by battery:")
     for i in range(0, nbat):

foxesscloud-2.9.1/README.md → foxesscloud-2.9.3/src/foxesscloud.egg-info/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.1
+Name: foxesscloud
+Version: 2.9.3
+Summary: library for accessing Fox ESS cloud data using Open API
+Author-email: Tony Matthews <tony@quasair.co.uk>
+Project-URL: Homepage, https://github.com/TonyM1958/FoxESS-Cloud
+Project-URL: Bug Tracker, https://github.com/TonyM1958/FoxESS-Cloud/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENCE
+
 # FoxESS-Cloud
 
 <a href="https://www.buymeacoffee.com/tonym1958" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174" align="right"></a>
@@ -47,6 +61,7 @@ You don't have to configure all of the settings. Your Fox ESS Cloud api key is t
 For example, replace _my.fox_api_key_ with the API key. Add you inverter serial number if you have more than 1 inverter linked to your account. Be sure to keep the double quotes around the values you enter or you will get a syntax error.
 
 Residual handling configures how battery residual energy reported by Fox is handled:
++ 0: Use rated capacity, SoH and SoC to calculate residual energy (default)
 + 1: Fox returns the current battery residual energy and battery capacity is calculated using soc
 + 2: Fox returns the current battery capacity and battery residual is calculated using soc
 + 3: Fox returns the residual capacity per battery (Mira)
@@ -94,8 +109,8 @@ Once an inverter is selected, you can make other calls to get information:
 
 ```
 f.get_generation()
-f.get_battery(info, rated, count)
-f.get_batteries(info, rated, count)
+f.get_battery()
+f.get_batteries(info)
 f.get_settings()
 f.get_charge()
 f.get_min()
@@ -103,17 +118,15 @@ f.get_peakshaving()
 f.get_flag()
 f.get_schedule()
 f.get_named_settings(name)
+f.get_battery_heating()
 
 ```
 Each of these calls will return a dictionary or list containing the relevant information.
 
 get_generation() will return the latest generation information for the device. The results are also stored in f.device as 'generationToday', 'generationMonth' and 'generationTotal'.
 
-get_battery() / get_batteries() returns the current battery status, including 'soc', 'volt', 'current', 'power', 'temperature' and 'residual'. The result also updates f.battery / f.batteries.
-get_batteries() returns multiple batteries (if available) as a list. get_battery() returns the first battery. Parameters:
-+ 'info': get battery serial number info, if available. Default 0 (not available via Open API)
-+ 'rated': optional rated capacity for the battery in Wh to work out SoH. If not provided, it will try to work this out.
-+ 'count': optional battery count. If not provided, it will try to work this out.
+get_battery() / get_batteries() returns the current battery status, including 'soc', 'volt', 'current', 'power', 'temperature', 'residual' and 'throughput'. The result also updates f.battery / f.batteries.
+get_batteries() returns multiple batteries (if available) as a list. get_battery() returns the first battery.
 
 Additional battery attributes provided include:
 + 'capacity': the estimated battery capacity, derrived from 'residual' and 'soc'
@@ -132,8 +145,9 @@ get_schedule() returns the current work mode / soc schedule settings. The result
 
 get_named_settings() returns the value of a named setting. If 'name' is a list, it returns a list of values.
 + f.named_settings is updated. This is dictionary of information and current value, indexed by 'name'.
-+ named_settings currently supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode, WorkMode
++ named_settings currently available are stored in f.name_list. The settings supported depends on the inverter model and firmware version. An error will be returned if an unsupported variable is used.
 
+get_battery_heating returns the current battery heating parameters and store these in f.battery_heating
 
 ## Inverter Settings
 You can change inverter settings using:
@@ -144,6 +158,7 @@ f.set_charge(ch1, st1, en1, ch2, st2, en2, enable)
 f.set_period(start, end, mode, min_soc, max_soc, fdsoc, fdpwr, price, segment)
 f.set_schedule(periods, enable)
 f.set_named_settings(name, value, force)
+f.set_battery_heating(enable, start, end, time1, time2, time3)
 ```
 
 set_min() applies new SoC settings to the inverter. The parameters update battery_settings:
@@ -166,12 +181,16 @@ set_period() returns a period structure that can be used to build a list for set
 + max_soc: optional, default is 100
 + fdsoc: optional, default is 10. Used when setting a period with ForceDischarge mode
 + fdpwr: optional, default is 0. Used when setting a period with ForceDischarge mode
++ import_limit: optional, default is None (not set). Used when setting a period with ForceCharge mode
++ export_limit: optional, default is None (not set). Used when setting a period with ForceDischarge mode
 + price: optional, default None. Used to display plunge pricing for time period.
 + enable: sets whether this time segment is enable (1) or disabled (0). The default is enabled.
 + segment: optional, allows the parameters for the period to be passed as a dictionary instead of individual values.
 
 Before calling set_period(), do at least one call to get_schedule(). This will inspect the schedule result to check if max_soc is supported and set the flag f.schedule['maxsoc'] to enable or disable this field as appropriate.
 
+The variable f.max_periods is used to check the number of time periods allowed. The default is 8.
+
 set_schedule() configures a list of scheduled work mode / soc changes with enable=1. If called with enable=0, any existing schedules are disabled. To enable a schedule, you must provide a list of time segments
 + periods: a time segment or list of time segments created using f.set_period().
 + enable: 1 to enable schedules, 0 to disable schedules. The default is 1.
@@ -180,8 +199,12 @@ set_named_settings() sets the 'name' setting to 'value'.
 + 'name' may also be a list of (name, value) pairs.
 + force: setting to 1 will disable Mode Scheduler, if enabled. Default is 0.
 + a return value of 1 is success. 0 means setting failed. None is another error e.g. device not found, invalid name or value.
-+ named_settings currently supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode, WorkMode
++ named_settings currently available are stored in f.name_list. The settings supported depend on the inverter model and firmware version. An error will be returned if an unsupported varaible is used.
 
+set_battery_heating() set the heating parameters as follows:
++ enable: optional, 0 or 1, default is 1
++ start, end: optional start and end temperatures. The defaults are start at 9C and end at 12C.
++ time1, time2, time3: optional times when the battery can heat from the grid time. The structure is {'enable': 1, 'start': '00:30', 'end': '05:30'}. The time slot is disabled by default.
 
 ## Real Time Data
 Real time data reports the latest values for inverter variables, collected every 5 minutes:
@@ -807,6 +830,19 @@ This setting can be:
 
 # Version Info
 
+2.9.3 - 2026/01/18<br>
+Update get_device() to use v1 API call.
+Update get_battery() to work out battery count and rated capacity from device battery list.
+Update default residual_handling to option 0 (residual is calculated from rated capacity, SoH and SoC).
+Added get_battery_real() for testing (Fox does not currently populate most of the data).
+Added 'throughput' to battery variables returned.
+Add f.name_list to hold the list of setting variables and update the list.
+Added get_battery_heating() and set_battery_heating().
+
+2.9.2 - 2025/11/30<br>
+Update get_schedule(), set_period() and set_schedule() to use v2 interface and add setting import_limit and export_limit.
+Added f.max_periods to allow for more time periods in schedules (default is 8).
+
 2.9.1 - 2025/10/25<br>
 Change default contingency for charge_needed() to [25,15,10,20] and special contingency to 35.
 Update info shown around contingency.