foxesscloud 2.8.6__py3-none-any.whl → 2.8.8__py3-none-any.whl

foxesscloud/foxesscloud.py

@@ -1,7 +1,7 @@
 ##################################################################################################
 """
 Module:   Fox ESS Cloud
-Updated:  21 May 2025
+Updated:  2 October 2025
 By:       Tony Matthews
 """
 ##################################################################################################
@@ -10,7 +10,7 @@ By:       Tony Matthews
 # ALL RIGHTS ARE RESERVED © Tony Matthews 2023
 ##################################################################################################
 
-version = "1.9.6"
+version = "1.9.8"
 print(f"FoxESS-Cloud version {version}")
 
 debug_setting = 1
@@ -653,6 +653,8 @@ def get_battery(info=1, rated=None, count=None):
                     residual_handling = 2
                 elif battery['info']['masterSN'][:7] == '60MBB01' and battery['info']['masterVersion'] >= '1.014':
                     residual_handling = 3
+    if debug_setting > 1:
+        print(f"raw battery = {battery}")
     battery['residual_handling'] = residual_handling
     battery['soh'] = None
     battery['soh_supported'] = False
@@ -910,14 +912,14 @@ def get_min():
         output(f"** get_min(), no result data, {errno_message(errno)}")
         return None
     battery_settings['minSoc'] = result.get('minSoc')
-    battery_settings['minGridSoc'] = result.get('minGridSoc')
+    battery_settings['minSocOnGrid'] = result.get('minGridSoc')
     return battery_settings
 
 ##################################################################################################
 # set min soc from battery_settings or parameters
 ##################################################################################################
 
-def set_min(minGridSoc = None, minSoc = None, force = 0):
+def set_min(minSocOnGrid = None, minSoc = None, force = 0):
     global device_sn, battery_settings, debug_setting, messages
     if get_device() is None:
         return None
@@ -926,16 +928,24 @@ def set_min(minGridSoc = None, minSoc = None, force = 0):
             output(f"** set_min(): cannot set min SoC mode when a schedule is enabled")
             return None
         set_schedule(enable=0)
-    data = {'sn': device_sn}
     if battery_settings is None:
         battery_settings = {}
-    if minGridSoc is not None:
-        data['minGridSoc'] = minGridSoc
-        battery_settings['minGridSoc'] = minGridSoc
+    if minSocOnGrid is not None:
+        if minSocOnGrid < 0 or minSocOnGrid > 100:
+            output(f"** set_min(): invalid minSocOnGrid = {minSocOnGrid}. Must be between 0 and 100")
+            return None
+        battery_settings['minSocOnGrid'] = minSocOnGrid
     if minSoc is not None:
-        data['minSoc'] = minSoc
+        if minSoc < 0 or minSoc > 100:
+            output(f"** set_min(): invalid minSoc = {minSoc}. Must be between 0 and 100")
+            return None
         battery_settings['minSoc'] = minSoc
-    output(f"\nSetting minSoc = {battery_settings.get('minSoc')}, minGridSoc = {battery_settings.get('minGridSoc')}", 1)
+    data = {'sn': device_sn}
+    if battery_settings.get('minSocOnGrid') is not None:
+        data['minGridSoc'] = battery_settings['minSocOnGrid']
+    if battery_settings.get('minSoc') is not None:
+        data['minSoc'] = battery_settings['minSoc']
+    output(f"\nSetting minSocOnGrid = {battery_settings.get('minSocOnGrid')}, minSoc = {battery_settings.get('minSoc')}", 1)
     setting_delay()
     response = signed_post(path="/c/v0/device/battery/soc/set", data=data)
     if response.status_code != 200:
@@ -1417,7 +1427,7 @@ def find_template(name):
 
 # create a period 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, quiet=1):
-    global schedule
+    global schedule, device
     if schedule is None and get_flag() is None:
         return None
     if segment is not None and type(segment) is dict:
