fix(sunsynk): pvMaxLimit is the export cap, not the inverter limit

Sunsynk's documentation (checked by the system owner) confirms the app's
"Inverter Power Limiter" control limits EXPORT despite its label - which is
why the app shows the same value under that name in System Mode and as
"Export power limiter" in Grid Settings, and why pvMaxLimit was the only
settings field holding the 7000 both screens displayed.

So the two limits swap owners:
  inverter_limit -> ratePower  (8000W) - the inverter can still deliver its
                                full rating to the house, so reducing it by
                                the export cap would under-rate
                                self-consumption
  export_limit   -> pvMaxLimit (7000W), bounded by the rating - previously
                                unmapped, leaving inverter.py's effectively
                                unlimited 99999W default in place

That default is the reason this matters: a G98/G99 site capped at 3.68kW
behind a much larger inverter would otherwise have Predbat plan exports the
inverter simply clips.

Tests pin both directions: the rating is not reduced by the cap, the cap is
not raised above the rating, and the G98 case survives intact.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: springfall2008

apps/predbat/sunsynk.py

@@ -44,7 +44,7 @@
     SUNSYNK_CAPACITY_AH_FIELD,
     SUNSYNK_CHARGE_VOLT_FIELD,
     SUNSYNK_CHARGE_CURRENT_FIELDS,
-    SUNSYNK_POWER_LIMIT_FIELD,
+    SUNSYNK_EXPORT_LIMIT_FIELD,
     SUNSYNK_RATED_POWER_FIELD,
     SUNSYNK_BATTERY_LOW_CAP_FIELD,
     LIFEPO4_CELL_COUNTS,
@@ -583,15 +583,26 @@ def battery_rate_max(self, sn):
         return amps * volts
 
     def inverter_limit(self, sn):
-        """Return the inverter's usable AC limit in watts, or 0 when unknown.
+        """Return the inverter's AC power rating in watts, or 0 when unknown.
 
