fix: SPH AC charge energy reads registers 112-115 as a pair (#390)

Protocol V1.39 gives input 112-115 two meanings selected by device class: warn
and fault codes on MAX-class string inverters, AC charge energy on Storage Power
models. SPH is Storage Power.

The SPH profiles read BOTH interpretations at once - 112 as warning_code and 115
alone as ac_charge_energy_total - which cannot both be right on one device. And
reading 115 without its high word at 114 capped the lifetime total at 6553.5 kWh.

A reporter's scan: 114=1, 115=5462 -> (1<<16)|5462 = 70998 -> 7099.8 kWh. The
old mapping would have said 546.2.

His entity actually showed 13820.7, because the decode path copied
charge_energy_total into ac_charge_energy_total for every profile despite the
comment saying 'SPF uses...'. On a grid-tied hybrid those are different
quantities: 1058/1059 is total battery charge (PV + grid), AC charge is grid
only. Now gated to off-grid profiles, where every charge really is an AC charge.

Also removes ac_discharge_energy_total from the shared BATTERY_SENSORS group.
V1.39 has no AC-discharge counter anywhere - only the off-grid protocol defines
one - so 21 grid-tied profiles exposed a sensor with no register behind it. It
read 0.0 every poll, and _protect_energy_totals latches any non-zero value and
restores it whenever the reading is 0, so one garbage frame became permanent:
21,069,824 kWh on a 12 kWh battery, unclearable. Moved to the SPF and SPE groups,
which map registers 66/67. The existing blanket stale-entity rule removes it on
upgrade - no per-removal block needed.

Scope is SPH only. MIN/MID/MOD/MIC/TL3-S/TL-XH also map 112 as warning_code; for
the MAX-class ones that is correct, and for the XH hybrids there is no evidence
either way.

Verified red without the fix (22 failures). NOT RELEASED - manifest still at
1.7.5 pending @Vict20 confirming 7099.8 against his portal.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: 0xAHA

custom_components/growatt_modbus/device_profiles.py

@@ -73,8 +73,18 @@
     "priority_mode",
     # WIT: Battery SOH and BMS voltage
     "battery_soh", "battery_voltage_bms",
-    # WIT/SPF/MOD: AC charge/discharge energy
-    "ac_charge_energy_today", "ac_charge_energy_total", "ac_discharge_energy_total",
+    # AC charge energy — SPH reads these from registers 112-115, SPF/SPE from their own
+    # off-grid range.
+    "ac_charge_energy_today", "ac_charge_energy_total",
+    # NOT here: ac_discharge_energy_total. Protocol V1.39 has no AC-discharge counter at
+    # all — there is an EACharge_Total but no EADischarge anywhere in the input table. Only
+    # the off-grid protocol defines one (registers 66/67), so it belongs to SPF and SPE and
+    # is listed in their own groups below.
+    #
+    # While it sat here, 21 grid-tied profiles created the sensor with nothing behind it.
+    # It read 0.0 every poll, and _protect_energy_totals latched a single garbage frame
+    # (3215 << 16) and restored it forever after — one reporter saw 21,069,824 kWh on a
+    # 12 kWh battery, a value the integration could never clear on its own (#390).
 }
 
 _EXTRA_BATTERY_FIELDS = (
@@ -166,8 +176,10 @@
     # Generator sensors (SPF with generator input)
     "generator_power", "generator_voltage",
     "generator_discharge_today", "generator_discharge_total",
-    # AC charge/discharge energy (from grid/generator)
-    "ac_charge_energy_today", "ac_discharge_energy_today",
+    # AC charge/discharge energy (from grid/generator). ac_discharge_energy_total is
+    # here rather than in BATTERY_SENSORS because only the off-grid protocol defines it
+    # (registers 66/67) — see the note there (#390).
+    "ac_charge_energy_today", "ac_discharge_energy_today", "ac_discharge_energy_total",
     # Operational discharge energy
     "op_discharge_energy_today", "op_discharge_energy_total",
     # Fan speeds
@@ -184,6 +196,7 @@
     "grid_voltage",              # reg 20
     "grid_frequency",            # reg 21
     "ac_discharge_energy_today", # regs 64/65 (= grid import today on SPE)
+    "ac_discharge_energy_total", # regs 66/67 (= grid import total on SPE)
     "mppt_fan_speed",            # reg 81
     "inverter_fan_speed",        # reg 82
     "dcdc_temp",                 # reg 26

custom_components/growatt_modbus/growatt_modbus.py

@@ -3496,14 +3496,18 @@ def _read_battery_data(self, data: GrowattData) -> None:
                 value = self._get_register_value_with_fallback('battery_charge_today_low')
             if value is not None:
                 data.charge_energy_today = value
-                # SPF uses charge_energy_* registers for AC charging - populate both fields
-                data.ac_charge_energy_today = data.charge_energy_today
+                # On an off-grid inverter every charge is an AC charge, so the same counter
+                # serves both. On a grid-tied hybrid it does not: this register is total
+                # battery charge (PV + grid), while AC charge is grid-only and lives at
+                # 112-115. Copying it here made AC Charge Energy report battery charge —
+                # 13820.7 kWh against a true 7099.8 on the reporter's SPH (#390).
+                if self.register_map.get('offgrid_protocol', False):
+                    data.ac_charge_energy_today = data.charge_energy_today
                 # Log which register was used
                 addr = self._find_register_by_name('charge_energy_today_low') or self._find_register_by_name('battery_charge_today_low')
-                logger.debug(f"Charge energy today from register {addr}: {data.charge_energy_today} kWh (also populating ac_charge_energy_today for SPF)")
+                logger.debug(f"Charge energy today from register {addr}: {data.charge_energy_today} kWh")
             else:
                 data.charge_energy_today = 0.0
-                data.ac_charge_energy_today = 0.0
 
             # Discharge energy today
             # Try both naming conventions with smart fallback: "discharge_energy_today" and "battery_discharge_today"
@@ -3525,14 +3529,14 @@ def _read_battery_data(self, data: GrowattData) -> None:
                 value = self._get_register_value_with_fallback('battery_charge_total_low')
             if value is not None:
                 data.charge_energy_total = value
-                # SPF uses charge_energy_* registers for AC charging - populate both fields
-                data.ac_charge_energy_total = data.charge_energy_total
+                # Off-grid only — see the matching note on charge_energy_today above.
+                if self.register_map.get('offgrid_protocol', False):
+                    data.ac_charge_energy_total = data.charge_energy_total
                 # Log which register was used
                 addr = self._find_register_by_name('charge_energy_total_low') or self._find_register_by_name('battery_charge_total_low')
-                logger.debug(f"Charge energy total from register {addr}: {data.charge_energy_total} kWh (also populating ac_charge_energy_total for SPF)")
+                logger.debug(f"Charge energy total from register {addr}: {data.charge_energy_total} kWh")
             else:
                 data.charge_energy_total = 0.0
-                data.ac_charge_energy_total = 0.0
 
             # Discharge energy total
             # Try both naming conventions with smart fallback: "discharge_energy_total" and "battery_discharge_total"

custom_components/growatt_modbus/profiles/sph.py

@@ -4,6 +4,42 @@
     VPP_V201_BATTERY2, VPP_V201_HOLDING_1P,
 )
 
