Hybrid Gen4: dry-contact section as a sub-device with dependency-driven availability

The Gen4 dry-contact load-management controls become their own HA
device ("<hub> Dry Contact", linked to the inverter via via_device,
same pattern as the battery pack devices), and each entity is only
available while its full parent chain in the app's dependency tree is
active:

  Dry Contact Mode (0xC3 -> 0x12F): Generator Control | Load Management
    Load Management (0xC2 -> 0x12E): Disabled | Manual Mode | Smart Save
      Manual Mode switch (0xB6 -> 0x122): only in Manual Mode
      Threshold On Feed-in Power (0xB7 -> 0x123)        Threshold Off Consumption (0xB9 -> 0x125)    |
      Threshold Off Battery SOC (0xBA -> 0x126)    | only in Smart Save
      Minimum Per On Signal (0xBB -> 0x127)        |
      Maximum Per Day (0xBC -> 0x128)              |
      Schedule (0xBD -> 0x129)                    /
        Work Start/End Time 1 and 2 (0xBE-0xC1 -> 0x12A-0x12D):
        only while Schedule is enabled

All register mappings were verified live on an X3-Hybrid-G4 15kW by
changing each setting in the SolaX app and tracking the readback.

New generic infrastructure, reusable by any plugin: entity descriptions
gain device_group (assigns the entity to a named sub-device) and
active_when ({sensor_key: allowed values} evaluated against polled
hub.data; keys not polled on a model never block availability). The
number, select, switch and time platforms honour both.

The "Read Dry Contact Box" setup question is removed: the dry-contact
entities are managed dynamically by the availability tree, so the DCB
feature flag is no longer needed for them and no longer gates anything
in the SolaX plugin (other brand plugins never had DCB-gated entities;
their unused boilerplate is untouched). Display names follow the app:
Work Mode -> Load Management (option Manual -> Manual Mode), Manual
Mode Control -> Manual Mode, Feedin On Power -> Threshold On Feed-in
Power, Consume Off Power -> Threshold Off Consumption, Switch Off SOC
-> Threshold Off Battery SOC, Maximum Per Day On -> Maximum Per Day.
Keys and entity ids are unchanged. Generator management entities are
intentionally untouched and stay on the main inverter device.

Author: Bl00d-B0b

custom_components/solax_modbus/__init__.py

@@ -34,6 +34,7 @@
 )
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.exceptions import HomeAssistantError
+from homeassistant.helpers import device_registry as dr
 from homeassistant.helpers import entity_registry as er
 from homeassistant.helpers.device_registry import DeviceInfo
 from homeassistant.helpers.event import async_track_time_interval
@@ -101,6 +102,9 @@
 from .const import (
     CONF_READ_EPS as CONF_READ_EPS,
 )
+from .const import (
+    CONF_READ_GEN as CONF_READ_GEN,
+)
 from .const import (
     DEFAULT_INTERFACE as DEFAULT_INTERFACE,
 )
@@ -119,6 +123,9 @@
 from .const import (
     DEFAULT_READ_EPS as DEFAULT_READ_EPS,
 )
+from .const import (
+    DEFAULT_READ_GEN as DEFAULT_READ_GEN,
+)
 from .const import (
     DEFAULT_SCAN_INTERVAL as DEFAULT_SCAN_INTERVAL,
 )
@@ -421,9 +428,61 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     await hub.async_init()
 
     entry.async_on_unload(entry.add_update_listener(config_entry_update_listener))
+
+    await async_cleanup_disabled_devices(hass, entry, hub)
     return True
 
 
