foxesscloud 2.6.0__tar.gz → 2.6.2__tar.gz

{foxesscloud-2.6.0 → foxesscloud-2.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: foxesscloud
-Version: 2.6.0
+Version: 2.6.2
 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
@@ -105,6 +105,7 @@ Once an inverter is selected, you can make other calls to get information:
 ```
 f.get_generation()
 f.get_battery()
+f.get_batteries()
 f.get_settings()
 f.get_charge()
 f.get_min()
@@ -116,8 +117,8 @@ Each of these calls will return a dictionary or list containing the relevant inf
 
 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() returns the current battery status, including 'soc', 'volt', 'current', 'power', 'temperature' and 'residual'. The result also updates f.battery. Additional battery attributes include:
-+ 'info': a list of BMS and battery serial numbers and firmware versions
+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. Additional battery attributes include:
 + 'capacity': the estimated battery capacity, derrived from 'residual' and 'soc'
 + 'charge_rate': the estimated BMS charge rate available, based on the current 'temperature' of the BMS
 + 'charge_loss': the ratio of the kWh added to the battery for each kWh applied during charging
@@ -786,6 +787,18 @@ This setting can be:
 
 # Version Info
 
+2.6.2<br>
+Update battery calibration for charge_needed() when residual_handling is 2.
+Update get_battery() and get_batteries() to include states for ratedCapacity, soh, residual_handling and soh_supported.
+Update charge_compare(), Solcast() and Solar() so date (d) parameter is more flexible.
+
+2.6.1<br>
+Fix problem where battery discharges below min_soc while waiting for charging to start.
+Update calibration for Force Charge with BMS 1.014 and later.
+Add get_batteries() to return a list of BMS and batteries where inverters support more than 1 BMS.
+Update battery_info() to support multiple BMS.
+Add rated capacity and SoH to battery info if available.
+
 2.6.0<br>
 Rework charge de-rating with temperature, losses and other info provided by get_battery() to take new BMS behaviour into account.
 

foxesscloud-2.6.0/src/foxesscloud.egg-info/PKG-INFO → foxesscloud-2.6.2/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.1
-Name: foxesscloud
-Version: 2.6.0
-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>
@@ -105,6 +91,7 @@ Once an inverter is selected, you can make other calls to get information:
 ```
 f.get_generation()
 f.get_battery()
+f.get_batteries()
 f.get_settings()
 f.get_charge()
 f.get_min()
@@ -116,8 +103,8 @@ Each of these calls will return a dictionary or list containing the relevant inf
 
 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() returns the current battery status, including 'soc', 'volt', 'current', 'power', 'temperature' and 'residual'. The result also updates f.battery. Additional battery attributes include:
-+ 'info': a list of BMS and battery serial numbers and firmware versions
+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. Additional battery attributes include:
 + 'capacity': the estimated battery capacity, derrived from 'residual' and 'soc'
 + 'charge_rate': the estimated BMS charge rate available, based on the current 'temperature' of the BMS
 + 'charge_loss': the ratio of the kWh added to the battery for each kWh applied during charging
@@ -786,6 +773,18 @@ This setting can be:
 
 # Version Info
 
+2.6.2<br>
+Update battery calibration for charge_needed() when residual_handling is 2.
+Update get_battery() and get_batteries() to include states for ratedCapacity, soh, residual_handling and soh_supported.
+Update charge_compare(), Solcast() and Solar() so date (d) parameter is more flexible.
+
+2.6.1<br>
+Fix problem where battery discharges below min_soc while waiting for charging to start.
+Update calibration for Force Charge with BMS 1.014 and later.
+Add get_batteries() to return a list of BMS and batteries where inverters support more than 1 BMS.
+Update battery_info() to support multiple BMS.
+Add rated capacity and SoH to battery info if available.
+
 2.6.0<br>
 Rework charge de-rating with temperature, losses and other info provided by get_battery() to take new BMS behaviour into account.
 

{foxesscloud-2.6.0 → foxesscloud-2.6.2}/pyproject.toml

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

{foxesscloud-2.6.0 → foxesscloud-2.6.2}/src/foxesscloud/foxesscloud.py

@@ -1,7 +1,7 @@
 ##################################################################################################
 """
 Module:   Fox ESS Cloud
-Updated:  05 October 2024
+Updated:  12 October 2024
 By:       Tony Matthews
 """
 ##################################################################################################
@@ -10,7 +10,7 @@ By:       Tony Matthews
 # ALL RIGHTS ARE RESERVED © Tony Matthews 2023
 ##################################################################################################
 
-version = "1.7.2"
+version = "1.7.4"
 print(f"FoxESS-Cloud version {version}")
 
 debug_setting = 1
@@ -65,7 +65,7 @@ def plot_show():
 ##################################################################################################
 ##################################################################################################
 
-def query_date(d, offset = None):
+def convert_date(d):
     if d is not None and len(d) < 18:
         if len(d) == 10:
             d += ' 00:00:00'
@@ -76,8 +76,12 @@ def query_date(d, offset = None):
     try:
         t = datetime.now() if d is None else datetime.strptime(d, "%Y-%m-%d %H:%M:%S")
     except Exception as e:
-        output(f"** query_date(): {str(e)}")
+        output(f"** convert_date(): {str(e)}")
         return None
+    return t
+
+def query_date(d, offset = None):
+    t = convert_date(d)
     if offset is not None:
         t += timedelta(days = offset)
     return {'year': t.year, 'month': t.month, 'day': t.day, 'hour': t.hour, 'minute': t.minute, 'second': t.second}
@@ -477,6 +481,7 @@ def get_device(sn=None):
     device_id = device.get('deviceID')
     device_sn = device.get('deviceSN')
     battery = None
+    batteries = None
     battery_settings = None
     schedule = None
     templates = None
@@ -575,6 +580,7 @@ def get_firmware():
 ##################################################################################################
 
 battery = None
+batteries = None
 battery_settings = None
 
 # 1 = Residual Energy, 2 = Residual Capacity
@@ -592,8 +598,8 @@ battery_params = {
     2: {'table': [ 0, 2, 10, 10, 15, 15, 25, 50, 50, 50, 30, 20, 0],
         'step': 5,
         'offset': 5,
-        'charge_loss': 1.040,
-        'discharge_loss': 0.975},
+        'charge_loss': 1.08,
+        'discharge_loss': 0.85},
 }
 
 def get_battery(info=1):
