Bound the solar surplus by the CT clamp setting and by generation

Two ways the sensor could report a surplus that was not there.

A charger outside the CT clamp is never seen by the inverter's grid reading, so
adding car_charging_power back invented a surplus equal to the whole charger
draw. The add-back is now gated on car_energy_reported_load, the flag
prediction.py already uses for this. car_charging_power_included says which
applies.

The result is capped at pv_power. A grid sensor wired positive-on-import
without grid_power_invert made the surplus track the import instead, holding a
charger at full rate. The cap cannot fix the sign in daylight, but it bounds
the error and forces 0 after dark.

The documented automation had three faults: a bare state trigger on
car_charging_slot turned the charger on when the cheap slot ended, charging
could not resume after a force export slot because numeric_state only fires on
a crossing, and the modulating-current snippet floored at 6A with no off state.

Docs now also cover the PV inventory and freshness checks, and correct the
update interval to INVERTER_QUICK_UPDATE_SECONDS.

Author: Pezmc

apps/predbat/execute.py

@@ -1170,18 +1170,22 @@ def publish_inverter_data(self):
                 },
             )
 
-        # Power a flexible load could take right now without importing or draining the battery.
+        # Power a load could take now without importing or draining the battery.
         #
-        # A car charger sits behind the grid meter, so once a car is charging the export collapses
-        # towards zero - car_charging_power is added back to recover what the export would be with
-        # the car off, which is what makes this stable enough to drive a charger from. Any other
-        # load reading this while a car charges wants the car's share left out, so it can subtract
-        # the car_charging_power attribute. Battery discharge is subtracted so battery power is
-        # never offered up as if it were solar: if cloud cover arrives mid-charge the battery starts
-        # covering the load, and without the subtraction the sensor would keep reporting a surplus
-        # that is really coming out of the battery. Battery charging is deliberately not added -
-        # what gets the surplus is the user's policy, and the components are in the attributes.
-        solar_surplus = max(0.0, self.grid_power + self.car_charging_power - max(0.0, self.battery_power))
+        # The car's own draw is added back so the sensor keeps reading what is available for it
+        # rather than collapsing once the charger starts. Only when the charger is inside the CT
+        # clamp: outside it the grid reading never saw the car, so adding it would invent a surplus
+        # equal to the charger draw. prediction.py branches on the same flag.
+        car_add_back = self.car_charging_power if self.car_energy_reported_load else 0.0
+
+        # Subtracting battery discharge keeps battery power from being reported as solar. Battery
+        # charging is not added back, so a charging battery takes the surplus first.
+        solar_surplus = max(0.0, self.grid_power + car_add_back - max(0.0, self.battery_power))
+
+        # Nothing can be spare that was never generated. A grid sensor wired positive-on-import
+        # without grid_power_invert would otherwise make the surplus track the import, and this
+        # sensor switches real load on.
+        solar_surplus = min(solar_surplus, max(0.0, self.pv_power))
         self.dashboard_item(
             self.prefix + ".solar_surplus_power",
             state=dp3(solar_surplus / 1000.0),
@@ -1193,8 +1197,10 @@ def publish_inverter_data(self):
                 "icon": "mdi:solar-power",
                 "grid_power": dp3(self.grid_power / 1000.0),
                 "battery_power": dp3(self.battery_power / 1000.0),
+                "pv_power": dp3(self.pv_power / 1000.0),
                 "car_charging_power": dp3(self.car_charging_power / 1000.0),
                 "car_charging_power_configured": self.car_charging_power_configured,
+                "car_charging_power_included": bool(self.car_energy_reported_load),
             },
         )
 

apps/predbat/output.py

@@ -2936,11 +2936,9 @@ def set_charge_export_status(self, isCharging, isExporting, isDemand):
         )
         self.dashboard_item("binary_sensor." + self.prefix + "_demand", state="on" if isDemand else "off", attributes={"friendly_name": "Predbat is in demand mode", "icon": "mdi:battery-arrow-up"})
 