+# AC charge energy — input registers 112-115, Storage Power interpretation.
+#
+# Protocol V1.39 gives this block two meanings, selected by device class. The rightmost
+# column of the spec table is the selector:
+#
+#   | Reg | MAX-class string inverter | Storage Power (SPH, SPA) |
+#   |-----|---------------------------|--------------------------|
+#   | 112 | Warn Maincode             | EACharge_Today_H         |
+#   | 113 | real Power Percent        | EACharge_Today_L         |
+#   | 114 | inv start delay time      | EACharge_Total_H         |
+#   | 115 | bINVAllFaultCode          | EACharge_Total_L         |
+#
+# SPH is a Storage Power model, so the energy reading applies to every profile in this
+# file. Until this was corrected these profiles mapped 112 as `warning_code` (the MAX
+# meaning) *and* 115 alone as `ac_charge_energy_total` (the Storage meaning) — two
+# interpretations of one block, which cannot both be right on one device (#390).
+#
+# Reading 115 without its high word at 114 also capped the lifetime total at 6553.5 kWh.
+# A reporter's scan read 114=1, 115=5462 → (1<<16)|5462 = 70998 → 7099.8 kWh, where 115
+# alone would have said 546.2.
+#
+# NOT applied to MIN/MID/MOD/MIC/TL3-S/TL-XH. Those also map 112 as warning_code, and for
+# the MAX-class ones that is correct; for the XH hybrids there is no evidence either way
+# and guessing which side of the column they fall on is how wrong-but-plausible values
+# get shipped.
+STORAGE_AC_CHARGE_ENERGY = {
+    112: {'name': 'ac_charge_energy_today_high', 'scale': 1, 'unit': '', 'pair': 113,
+          'desc': 'AC charge energy today HIGH (EACharge_Today_H)'},
+    113: {'name': 'ac_charge_energy_today_low', 'scale': 1, 'unit': '', 'pair': 112,
+          'combined_scale': 0.1, 'combined_unit': 'kWh'},
+    114: {'name': 'ac_charge_energy_total_high', 'scale': 1, 'unit': '', 'pair': 115,
+          'desc': 'AC charge energy total HIGH (EACharge_Total_H)'},
+    115: {'name': 'ac_charge_energy_total_low', 'scale': 1, 'unit': '', 'pair': 114,
+          'combined_scale': 0.1, 'combined_unit': 'kWh'},
+}
+
 # SPH 3000-6000 (Single-phase hybrid with battery)
 SPH_3000_6000 = {
     'name': 'SPH Series 3-6kW',
@@ -146,10 +182,9 @@
         # Diagnostics
         104: {'name': 'derating_mode', 'scale': 1, 'unit': ''},
         105: {'name': 'fault_code', 'scale': 1, 'unit': ''},
-        112: {'name': 'warning_code', 'scale': 1, 'unit': ''},
 
-        # Battery AC Charge Energy (SPH 3-6kW V201 with newer firmware)
-        115: {'name': 'ac_charge_energy_total', 'scale': 0.1, 'unit': 'kWh', 'desc': 'Total energy charged from AC/grid to battery'},
+        # AC charge energy today/total — see STORAGE_AC_CHARGE_ENERGY above.
+        **STORAGE_AC_CHARGE_ENERGY,
     },
     'holding_registers': {
         # Basic Control
@@ -445,7 +480,9 @@
         # Diagnostics
         104: {'name': 'derating_mode', 'scale': 1, 'unit': ''},
         105: {'name': 'fault_code', 'scale': 1, 'unit': ''},
-        112: {'name': 'warning_code', 'scale': 1, 'unit': ''},
+
+        # AC charge energy today/total — see STORAGE_AC_CHARGE_ENERGY above.
+        **STORAGE_AC_CHARGE_ENERGY,
     },
     'holding_registers': {
         # Basic Control
@@ -1007,12 +1044,10 @@
         31217: {'name': 'battery_soc_vpp', 'scale': 1, 'unit': '%', 'maps_to': 'battery_soc'},
         31218: {'name': 'battery_soh', 'scale': 1, 'unit': '%', 'desc': 'Battery state of health'},
         # Note: Registers 31220-31221 appear to contain incorrect data when paired as 32-bit
-        # AC charge energy total is available in register 115 (legacy range) instead
+        # AC charge energy total is available in registers 114/115 (legacy range) instead,
+        # inherited from SPH_7000_10000 above.
         31222: {'name': 'battery_temp_vpp', 'scale': 0.1, 'unit': '°C', 'maps_to': 'battery_temp', 'signed': True},
 
-        # Battery AC Charge Energy (SPH 7-10kW V201 with newer firmware)
-        115: {'name': 'ac_charge_energy_total', 'scale': 0.1, 'unit': 'kWh', 'desc': 'Total energy charged from AC/grid to battery'},
-
         # Battery Cluster 2 State
         **VPP_V201_BATTERY2,
     },

