feat(e_v3): rename ac_* to inverter_*, add alt/derived sensors, unify cycle sensor

Author: mgutt

custom_components/marstek_modbus/coordinator.py

@@ -64,7 +64,7 @@ def __init__(self, hass: HomeAssistant, entry: ConfigEntry):
         self.BUTTON_DEFINITIONS = []
         self.EFFICIENCY_SENSOR_DEFINITIONS = []
         self.STORED_ENERGY_SENSOR_DEFINITIONS = []
-        self.CYCLE_SENSOR_DEFINITIONS = []
+        self.DERIVED_SENSOR_DEFINITIONS = []
 
         # Combine all sensor definitions for polling
         self._all_definitions = []
@@ -233,7 +233,7 @@ async def async_load_registers(self, version: str | None = None):
             self.BUTTON_DEFINITIONS = data.get("BUTTON_DEFINITIONS", [])
             self.EFFICIENCY_SENSOR_DEFINITIONS = data.get("EFFICIENCY_SENSOR_DEFINITIONS", [])
             self.STORED_ENERGY_SENSOR_DEFINITIONS = data.get("STORED_ENERGY_SENSOR_DEFINITIONS", [])
-            self.CYCLE_SENSOR_DEFINITIONS = data.get("CYCLE_SENSOR_DEFINITIONS", [])
+            self.DERIVED_SENSOR_DEFINITIONS = data.get("DERIVED_SENSOR_DEFINITIONS", [])
 
             # Combine into a single list for polling
             self._all_definitions = (
@@ -461,7 +461,7 @@ async def _async_update_data(self):
         all_definitions_for_deps = (
             self.EFFICIENCY_SENSOR_DEFINITIONS
             + self.STORED_ENERGY_SENSOR_DEFINITIONS
-            + self.CYCLE_SENSOR_DEFINITIONS
+            + self.DERIVED_SENSOR_DEFINITIONS
         )
         dependency_keys_set = {
             dep_key
@@ -738,7 +738,7 @@ def get_registers(version: str):
       - BUTTON_DEFINITIONS
       - EFFICIENCY_SENSOR_DEFINITIONS
       - STORED_ENERGY_SENSOR_DEFINITIONS
-    - CYCLE_SENSOR_DEFINITIONS
+      - DERIVED_SENSOR_DEFINITIONS
 
     If an unknown version is requested, the function falls back to the v1/v2
     register set (because v1 and v2 share the same registers in this integration).
@@ -819,8 +819,8 @@ def _normalize_section(section):
                     "STORED_ENERGY_SENSOR_DEFINITIONS": _normalize_section(
                         data.get("STORED_ENERGY_SENSOR_DEFINITIONS")
                     ),
-                    "CYCLE_SENSOR_DEFINITIONS": _normalize_section(
-                        data.get("CYCLE_SENSOR_DEFINITIONS")
+                    "DERIVED_SENSOR_DEFINITIONS": _normalize_section(
+                        data.get("DERIVED_SENSOR_DEFINITIONS")
                     ),
                 }
             except Exception as e:

custom_components/marstek_modbus/registers/e_v3.yaml

@@ -8,8 +8,6 @@ MISSING:
     sensor:
         - sn_code
         - software_version
-        - fault_status
-        - alarm_status
     binary:
         - discharge_limit_mode
     select:
@@ -115,6 +113,16 @@ SENSOR_DEFINITIONS:
         data_type: int16
         precision: 1
         scan_interval: medium
+    battery_voltage_alt:
+        register: 30000
+        scale: 0.1
+        unit: V
+        device_class: voltage
+        state_class: measurement
+        enabled_by_default: false
+        data_type: uint16
+        precision: 1
+        scan_interval: medium
     battery_power:
         register: 30001
         count: 1
@@ -126,6 +134,46 @@ SENSOR_DEFINITIONS:
         data_type: int16
         precision: 1
         scan_interval: high
+    internal_temperature_alt:
+        register: 30002
+        scale: 0.1
+        unit: °C
+        device_class: temperature
+        state_class: measurement
+        enabled_by_default: false
+        data_type: int16
+        precision: 1
+        scan_interval: medium
+    internal_mos1_temperature_alt:
+        register: 30003
+        scale: 0.1
+        unit: °C
+        device_class: temperature
+        state_class: measurement
+        enabled_by_default: false
+        data_type: int16
+        precision: 1
+        scan_interval: medium
+    inverter_voltage_alt:
+        register: 30004
+        scale: 0.1
+        unit: V
+        device_class: voltage
+        state_class: measurement
+        enabled_by_default: false
+        data_type: uint16
+        precision: 1
+        scan_interval: medium
+    ac_offgrid_voltage_alt:
+        register: 30005
+        scale: 0.1
+        unit: V
+        device_class: voltage
+        state_class: measurement
+        enabled_by_default: false
+        data_type: uint16
+        precision: 1
+        scan_interval: medium
     internal_temperature:
         register: 35000
         scale: 0.1
@@ -156,7 +204,7 @@ SENSOR_DEFINITIONS:
         data_type: int16
         precision: 2
         scan_interval: medium
-    ac_voltage:
+    inverter_voltage:
         register: 32200
         scale: 0.1
         unit: V
@@ -166,7 +214,7 @@ SENSOR_DEFINITIONS:
         data_type: uint16
         precision: 1
         scan_interval: medium
-    ac_current:
+    inverter_current:
         register: 37004
         scale: 0.004
         unit: A
@@ -176,7 +224,7 @@ SENSOR_DEFINITIONS:
         data_type: int16
         precision: 1
         scan_interval: medium
-    ac_power:
+    inverter_power:
         register: 30006
         count: 1
         scale: 1
@@ -187,7 +235,17 @@ SENSOR_DEFINITIONS:
         data_type: int16
         precision: 0
         scan_interval: high
-    ac_frequency:
+    ac_offgrid_power_alt:
+        register: 30007
+        scale: 1
+        unit: W
+        device_class: power
+        state_class: measurement
+        enabled_by_default: false
+        data_type: int16
+        precision: 0
+        scan_interval: high
+    inverter_frequency:
         register: 32204
         scale: 0.1
         unit: Hz
@@ -508,11 +566,11 @@ SENSOR_DEFINITIONS:
         data_type: uint16
         precision: 1
         scan_interval: medium
-    ac_offgrid_current:
+    ac_offgrid_voltage_raw:
         register: 32301
-        scale: 0.01
-        unit: A
-        device_class: current
+        scale: 0.1
+        unit: V
+        device_class: voltage
         state_class: measurement
         enabled_by_default: false
         data_type: uint16
@@ -548,6 +606,28 @@ SENSOR_DEFINITIONS:
         category: diagnostic
         enabled_by_default: false
         scan_interval: medium
+    alarm_status:
+        register: 36000
+        count: 2
+        scale: 1
+        unit: null
+        icon: "mdi:alert"
+        category: diagnostic
+        enabled_by_default: false
+        data_type: uint32
+        precision: 0
+        scan_interval: medium
+    fault_status:
+        register: 36100
+        count: 2
+        scale: 1
+        unit: null
+        icon: "mdi:alert-circle"
+        category: diagnostic
+        enabled_by_default: false
+        data_type: uint32
+        precision: 0
+        scan_interval: medium
 
 BINARY_SENSOR_DEFINITIONS:
     wifi_status:
@@ -1031,7 +1111,7 @@ EFFICIENCY_SENSOR_DEFINITIONS:
         mode: conversion
         dependency_keys:
             battery_power: battery_power
-            ac_power: ac_power
+            ac_power: inverter_power
 
 STORED_ENERGY_SENSOR_DEFINITIONS:
     stored_energy:
@@ -1043,12 +1123,49 @@ STORED_ENERGY_SENSOR_DEFINITIONS:
             soc: battery_soc
             capacity: battery_total_energy
 
-CYCLE_SENSOR_DEFINITIONS:
+DERIVED_SENSOR_DEFINITIONS:
+    ac_power:
+        key: ac_power
+        unit: W
+        device_class: power
+        state_class: measurement
+        enabled_by_default: true
+        icon: "mdi:transmission-tower"
+        mode: difference
+        dependency_keys:
+            a: ac_offgrid_power
+            b: inverter_power
+    ac_current:
+        key: ac_current
+        unit: A
+        device_class: current
+        state_class: measurement
+        enabled_by_default: true
+        icon: "mdi:transmission-tower"
+        mode: difference_quotient
+        dependency_keys:
+            a: ac_offgrid_power
+            b: inverter_power
+            c: inverter_voltage
+    # ac_offgrid_current: register 32301 returns duplicate voltage (same as 32300).
+    # Calculated as ac_offgrid_power / ac_offgrid_voltage instead.
+    ac_offgrid_current:
+        key: ac_offgrid_current
+        unit: A
+        device_class: current
+        state_class: measurement
+        enabled_by_default: true
+        icon: "mdi:power-socket"
+        mode: quotient
+        dependency_keys:
+            a: ac_offgrid_power
+            b: ac_offgrid_voltage
     battery_cycle_count_calc:
         key: battery_cycle_count_calc
         icon: "mdi:counter"
         category: diagnostic
         state_class: measurement
+        mode: quotient
         dependency_keys:
-            discharge: total_discharging_energy
-            capacity: battery_total_energy
+            a: total_discharging_energy
+            b: battery_total_energy

custom_components/marstek_modbus/sensor.py

@@ -34,7 +34,7 @@ async def async_setup_entry(
         (MarstekSensor, coordinator.SENSOR_DEFINITIONS),
         (MarstekEfficiencySensor, coordinator.EFFICIENCY_SENSOR_DEFINITIONS),
         (MarstekStoredEnergySensor, coordinator.STORED_ENERGY_SENSOR_DEFINITIONS),
-        (MarstekBatteryCycleSensor, coordinator.CYCLE_SENSOR_DEFINITIONS),
+        (MarstekDerivedSensor, coordinator.DERIVED_SENSOR_DEFINITIONS),
     )
     for entity_cls, definitions in sensor_groups:
         entities.extend(entity_cls(coordinator, definition) for definition in definitions)
@@ -347,6 +347,18 @@ def get_dependency_keys(self):
         """Return the keys this sensor depends on."""
         return self.definition.get("dependency_keys", {})
 
+    @property
+    def available(self) -> bool:
+        """Return True only when all dependency values are present in coordinator data."""
+        data = getattr(self.coordinator, "data", None)
+        if not isinstance(data, dict):
+            return False
+        return all(
+            dep_key in data and data.get(dep_key) is not None
+            for dep_key in self.get_dependency_keys().values()
+            if dep_key
+        )
+
     @property
     def entity_type(self) -> str:
         """
@@ -487,15 +499,30 @@ def calculate_value(self, dep_values: dict):
         return efficiency_rounded
 
 
-class MarstekBatteryCycleSensor(MarstekCalculatedSensor):
-    """Calculate estimated battery cycles from discharge energy and capacity."""
+class MarstekDerivedSensor(MarstekCalculatedSensor):
+    """Sensor that derives a value from two or three dependency keys using a simple arithmetic mode.
+
+    Supported modes:
+    - "difference": a - b
+    - "difference_quotient": (a - b) / c
+    - "quotient": a / b
+    """
 
     def calculate_value(self, dep_values: dict):
-        discharge = dep_values.get("discharge")
-        capacity = dep_values.get("capacity")
-        if discharge is None or capacity in (None, 0):
-            return None
+        mode = self.definition.get("mode")
+        if mode == "difference":
+            return round(dep_values["a"] - dep_values["b"], 1)
+        if mode == "difference_quotient":
+            c = dep_values["c"]
+            if c == 0:
+                return None
+            return round((dep_values["a"] - dep_values["b"]) / c, 2)
+        if mode == "quotient":
+            b = dep_values["b"]
+            if b == 0:
+                return None
+            return round(dep_values["a"] / b, 2)
+        _LOGGER.warning("%s unknown derived mode '%s'", self._key, mode)
+        return None
+
 
-        cycles = round(discharge / capacity, 2)
-        self._attr_native_value = cycles
-        return cycles