foxesscloud 2.8.5__py3-none-any.whl → 2.8.7__py3-none-any.whl

foxesscloud/foxesscloud.py

@@ -1,7 +1,7 @@
 ##################################################################################################
 """
 Module:   Fox ESS Cloud
-Updated:  21 May 2025
+Updated:  15 September 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.7"
 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
@@ -1417,7 +1419,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 +1444,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 +1456,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 +1465,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:  28 May 2025
+Updated:  15 September 2025
 By:       Tony Matthews
 """
 ##################################################################################################
@@ -10,7 +10,7 @@ By:       Tony Matthews
 # ALL RIGHTS ARE RESERVED © Tony Matthews 2024
 ##################################################################################################
 
-version = "2.8.5"
+version = "2.8.7"
 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
@@ -950,8 +975,6 @@ def get_work_mode():
     global work_mode
     if get_device() is None:
         return None
-    # not implemented by Open API, skip to avoid error
-    return None
     work_mode = get_named_settings('WorkMode')
     return work_mode
 
@@ -1110,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')
@@ -1134,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")
@@ -1143,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")
@@ -1152,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)

{foxesscloud-2.8.5.dist-info → foxesscloud-2.8.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: foxesscloud
-Version: 2.8.5
+Version: 2.8.7
 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)
 ```
@@ -180,16 +183,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().
@@ -199,7 +193,7 @@ 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 current supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode
++ named_settings currently supported include: ExportLimit, MinSoc, MinSocOnGrid, MaxSoc, GridCode, WorkMode
 
 
 ## Real Time Data
@@ -826,6 +820,15 @@ This setting can be:
 
 # Version Info
 
+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>
 Update battery variables to include SOH.
 Add get_peakshaving().

foxesscloud-2.8.7.dist-info/RECORD

@@ -0,0 +1,7 @@
+foxesscloud/foxesscloud.py,sha256=fUB4O3p4UvnHAU2YMzUYh5eunMYjqJu9FpIfE9mPtVE,225412
+foxesscloud/openapi.py,sha256=ZpVcrpMU11FI8oAQlrbhoXCiFGP-ooD6me7D37CbkkE,210915
+foxesscloud-2.8.7.dist-info/LICENCE,sha256=8JF-24QkE8UfdII-g6RaIEvM-PZ9zwaEcxlwYUDMt-4,1079
+foxesscloud-2.8.7.dist-info/METADATA,sha256=XqyaBg9PXtXn82IkUJmvRQ59GFOCgUKUyqtxfvfr1xk,65846
+foxesscloud-2.8.7.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+foxesscloud-2.8.7.dist-info/top_level.txt,sha256=IWOrKSNZCLU6IDXSX_b4_bqCfbZoWAT4CC0w0Lg7PuU,12
+foxesscloud-2.8.7.dist-info/RECORD,,

foxesscloud-2.8.5.dist-info/RECORD

@@ -1,7 +0,0 @@
-foxesscloud/foxesscloud.py,sha256=_Su3Dcs0CSM2TlbAmCtouM4LkhYfYZ2Bk70eVgZqBJg,225011
-foxesscloud/openapi.py,sha256=fRW2f2kIsvib3Y8reYXIegqQBBkMFgqjHhy1n29uzoY,209773
-foxesscloud-2.8.5.dist-info/LICENCE,sha256=8JF-24QkE8UfdII-g6RaIEvM-PZ9zwaEcxlwYUDMt-4,1079
-foxesscloud-2.8.5.dist-info/METADATA,sha256=b5LAyooq_E3GPMcDXEwb-ghyxbYOs4Ughah03NH7I78,65861
-foxesscloud-2.8.5.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-foxesscloud-2.8.5.dist-info/top_level.txt,sha256=IWOrKSNZCLU6IDXSX_b4_bqCfbZoWAT4CC0w0Lg7PuU,12
-foxesscloud-2.8.5.dist-info/RECORD,,