@@ -625,12 +631,16 @@ def get_battery(info=1):
                 errno = response.json().get('errno')
                 output(f"** get_battery().info, no result data, {errno_message(errno)}")
             else:
-                battery['info'] = result['batteries']
-                if battery['info'][0]['masterVersion'] >= '1.014':
+                battery['info'] = result['batteries'][0]
+                if battery['info']['masterVersion'] >= '1.014':
                     residual_handling = 2
+    battery['residual_handling'] = residual_handling
+    battery['rated_capacity'] = None
+    battery['soh'] = None
+    battery['soh_supported'] = False
     if battery.get('residual') is not None:
         battery['residual'] /= 1000
-    if residual_handling == 2:
+    if 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
@@ -641,13 +651,70 @@ def get_battery(info=1):
     battery['capacity'] = round(capacity, 3)
     battery['residual'] = round(residual, 3)
     battery['charge_rate'] = 50
-    params = battery_params[residual_handling]
+    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'] = params['table'][int((battery['temperature'] - params['offset']) / params['step'])]
     return battery
 
+def get_batteries(info=1):
+    global token, device_id, battery, debug_setting, messages, batteries, battery_params, residual_handling
+    if get_device() is None:
+        return None
+    output(f"getting batteries", 2)
+    params = {'id': device_id}
+    response = signed_get(path="/generic/v0/device/battery/info", params=params)
+    if response.status_code != 200:
+        output(f"** get_batteries() got response code {response.status_code}: {response.reason}")
+        return None
+    result = response.json().get('result')
+    if result is None:
+        errno = response.json().get('errno')
+        output(f"** get_batteries(), no result data, {errno_message(errno)}")
+        return None
+    batteries = result['batterys']
+    if info == 1:
+        response = signed_get(path="/generic/v0/device/battery/list", params=params)
+        if response.status_code != 200:
+            output(f"** get_battery().info got response code {response.status_code}: {response.reason}")
+        else:
+            result = response.json().get('result')
+            if result is None:
+                errno = response.json().get('errno')
+                output(f"** get_battery().info, no result data, {errno_message(errno)}")
+            else:
+                for i in range(0, len(batteries)):
+                    batteries[i]['info'] = result['batteries'][i]
+    for b in batteries:
+        if b.get('info') is not None and b['info']['masterVersion'] >= '1.014':
+            b['residual_handling'] = 2
+        if b.get('soh') is not None and b['soh'].isnumeric():
+            b['soh_supported'] = True
+        else:
+            b['rated_capacity'] = None
+            b['soh'] = None
+            b['soh_supported'] = False
+    for b in batteries:
+        if b.get('soh_supported') is not None and b['soh_supported']:
+            capacity = (b['ratedCapacity'] / 1000 * int(b['soh']) / 100)
+            soc = b.get('soc')
+            residual = capacity * soc / 100 if capacity is not None and soc is not None else capacity
+            b['capacity'] = round(capacity, 3)
+            b['residual'] = round(residual, 3)
+            b['charge_rate'] = 50
+            params = battery_params[residual_handling]
+            b['charge_loss'] = params['charge_loss']
+            b['discharge_loss'] = params['discharge_loss']
+            if b.get('temperature') is not None:
+                b['charge_rate'] = params['table'][int((b['temperature'] - params['offset']) / params['step'])]
+        else:
+            get_battery(info=info)
+            batteries = [battery]
+            break
+    battery = batteries[0]
+    return batteries
+
 ##################################################################################################
 # get charge times and save to battery_settings
 ##################################################################################################
@@ -2118,9 +2185,9 @@ def hours_difference(t1, t2):
     if t1 == t2:
         return 0.0
     if type(t1) is str:
-        t1 = datetime.strptime(t1, '%Y-%m-%d %H:%M')
+        t1 = convert_date(t1)
     if type(t2) is str:
-        t2 = datetime.strptime(t2, '%Y-%m-%d %H:%M')
+        t2 = convert_date(t2)
     return round((t1 - t2).total_seconds() / 3600,1)
 
 ##################################################################################################
@@ -2297,7 +2364,7 @@ def get_agile_times(tariff=agile_octopus, d=None):
     if d is not None and len(d) < 11:
         d += " 18:00"
     # get dates and times