@@ -1442,7 +1452,11 @@ def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdso
         return None
     min_soc = 10 if min_soc is None else min_soc
     max_soc = None if schedule.get('maxsoc') is None or schedule['maxsoc'] == False else 100 if max_soc is None else max_soc
+    if mode == 'ForceCharge' and fdsoc is None:
+        fdsoc = max_soc if max_soc is not None else 100
     fdsoc = min_soc if fdsoc is None else fdsoc
+    power = (device['power'] * 1000) if device.get('power') is not None else None
+    fdpwr = power if fdpwr is None and power is not None and mode in ['ForceCharge', 'ForceDischarge'] 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")
@@ -1450,8 +1464,8 @@ def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdso
     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")
         return None
-    if fdpwr < 0 or fdpwr > 6000:
-        output(f"set_period(): ** fdpwr must be between 0 and 6000")
+    if fdpwr < 0 or fdpwr > 30000:
+        output(f"set_period(): ** fdpwr must be between 0 and 30000")
         return None
     if fdsoc < min_soc or fdsoc > 100:
         output(f"set_period(): ** fdsoc must between {min_soc} and 100")
@@ -1459,7 +1473,7 @@ def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdso
     if quiet == 0:
         s = f"   {hours_time(start)}-{hours_time(end)} {mode}, minsoc {min_soc}%"
         s += f", maxsoc {max_soc}%" if max_soc is not None and mode == 'ForceCharge' else ""
-        s += f", fdPwr {fdpwr}W, fdSoC {fdsoc}%" if mode == 'ForceDischarge' else ""
+        s += f", fdPwr {fdpwr}W, fdSoC {fdsoc}%" if mode in ['ForceCharge', 'ForceDischarge'] else ""
         s += f", {price:.2f}p/kWh" if price is not None else ""
         output(s, 1)
     start_h, start_m = split_hours(start)

foxesscloud/openapi.py

@@ -1,7 +1,7 @@
 ##################################################################################################
 """
 Module:   Fox ESS Cloud using Open API
-Updated:  5 July 2025
+Updated:  2 October 2025
 By:       Tony Matthews
 """
 ##################################################################################################
@@ -10,7 +10,7 @@ By:       Tony Matthews
 # ALL RIGHTS ARE RESERVED © Tony Matthews 2024
 ##################################################################################################
 
-version = "2.8.6"
+version = "2.8.8"
 print(f"FoxESS-Cloud Open API version {version}")
 
 debug_setting = 1
@@ -371,9 +371,10 @@ def get_site(name=None):
 
 logger_list = None
 logger = None
+logger_sn = None
 
 def get_logger(sn=None):
-    global logger_list, logger, debug_setting
+    global logger_list, logger, logger_sn, debug_setting
     if get_vars() is None:
         return None
     if logger is not None and sn is None:
@@ -408,8 +409,30 @@ def get_logger(sn=None):
     else:
         n = 0
     logger = logger_list[n]
+    logger_sn = logger.get('moduleSN')
     return logger
 
+def get_signal(sn=None):
+    global logger_list, logger, logger_sn, debug_setting
+    if get_vars() is None:
+        return None
+    if sn is None:
+        if logger_sn is None:
+            get_logger()
+        sn = logger_sn
+        if sn is None:
+            return None
+    output(f"getting signal", 2)
+    body = {'sn': sn}
+    response = signed_post(path="/op/v0/module/getSignal", body=body)
+    if response.status_code != 200:
+        output(f"** get_signal() got response code {response.status_code}: {response.reason}")
+        return None
+    result = response.json().get('result')
+    if result is None:
+        output(f"** get_signal(), no result data, {errno_message(response)}")
+        return None
+    return result
 
 ##################################################################################################
 # get list of devices and select one, using the serial number if there is more than 1
@@ -593,6 +616,8 @@ def get_battery(info=0, v=None, rated=None, count=None):
     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