custom_components/growatt_modbus/profiles/sph_tl3.py

@@ -6,6 +6,7 @@
     VPP_V201_STATUS, VPP_V201_PV2_INPUT, VPP_V201_PV2_TOTAL,
     VPP_V201_TEMPERATURE_1P, VPP_V201_BATTERY2, VPP_V201_HOLDING_1P,
 )
+from .sph import STORAGE_AC_CHARGE_ENERGY
 
 SPH_TL3_3000_10000 = {
     'name': 'SPH-TL3 Series 3-10kW',
@@ -107,8 +108,12 @@
 
         # Status
         105: {'name': 'fault_code', 'scale': 1, 'unit': ''},
-        112: {'name': 'warning_code', 'scale': 1, 'unit': ''},
-        
+
+        # AC charge energy today/total. SPH-TL3 is a Storage Power model, so registers
+        # 112-115 carry energy rather than the warn/fault codes a MAX-class inverter puts
+        # there — see STORAGE_AC_CHARGE_ENERGY in sph.py for the protocol detail (#390).
+        **STORAGE_AC_CHARGE_ENERGY,
+
         # ============================================================================
         # STORAGE RANGE 1000-1124: Battery and Power Flow
         # ============================================================================

docs/controls/entity-reference.md

@@ -70,6 +70,29 @@ firmware.** They are mapped because the protocol defines them, but at least one
 (RAAA191904/ZCBA-0004) accepts the write and immediately reverts the register. If yours does
 that, disable the entities - other firmware may well support them.
 
+### Energy sensors worth distinguishing
+
+Three lifetime counters look similar and mean different things:
+
+| Sensor | Registers | Measures |
+|---|---|---|
+| Battery Charge Total | 1058/1059 | **All** energy into the battery — PV and grid |
+| AC Charge Energy Total | 114/115 | Grid→battery only |
+| Battery Discharge Total | 1054/1055 | All energy out of the battery |
+
+So AC Charge Energy Total is normally *lower* than Battery Charge Total; the difference is
+what came from your panels. On one reporter's system the figures were 7,099.8 kWh against
+13,820.8 kWh.
+
+Registers 112–115 carry AC charge energy on SPH because it is a "Storage Power" model. The
+same addresses hold warning and fault codes on MAX-class string inverters — the protocol
+lists both meanings side by side, selected by device class.
+
+> **There is no AC Discharge Energy Total on SPH.** Protocol V1.39 defines no AC-discharge
+> counter at all; only off-grid models (SPF, SPE) have one. If you had this entity before
+> v1.7.6 it was never populated by a register, and any value it showed was a stale artefact.
+> It is removed automatically on upgrade. Use **Battery Discharge Total** instead.
+
 **Notes:**
 - All SPH variants share the same 1000+ register range — controls apply across 3–6kW, 7–10kW, and HU variants automatically.
 - Time periods use HHMM format: `530` = 05:30, `2300` = 23:00.