-        The hardware rating (ratePower) is not the whole story: an installer-set power
-        limiter (pvMaxLimit) can cap the inverter below it, and that cap is what actually
-        binds. A real system was seen with ratePower 8000 and pvMaxLimit 7000, so taking the
-        rating alone would have Predbat plan a kilowatt the inverter will never deliver.
-        Whichever is lower wins; if only one is known, that one is used.
+        This is the hardware rating (ratePower) only. It is deliberately NOT reduced by
+        pvMaxLimit: despite that setting's "Inverter Power Limiter" label in the app, Sunsynk
+        documents it as an EXPORT cap, so the inverter can still deliver its full rating to
+        the house. See export_limit.
         """
-        limits = [value for value in (self.device_rated_power.get(sn, 0.0), self._as_float(self.device_settings.get(sn, {}).get(SUNSYNK_POWER_LIMIT_FIELD))) if value > 0]
+        return self.device_rated_power.get(sn, 0.0)
+
+    def export_limit(self, sn):
+        """Return the maximum export power in watts, or 0 when unknown.
+
+        Predbat's inverter.py defaults export_limit to 99999W - effectively unlimited - so
+        leaving this unmapped lets it plan an export the inverter will simply clip. A real
+        system had a 7000W export cap behind an 8000W inverter.
+
+        Bounded by the inverter rating too: whatever the setting nominally allows, the
+        inverter cannot export more AC than it can produce.
+        """
+        limits = [value for value in (self.inverter_limit(sn), self._as_float(self.device_settings.get(sn, {}).get(SUNSYNK_EXPORT_LIMIT_FIELD))) if value > 0]
         return min(limits) if limits else 0.0
 
     def battery_reserve_min(self, sn):
@@ -974,6 +985,9 @@ async def publish_data(self):
             rated_power = self.inverter_limit(sn)
             if rated_power > 0:
                 self.dashboard_item(self._sensor_name(sn, "inverter_limit"), state=rated_power, attributes={"unit_of_measurement": "W", "friendly_name": f"Sunsynk {sn} Inverter Limit"}, app="sunsynk")
+            export_cap = self.export_limit(sn)
+            if export_cap > 0:
+                self.dashboard_item(self._sensor_name(sn, "export_limit"), state=export_cap, attributes={"unit_of_measurement": "W", "friendly_name": f"Sunsynk {sn} Export Limit"}, app="sunsynk")
             floor = self.battery_reserve_min(sn)
             if floor > 0:
                 self.dashboard_item(self._sensor_name(sn, "battery_reserve_min"), state=floor, attributes={"unit_of_measurement": "%", "friendly_name": f"Sunsynk {sn} Battery Reserve Min"}, app="sunsynk")
@@ -1343,20 +1357,15 @@ async def automatic_config(self):
             self.set_arg_auto("inverter_limit", [self._sensor_name(sn, "inverter_limit") for sn in devices])
         else:
             self.log("Warn: Sunsynk no ratePower reported, inverter_limit must be set manually in apps.yaml")
-        # export_limit is deliberately NOT auto-mapped. The Sunsynk app has an "Export power
-        # limiter" in Grid Settings which can legitimately sit BELOW the inverter limit -
-        # a G98/G99 site is commonly capped at 3.68kW behind a much larger inverter - but no
-        # settings field could be identified that carries it: on the one system inspected the
-        # app showed 7000 for both the inverter and export limiters while pvMaxLimit was the
-        # only field holding 7000, so the two could not be told apart.
-        #
-        # Guessing it from pvMaxLimit would be worse than leaving it alone, because
-        # set_arg_auto always beats apps.yaml: a user who correctly set export_limit to their
-        # real 3.68kW cap would have it silently replaced by the inverter limit. Left unset,
-        # Predbat keeps its own default and the user's apps.yaml value is honoured.
-        self.log(
-            "Info: Sunsynk cannot identify the inverter's export power limiter from the settings object, so export_limit is left for apps.yaml. If your Export power limiter (app: Grid Settings) is lower than the inverter limit - a G98/G99 export cap, for instance - set export_limit manually."
-        )
+        # Without this Predbat falls back to inverter.py's effectively unlimited 99999W
+        # default and plans exports the inverter simply clips. pvMaxLimit is the export cap
+        # despite its "Inverter Power Limiter" label in the app - a G98/G99 site capped at
+        # 3.68kW behind a much larger inverter is exactly the case this protects.
+        # See SUNSYNK_EXPORT_LIMIT_FIELD.
+        if all(self.export_limit(sn) > 0 for sn in self.device_list):
+            self.set_arg_auto("export_limit", [self._sensor_name(sn, "export_limit") for sn in devices])
+        else:
+            self.log("Warn: Sunsynk no export power limit available, export_limit must be set manually in apps.yaml")
         if all(self.battery_reserve_min(sn) > 0 for sn in self.device_list):
             self.set_arg_auto("battery_min_soc", [self._sensor_name(sn, "battery_reserve_min") for sn in devices])
 

apps/predbat/sunsynk_const.py

@@ -167,14 +167,16 @@ def encode_setting(name, value):
 # 8000 with pvMaxLimit 7000, so using the rating alone would have Predbat plan a kilowatt
 # the inverter will never deliver.
 #
-# This is the INVERTER limit (confirmed by the system owner). The Sunsynk app surfaces the
-# same 7000 under two labels with an identical 500-16000W range - "Inverter Power Limiter"
-# (System Mode) and "Export power limiter" (Grid Settings) - and pvMaxLimit is the only
-# settings field holding 7000, so one register is evidently shown on both screens. It
-# therefore backs both inverter_limit and export_limit.
+# The EXPORT limit. The Sunsynk app shows this same value under two labels with an identical
+# 500-16000W range - "Inverter Power Limiter" (System Mode) and "Export power limiter" (Grid
+# Settings) - which is why pvMaxLimit was the only field holding the 7000 both screens
+# displayed. Per Sunsynk's documentation (confirmed by the system owner) the control despite
+# its System Mode label caps EXPORT, not the inverter's AC output: the inverter can still
+# deliver its full ratePower to the house. So this backs export_limit, and inverter_limit
+# stays on ratePower.
 #
 # Not to be confused with solarMaxSellPower (SUNSYNK_MAX_SOLAR_FIELD), a separate setting.
-SUNSYNK_POWER_LIMIT_FIELD = "pvMaxLimit"  # settings, watts
+SUNSYNK_EXPORT_LIMIT_FIELD = "pvMaxLimit"  # settings, watts
 
 # Grid import cap - "Import power limiter" in the app's Grid Settings. CONFIRMED live:
 # app 10350 W, settings importPower '10350'. Not consumed yet; recorded so the mapping is

apps/predbat/tests/test_sunsynk_api.py

@@ -1071,35 +1071,40 @@ def test_nominal_pack_voltage_across_the_lifepo4_charge_window():
     assert not failed, "test_nominal_pack_voltage_across_the_lifepo4_charge_window"
 
 
-def test_inverter_limit_respects_the_installer_power_limiter():
-    """The installer's Inverter Power Limiter can cap the inverter below its rating.
+def test_inverter_limit_is_the_rating_and_export_limit_is_the_cap():
+    """pvMaxLimit caps EXPORT, not the inverter's output, despite its app label.
 
-    Confirmed live: ratePower 8000 with pvMaxLimit 7000. Using the rating alone would have
-    Predbat plan a kilowatt the inverter will never deliver.
+    Sunsynk's documentation confirms the "Inverter Power Limiter" control is an export cap,
+    which is why the app shows the same value on both the System Mode and Grid Settings
+    screens. The inverter can still deliver its full ratePower to the house, so reducing
+    inverter_limit by it would under-rate the inverter for self-consumption.
     """
     failed = False
     s = MockSunsynk()
     s.device_rated_power["INV1"] = 8000.0
     s.device_settings["INV1"] = {"pvMaxLimit": "7000"}
