feat: add external_solar_mode for AC-coupled PV setups

On AC-coupled installations the PV panels are wired to a separate
inverter (e.g. SolarEdge, microinverters) and the battery inverter has
no DC solar input. The only physical charging path is via the grid —
surplus solar returns through the meter. With SOLAR_STORAGE hard-coded
to grid_charge=False the battery sits idle the entire solar window.

Adds an opt-in battery.external_solar_mode flag (default false, so
DC-coupled users see no change). When enabled, the SOLAR_STORAGE intent
maps to grid_charge=True in the inverter controller; all other intents
keep their default mapping.

Wired end-to-end:
- BatterySettings dataclass + from_ha_config
- InverterController helper applied in _map_intent_to_rates,
  get_period_settings, and get_detailed_period_groups
- settings_store bootstrap defaults + schema migration
- Settings → Battery tab toggle (PV coupling section)
- Setup wizard load + complete payload

Tests: 10 new behavioral tests covering the override in isolation and
through get_period_settings / get_detailed_period_groups. Full unit
suite (600) and backend suite (201) pass.

Closes johanzander#162

Author: jdungen

backend/api.py

@@ -2958,6 +2958,7 @@ async def setup_complete(payload: APISetupCompletePayload):
             "maxSoc": "max_soc",
             "cycleCost": "cycle_cost_per_kwh",
             "minActionProfitThreshold": "min_action_profit_threshold",
+            "externalSolarMode": "external_solar_mode",
         }
         if any(getattr(payload, f) is not None for f in _BATTERY_MAP) or (
             payload.maxChargeDischargePower is not None
@@ -3086,6 +3087,7 @@ def _nn(d: dict) -> dict:
                     "maxDischargePowerKw": payload.maxChargeDischargePower,
                     "cycleCostPerKwh": payload.cycleCost,
                     "minActionProfitThreshold": payload.minActionProfitThreshold,
+                    "externalSolarMode": payload.externalSolarMode,
                 }
             )
         if "home" in sections:

backend/api_dataclasses.py

@@ -978,6 +978,7 @@ class APISetupCompletePayload(BaseModel):
     maxChargeDischargePower: float | None = None
     cycleCost: float | None = None
     minActionProfitThreshold: float | None = None
+    externalSolarMode: bool | None = None
     # Home settings
     currency: str | None = None
     consumption: float | None = None

backend/settings_store.py

@@ -378,6 +378,7 @@ def _bootstrap_defaults() -> dict:
                 "max_discharge_power_kw": BATTERY_MAX_CHARGE_DISCHARGE_POWER_KW,
                 "cycle_cost_per_kwh": BATTERY_CHARGE_CYCLE_COST,
                 "min_action_profit_threshold": BATTERY_MIN_ACTION_PROFIT_THRESHOLD,
+                "external_solar_mode": False,
             },
             "home": {
                 "default_hourly": HOME_HOURLY_CONSUMPTION_KWH,
@@ -465,6 +466,7 @@ def _migrate_schema(self) -> None:
                 ("charging_power_rate", BATTERY_DEFAULT_CHARGING_POWER_RATE),
                 ("efficiency_charge", BATTERY_EFFICIENCY_CHARGE),
                 ("efficiency_discharge", BATTERY_EFFICIENCY_DISCHARGE),
+                ("external_solar_mode", False),
             ):
                 if key not in battery:
                     battery[key] = default

core/bess/inverter_controller.py