+# Device groups that a config option can switch off, and the option controlling each.
+# The Energy Dashboard device is deliberately absent: it also hosts the dashboard
+# configuration switches, which exist independently of the dashboard option.
+GATED_DEVICE_GROUPS: dict[str, tuple[str, bool]] = {
+    "dry_contact": (CONF_READ_DCB, DEFAULT_READ_DCB),
+    "external_generator": (CONF_READ_GEN, DEFAULT_READ_GEN),
+}
+
+
+def device_group_of(device_entry: Any) -> str | None:
+    """Return the group name encoded in a device's solax identifiers, if any."""
+    for identifier in device_entry.identifiers:
+        parts = tuple(identifier)
+        if parts and parts[0] == DOMAIN and len(parts) > 2:
+            return str(parts[2])
+    return None
+
+
+async def async_cleanup_disabled_devices(hass: HomeAssistant, entry: ConfigEntry, hub: Any) -> None:
+    """Remove devices (and their entities) for device groups switched off in the options.
+
+    Home Assistant never removes devices on its own, so a device group that is no
+    longer created would otherwise linger in the registry with stale entities.
+    """
+    configdict = entry.options if entry.options else entry.data
+    dev_registry = dr.async_get(hass)
+    for device_entry in dr.async_entries_for_config_entry(dev_registry, entry.entry_id):
+        group = device_group_of(device_entry)
+        gate = GATED_DEVICE_GROUPS.get(group) if group else None
+        if gate is None:
+            continue
+        option, default = gate
+        if not configdict.get(option, default):
+            _LOGGER.info(f"{hub.name}: removing device {device_entry.name} - option {option} is disabled")
+            dev_registry.async_remove_device(device_entry.id)
+
+
+async def async_remove_config_entry_device(hass: HomeAssistant, entry: ConfigEntry, device_entry: Any) -> bool:
+    """Allow the user to delete devices this integration no longer provides.
+
+    The main inverter device of a running hub is kept; everything else (sub-devices
+    of a disabled feature, renamed hubs, removed battery packs) may be deleted.
+    """
+    group = device_group_of(device_entry)
+    if group != INVERTER_IDENT:
+        return True
+    hub_name = (entry.options or entry.data).get(CONF_NAME)
+    return not any(tuple(i)[:2] == (DOMAIN, hub_name) for i in device_entry.identifiers)
+
+
 async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Unload SolaX modbus entry and tear down transports cleanly."""
     name = entry.options.get("name")
@@ -918,6 +977,26 @@ def _warn_duplicate_inverter_configuration(self, interval: int) -> None:
             describe_modbus_connection(identity),
         )
 
+    def device_group_enabled(self, group: str | None) -> bool:
+        """Return whether a named device group is enabled in this entry's options."""
+        if not group:
+            return True
+        configdict = self.entry.options if self.entry.options else self.entry.data
+        if group == "dry_contact":
+            return bool(configdict.get(CONF_READ_DCB, DEFAULT_READ_DCB))
+        if group == "external_generator":
+            return bool(configdict.get(CONF_READ_GEN, DEFAULT_READ_GEN))
+        return True
+
+    def group_device_info(self, group: str) -> DeviceInfo:
+        """Return the DeviceInfo for a named sub-device (e.g. "dry_contact")."""
+        return DeviceInfo(
+            identifiers=cast(set[tuple[str, str]], {(DOMAIN, self._name, group)}),
+            name=f"{self._name} {group.replace('_', ' ').title()}",
+            manufacturer=self.plugin.plugin_manufacturer,
+            via_device=cast(tuple[str, str], (DOMAIN, self._name, INVERTER_IDENT)),
+        )
+
     def device_group_key(self, device_info: DeviceInfo) -> str:
         """Extract device group key from device_info identifiers.
 

custom_components/solax_modbus/config_flow.py

@@ -46,6 +46,7 @@
     CONF_READ_BATTERY,
     CONF_READ_DCB,
     CONF_READ_EPS,
+    CONF_READ_GEN,
     CONF_READ_PM,
     CONF_SCAN_INTERVAL_FAST,
     CONF_SCAN_INTERVAL_MEDIUM,
@@ -64,6 +65,7 @@
     DEFAULT_READ_BATTERY,
     DEFAULT_READ_DCB,
     DEFAULT_READ_EPS,
+    DEFAULT_READ_GEN,
     DEFAULT_READ_PM,
     DEFAULT_SCAN_INTERVAL,
     DEFAULT_SERIAL_PORT,
@@ -155,6 +157,7 @@ def _configured_hub_names(handler: SchemaCommonFlowHandler) -> set[str]:
         vol.Optional(CONF_ENERGY_DASHBOARD_DEVICE, default=DEFAULT_ENERGY_DASHBOARD_DEVICE): bool,
         vol.Optional(CONF_READ_EPS, default=DEFAULT_READ_EPS): bool,
         vol.Optional(CONF_READ_DCB, default=DEFAULT_READ_DCB): bool,
+        vol.Optional(CONF_READ_GEN, default=DEFAULT_READ_GEN): bool,
         vol.Optional(CONF_READ_PM, default=DEFAULT_READ_PM): bool,
         vol.Optional(CONF_TIME_OUT, default=DEFAULT_TIME_OUT): int,
     }
@@ -177,6 +180,7 @@ def _configured_hub_names(handler: SchemaCommonFlowHandler) -> set[str]:
         vol.Optional(CONF_ENERGY_DASHBOARD_DEVICE, default=DEFAULT_ENERGY_DASHBOARD_DEVICE): bool,
         vol.Optional(CONF_READ_EPS, default=DEFAULT_READ_EPS): bool,
         vol.Optional(CONF_READ_DCB, default=DEFAULT_READ_DCB): bool,
+        vol.Optional(CONF_READ_GEN, default=DEFAULT_READ_GEN): bool,
         vol.Optional(CONF_READ_PM, default=DEFAULT_READ_PM): bool,
         vol.Optional(CONF_TIME_OUT, default=DEFAULT_TIME_OUT): int,
     }

custom_components/solax_modbus/const.py

@@ -50,6 +50,7 @@ class UnitOfReactivePower(StrEnum):  # type: ignore[no-redef]
 CONF_INVERTER_POWER_KW = "inverter_power_kw"
 CONF_READ_EPS = "read_eps"
 CONF_READ_DCB = "read_dcb"
+CONF_READ_GEN = "read_gen"
 CONF_READ_PM = "read_pm"
 CONF_MODBUS_ADDR = "read_modbus_addr"
 CONF_INTERFACE = "interface"
@@ -66,6 +67,7 @@ class UnitOfReactivePower(StrEnum):  # type: ignore[no-redef]
 DEFAULT_SERIAL_PORT = "/dev/ttyUSB0"
 DEFAULT_READ_EPS = False
 DEFAULT_READ_DCB = False
+DEFAULT_READ_GEN = True
 DEFAULT_READ_PM = False
 DEFAULT_BAUDRATE = "19200"
 DEFAULT_PLUGIN = "solax"
@@ -238,6 +240,8 @@ class BaseModbusSensorEntityDescription(SensorEntityDescription):
     """Base class for modbus sensor declarations."""
 
     allowedtypes: int = 0  # overload with ALLDEFAULT from plugin
+    device_group: str | None = None  # assign the entity to a named sub-device instead of the main inverter device
+    active_when: dict[str, tuple[Any, ...]] | None = None  # {sensor_key: allowed values}; entity is unavailable unless every polled key matches
     order32: str | None = None  # per-sensor 32-bit word order override ("big"/"little"); None = plugin default
     modbus_min: int | None = None  # Minimum protocol version as reported by register 0x82 (e.g. 100 for V001.00); not the document revision.
     modbus_max: int | None = None  # Maximum protocol version as reported by register 0x82.
@@ -305,6 +309,8 @@ class BaseModbusSelectEntityDescription(SelectEntityDescription):
     """Base class for modbus select declarations."""
 
     allowedtypes: int = 0  # overload with ALLDEFAULT from plugin
+    device_group: str | None = None  # assign the entity to a named sub-device instead of the main inverter device
+    active_when: dict[str, tuple[Any, ...]] | None = None  # {sensor_key: allowed values}; entity is unavailable unless every polled key matches
     modbus_min: int | None = None  # Minimum protocol version as reported by register 0x82 (e.g. 100 for V001.00); not the document revision.
     modbus_max: int | None = None  # Maximum protocol version as reported by register 0x82.
     register: int | None = None
@@ -325,6 +331,8 @@ class BaseModbusSwitchEntityDescription(SwitchEntityDescription):
     """Base class for modbus switch declarations."""
 
     allowedtypes: int = 0  # overload with ALLDEFAULT from plugin
+    device_group: str | None = None  # assign the entity to a named sub-device instead of the main inverter device
+    active_when: dict[str, tuple[Any, ...]] | None = None  # {sensor_key: allowed values}; entity is unavailable unless every polled key matches
     modbus_min: int | None = None  # Minimum protocol version as reported by register 0x82 (e.g. 100 for V001.00); not the document revision.
     modbus_max: int | None = None  # Maximum protocol version as reported by register 0x82.
     register: int | None = None
@@ -344,6 +352,8 @@ class BaseModbusTimeEntityDescription(TimeEntityDescription):
     """Base class for modbus time declarations."""
 
     allowedtypes: int = 0  # overload with ALLDEFAULT from plugin
+    device_group: str | None = None  # assign the entity to a named sub-device instead of the main inverter device
+    active_when: dict[str, tuple[Any, ...]] | None = None  # {sensor_key: allowed values}; entity is unavailable unless every polled key matches
     modbus_min: int | None = None  # Minimum protocol version as reported by register 0x82 (e.g. 100 for V001.00); not the document revision.
     modbus_max: int | None = None  # Maximum protocol version as reported by register 0x82.
     scale: float | dict[Any, Any] | Callable[[Any, Any, dict[str, Any]], Any] = 1
@@ -373,6 +383,8 @@ class BaseModbusNumberEntityDescription(NumberEntityDescription):
     """Base class for modbus number declarations."""
 
     allowedtypes: int = 0  # overload with ALLDEFAULT from plugin
+    device_group: str | None = None  # assign the entity to a named sub-device instead of the main inverter device
+    active_when: dict[str, tuple[Any, ...]] | None = None  # {sensor_key: allowed values}; entity is unavailable unless every polled key matches
     modbus_min: int | None = None  # Minimum protocol version as reported by register 0x82 (e.g. 100 for V001.00); not the document revision.
     modbus_max: int | None = None  # Maximum protocol version as reported by register 0x82.
     register: int | None = None
@@ -406,6 +418,22 @@ def modbus_protocol_version(hub: Any) -> int:
         return 0
 
 
+def matches_active_when(hub: Any, description: Any) -> bool:
+    """Return whether an entity's active_when conditions are currently met.
+
+    Conditions reference polled hub.data keys; a key that is absent from
+    hub.data (not polled on this model) does not block availability.
+    """
+    conditions = getattr(description, "active_when", None)
+    if not conditions:
+        return True
+    data = getattr(hub, "data", {})
+    for key, allowed in conditions.items():
+        if key in data and data[key] not in allowed:
+            return False
+    return True
+
+
 def matches_modbus_protocol(hub: Any, description: Any) -> bool:
     """Return whether a description applies to the detected Modbus protocol version.
 