-    if s.inverter_limit("INV1") != 7000.0:
-        print(f"ERROR: expected the lower of 8000/7000, got {s.inverter_limit('INV1')}")
+    if s.inverter_limit("INV1") != 8000.0:
+        print(f"ERROR: inverter_limit should be the 8000W rating, got {s.inverter_limit('INV1')}")
         failed = True
-    # A limiter above the rating must not raise the limit beyond what the hardware can do.
-    s.device_rated_power["INV2"] = 5000.0
+    if s.export_limit("INV1") != 7000.0:
+        print(f"ERROR: export_limit should be the 7000W cap, got {s.export_limit('INV1')}")
+        failed = True
+    # Export can never exceed what the inverter can produce, whatever the setting allows.
+    s.device_rated_power["INV2"] = 3600.0
     s.device_settings["INV2"] = {"pvMaxLimit": "16000"}
-    if s.inverter_limit("INV2") != 5000.0:
-        print(f"ERROR: rating must cap the limiter, got {s.inverter_limit('INV2')}")
+    if s.export_limit("INV2") != 3600.0:
+        print(f"ERROR: export must be bounded by the rating, got {s.export_limit('INV2')}")
         failed = True
-    # Either one alone is still usable.
+    # A G98 site: a 3.68kW export cap behind a much larger inverter must survive intact.
     s.device_rated_power["INV3"] = 8000.0
-    s.device_settings["INV3"] = {}
-    if s.inverter_limit("INV3") != 8000.0:
-        print(f"ERROR: rating alone should be used, got {s.inverter_limit('INV3')}")
+    s.device_settings["INV3"] = {"pvMaxLimit": "3680"}
+    if s.export_limit("INV3") != 3680.0 or s.inverter_limit("INV3") != 8000.0:
+        print(f"ERROR: G98 case wrong - export {s.export_limit('INV3')}, inverter {s.inverter_limit('INV3')}")
         failed = True
-    if s.inverter_limit("UNKNOWN") != 0:
-        print(f"ERROR: an unknown serial should derive 0, got {s.inverter_limit('UNKNOWN')}")
+    if s.inverter_limit("UNKNOWN") != 0 or s.export_limit("UNKNOWN") != 0:
+        print("ERROR: an unknown serial should derive 0 for both")
         failed = True
-    assert not failed, "test_inverter_limit_respects_the_installer_power_limiter"
+    assert not failed, "test_inverter_limit_is_the_rating_and_export_limit_is_the_cap"
 
 
 def run_sunsynk_api_tests(my_predbat):
