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

@@ -918,6 +918,22 @@ 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
+        return bool(configdict.get(f"{group}_device", 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

@@ -37,14 +37,15 @@
 from .const import (
     CONF_BAUDRATE,
     CONF_CORE_HUB,
+    CONF_DRY_CONTACT_DEVICE,
     CONF_ENERGY_DASHBOARD_DEVICE,
+    CONF_EXTERNAL_GENERATOR_DEVICE,
     CONF_INTERFACE,
     CONF_INVERTER_NAME_SUFFIX,
     CONF_INVERTER_POWER_KW,
     CONF_MODBUS_ADDR,
     CONF_PLUGIN,
     CONF_READ_BATTERY,
-    CONF_READ_DCB,
     CONF_READ_EPS,
     CONF_READ_PM,
     CONF_SCAN_INTERVAL_FAST,
@@ -53,7 +54,9 @@
     CONF_TCP_TYPE,
     CONF_TIME_OUT,
     DEFAULT_BAUDRATE,
+    DEFAULT_DRY_CONTACT_DEVICE,
     DEFAULT_ENERGY_DASHBOARD_DEVICE,
+    DEFAULT_EXTERNAL_GENERATOR_DEVICE,
     # PLUGIN_PATH_OLDSTYLE,
     DEFAULT_INVERTER_NAME_SUFFIX,
     DEFAULT_INVERTER_POWER_KW,
@@ -62,7 +65,6 @@
     DEFAULT_PLUGIN,
     DEFAULT_PORT,
     DEFAULT_READ_BATTERY,
-    DEFAULT_READ_DCB,
     DEFAULT_READ_EPS,
     DEFAULT_READ_PM,
     DEFAULT_SCAN_INTERVAL,
@@ -153,8 +155,9 @@ def _configured_hub_names(handler: SchemaCommonFlowHandler) -> set[str]:
         vol.Optional(CONF_INVERTER_NAME_SUFFIX, description={"suggested_value": DEFAULT_INVERTER_NAME_SUFFIX}): str,
         vol.Optional(CONF_INVERTER_POWER_KW, default=DEFAULT_INVERTER_POWER_KW): cv.positive_int,
         vol.Optional(CONF_ENERGY_DASHBOARD_DEVICE, default=DEFAULT_ENERGY_DASHBOARD_DEVICE): bool,
+        vol.Optional(CONF_DRY_CONTACT_DEVICE, default=DEFAULT_DRY_CONTACT_DEVICE): bool,
+        vol.Optional(CONF_EXTERNAL_GENERATOR_DEVICE, default=DEFAULT_EXTERNAL_GENERATOR_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_PM, default=DEFAULT_READ_PM): bool,
         vol.Optional(CONF_TIME_OUT, default=DEFAULT_TIME_OUT): int,
     }
@@ -175,8 +178,9 @@ def _configured_hub_names(handler: SchemaCommonFlowHandler) -> set[str]:
         vol.Optional(CONF_INVERTER_NAME_SUFFIX): str,
         vol.Optional(CONF_INVERTER_POWER_KW, default=DEFAULT_INVERTER_POWER_KW): cv.positive_int,
         vol.Optional(CONF_ENERGY_DASHBOARD_DEVICE, default=DEFAULT_ENERGY_DASHBOARD_DEVICE): bool,
+        vol.Optional(CONF_DRY_CONTACT_DEVICE, default=DEFAULT_DRY_CONTACT_DEVICE): bool,
+        vol.Optional(CONF_EXTERNAL_GENERATOR_DEVICE, default=DEFAULT_EXTERNAL_GENERATOR_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_PM, default=DEFAULT_READ_PM): bool,
         vol.Optional(CONF_TIME_OUT, default=DEFAULT_TIME_OUT): int,
     }

custom_components/solax_modbus/const.py

@@ -60,6 +60,8 @@ class UnitOfReactivePower(StrEnum):  # type: ignore[no-redef]
 CONF_READ_BATTERY = "read_battery"
 CONF_CORE_HUB = "read_core_hub"
 CONF_ENERGY_DASHBOARD_DEVICE = "energy_dashboard_device"
+CONF_DRY_CONTACT_DEVICE = "dry_contact_device"
+CONF_EXTERNAL_GENERATOR_DEVICE = "external_generator_device"
 CONF_DEBUG_SETTINGS = "debug_settings"
 ATTR_MANUFACTURER = "SolaX Power"
 DEFAULT_INTERFACE = "tcp"
@@ -73,6 +75,8 @@ class UnitOfReactivePower(StrEnum):  # type: ignore[no-redef]
 ENERGY_DASHBOARD_DEVICE_ENABLED = True
 ENERGY_DASHBOARD_DEVICE_DISABLED = False
 DEFAULT_ENERGY_DASHBOARD_DEVICE = ENERGY_DASHBOARD_DEVICE_ENABLED
+DEFAULT_DRY_CONTACT_DEVICE = True
+DEFAULT_EXTERNAL_GENERATOR_DEVICE = True
 PLUGIN_PATH = f"{pathlib.Path(__file__).parent.absolute()}/plugin_*.py"
 SLEEPMODE_NONE = None
 SLEEPMODE_ZERO = 0  # when no communication at all
@@ -238,6 +242,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 +311,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 +333,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 +354,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 +385,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 +420,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)."""