-    system_time = (datetime.now(tz=timezone.utc) + timedelta(hours=time_shift)) if d is None else datetime.strptime(d, '%Y-%m-%d %H:%M')
+    system_time = (datetime.now(tz=timezone.utc) + timedelta(hours=time_shift)) if d is None else convert_date(d)
     time_offset = daylight_saving(system_time) if daylight_saving is not None else 0
     # adjust system to get local time now
     now = system_time + timedelta(hours=time_offset)
@@ -2723,7 +2790,7 @@ charge_config = {
     'export_limit': None,             # maximum export power in kW
     'dc_ac_loss': 0.970,              # loss converting battery DC power to AC grid power
     'pv_loss': 0.950,                 # loss converting PV power to DC battery charge power
-    'ac_dc_loss': 0.960,              # loss converting AC grid power to DC battery charge power
+    'ac_dc_loss': 0.963,              # loss converting AC grid power to DC battery charge power
     'inverter_power': 101,            # Inverter power consumption in W
     'bms_power': 50,                  # BMS power consumption in W
     'force_charge_power': 5.00,       # charge power in kW when using force charge
@@ -2768,7 +2835,7 @@ charge_needed_app_key = "awcr5gro2v13oher3v1qu6hwnovp28"
 def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=None, show_plot=None, run_after=None, reload=2,
         forecast_times=None, force_charge=0, test_time=None, test_soc=None, test_charge=None, **settings):
     global device, seasonality, solcast_api_key, debug_setting, tariff, solar_arrays, legend_location, time_shift, charge_needed_app_key
-    global timed_strategy, steps_per_hour, base_time, storage, battery
+    global timed_strategy, steps_per_hour, base_time, storage, battery, charge_rates
     print(f"\n---------------- charge_needed ----------------")
     # validate parameters
     args = locals()
@@ -2796,7 +2863,7 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
     if type(forecast_times) is not list:
         forecast_times = [forecast_times]
     # get dates and times
-    system_time = (datetime.now(tz=timezone.utc) + timedelta(hours=time_shift)) if test_time is None else datetime.strptime(test_time, '%Y-%m-%d %H:%M')
+    system_time = (datetime.now(tz=timezone.utc) + timedelta(hours=time_shift)) if test_time is None else convert_date(test_time)
     time_offset = daylight_saving(system_time) if daylight_saving is not None else 0
     now = system_time + timedelta(hours=time_offset)
     today = datetime.strftime(now, '%Y-%m-%d')
@@ -2848,7 +2915,6 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
     time_to_end = times[0]['time_to_end']
     charge_time = times[0]['charge_time']
     # work out time window and times with clock changes
-    time_to_next = int(time_to_start)
     charge_today = (base_hour + time_to_start / steps_per_hour) < 24
     forecast_day = today if charge_today else tomorrow
     run_to = time_to_end1 if time_to_end < time_to_end1 else time_to_end1 + 24 * steps_per_hour
@@ -2867,17 +2933,17 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
         output(f"start_at = {start_at}, end_by = {end_by}, bat_hold = {bat_hold}")
         output(f"base_hour = {base_hour}, hour_adjustment = {hour_adjustment}, change_hour = {change_hour}, time_change = {time_change}")
         output(f"time_to_start = {time_to_start}, run_time = {run_time}, charge_today = {charge_today}")
-        output(f"time_to_next = {time_to_next}, full_charge = {full_charge}")
+        output(f"full_charge = {full_charge}")
     if test_soc is not None:
         current_soc = test_soc
-        capacity = 14.54
+        capacity = 14.53
         residual = test_soc * capacity / 100
         bat_volt = 317.4
         bat_power = 0.0
         temperature = 30
-        bms_charge_current = 25
-        charge_loss = 1.040
-        discharge_loss = 0.974
+        bms_charge_current = 15
+        charge_loss = charge_rates[2]['charge_loss']
+        discharge_loss = charge_rates[2]['discharge_loss']
         bat_current = 0.0
         device_power = 6.0
         device_current = 35
@@ -2921,10 +2987,11 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
     output(f"  Min SoC:     {min_soc}% ({reserve:.2f}kWh)")
     output(f"  Current SoC: {current_soc}%")
     output(f"  Max SoC:     {max_soc}% ({capacity * max_soc / 100:.2f}kWh)")
-    output(f"  Charge Rate: {bms_charge_current:.1f}A")
+    output(f"  Max Charge:  {bms_charge_current:.1f}A")
     output(f"  Temperature: {temperature:.1f}°C")
     output(f"  Resistance:  {bat_resistance:.2f} ohms")
     output(f"  Nominal OCV: {bat_ocv:.1f}V at {nominal_soc}% SoC")
+    output(f"  Losses:      {charge_loss * 100:.1f}% charge / {discharge_loss * 100:.1f}% discharge")
     # charge current may be derated based on temperature
     charge_current = device_current if charge_config['charge_current'] is None else charge_config['charge_current']
     if charge_current > bms_charge_current:
@@ -3100,7 +3167,7 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
         work_mode_timed[i]['discharge'] = discharge_timed[i]
     # build the battery residual if we don't add any charge and don't limit discharge at min_soc
     kwh_current = residual - (charge_timed[0] - discharge_timed[0]) * (hour_now % 1)