@@ -798,13 +823,13 @@ def set_min(minSocOnGrid = None, minSoc = None, force = 0):
     if battery_settings is None:
         battery_settings = {}
     if minSocOnGrid is not None:
-        if minSocOnGrid < 10 or minSocOnGrid > 100:
-            output(f"** set_min(): invalid minSocOnGrid = {minSocOnGrid}. Must be between 10 and 100")
+        if minSocOnGrid < 0 or minSocOnGrid > 100:
+            output(f"** set_min(): invalid minSocOnGrid = {minSocOnGrid}. Must be between 0 and 100")
             return None
         battery_settings['minSocOnGrid'] = minSocOnGrid
     if minSoc is not None:
-        if minSoc < 10 or minSoc > 100:
-            output(f"** set_min(): invalid minSoc = {minSoc}. Must be between 10 and 100")
+        if minSoc < 0 or minSoc > 100:
+            output(f"** set_min(): invalid minSoc = {minSoc}. Must be between 0 and 100")
             return None
         battery_settings['minSoc'] = minSoc
     body = {'sn': device_sn}
@@ -812,7 +837,7 @@ def set_min(minSocOnGrid = None, minSoc = None, force = 0):
         body['minSocOnGrid'] = battery_settings['minSocOnGrid']
     if battery_settings.get('minSoc') is not None:
         body['minSoc'] = battery_settings['minSoc']
-    output(f"\nSetting minSoc = {battery_settings.get('minSoc')}, minSocOnGrid = {battery_settings.get('minSocOnGrid')}", 1)
+    output(f"\nSetting minSocOnGrid = {battery_settings.get('minSocOnGrid')}, minSoc = {battery_settings.get('minSoc')}", 1)
     setting_delay()
     response = signed_post(path="/op/v0/device/battery/soc/set", body=body)
     if response.status_code != 200:
@@ -1108,9 +1133,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):
-    global schedule
-    if schedule is None and get_flag() is None:
-        return None
+    global schedule, device
+    if schedule is None:
+        get_schedule()
     if segment is not None and type(segment) is dict:
         start = segment.get('start')
         end = segment.get('end')
@@ -1132,8 +1157,12 @@ def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdso
         output(f"** mode must be one of {work_modes}")
         return None
     min_soc = 10 if min_soc is None else min_soc
-    max_soc = None if schedule.get('maxsoc') is None or schedule['maxsoc'] == False else 100 if max_soc is None else max_soc
+    max_soc = None if schedule is None or schedule.get('maxsoc') is None or schedule['maxsoc'] == False else 100 if max_soc is None else max_soc
+    if mode == 'ForceCharge' and fdsoc is None:
+        fdsoc = max_soc if max_soc is not None else 100
     fdsoc = min_soc if fdsoc is None else fdsoc
+    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 mode in ['ForceCharge', 'ForceDischarge'] 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")
@@ -1141,8 +1170,8 @@ def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdso
     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")
         return None
-    if fdpwr < 0 or fdpwr > 6000:
-        output(f"set_period(): ** fdpwr must be between 0 and 6000")
+    if fdpwr < 0 or fdpwr > 30000:
+        output(f"set_period(): ** fdpwr must be between 0 and 30000")
         return None
     if fdsoc < min_soc or fdsoc > 100:
         output(f"set_period(): ** fdsoc must between {min_soc} and 100")
