Merge pull request #461 from Nino6689/feat/poll-profiles

Add extreme poll profile for tight control loops

Author: Pho3niX90

README.md

@@ -58,7 +58,9 @@ Whilst the solis inverters do provide total sensors for today, yesterday, month
 - **Storage Mode select** (renamed from "Work Mode", issue #413): mode changes now clear all conflicting mode bits — switching Self-Use ↔ Peak Shaving ↔ Feed-in writes exactly the values SolisCloud uses (grid-charge and wakeup bits are preserved). New *Reserve / Backup* options. The raw register value is exposed as a state attribute for debugging.
 - **Dual-meter support** (issue #425): enable *"Second smart meter installed"* to poll the Meter 2 block (33300-33337) on "Grid + PV Inverter" installs — per-phase V/A/W, total power, PF, frequency and lifetime import/export counters.
 - **Direct-meter grid energy for string inverters** (issue #410): grid import/export lifetime counters read from the attached meter (registers 3283-3286), for S5-GR3P-style installs without an EPM.
-- **Read-only mode completed** (issue #149): with *"Essential sensors only"* enabled, control entities (numbers/switches/selects/times) are no longer created.
+- **Read-only mode completed** (issue #149): under either reduced **poll profile**, control entities (numbers/switches/selects/times) are no longer created.
+- **Poll profiles** (issue #457): the *"Essential sensors only"* toggle is now a **Poll profile** select — *Full*, *Essential* or *Extreme*. Extreme polls only the live meter/CT and PV groups (plus the one-off identity groups), which is few enough Modbus frames that the fast-interval floor drops from 10s to **2s** — for tight control loops such as export limiting against grid voltage rise (issue #451). An opt-in toggle adds the battery/load group (SOC, household load, battery and grid-port power) for battery-aware automations. Existing `essential_only` settings migrate automatically. Entities outside the chosen profile are **not created**, rather than created and left unavailable.
+  Extreme mode is an optimisation, **not** a protection or compliance mechanism: a Home Assistant control loop cannot satisfy G100's requirement that an export limitation scheme hold its limit through component or communications failure.
 - **Diagnostics**: download a redacted support dump from the integration's menu.
 - **Repairs**: a repair issue is raised when the datalogger is unreachable for a sustained period, and auto-clears on reconnect.
 - New AC-grid-port lifetime energy sensors (registers 33186-33189, protocol Ver3.4).

custom_components/solis_modbus/__init__.py

@@ -18,6 +18,7 @@
     CONF_CONNECTION_TYPE,
     CONF_INVERTER_SERIAL,
     CONF_PARITY,
+    CONF_POLL_PROFILE,
     CONF_SERIAL_PORT,
     CONF_SLAVE,
     CONF_STOPBITS,
@@ -29,15 +30,23 @@
     DEFAULT_STOPBITS,
     DOMAIN,
     MODBUS_ILLEGAL_DATA_ADDRESS,
+    POLL_PROFILE_ESSENTIAL,
+    POLL_PROFILE_EXTREME,
+    POLL_PROFILE_FULL,
 )
 from .data.solis_config import SOLIS_INVERTERS, InverterConfig, InverterType, inverter_options_from_config
 from .data_retrieval import DataRetrieval
 from .helpers import (
     combine_u32,
     combine_u32_le,
+    derived_sensor_is_supported,
+    extreme_includes_battery,
     get_controller,
+    get_poll_profile,
+    group_in_poll_profile,
     iter_controllers,
     iter_platform_entities,
+    registers_declared_by,
     set_controller,
     split_s32,
     unique_id_generator,
@@ -554,28 +563,56 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry):
     # call async_unload_entry when async_setup_entry raises).
     try:
         controller._sensor_groups = []
-        essential_only = config.get("essential_only", False)
-        skipped_essential = 0
+        poll_profile = get_poll_profile(entry)
+        include_battery = extreme_includes_battery(entry)
+
+        # A profile that matches nothing would set the entry up with no sensors at
+        # all, which reads as a broken integration. Extreme currently only maps the
+        # hybrid groups, so fall back rather than silently produce an empty entry.
+        if poll_profile == POLL_PROFILE_EXTREME and not any(group.get("extreme") for group in sensors):
+            _LOGGER.warning(
+                "Extreme poll profile is not mapped for this inverter type yet; falling back to essential-only polling",
+            )
+            poll_profile = POLL_PROFILE_ESSENTIAL
+
+        skipped_by_profile = 0
+        selected_groups = []
         for group in sensors:
             feature_requirement = group.get("feature_requirement", [])
             if feature_requirement and not any(feature in inverter_config.features for feature in feature_requirement):
                 group_name = group.get("name", group.get("register_start", "Unnamed"))
                 _LOGGER.warning(f"Skipping sensor group '{group_name}' due to missing required features: {feature_requirement}")
                 continue
 
-            if essential_only and not group.get("essential", False):
-                skipped_essential += 1
+            if not group_in_poll_profile(group, poll_profile, include_battery):
+                skipped_by_profile += 1
                 continue
 
+            selected_groups.append(group)
             controller._sensor_groups.append(SolisSensorGroup(hass=hass, definition=group, controller=controller, identification=identification))
 
-        if essential_only:
+        if poll_profile != POLL_PROFILE_FULL:
             _LOGGER.info(
-                "Essential-only polling enabled: %d sensor group(s) skipped, %d remaining (reduces datalogger load)",
-                skipped_essential,
+                "Poll profile '%s' active: %d sensor group(s) skipped, %d remaining (reduces datalogger load)",
+                poll_profile,
+                skipped_by_profile,
                 len(controller._sensor_groups),
             )
 
+        # Derived sensors are computed from registers other groups poll, so a
+        # reduced profile has to filter them too — otherwise e.g. Power Factor
+        # (33079-33082) survives into extreme mode and never receives a value.
+        polled_registers = registers_declared_by(selected_groups)
+        known_registers = registers_declared_by(sensors)
+        supported_derived = [entity for entity in sensors_derived if derived_sensor_is_supported(entity, polled_registers, known_registers)]
+
+        if poll_profile != POLL_PROFILE_FULL and len(supported_derived) != len(sensors_derived):
+            _LOGGER.info(
+                "Poll profile '%s': %d derived sensor(s) skipped, their source registers are not polled",
+                poll_profile,
+                len(sensors_derived) - len(supported_derived),
+            )
+
         controller._derived_sensors = [
             SolisBaseSensor(
                 hass=hass,
@@ -592,7 +629,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry):
                 category=entity.get("category", None),
                 unique_id=unique_id_generator(controller, entity.get("unique", "reserve")),
             )
-            for entity in sensors_derived
+            for entity in supported_derived
         ]
 
         set_controller(hass, controller, entry)
@@ -910,10 +947,43 @@ async def async_migrate_entry(hass: HomeAssistant, config_entry: ConfigEntry) ->
         await async_migrate_dict_unique_ids(hass, config_entry)
         hass.config_entries.async_update_entry(config_entry, version=4)
 
+    if config_entry.version == 4:
+        _migrate_essential_only_to_poll_profile(hass, config_entry)
+        hass.config_entries.async_update_entry(config_entry, version=5)
+
     _LOGGER.info("Migration to version %s successful", config_entry.version)
     return True
 
 
+def _migrate_essential_only_to_poll_profile(hass: HomeAssistant, config_entry: ConfigEntry) -> None:
+    """Fold the `essential_only` boolean into the `poll_profile` select (#457).
+
+    Both data and options are rewritten: setup merges {**data, **options}, so a
+    leftover `essential_only` in options would shadow a migrated data key and
+    quietly keep the old behaviour.
+    """
+    merged = {**config_entry.data, **config_entry.options}
+    existing = merged.get(CONF_POLL_PROFILE)
+    had_legacy_key = "essential_only" in config_entry.data or "essential_only" in config_entry.options
+
+    if existing is not None and not had_legacy_key:
+        return
+
+    if existing is not None:
+        # Already on a profile, but a stale boolean is still present. Keep the
+        # chosen profile and drop the dead key rather than letting it linger.
+        profile = existing
+    else:
+        profile = POLL_PROFILE_ESSENTIAL if merged.get("essential_only", False) else POLL_PROFILE_FULL
+
+    data = {k: v for k, v in config_entry.data.items() if k != "essential_only"}
+    options = {k: v for k, v in config_entry.options.items() if k != "essential_only"}
+    data[CONF_POLL_PROFILE] = profile
+
+    hass.config_entries.async_update_entry(config_entry, data=data, options=options)
+    _LOGGER.info("Migrated essential_only=%s to poll_profile='%s'", merged.get("essential_only", False), profile)
+
+
 async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry):
     """Unload a Modbus config entry."""
     _LOGGER.debug("init async_unload_entry")

custom_components/solis_modbus/config_flow.py

@@ -11,8 +11,10 @@
     CONF_BAUDRATE,
     CONF_BYTESIZE,
     CONF_CONNECTION_TYPE,
+    CONF_EXTREME_INCLUDE_BATTERY,
     CONF_INVERTER_SERIAL,
     CONF_PARITY,
+    CONF_POLL_PROFILE,
     CONF_SERIAL_PORT,
     CONF_STOPBITS,
     CONN_TYPE_SERIAL,
@@ -22,6 +24,11 @@
     DEFAULT_PARITY,
     DEFAULT_STOPBITS,
     DOMAIN,
+    POLL_INTERVAL_FAST_MIN,
+    POLL_INTERVAL_FAST_MIN_EXTREME,
+    POLL_PROFILE_EXTREME,
+    POLL_PROFILE_FULL,
+    POLL_PROFILES,
 )
 from .data.enums import InverterType
 from .data.solis_config import CONNECTION_METHOD, SOLIS_INVERTERS, InverterConfig, inverter_options_from_config
@@ -42,10 +49,14 @@
     vol.Required(CONF_CONNECTION_TYPE, default=CONN_TYPE_TCP): vol.In(CONNECTION_TYPES),
     vol.Required(CONF_INVERTER_SERIAL): str,
     vol.Required("slave", default=1): int,
-    vol.Optional("poll_interval_fast", default=10): vol.All(int, vol.Range(min=10)),
+    # Floor is the extreme-profile minimum; _validate_poll_interval enforces the
+    # stricter default floor, which voluptuous can't do since the profile is
+    # chosen on this same form.
+    vol.Optional("poll_interval_fast", default=POLL_INTERVAL_FAST_MIN): vol.All(int, vol.Range(min=POLL_INTERVAL_FAST_MIN_EXTREME)),
     vol.Optional("poll_interval_normal", default=15): vol.All(int, vol.Range(min=15)),
     vol.Optional("poll_interval_slow", default=30): vol.All(int, vol.Range(min=30)),
-    vol.Required("essential_only", default=False): bool,
+    vol.Required(CONF_POLL_PROFILE, default=POLL_PROFILE_FULL): vol.In(POLL_PROFILES),
+    vol.Required(CONF_EXTREME_INCLUDE_BATTERY, default=False): bool,
     vol.Required("model", default=list(SOLIS_MODELS.keys())[0]): vol.In(SOLIS_MODELS),
     # Boolean options (Yes/No toggle)
     vol.Required("has_v2", default=True): bool,
@@ -79,10 +90,11 @@
 
 OPTIONS_SCHEMA = vol.Schema(
     {
-        vol.Required("poll_interval_fast"): vol.All(int, vol.Range(min=10)),
+        vol.Required("poll_interval_fast"): vol.All(int, vol.Range(min=POLL_INTERVAL_FAST_MIN_EXTREME)),
         vol.Required("poll_interval_normal"): vol.All(int, vol.Range(min=15)),
         vol.Required("poll_interval_slow"): vol.All(int, vol.Range(min=30)),
-        vol.Required("essential_only", default=False): bool,
+        vol.Required(CONF_POLL_PROFILE, default=POLL_PROFILE_FULL): vol.In(POLL_PROFILES),
+        vol.Required(CONF_EXTREME_INCLUDE_BATTERY, default=False): bool,
         vol.Required("model"): vol.In(SOLIS_MODELS),
         vol.Required("connection", default=list(CONNECTION_METHOD.keys())[0]): vol.In(CONNECTION_METHOD),
         # Boolean options (Yes/No toggle)
@@ -99,6 +111,21 @@
 )
 
 
+def _validate_poll_interval(config: dict) -> str | None:
+    """Enforce the fast-poll floor that applies to the chosen profile.
+
+    The schemas only declare the extreme floor, because the profile is picked on
+    the same form and voluptuous can't vary a field's range by another field's
+    value. Returns an error key, or None when the interval is acceptable.
+    """
+    profile = config.get(CONF_POLL_PROFILE, POLL_PROFILE_FULL)
+    floor = POLL_INTERVAL_FAST_MIN_EXTREME if profile == POLL_PROFILE_EXTREME else POLL_INTERVAL_FAST_MIN
+    interval = config.get("poll_interval_fast")
+    if interval is not None and int(interval) < floor:
+        return "poll_interval_below_floor"
+    return None
+
+
 async def _probe_tcp_port(host: str, port: int, timeout: float = 5.0) -> tuple[bool, str | None]:
     """Check that something is actually accepting TCP connections on host:port.
 
@@ -137,7 +164,7 @@ def clean_identification(iden: str | None) -> str | None:
 class ModbusConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
     """Modbus configuration flow."""
 
-    VERSION = 4
+    VERSION = 5
     MINOR_VERSION = 0
 
     def __init__(self):
@@ -211,6 +238,8 @@ async def async_step_reconfigure(self, user_input=None):
             elif any(other.unique_id == serial and other.entry_id != entry.entry_id for other in self.hass.config_entries.async_entries(DOMAIN)):
                 # Another entry already manages this inverter
                 return self.async_abort(reason="already_configured")
+            elif interval_error := _validate_poll_interval(data):
+                errors["base"] = interval_error
             else:
                 valid, err_key = await self._validate_config(data)
                 if valid:
@@ -243,7 +272,8 @@ async def _create_entry_from_input(self, data):
             data[CONF_INVERTER_SERIAL] = str(data[CONF_INVERTER_SERIAL]).upper()
 
         # 2. Validate Connection
-        valid, err_key = await self._validate_config(data)
+        interval_error = _validate_poll_interval(data)
+        valid, err_key = (False, interval_error) if interval_error else await self._validate_config(data)
         if not valid:
             errors["base"] = err_key or "cannot_connect"
 
@@ -353,7 +383,10 @@ async def async_step_init(self, user_input=None):
 
         if user_input is not None:
             merged = {**self.config_entry.options, **user_input}
-            return self.async_create_entry(title="", data=merged)
+            interval_error = _validate_poll_interval(merged)
+            if interval_error is None:
+                return self.async_create_entry(title="", data=merged)
+            errors["base"] = interval_error
 
         current = {**self.config_entry.data, **self.config_entry.options}
         return self.async_show_form(

custom_components/solis_modbus/const.py

@@ -37,3 +37,30 @@
 # Modbus exception code 2: the slave has no register at the requested address.
 # Distinguishes "you asked for the wrong thing" from "the read failed".
 MODBUS_ILLEGAL_DATA_ADDRESS = 2
+
+# Poll profiles (issue #457): how much of the register map gets polled.
+#
+# FULL      — every group the inverter's features allow.
+# ESSENTIAL — the core power-flow groups only (issue #412), no 43xxx settings
+#             groups, so writable entities are not created.
+# EXTREME   — live meter/CT + PV only, for tight control loops (issue #451).
+#             Small enough that a 2s fast interval is realistic: each group is
+#             one Modbus frame and the Solis spec requires >300ms between frames,
+#             so a full ~11-group pass can never be that fast.
+POLL_PROFILE_FULL = "full"
+POLL_PROFILE_ESSENTIAL = "essential"
+POLL_PROFILE_EXTREME = "extreme"
+
+CONF_POLL_PROFILE = "poll_profile"
+CONF_EXTREME_INCLUDE_BATTERY = "extreme_include_battery"
+
+POLL_PROFILES = {
+    POLL_PROFILE_FULL: "Full (all sensors)",
+    POLL_PROFILE_ESSENTIAL: "Essential only (reduce datalogger load)",
+    POLL_PROFILE_EXTREME: "Extreme (meter/CT + PV live only, for control loops)",
+}
+
+# Minimum fast-poll interval. The default floor protects the bus for everyone;
+# extreme mode polls few enough frames that a tighter loop is safe.
+POLL_INTERVAL_FAST_MIN = 10
+POLL_INTERVAL_FAST_MIN_EXTREME = 2