-    (bat_timed, kwh_min) = battery_timed(work_mode_timed, kwh_current, capacity, time_to_next, kwh_min=capacity)
+    (bat_timed, kwh_min) = battery_timed(work_mode_timed, kwh_current, capacity, time_to_next=time_to_end, kwh_min=capacity)
     # work out what we need to add to stay above reserve and provide contingency or to hit target_soc
     contingency = charge_config['special_contingency'] if tomorrow[-5:] in charge_config['special_days'] else charge_config['contingency']
     contingency = contingency[quarter] if type(contingency) is list else contingency
@@ -3178,7 +3245,7 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
                 work_mode_timed[i]['max_soc'] = target_soc if target_soc is not None else max_soc
                 work_mode_timed[i]['discharge'] *= (1-t)
     # rebuild the battery residual with the charge added and min_soc
-    (bat_timed, x) = battery_timed(work_mode_timed, kwh_current, capacity, time_to_next)
+    (bat_timed, x) = battery_timed(work_mode_timed, kwh_current, capacity, time_to_next=start_timed)
     end_residual = interpolate(time_to_end, bat_timed)          # residual when charge time ends
     # show the results
     output(f"  End SoC:     {end_residual / capacity * 100:.0f}% at {hours_time(adjusted_hour(time_to_end, time_line))} ({end_residual:.2f}kWh)")
@@ -3263,10 +3330,10 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
 
 def charge_compare(save=None, v=None, show_data=1, show_plot=3, d=None):
     global charge_config, storage
-    now = datetime.now() if d is None else datetime.strptime(d, '%Y-%m-%d %H:%M')
+    now = convert_date(d)
     yesterday = datetime.strftime(datetime.date(now - timedelta(days=1)), '%Y-%m-%d')
     if save is None and charge_config.get('save') is not None:
-        save = charge_config.get('save').replace('###', yesterday)
+        save = charge_config.get('save').replace('###', yesterday if d is None else d[:10])
         if not os.path.exists(storage + save):
             save = None
     if save is None:
@@ -3293,7 +3360,7 @@ def charge_compare(save=None, v=None, show_data=1, show_plot=3, d=None):
     base_hour = int(time_hours(base_time[11:16]))
     start_day = base_time[:10]
     print(f"Run at {start_day} {hours_time(hour_now)} with SoC {current_soc:.0f}%")
-    now = datetime.strptime(base_time, '%Y-%m-%d %H:%M')
+    now = convert_date(base_time)
     end_day = datetime.strftime(now + timedelta(hours=run_time / steps_per_hour), '%Y-%m-%d')
     if v is None:
         v = ['pvPower', 'loadsPower', 'SoC']
@@ -3326,13 +3393,14 @@ def charge_compare(save=None, v=None, show_data=1, show_plot=3, d=None):
         for i in range(0, run_time):
             plots[v][i] = plots[v][i] / count[v][i] if count[v][i] > 0 else None
     if show_data > 0 and plots.get('SoC') is not None:
-        data_wrap = charge_config['data_wrap'] if charge_config.get('data_wrap') is not None else 6
-        s = f"\nBattery Energy kWh:" if show_data == 2 else f"\nBattery SoC:"
+        data_wrap = 1 #charge_config['data_wrap'] if charge_config.get('data_wrap') is not None else 1
+        s = f"\nBattery Energy kWh (predicted / actual):" if show_data == 2 else f"\nBattery SoC (predicted / actual):"
         h = base_hour
         t = 0
         while t < len(time_line) and bat_timed[t] is not None and plots['SoC'][t] is not None:
             col = h % data_wrap
             s += f"\n  {hours_time(time_line[t])}" if t == 0 or col == 0 else ""
+            s += f" {bat_timed[t]:5.2f}" if show_data == 2 else f"  {bat_timed[t] / capacity * 100:3.0f}%"
             s += f" {plots['SoC'][t]:5.2f}" if show_data == 2 else f"  {plots['SoC'][t] / capacity * 100:3.0f}%"
             h += 1
             t += steps_per_hour
@@ -3411,21 +3479,28 @@ def bat_count(cell_count):
 battery_info_app_key = "aug938dqt5cbqhvq69ixc4v39q6wtw"
 
 # show information about the current state of the batteries
-def battery_info(log=0, plot=1, count=None, info=1):
-    global debug_setting, battery_info_app_key, residual_handling
-    output_spool(battery_info_app_key)
-    bat = get_battery(info=info)
+def battery_info(log=0, plot=1, count=None, info=1, bat=None):
+    global debug_setting, battery_info_app_key
     if bat is None:
-        output_close()
+        bats = get_batteries(info=info)
+        if bats is None:
+            return None
+        for i in range(0, len(bats)):
+            output(f"\n----------------------- BMS {i+1} -----------------------")
+            battery_info(log=log, plot=plot, count=count, info=info, bat=bats[i])
         return None
+    output_spool(battery_info_app_key)
     nbat = None
     if info == 1 and bat.get('info') is not None:
-        for b in bat['info']:
-            output(f"\nSN {b['masterSN']}, {b['masterBatType']}, Version {b['masterVersion']} (BMS)")
-            nbat = 0
-            for s in b['slaveBatteries']:
-                nbat += 1
-                output(f"SN {s['sn']}, {s['batType']}, Version {s['version']} (Battery {nbat})")
+        b = bat['info']
+        output(f"SN {b['masterSN']}, {b['masterBatType']}, Version {b['masterVersion']} (BMS)")
+        nbat = 0
+        for s in b['slaveBatteries']:
+            nbat += 1
+            output(f"SN {s['sn']}, {s['batType']}, Version {s['version']} (Battery {nbat})")
+        output()
+    rated_capacity = bat.get('ratedCapacity')
+    bat_soh = bat.get('soh')
     bat_volt = bat['volt']
     current_soc = bat['soc']
     residual = bat['residual']
@@ -3476,9 +3551,12 @@ def battery_info(log=0, plot=1, count=None, info=1):
                 for v in cell_temps:
                     s +=f",{v:.0f}"
         return s
-    output(f"\nCurrent SoC:         {current_soc}%")
+    if rated_capacity is not None:
+        output(f"Rated Capacity:      {rated_capacity / 1000:.2f}kWh")
+        output(f"SoH:                 {bat_soh}%")
+    output(f"Current SoC:         {current_soc}%")
     output(f"Capacity:            {capacity:.2f}kWh")
-    output(f"Residual:            {residual:.2f}kWh")
+    output(f"Residual:            {residual:.2f}kWh" + (" (SoC x Capacity)" if bat['residual_handling'] == 2 else ""))
     output(f"InvBatVolt:          {bat_volt:.1f}V")
     output(f"InvBatCurrent:       {bat_current:.1f}A")
     output(f"State:               {'Charging' if bat_power < 0 else 'Discharging'} ({abs(bat_power):.3f}kW)")
@@ -3888,7 +3966,7 @@ class Solcast :
         # The forecasts and estimated also both include the current time, so the data has to be de-duplicated to get an accurate total for a day
         global debug_setting, solcast_url, solcast_api_key, solcast_save, storage
         self.data = {}
-        now = datetime.now() if d is None else datetime.strptime(d, '%Y-%m-%d %H:%M')
+        now = convert_date(d)
         self.shading = None if shading is None else shading if shading.get('solcast') is None else shading['solcast'] 
         self.today = datetime.strftime(datetime.date(now), '%Y-%m-%d')
         self.quarter = int(self.today[5:7]) // 3 % 4
@@ -4232,7 +4310,7 @@ class Solar :
     def __init__(self, reload=0, quiet=False, shading=None, d=None):
         global solar_arrays, solar_save, solar_total, solar_url, solar_api_key, storage
         self.shading = None if shading is None else shading if shading.get('solar') is None else shading['solar'] 
-        now = datetime.now() if d is None else datetime.strptime(d, '%Y-%m-%d %H:%M')
+        now = convert_date(d)
         self.today = datetime.strftime(datetime.date(now), '%Y-%m-%d')
         self.quarter = int(self.today[5:7]) // 3 % 4
         self.tomorrow = datetime.strftime(datetime.date(now + timedelta(days=1)), '%Y-%m-%d')

{foxesscloud-2.6.0 → foxesscloud-2.6.2}/src/foxesscloud/openapi.py

@@ -1,7 +1,7 @@
 ##################################################################################################
 """
 Module:   Fox ESS Cloud using Open API
-Updated:  05 October 2024
+Updated:  12 October 2024
 By:       Tony Matthews
 """
 ##################################################################################################
@@ -10,7 +10,7 @@ By:       Tony Matthews
 # ALL RIGHTS ARE RESERVED © Tony Matthews 2024
 ##################################################################################################
 
-version = "2.6.0"
+version = "2.6.2"
 print(f"FoxESS-Cloud Open API version {version}")
 
 debug_setting = 1
@@ -66,8 +66,7 @@ def plot_show():
 ##################################################################################################
 ##################################################################################################
 
-# return query date as a dictionary with year, month, day, hour, minute, second
-def query_date(d, offset = None):
+def convert_date(d):
     if d is not None and len(d) < 18:
         if len(d) == 10:
             d += ' 00:00:00'
@@ -78,8 +77,13 @@ def query_date(d, offset = None):
     try:
         t = datetime.now() if d is None else datetime.strptime(d, "%Y-%m-%d %H:%M:%S")
     except Exception as e:
-        output(f"** query_date(): {str(e)}")
+        output(f"** convert_date(): {str(e)}")
         return None
+    return t
+
+# return query date as a dictionary with year, month, day, hour, minute, second
+def query_date(d, offset = None):
+    t = convert_date(d)
     if offset is not None:
         t += timedelta(days = offset)
     return {'year': t.year, 'month': t.month, 'day': t.day, 'hour': t.hour, 'minute': t.minute, 'second': t.second}
@@ -94,7 +98,7 @@ def query_time(d, time_span):
         else:
             d += ':00'
     try:
-        t = datetime.now().replace(minute=0, second=0, microsecond=0) if d is None else datetime.strptime(d, "%Y-%m-%d %H:%M:%S")
+        t = datetime.now().replace(minute=0, second=0, microsecond=0) if d is None else convert_date(d)
     except Exception as e:
         output(f"** query_time(): {str(e)}")
         return (None, None)
@@ -469,6 +473,7 @@ def get_device(sn=None):
         return None
     device = result
     battery = None
+    batteries = None
     battery_settings = None
     schedule = None
     get_flag()
@@ -538,6 +543,7 @@ def get_generation(update=1):
 ##################################################################################################
 
 battery = None