@@ -1128,7 +1133,7 @@ def run_sunsynk_api_tests(my_predbat):
         ("battery_rate_max", test_battery_rate_max_from_charge_current),
         ("rate_max_field_priority", test_battery_rate_max_prefers_a_populated_current_field),
         ("pack_voltage_window", test_nominal_pack_voltage_across_the_lifepo4_charge_window),
-        ("inverter_limit_limiter", test_inverter_limit_respects_the_installer_power_limiter),
+        ("inverter_limit_vs_export", test_inverter_limit_is_the_rating_and_export_limit_is_the_cap),
         ("battery_reserve_min", test_battery_reserve_min_from_settings),
         ("device_list_no_serials_terminates", test_get_device_list_terminates_when_serials_are_missing),
         ("device_list_deduplicates", test_get_device_list_deduplicates_repeated_pages),

apps/predbat/tests/test_sunsynk_config.py

@@ -750,14 +750,12 @@ async def fake_publish_data():
     assert not failed, "test_run_isolates_one_inverters_failure_from_the_rest"
 
 
-def test_export_limit_is_never_auto_mapped():
-    """export_limit must be left to apps.yaml, because we cannot identify the real field.
-
-    The app's Export power limiter can sit below the inverter limit (a G98/G99 site is
-    commonly capped at 3.68kW behind a much larger inverter), but no settings field carrying
-    it could be identified. Guessing it from pvMaxLimit would be worse than leaving it:
-    set_arg_auto always beats apps.yaml, so a user who correctly set their real export cap
-    would have it silently replaced by the larger inverter limit.
+def test_export_limit_is_auto_mapped_from_the_export_cap():
+    """export_limit must be mapped, or Predbat plans exports the inverter clips.
+
+    inverter.py defaults export_limit to 99999W. pvMaxLimit is the export cap (Sunsynk
+    documents the app's "Inverter Power Limiter" as limiting export), so it is mapped, while
+    inverter_limit stays on the hardware rating.
     """
     failed = False
     s = ConfigSunsynk()
@@ -767,17 +765,17 @@ def test_export_limit_is_never_auto_mapped():
     s.device_rated_power["INV1"] = 8000.0
     s.device_settings["INV1"] = {"batteryLowCap": "20", "pvMaxLimit": "7000"}
     run_async_local(s.automatic_config())
-    if "export_limit" in s.args_set:
-        print(f"ERROR: export_limit was auto-mapped to {s.args_set['export_limit']}, which would override the user's apps.yaml value")
-        failed = True
-    # The inverter limit IS mapped, and reflects the app's power limiter rather than ratePower.
-    if "inverter_limit" not in s.args_set:
-        print("ERROR: inverter_limit should still be mapped")
+    for arg in ("inverter_limit", "export_limit"):
+        if arg not in s.args_set:
+            print(f"ERROR: {arg} was not mapped")
+            failed = True
+    if s.inverter_limit("INV1") != 8000.0:
+        print(f"ERROR: inverter_limit should be the rating 8000, got {s.inverter_limit('INV1')}")
         failed = True
-    if s.inverter_limit("INV1") != 7000.0:
-        print(f"ERROR: inverter_limit should honour pvMaxLimit 7000, got {s.inverter_limit('INV1')}")
+    if s.export_limit("INV1") != 7000.0:
+        print(f"ERROR: export_limit should be the cap 7000, got {s.export_limit('INV1')}")
         failed = True
-    assert not failed, "test_export_limit_is_never_auto_mapped"
+    assert not failed, "test_export_limit_is_auto_mapped_from_the_export_cap"
 
 
 def run_sunsynk_config_tests(my_predbat):
@@ -788,7 +786,7 @@ def run_sunsynk_config_tests(my_predbat):
         ("component_registered", test_component_registered),
         ("apps_schema", test_apps_schema_keys),
         ("automatic_config", test_automatic_config_maps_control_entities),
-        ("export_limit_not_mapped", test_export_limit_is_never_auto_mapped),
+        ("export_limit_mapped", test_export_limit_is_auto_mapped_from_the_export_cap),
         ("partial_capabilities", test_automatic_config_skips_partial_capabilities),
         ("ignore_pv", test_automatic_config_respects_ignore_pv),
         ("run_first_cycle", test_run_first_cycle_polls_and_publishes),