@@ -1150,7 +1179,7 @@ def set_period(start=None, end=None, mode=None, min_soc=None, max_soc=None, fdso
     if quiet == 0:
         s = f"   {hours_time(start)}-{hours_time(end)} {mode}, minsoc {min_soc}%"
         s += f", maxsoc {max_soc}%" if max_soc is not None and mode == 'ForceCharge' else ""
-        s += f", fdPwr {fdpwr}W, fdSoC {fdsoc}%" if mode == 'ForceDischarge' else ""
+        s += f", fdPwr {fdpwr}W, fdSoC {fdsoc}%" if mode in ['ForceCharge', 'ForceDischarge'] else ""
         s += f", {price:.2f}p/kWh" if price is not None else ""
         output(s, 1)
     start_hour, start_minute = split_hours(start)
@@ -1636,6 +1665,10 @@ def get_report(dimension='day', d=None, v=None, summary=1, save=None, load=None,
         if errno > 0 or result is None or len(result) == 0:
             output(f"** get_report(), no report data available, {errno_message(response)}")
             return None
+        # correct variables in year report (AP 19/09/2025):
+        if dimension == 'year':
+            for i, var in enumerate(result):
+                var['variable'] = v[i]
         # correct errors in report values:
         if fix_values == 1:
             for var in result:

{foxesscloud-2.8.6.dist-info → foxesscloud-2.8.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: foxesscloud
-Version: 2.8.6
+Version: 2.8.8
 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
@@ -63,13 +63,14 @@ For example, replace _my.fox_api_key_ with the API key. Add you inverter serial
 Residual handling configures how battery residual energy reported by Fox is handled:
 + 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)
 
 If a value is set for f.plot_file, any charts created will also be saved to an image file:
 + f.plot_file: the file name to use. The file extension determines the format - .png, .pdf or .svg. If you provide just a filename, each chart will over-write the file. The default is None and disables saving.
 + f.plot_no: if the file name contains ###, this will be replaced by 3 digit plot number that increases for each chart created. The default is 0.
 + f.plot_dpi: sets the image resolution. The default is 150. Reducing this value produces smaller, lower resolution images. Increasing this value produces larger, highe resolution images
 
-If you set f.pushover_user_key to your user_key for pushover.net, a summary from set_tariff(), charge_needed(), set_pvoutput() and battery_info() will be sent to your pushover app.
+If you set f.pushover_user_key to your user_key for [pushover.net](https://pushover.net), a summary from set_tariff(), charge_needed(), set_pvoutput() and battery_info() will be sent to your pushover app.
 
 You can set 'f.storage' to a path to save files to a different location such as cloud storage. The default is to use the current working directory.
 
@@ -90,6 +91,7 @@ Load information about a site, data logger or inverter (device):
 ```
 f.get_site()
 f.get_logger()
+f.get_signal()
 f.get_device()
 ```
 
@@ -98,7 +100,9 @@ By default, this will load the first item in the list provided by the cloud. If
 + Logger: full or partial serial number
 + Inverter: full or partial serial number
 
-When an item is selected, the functions returns a dictionary containing item details and saves these to a global variable (f.site, f.logger, f.device respectively)
+When an item is selected, the functions returns a dictionary containing item details and saves these to a global variable (f.site, f.logger, f.device respectively).
+
+get_signal() is ancillary to get_logger() and returns the current data logger signal strength and time stamp.
 
 Once an inverter is selected, you can make other calls to get information:
 
@@ -142,7 +146,7 @@ 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 current supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode
++ named_settings currently supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode, WorkMode
 
 
 ## Inverter Settings
@@ -152,7 +156,6 @@ You can change inverter settings using:
 f.set_min(minSocOnGrid, minSoc)
 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.charge_periods(st0, en0, st1, en1, st2, en2, min_soc, target_soc, start_soc)
 f.set_schedule(periods, enable)
 f.set_named_settings(name, value, force)
 ```
@@ -160,6 +163,7 @@ f.set_named_settings(name, value, force)
 set_min() applies new SoC settings to the inverter. The parameters update battery_settings:
 + minSocOnGrid: min Soc on Grid setting e.g. 15 = 15%
 + minSoc: min Soc setting e.g. 10 = 10%
++ force: setting to 1 will disable Mode Scheduler, if enabled. Default is 0.
 
 set_charge() takes the charge times from the battery_settings and applies these to the inverter. The parameters are optional and will update battery_settings. You should specify all 3 parameter for a time period:
 + ch1: enable charge from grid for period 1 (default True)
@@ -180,16 +184,7 @@ set_period() returns a period structure that can be used to build a list for set
 + 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.
 
-charge_periods(): returns a list of periods that describe the strategy for the current tariff and adds the periods required for charging:
-+ st0: the start time for period 0 when you don't want the battery to discharge before charging
-+ en0: the end time for period 0
-+ st1: the start time for the period when the battery charges from the grid
-+ en1: the end time for period 1
-+ st2: the start time for period 2 when you don't want the batteru to discharge after charging
-+ en2: the end time for period 2
-+ min_soc: the min_soc to use when building the strategy
-+ start_soc: the min_soc to use for period 0
-+ target_soc: the max_soc to set during period 1 and min_soc to use for period 2
+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.
 
 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().
@@ -197,9 +192,9 @@ set_schedule() configures a list of scheduled work mode / soc changes with enabl
 
 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.
++ 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 current supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode
++ named_settings currently supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode, WorkMode
 
 
 ## Real Time Data
@@ -826,7 +821,18 @@ This setting can be:
 
 # Version Info
 
-2.8.6<br>#
+2.8.8<br>
+Fix problem where Open API returns conflicting variable names when reporting stats by year.
+Update daily template for Saturn Cloud to new YAML format.
+Update set_min() to accept 0 instead of 10.
+
+2.8.7<br>
+Added f.get_signal().
+Updated set_period so you don't have to call get_schedule before.
+Update set_period() to pass fdpwr and fdsoc for ForceCharge and display value.
+Increase max value of fdpwr from 6000 to 30000.
+
+2.8.6<br>
 Update to charge_needed() to get current work mode.
 
 2.8.5<br>

foxesscloud-2.8.8.dist-info/RECORD

@@ -0,0 +1,7 @@
+foxesscloud/foxesscloud.py,sha256=vd3nBwhrqxkRmKMRa6iOXOiFq8Eg4czmv9_NNghiSq0,225903
+foxesscloud/openapi.py,sha256=pgn4e_bVjTr_IWjHoeNFWM1GI3vlpD9dOOCkmpy4Yqg,211084
+foxesscloud-2.8.8.dist-info/LICENCE,sha256=8JF-24QkE8UfdII-g6RaIEvM-PZ9zwaEcxlwYUDMt-4,1079
+foxesscloud-2.8.8.dist-info/METADATA,sha256=zPZSZtAiAyBJPfe93ZsOVTWSFVrIYOYlvkw4Icxil4Y,66133
+foxesscloud-2.8.8.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+foxesscloud-2.8.8.dist-info/top_level.txt,sha256=IWOrKSNZCLU6IDXSX_b4_bqCfbZoWAT4CC0w0Lg7PuU,12
+foxesscloud-2.8.8.dist-info/RECORD,,

foxesscloud-2.8.6.dist-info/RECORD

@@ -1,7 +0,0 @@
-foxesscloud/foxesscloud.py,sha256=_Su3Dcs0CSM2TlbAmCtouM4LkhYfYZ2Bk70eVgZqBJg,225011
-foxesscloud/openapi.py,sha256=ftS5WZ838P3kSbjoHB0Ypcb6MYV-ePGX6nDbhpEpf0I,209702
-foxesscloud-2.8.6.dist-info/LICENCE,sha256=8JF-24QkE8UfdII-g6RaIEvM-PZ9zwaEcxlwYUDMt-4,1079
-foxesscloud-2.8.6.dist-info/METADATA,sha256=YceASwn6QpmzkI1IXtC33PQ-lBW0XWZU6YbmxYj3eMo,65928
-foxesscloud-2.8.6.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-foxesscloud-2.8.6.dist-info/top_level.txt,sha256=IWOrKSNZCLU6IDXSX_b4_bqCfbZoWAT4CC0w0Lg7PuU,12
-foxesscloud-2.8.6.dist-info/RECORD,,