-        # Whether the plan has a force export window running now, taken from the plan rather than
-        # from isExporting above. That makes it stay on right through a slot, cover freeze export
-        # (where Predbat is selling the PV rather than the battery) and the Hold exporting phases,
-        # and still report in read only mode - all cases where an automation wants to leave the
-        # solar for Predbat to sell, but where the commanded state above is off.
+        # Taken from the plan, not from isExporting above. isExporting is off in read only mode,
+        # off during Hold exporting, and only on for the minutes an export is commanded, whereas an
+        # automation needs to know a slot is running for its whole duration including freeze export.
         export_window_n = self.in_charge_window(self.export_window_best, self.minutes_now)
         in_export_slot = self.set_export_window and export_window_n >= 0 and self.export_limits_best[export_window_n] < EXPORT_LIMIT_IDLE
         self.dashboard_item(

apps/predbat/tests/test_solar_surplus.py

@@ -15,12 +15,17 @@
 EXPORT_SLOT_ENTITY = "_force_export_slot"
 
 
-def check_surplus(my_predbat, name, grid_power, battery_power, car_charging_power, car_configured, expect_state):
-    """Publish the inverter sensors for one power reading and check the surplus state"""
+def check_surplus(my_predbat, name, grid_power, battery_power, car_charging_power, car_configured, expect_state, pv_power=20000, car_reported_load=True):
+    """Publish the inverter sensors for one power reading and check the surplus state
+
+    pv_power defaults high enough not to clip. Cases exercising the clamp pass their own.
+    """
     my_predbat.grid_power = grid_power
     my_predbat.battery_power = battery_power
+    my_predbat.pv_power = pv_power
     my_predbat.car_charging_power = car_charging_power
     my_predbat.car_charging_power_configured = car_configured
+    my_predbat.car_energy_reported_load = car_reported_load
     my_predbat.publish_inverter_data()
 
     entity_id = my_predbat.prefix + SURPLUS_ENTITY
@@ -57,8 +62,7 @@ def check_export_slot(my_predbat, name, minutes_now, export_window, export_limit
 def run_export_slot_tests(my_predbat):
     """
     binary_sensor.predbat_force_export_slot reports whether the plan has a force export window
-    running now, so an automation can leave the solar for Predbat to sell rather than putting it
-    into the car.
+    running, so an automation can leave the solar for Predbat to sell.
     """
     failed = False
     saved = {key: getattr(my_predbat, key) for key in ["minutes_now", "export_window_best", "export_limits_best", "set_export_window"]}
@@ -101,14 +105,13 @@ def run_export_slot_tests(my_predbat):
 
 def run_solar_surplus_tests(my_predbat):
     """
-    predbat.solar_surplus_power reports the power a flexible load could take right now without
-    importing or draining the battery, so a Home Assistant automation can start a car, an immersion
-    heater or anything else on spare solar without Predbat deciding anything.
+    predbat.solar_surplus_power reports the power a load could take now without importing or
+    draining the battery, so an automation can run a car or immersion heater on spare solar.
     """
     reset_inverter(my_predbat)
     failed = False
 
-    saved = {key: getattr(my_predbat, key) for key in ["grid_power", "battery_power", "car_charging_power", "car_charging_power_configured"]}
+    saved = {key: getattr(my_predbat, key) for key in ["grid_power", "battery_power", "pv_power", "car_charging_power", "car_charging_power_configured", "car_energy_reported_load"]}
     try:
         print("Test: with no car charging the surplus is the grid export")
         failed |= check_surplus(my_predbat, "plain export", grid_power=2000, battery_power=0, car_charging_power=0, car_configured=False, expect_state=2.0)
@@ -119,20 +122,38 @@ def run_solar_surplus_tests(my_predbat):
         print("Test: a charging car is added back, so the sensor does not collapse once the car starts")
         failed |= check_surplus(my_predbat, "car charging", grid_power=200, battery_power=0, car_charging_power=7000, car_configured=True, expect_state=7.2)
 
-        # Cloud cover arriving mid-charge: PV has dropped, the battery is covering part of the car and
-        # the grid has swung to import. Without subtracting the battery discharge this would still read
-        # 4.0kW and an automation would happily keep the car charging out of the battery.
+        # Cloud cover mid-charge: the battery is covering part of the car and the grid has swung
+        # to import. Without the subtraction this reads 4.0kW and the car keeps charging off it.
         print("Test: battery discharge is not offered to the car as solar surplus")
         failed |= check_surplus(my_predbat, "battery covering the car", grid_power=-3000, battery_power=3000, car_charging_power=7000, car_configured=True, expect_state=1.0)
 
-        print("Test: battery charging is left in the surplus, as who gets it is the user's choice")
+        print("Test: battery charging takes the surplus, it is not added back")
         failed |= check_surplus(my_predbat, "battery charging", grid_power=1000, battery_power=-2000, car_charging_power=0, car_configured=False, expect_state=1.0)
 
+        # Outside the CT clamp the grid reading never saw the car, so the add-back would invent a
+        # surplus equal to the charger draw and the automation would never turn the car off.
+        print("Test: a charger outside the CT clamp is not added back")
+        failed |= check_surplus(my_predbat, "outside CT clamp", grid_power=0, battery_power=0, car_charging_power=7000, car_configured=True, expect_state=0.0, car_reported_load=False)
+
+        print("Test: inside the CT clamp the same reading does add the car back")
+        failed |= check_surplus(my_predbat, "inside CT clamp", grid_power=0, battery_power=0, car_charging_power=7000, car_configured=True, expect_state=7.0, car_reported_load=True)
+
+        # A grid sensor wired positive-on-import without grid_power_invert reads +8kW while the
+        # house imports 8kW. Unclamped the surplus would track the import.
+        print("Test: the surplus can never exceed generation")
+        failed |= check_surplus(my_predbat, "inverted grid sensor at night", grid_power=8000, battery_power=0, car_charging_power=0, car_configured=False, expect_state=0.0, pv_power=0)
+        failed |= check_surplus(my_predbat, "clamped to PV", grid_power=8000, battery_power=0, car_charging_power=0, car_configured=False, expect_state=3.0, pv_power=3000)
+
+        print("Test: a genuine surplus is not clipped by the clamp")
+        failed |= check_surplus(my_predbat, "surplus below PV", grid_power=2500, battery_power=0, car_charging_power=0, car_configured=False, expect_state=2.5, pv_power=4000)
+
         print("Test: the components and whether a charger is configured are published as attributes")
         my_predbat.grid_power = 500
         my_predbat.battery_power = -250
+        my_predbat.pv_power = 2750
         my_predbat.car_charging_power = 1500
         my_predbat.car_charging_power_configured = True
+        my_predbat.car_energy_reported_load = True
         my_predbat.publish_inverter_data()
         item = my_predbat.ha_interface.dummy_items.get(my_predbat.prefix + SURPLUS_ENTITY)
         expect = {
@@ -144,8 +165,10 @@ def run_solar_surplus_tests(my_predbat):
             "icon": "mdi:solar-power",
             "grid_power": 0.5,
             "battery_power": -0.25,
+            "pv_power": 2.75,
             "car_charging_power": 1.5,
             "car_charging_power_configured": True,
+            "car_charging_power_included": True,
         }
         for key, value in expect.items():
             if item.get(key, None) != value:
@@ -164,6 +187,14 @@ def run_solar_surplus_tests(my_predbat):
         elif item.get("car_charging_power_configured", None) is not False:
             print("ERROR: {} car_charging_power_configured is {} expected False".format(my_predbat.prefix + SURPLUS_ENTITY, item.get("car_charging_power_configured", None)))
             failed = True
+
+        print("Test: car_charging_power_included reports whether the add-back was applied")
+        my_predbat.car_energy_reported_load = False
+        my_predbat.publish_inverter_data()
+        item = my_predbat.ha_interface.dummy_items.get(my_predbat.prefix + SURPLUS_ENTITY)
+        if item.get("car_charging_power_included", None) is not False:
+            print("ERROR: {} car_charging_power_included is {} expected False".format(my_predbat.prefix + SURPLUS_ENTITY, item.get("car_charging_power_included", None)))
+            failed = True
     finally:
         for key, value in saved.items():
             setattr(my_predbat, key, value)