+batteries = None
 battery_settings = None
 battery_vars = ['SoC', 'invBatVolt', 'invBatCurrent', 'invBatPower', 'batTemperature', 'ResidualEnergy' ]
 battery_data = ['soc', 'volt', 'current', 'power', 'temperature', 'residual']
@@ -557,11 +563,11 @@ battery_params = {
     2: {'table': [ 0, 2, 10, 10, 15, 15, 25, 50, 50, 50, 30, 20, 0],
         'step': 5,
         'offset': 5,
-        'charge_loss': 1.040,
-        'discharge_loss': 0.975},
+        'charge_loss': 1.080,
+        'discharge_loss': 0.85},
 }
 
-def get_battery(v = None, info=0):
+def get_battery(info=0, v=None):
     global device_sn, battery, debug_setting, residual_handling, battery_params
     if get_device() is None:
         return None
@@ -573,7 +579,11 @@ def get_battery(v = None, info=0):
         battery = {}
     for i in range(0, len(battery_vars)):
         battery[battery_data[i]] = result[i].get('value')
-    if residual_handling == 2:
+    battery['residual_handling'] = residual_handling
+    battery['rated_capacity'] = None
+    battery['soh'] = None
+    battery['soh_supported'] = False
+    if 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
@@ -585,13 +595,19 @@ def get_battery(v = None, info=0):
     battery['residual'] = round(residual, 3)
     battery['status'] = 1
     battery['charge_rate'] = 50
-    params = battery_params[residual_handling]
+    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'] = params['table'][int((battery['temperature'] - params['offset']) / params['step'])]
     return battery
 
+def get_batteries(info=0):
+    global battery, batteries
+    get_battery(info=info)
+    batteries = [battery]
+    return batteries
+
 ##################################################################################################
 # get charge times and save to battery_settings
 ##################################################################################################
@@ -1974,9 +1990,9 @@ def hours_difference(t1, t2):
     if t1 == t2:
         return 0.0
     if type(t1) is str:
-        t1 = datetime.strptime(t1, '%Y-%m-%d %H:%M')
+        t1 = convert_date(t1)
     if type(t2) is str:
-        t2 = datetime.strptime(t2, '%Y-%m-%d %H:%M')
+        t2 = convert_date(t2)
     return round((t1 - t2).total_seconds() / 3600,1)
 
 ##################################################################################################
@@ -2153,7 +2169,7 @@ def get_agile_times(tariff=agile_octopus, d=None):
     if d is not None and len(d) < 11:
         d += " 18:00"
     # get dates and times
-    system_time = (datetime.now(tz=timezone.utc) + timedelta(hours=time_shift)) if d is None else datetime.strptime(d, '%Y-%m-%d %H:%M')
+    system_time = (datetime.now(tz=timezone.utc) + timedelta(hours=time_shift)) if d is None else convert_date(d)
     time_offset = daylight_saving(system_time) if daylight_saving is not None else 0
     # adjust system to get local time now
     now = system_time + timedelta(hours=time_offset)
@@ -2579,7 +2595,7 @@ charge_config = {
     'export_limit': None,             # maximum export power in kW
     'dc_ac_loss': 0.97,               # loss converting battery DC power to AC grid power
     'pv_loss': 0.95,                  # loss converting PV power to DC battery charge power
-    'ac_dc_loss': 0.962,              # loss converting AC grid power to DC battery charge power
+    'ac_dc_loss': 0.963,              # loss converting AC grid power to DC battery charge power
     'inverter_power': 101,            # Inverter power consumption in W
     'bms_power': 50,                  # BMS power consumption in W
     'force_charge_power': 5.00,       # charge power in kW when using force charge
@@ -2624,7 +2640,7 @@ charge_needed_app_key = "awcr5gro2v13oher3v1qu6hwnovp28"
 def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=None, show_plot=None, run_after=None, reload=2,
         forecast_times=None, force_charge=0, test_time=None, test_soc=None, test_charge=None, **settings):
     global device, seasonality, solcast_api_key, debug_setting, tariff, solar_arrays, legend_location, time_shift, charge_needed_app_key
-    global timed_strategy, steps_per_hour, base_time, storage, battery
+    global timed_strategy, steps_per_hour, base_time, storage, battery, charge_rates
     print(f"\n---------------- charge_needed ----------------")
     # validate parameters
     args = locals()
@@ -2652,7 +2668,7 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
     if type(forecast_times) is not list:
         forecast_times = [forecast_times]
     # get dates and times
-    system_time = (datetime.now(tz=timezone.utc) + timedelta(hours=time_shift)) if test_time is None else datetime.strptime(test_time, '%Y-%m-%d %H:%M')
+    system_time = (datetime.now(tz=timezone.utc) + timedelta(hours=time_shift)) if test_time is None else convert_date(test_time)
     time_offset = daylight_saving(system_time) if daylight_saving is not None else 0
     now = system_time + timedelta(hours=time_offset)
     today = datetime.strftime(now, '%Y-%m-%d')
@@ -2704,7 +2720,6 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
     time_to_end = times[0]['time_to_end']
     charge_time = times[0]['charge_time']
     # work out time window and times with clock changes
-    time_to_next = int(time_to_start)
     charge_today = (base_hour + time_to_start / steps_per_hour) < 24
     forecast_day = today if charge_today else tomorrow
     run_to = time_to_end1 if time_to_end < time_to_end1 else time_to_end1 + 24 * steps_per_hour