@@ -113,6 +113,19 @@ def compute_rates_for_period(
         intent = self.strategic_intents[period]
         return self._map_intent_to_rates(intent, battery_action_kw)
 
+    def _effective_grid_charge(self, intent: str, grid_charge: bool) -> bool:
+        """Apply the external_solar_mode override for SOLAR_STORAGE.
+
+        On AC-coupled PV setups the battery inverter has no DC solar input,
+        so the only physical charging path is the grid (surplus solar
+        returns through the meter).  When external_solar_mode is enabled,
+        SOLAR_STORAGE periods must use grid_charge=True or the battery
+        sits idle the entire solar window.
+        """
+        if intent == "SOLAR_STORAGE" and self.battery_settings.external_solar_mode:
+            return True
+        return grid_charge
+
     def _map_intent_to_rates(
         self, intent: str, battery_action_kw: float
     ) -> tuple[bool, int]:
@@ -128,7 +141,7 @@ def _map_intent_to_rates(
         if intent == "GRID_CHARGING":
             return True, 0
         elif intent == "SOLAR_STORAGE":
-            return False, 0
+            return self._effective_grid_charge(intent, False), 0
         elif intent == "LOAD_SUPPORT":
             if battery_action_kw < -0.01:
                 discharge_rate = min(
@@ -215,7 +228,7 @@ def get_period_settings(self, period: int) -> dict:
             charge_rate = self.INTENT_TO_CONTROL[intent]["charge_rate"]
         else:
             control = self.INTENT_TO_CONTROL[intent]
-            grid_charge = control["grid_charge"]
+            grid_charge = self._effective_grid_charge(intent, control["grid_charge"])
             charge_rate = control["charge_rate"]
             discharge_rate = control["discharge_rate"]
 
@@ -298,7 +311,9 @@ def get_detailed_period_groups(
                     "period": period,
                     "intent": intent,
                     "mode": mode,
-                    "grid_charge": control["grid_charge"],
+                    "grid_charge": self._effective_grid_charge(
+                        intent, control["grid_charge"]
+                    ),
                     "charge_rate": control["charge_rate"],
                     "discharge_rate": control["discharge_rate"],
                 }

core/bess/settings.py

@@ -125,6 +125,10 @@ class BatterySettings:
     )
     efficiency_charge: float = BATTERY_EFFICIENCY_CHARGE
     efficiency_discharge: float = BATTERY_EFFICIENCY_DISCHARGE
+    # AC-coupled PV opt-in: when True, SOLAR_STORAGE periods enable grid
+    # charging so the battery can AC-charge from surplus solar that flows
+    # back through the meter (no DC solar input on the battery inverter).
+    external_solar_mode: bool = False
     reserved_capacity: float = field(init=False)
     min_soe_kwh: float = field(init=False)
     max_soe_kwh: float = field(init=False)
@@ -169,6 +173,9 @@ def from_ha_config(self, config: dict) -> "BatterySettings":
             self.min_action_profit_threshold = battery_config.get(
                 "min_action_profit_threshold", BATTERY_MIN_ACTION_PROFIT_THRESHOLD
             )
+            self.external_solar_mode = battery_config.get(
+                "external_solar_mode", False
+            )
             self.__post_init__()
         return self
 

core/bess/tests/unit/test_external_solar_mode.py

@@ -0,0 +1,80 @@
+"""Tests for the AC-coupled `external_solar_mode` battery setting.
+
+When enabled, the SOLAR_STORAGE strategic intent must translate to
+`grid_charge=True` so the battery can AC-charge from surplus solar that
+returns via the meter (the battery inverter has no DC solar input).
+All other intents must keep their default mapping.
+"""
+
+import pytest
+
+from core.bess.settings import BatterySettings
+from core.bess.solax_controller import SolaxController
+
+
+def _settings(*, external_solar_mode: bool) -> BatterySettings:
+    return BatterySettings(
+        total_capacity=10.0,
+        max_charge_power_kw=5.0,
+        max_discharge_power_kw=5.0,
+        min_soc=15.0,
+        max_soc=95.0,
+        external_solar_mode=external_solar_mode,
+    )
+
+
+class TestExternalSolarModeOverride:
+    def test_default_is_disabled(self) -> None:
+        assert BatterySettings(total_capacity=10.0).external_solar_mode is False
+
+    def test_solar_storage_grid_charge_false_when_disabled(self) -> None:
+        ctrl = SolaxController(battery_settings=_settings(external_solar_mode=False))
+        grid_charge, discharge_rate = ctrl._map_intent_to_rates("SOLAR_STORAGE", 0.0)
+        assert grid_charge is False
+        assert discharge_rate == 0
+
+    def test_solar_storage_grid_charge_true_when_enabled(self) -> None:
+        ctrl = SolaxController(battery_settings=_settings(external_solar_mode=True))
+        grid_charge, discharge_rate = ctrl._map_intent_to_rates("SOLAR_STORAGE", 0.0)
+        assert grid_charge is True
+        assert discharge_rate == 0
+
+    @pytest.mark.parametrize(
+        "intent,expected_grid_charge",
+        [
+            ("GRID_CHARGING", True),
+            ("LOAD_SUPPORT", False),
+            ("EXPORT_ARBITRAGE", False),
+            ("IDLE", False),
+        ],
+    )
+    def test_other_intents_unaffected_when_enabled(
+        self, intent: str, expected_grid_charge: bool
+    ) -> None:
+        ctrl = SolaxController(battery_settings=_settings(external_solar_mode=True))
+        grid_charge, _ = ctrl._map_intent_to_rates(intent, 0.0)
+        assert grid_charge is expected_grid_charge
+
+    def test_detailed_period_groups_apply_override(self) -> None:
+        ctrl = SolaxController(battery_settings=_settings(external_solar_mode=True))
+        ctrl.strategic_intents = ["SOLAR_STORAGE"] * 96
+        groups = ctrl.get_detailed_period_groups()
+        assert groups, "expected at least one period group"
+        for group in groups:
+            assert group["grid_charge"] is True
+            assert group["intent"] == "SOLAR_STORAGE"
+
+    def test_detailed_period_groups_no_override_when_disabled(self) -> None:
+        ctrl = SolaxController(battery_settings=_settings(external_solar_mode=False))
+        ctrl.strategic_intents = ["SOLAR_STORAGE"] * 96
+        groups = ctrl.get_detailed_period_groups()
+        for group in groups:
+            assert group["grid_charge"] is False
+
+    def test_get_period_settings_applies_override_without_schedule(self) -> None:
+        ctrl = SolaxController(battery_settings=_settings(external_solar_mode=True))
+        ctrl.strategic_intents = ["SOLAR_STORAGE"] * 96
+        ctrl.current_schedule = None
+        settings = ctrl.get_period_settings(period=10)
+        assert settings["grid_charge"] is True
+        assert settings["strategic_intent"] == "SOLAR_STORAGE"

frontend/src/components/settings/BatteryFormSection.tsx

@@ -12,6 +12,7 @@ export interface BatteryForm {
   efficiencyDischarge: number;
   temperatureDeratingEnabled: boolean;
   minActionProfit: number;
+  externalSolarMode: boolean;
 }
 
 interface Props {
@@ -54,6 +55,14 @@ export function BatteryFormSection({
         </div>
       </SectionCard>
 
+      <SectionCard
+        title="PV coupling"
+        description="Enable only if your solar panels are wired to a separate inverter (e.g. SolarEdge or microinverters) and the battery inverter has no DC solar input. Surplus solar reaches the battery via the grid, so SOLAR_STORAGE periods must enable AC charging."
+      >
+        {toggle('External solar mode (AC-coupled PV)', form.externalSolarMode,
+          v => onChange({ ...form, externalSolarMode: v }))}
+      </SectionCard>
+
       {/* Advanced settings collapsible — hidden in wizard mode since these
           fields are not sent by the wizard completion payload */}
       {!hideAdvanced && <div className="bg-white dark:bg-gray-800 rounded-xl shadow-sm border border-gray-200 dark:border-gray-700 overflow-hidden">

frontend/src/pages/SettingsPage.tsx

@@ -39,6 +39,7 @@ const EMPTY_BATTERY: BatteryForm = {
   cycleCostPerKwh: 0,
   efficiencyCharge: 97, efficiencyDischarge: 97,
   temperatureDeratingEnabled: false, minActionProfit: 0,
+  externalSolarMode: false,
 };
 const EMPTY_HOME: HomeForm = {
   consumption: 3.5, consumptionStrategy: 'sensor',
@@ -164,6 +165,7 @@ const SettingsPage: React.FC = () => {
         efficiencyDischarge: bat_s.efficiencyDischarge ?? 0.95,
         temperatureDeratingEnabled: bat_s.temperatureDerating?.enabled ?? false,
         minActionProfit: bat_s.minActionProfitThreshold ?? 0,
+        externalSolarMode: bat_s.externalSolarMode ?? false,
       };
       setBatteryForm(bat);
       savedBattery.current = JSON.stringify(bat);
@@ -439,6 +441,7 @@ const SettingsPage: React.FC = () => {
             enabled: batteryForm.temperatureDeratingEnabled,
             weatherEntity: sensors.shared?.['weather_entity'] ?? '',
           },
+          externalSolarMode: batteryForm.externalSolarMode,
         },
         growatt: {
           deviceId: inverterForm.deviceId,

frontend/src/pages/SetupWizardPage.tsx

@@ -45,6 +45,7 @@ const SetupWizardPage: React.FC = () => {
     efficiencyDischarge: 97,
     temperatureDeratingEnabled: false,
     minActionProfit: 8.0,
+    externalSolarMode: false,
   });
 
   const [inverterForm, setInverterForm] = useState<InverterForm>({
@@ -205,6 +206,7 @@ const SetupWizardPage: React.FC = () => {
         efficiencyCharge:         bat.efficiencyCharge         ?? f.efficiencyCharge,
         efficiencyDischarge:      bat.efficiencyDischarge      ?? f.efficiencyDischarge,
         temperatureDeratingEnabled: bat.temperatureDeratingEnabled ?? f.temperatureDeratingEnabled,
+        externalSolarMode:        bat.externalSolarMode        ?? f.externalSolarMode,
       }));
       setHomeForm(f => ({
         ...f,
@@ -274,6 +276,7 @@ const SetupWizardPage: React.FC = () => {
         maxChargeDischargePower: batteryForm.maxChargeDischargePowerKw,
         cycleCost: batteryForm.cycleCostPerKwh,
         minActionProfitThreshold: batteryForm.minActionProfit,
+        externalSolarMode: batteryForm.externalSolarMode,
         // Home
         currency: pricingForm.currency,
         consumption: homeForm.consumption,

frontend/src/types.ts

@@ -114,6 +114,9 @@ export interface BatterySettings {
   efficiencyCharge: number;     // % charging efficiency
   efficiencyDischarge: number;  // % discharge efficiency
 
+  // AC-coupled PV: route SOLAR_STORAGE through grid charging
+  externalSolarMode?: boolean;
+
   // Consumption estimate
   estimatedConsumption: number; // kWh daily estimate
   consumptionStrategy: string;  // "sensor", "fixed", or "influxdb_7d_avg"