custom_components/solax_modbus/number.py

@@ -21,6 +21,7 @@
     WRITE_MULTISINGLE_MODBUS,
     WRITE_SINGLE_MODBUS,
     BaseModbusNumberEntityDescription,
+    matches_active_when,
     matches_modbus_protocol,
 )
 
@@ -52,10 +53,13 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry, async_add_e
             ) in number_info.read_scale_exceptions:
                 if hub.seriesnumber.startswith(prefix):
                     newdescr = replace(number_info, read_scale=value)
-        if plugin.matchInverterWithMask(hub._invertertype, newdescr.allowedtypes, hub.seriesnumber, newdescr.blacklist) and matches_modbus_protocol(
-            hub, newdescr
+        if (
+            plugin.matchInverterWithMask(hub._invertertype, newdescr.allowedtypes, hub.seriesnumber, newdescr.blacklist)
+            and matches_modbus_protocol(hub, newdescr)
+            and hub.device_group_enabled(newdescr.device_group)
         ):
-            number = SolaXModbusNumber(hub_name, hub, modbus_addr, hub.device_info, newdescr)
+            device_info = hub.group_device_info(newdescr.device_group) if newdescr.device_group else hub.device_info
+            number = SolaXModbusNumber(hub_name, hub, modbus_addr, device_info, newdescr)
             if newdescr.write_method == WRITE_DATA_LOCAL:
                 hub.writeLocals[newdescr.key] = newdescr
             # Use the explicit sensor_key if provided, otherwise fall back to the number's own key.
@@ -175,6 +179,10 @@ def should_poll(self) -> bool:
         """Data is delivered by the hub."""
         return False
 
+    @property
+    def available(self) -> bool:
+        return matches_active_when(self._hub, self.entity_description)
+
     @property
     def name(self) -> str:
         """Return the entity name (description name only — the device name provides context)."""