@@ -2723,7 +2738,7 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
         output(f"start_at = {start_at}, end_by = {end_by}, force_charge = {force_charge}")
         output(f"base_hour = {base_hour}, hour_adjustment = {hour_adjustment}, change_hour = {change_hour}, time_change = {time_change}")
         output(f"time_to_start = {time_to_start}, run_time = {run_time}, charge_today = {charge_today}")
-        output(f"time_to_next = {time_to_next}, full_charge = {full_charge}")
+        output(f"full_charge = {full_charge}")
     if test_soc is not None:
         current_soc = test_soc
         capacity = 14.54
@@ -2731,9 +2746,9 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
         bat_volt = 317.4
         bat_power = 0.0
         temperature = 30
-        bms_charge_current = 25
-        charge_loss = 1.040
-        discharge_loss = 0.974
+        bms_charge_current = 15
+        charge_loss = charge_rates[2]['charge_loss']
+        discharge_loss = charge_rates[2]['discharge_loss']
         bat_current = 0.0
         device_power = 6.0
         device_current = 35
@@ -2778,7 +2793,7 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
     output(f"  Current SoC: {current_soc}%")
     output(f"  Max SoC:     {max_soc}% ({capacity * max_soc / 100:.2f}kWh)")
     output(f"  Temperature: {temperature:.1f}°C")
-    output(f"  Charge Rate: {bms_charge_current:.1f}A")
+    output(f"  Max Charge:  {bms_charge_current:.1f}A")
     output(f"  Resistance:  {bat_resistance:.2f} ohms")
     output(f"  Nominal OCV: {bat_ocv:.1f}V at {nominal_soc}% SoC")
     # charge current may be derated based on temperature
@@ -2955,7 +2970,7 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
         work_mode_timed[i]['discharge'] = discharge_timed[i]
     # build the battery residual if we don't add any charge and don't limit discharge at min_soc
     kwh_current = residual - (charge_timed[0] - discharge_timed[0]) * (hour_now % 1)
-    (bat_timed, kwh_min) = battery_timed(work_mode_timed, kwh_current, capacity, time_to_next, kwh_min=capacity)
+    (bat_timed, kwh_min) = battery_timed(work_mode_timed, kwh_current, capacity, time_to_next=time_to_end, kwh_min=capacity)
     # work out what we need to add to stay above reserve and provide contingency or to hit target_soc
     contingency = charge_config['special_contingency'] if tomorrow[-5:] in charge_config['special_days'] else charge_config['contingency']
     contingency = contingency[quarter] if type(contingency) is list else contingency
@@ -3033,7 +3048,7 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
                 work_mode_timed[i]['max_soc'] = target_soc if target_soc is not None else max_soc
                 work_mode_timed[i]['discharge'] *= (1-t)
     # rebuild the battery residual with any charge added and min_soc
-    (bat_timed, x) = battery_timed(work_mode_timed, kwh_current, capacity, time_to_next)
+    (bat_timed, x) = battery_timed(work_mode_timed, kwh_current, capacity, time_to_next=start_timed)
     end_residual = interpolate(time_to_end, bat_timed)          # residual when charge time ends
     # show the results
     output(f"  End SoC:     {end_residual / capacity * 100:.0f}% at {hours_time(adjusted_hour(time_to_end, time_line))} ({end_residual:.2f}kWh)")
@@ -3117,10 +3132,10 @@ def charge_needed(forecast=None, update_settings=0, timed_mode=None, show_data=N
 
 def charge_compare(save=None, v=None, show_data=1, show_plot=3):
     global charge_config, storage
-    now = datetime.now() if d is None else datetime.strptime(d, '%Y-%m-%d %H:%M')
+    now = convert_date(d)
     yesterday = datetime.strftime(datetime.date(now - timedelta(days=1)), '%Y-%m-%d')
     if save is None and charge_config.get('save') is not None:
-        save = charge_config.get('save').replace('###', yesterday)
+        save = charge_config.get('save').replace('###', yesterday if d is None else d[:10])
         if not os.path.exists(storage + save):
             save = None
     if save is None:
@@ -3147,7 +3162,7 @@ def charge_compare(save=None, v=None, show_data=1, show_plot=3):
     base_hour = int(time_hours(base_time[11:16]))
     start_day = base_time[:10]
     print(f"Run at {start_day} {hours_time(hour_now)} with SoC {current_soc:.0f}%")
-    now = datetime.strptime(base_time, '%Y-%m-%d %H:%M')
+    now = convert_date(base_time)
     end_day = datetime.strftime(now + timedelta(hours=run_time / steps_per_hour), '%Y-%m-%d')
     if v is None:
         v = ['pvPower', 'loadsPower', 'SoC']
@@ -3264,21 +3279,28 @@ def bat_count(cell_count):
 battery_info_app_key = "aug938dqt5cbqhvq69ixc4v39q6wtw"
 
 # show information about the current state of the batteries
-def battery_info(log=0, plot=1, count=None, info=1):
-    global debug_setting, battery_info_app_key, residual_handling
-    output_spool(battery_info_app_key)
-    bat = get_battery(info=info)
+def battery_info(log=0, plot=1, count=None, info=1, bat=None):
+    global debug_setting, battery_info_app_key
     if bat is None:
-        output_close()
+        bats = get_batteries(info=info)
+        if bats is None:
+            return None
+        for i in range(0, len(bats)):
+            output(f"\n----------------------- BMS {i+1} -----------------------")
+            battery_info(log=log, plot=plot, count=count, info=info, bat=bats[i])
         return None
+    output_spool(battery_info_app_key)
     nbat = None
     if info == 1 and bat.get('info') is not None:
-        for b in bat['info']:
-            output(f"\nSN {b['masterSN']}, {b['masterBatType']}, Version {b['masterVersion']} (BMS)")
-            nbat = 0
-            for s in b['slaveBatteries']:
-                nbat += 1
-                output(f"SN {s['sn']}, {s['batType']}, Version {s['version']} (Battery {nbat})")
+        b = bat['info']
+        output(f"SN {b['masterSN']}, {b['masterBatType']}, Version {b['masterVersion']} (BMS)")
+        nbat = 0
+        for s in b['slaveBatteries']:
+            nbat += 1
+            output(f"SN {s['sn']}, {s['batType']}, Version {s['version']} (Battery {nbat})")
+        output()
+    rated_capacity = bat.get('ratedCapacity')
+    bat_soh = bat.get('soh')
     bat_volt = bat['volt']
     current_soc = bat['soc']
     residual = bat['residual']
@@ -3329,7 +3351,10 @@ def battery_info(log=0, plot=1, count=None, info=1):
                 for v in cell_temps:
                     s +=f",{v:.0f}"
         return s
-    output(f"\nCurrent SoC:         {current_soc}%")
+    if rated_capacity is not None:
+        output(f"Rated Capacity:      {rated_capacity / 1000:.2f}kWh")
+        output(f"SoH:                 {bat_soh}%")
+    output(f"Current SoC:         {current_soc}%")
     output(f"Capacity:            {capacity:.2f}kWh")
     output(f"Residual:            {residual:.2f}kWh")
     output(f"InvBatVolt:          {bat_volt:.1f}V")
@@ -3741,7 +3766,7 @@ class Solcast :
         # The forecasts and estimated also both include the current time, so the data has to be de-duplicated to get an accurate total for a day
         global debug_setting, solcast_url, solcast_api_key, solcast_save, storage
         self.data = {}
-        now = datetime.now() if d is None else datetime.strptime(d, '%Y-%m-%d %H:%M')
+        now = convert_date(d)
         self.shading = None if shading is None else shading if shading.get('solcast') is None else shading['solcast'] 
         self.today = datetime.strftime(datetime.date(now), '%Y-%m-%d')
         self.quarter = int(self.today[5:7]) // 3 % 4
@@ -4085,7 +4110,7 @@ class Solar :
     def __init__(self, reload=0, quiet=False, shading=None, d=None):
         global solar_arrays, solar_save, solar_total, solar_url, solar_api_key, storage
         self.shading = None if shading is None else shading if shading.get('solar') is None else shading['solar'] 
-        now = datetime.now() if d is None else datetime.strptime(d, '%Y-%m-%d %H:%M')
+        now = convert_date(d)
         self.today = datetime.strftime(datetime.date(now), '%Y-%m-%d')
         self.quarter = int(self.today[5:7]) // 3 % 4
         self.tomorrow = datetime.strftime(datetime.date(now + timedelta(days=1)), '%Y-%m-%d')

foxesscloud-2.6.0/README.md → foxesscloud-2.6.2/src/foxesscloud.egg-info/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.1
+Name: foxesscloud
+Version: 2.6.2
+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>
@@ -91,6 +105,7 @@ Once an inverter is selected, you can make other calls to get information:
 ```
 f.get_generation()
 f.get_battery()
+f.get_batteries()
 f.get_settings()
 f.get_charge()
 f.get_min()
@@ -102,8 +117,8 @@ Each of these calls will return a dictionary or list containing the relevant inf
 
 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() returns the current battery status, including 'soc', 'volt', 'current', 'power', 'temperature' and 'residual'. The result also updates f.battery. Additional battery attributes include:
-+ 'info': a list of BMS and battery serial numbers and firmware versions
+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. Additional battery attributes include:
 + 'capacity': the estimated battery capacity, derrived from 'residual' and 'soc'
 + 'charge_rate': the estimated BMS charge rate available, based on the current 'temperature' of the BMS
 + 'charge_loss': the ratio of the kWh added to the battery for each kWh applied during charging
@@ -772,6 +787,18 @@ This setting can be:
 
 # Version Info
 
+2.6.2<br>
+Update battery calibration for charge_needed() when residual_handling is 2.
+Update get_battery() and get_batteries() to include states for ratedCapacity, soh, residual_handling and soh_supported.
+Update charge_compare(), Solcast() and Solar() so date (d) parameter is more flexible.
+
+2.6.1<br>
+Fix problem where battery discharges below min_soc while waiting for charging to start.
+Update calibration for Force Charge with BMS 1.014 and later.
+Add get_batteries() to return a list of BMS and batteries where inverters support more than 1 BMS.
+Update battery_info() to support multiple BMS.
+Add rated capacity and SoH to battery info if available.
+
 2.6.0<br>
 Rework charge de-rating with temperature, losses and other info provided by get_battery() to take new BMS behaviour into account.