pylxpweb 0.1.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

pylxpweb/endpoints/control.py

@@ -8,6 +8,7 @@ This module provides device control functionality including:
 
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING
 
 from pylxpweb.endpoints.base import BaseEndpoint
@@ -20,6 +21,8 @@ from pylxpweb.models import (
 if TYPE_CHECKING:
     from pylxpweb.client import LuxpowerClient
 
+_LOGGER = logging.getLogger(__name__)
+
 
 class ControlEndpoints(BaseEndpoint):
     """Device control endpoints for parameters, functions, and quick charge."""
@@ -162,7 +165,72 @@ class ControlEndpoints(BaseEndpoint):
         response = await self.client._request(
             "POST", "/WManage/web/maintain/remoteSet/write", data=data
         )
-        return SuccessResponse.model_validate(response)
+        result = SuccessResponse.model_validate(response)
+
+        # Invalidate cache after successful write to ensure fresh data on next read
+        if result.success:
+            self.client.invalidate_cache_for_device(inverter_sn)
+
+        return result
+
+    async def write_parameters(
+        self,
+        inverter_sn: str,
+        parameters: dict[int, int],
+        client_type: str = "WEB",
+    ) -> SuccessResponse:
+        """Write multiple configuration parameters to the inverter.
+
+         WARNING: This changes device configuration!
+
+        This is a convenience method that writes register values directly.
+        For named parameters, use write_parameter() instead.
+
+        Args:
+            inverter_sn: Inverter serial number
+            parameters: Dict mapping register addresses to values
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            # Set multiple registers at once
+            await client.control.write_parameters(
+                "1234567890",
+                {21: 512, 66: 50, 67: 100}  # Register addresses and values
+            )
+        """
+        # Note: The API doesn't support batch writes, so we write sequentially
+        # For now, just write the first parameter (most common use case is single register)
+        # Multi-parameter support would require sequential writes with proper error handling
+        if not parameters:
+            return SuccessResponse(success=True)
+
+        # For now, we only support single parameter writes through this method
+        # Multi-parameter support would require discovering parameter names from register IDs
+        register, value = next(iter(parameters.items()))
+
+        # This is a simplified implementation - would need register-to-param mapping
+        # for production use. For now, used primarily by device classes for single writes.
+        await self.client._ensure_authenticated()
+
+        data = {
+            "inverterSn": inverter_sn,
+            "data": {str(register): value},
+            "clientType": client_type,
+        }
+
+        response = await self.client._request(
+            "POST", "/WManage/web/maintain/remoteSet/write", data=data
+        )
+        result = SuccessResponse.model_validate(response)
+
+        # Invalidate cache after successful write to ensure fresh data on next read
+        if result.success:
+            self.client.invalidate_cache_for_device(inverter_sn)
+
+        return result
 
     async def control_function(
         self,
@@ -219,7 +287,13 @@ class ControlEndpoints(BaseEndpoint):
         response = await self.client._request(
             "POST", "/WManage/web/maintain/remoteSet/functionControl", data=data
         )
-        return SuccessResponse.model_validate(response)
+        result = SuccessResponse.model_validate(response)
+
+        # Invalidate cache after successful write to ensure fresh data on next read
+        if result.success:
+            self.client.invalidate_cache_for_device(inverter_sn)
+
+        return result
 
     async def start_quick_charge(
         self, inverter_sn: str, client_type: str = "WEB"
@@ -304,3 +378,907 @@ class ControlEndpoints(BaseEndpoint):
             cache_endpoint="quick_charge_status",
         )
         return QuickChargeStatus.model_validate(response)
+
+    async def start_quick_discharge(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Start quick discharge operation.
+
+         WARNING: This starts discharging!
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            result = await client.control.start_quick_discharge("1234567890")
+            if result.success:
+                print("Quick discharge started successfully")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"inverterSn": inverter_sn, "clientType": client_type}
+
+        response = await self.client._request(
+            "POST", "/WManage/web/config/quickDischarge/start", data=data
+        )
+        return SuccessResponse.model_validate(response)
+
+    async def stop_quick_discharge(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Stop quick discharge operation.
+
+         WARNING: This stops discharging!
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            result = await client.control.stop_quick_discharge("1234567890")
+            if result.success:
+                print("Quick discharge stopped successfully")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"inverterSn": inverter_sn, "clientType": client_type}
+
+        response = await self.client._request(
+            "POST", "/WManage/web/config/quickDischarge/stop", data=data
+        )
+        return SuccessResponse.model_validate(response)
+
+    # ============================================================================
+    # Convenience Helper Methods
+    # ============================================================================
+
+    async def enable_battery_backup(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable battery backup (EPS) mode.
+
+        Convenience wrapper for control_function(..., "FUNC_EPS_EN", True).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_battery_backup("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_EPS_EN", True, client_type=client_type
+        )
+
+    async def disable_battery_backup(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Disable battery backup (EPS) mode.
+
+        Convenience wrapper for control_function(..., "FUNC_EPS_EN", False).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.disable_battery_backup("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_EPS_EN", False, client_type=client_type
+        )
+
+    async def enable_battery_backup_ctrl(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable battery backup control mode (working mode).
+
+        This controls FUNC_BATTERY_BACKUP_CTRL, which is distinct from
+        FUNC_EPS_EN (EPS/off-grid mode). Battery backup control is a
+        working mode setting that affects how the inverter manages
+        battery reserves for backup power.
+
+        Convenience wrapper for control_function(..., "FUNC_BATTERY_BACKUP_CTRL", True).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_battery_backup_ctrl("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_BATTERY_BACKUP_CTRL", True, client_type=client_type
+        )
+
+    async def disable_battery_backup_ctrl(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Disable battery backup control mode (working mode).
+
+        This controls FUNC_BATTERY_BACKUP_CTRL, which is distinct from
+        FUNC_EPS_EN (EPS/off-grid mode). Battery backup control is a
+        working mode setting that affects how the inverter manages
+        battery reserves for backup power.
+
+        Convenience wrapper for control_function(..., "FUNC_BATTERY_BACKUP_CTRL", False).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.disable_battery_backup_ctrl("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_BATTERY_BACKUP_CTRL", False, client_type=client_type
+        )
+
+    async def enable_normal_mode(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable normal operating mode (power on).
+
+        Convenience wrapper for control_function(..., "FUNC_SET_TO_STANDBY", True).
+        Note: FUNC_SET_TO_STANDBY = True means NOT in standby (normal mode).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_normal_mode("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_SET_TO_STANDBY", True, client_type=client_type
+        )
+
+    async def enable_standby_mode(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable standby mode (power off).
+
+        Convenience wrapper for control_function(..., "FUNC_SET_TO_STANDBY", False).
+        Note: FUNC_SET_TO_STANDBY = False means standby mode is active.
+
+        WARNING: This powers off the inverter!
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_standby_mode("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_SET_TO_STANDBY", False, client_type=client_type
+        )
+
+    async def enable_grid_peak_shaving(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable grid peak shaving mode.
+
+        Convenience wrapper for control_function(..., "FUNC_GRID_PEAK_SHAVING", True).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_grid_peak_shaving("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_GRID_PEAK_SHAVING", True, client_type=client_type
+        )
+
+    async def disable_grid_peak_shaving(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Disable grid peak shaving mode.
+
+        Convenience wrapper for control_function(..., "FUNC_GRID_PEAK_SHAVING", False).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.disable_grid_peak_shaving("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_GRID_PEAK_SHAVING", False, client_type=client_type
+        )
+
+    async def get_battery_backup_status(self, inverter_sn: str) -> bool:
+        """Get battery backup (EPS) enabled status.
+
+        Reads register 21 (function enable) and extracts FUNC_EPS_EN bit.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            bool: True if EPS mode is enabled, False otherwise
+
+        Example:
+            >>> enabled = await client.control.get_battery_backup_status("1234567890")
+            >>> if enabled:
+            >>>     print("EPS mode is active")
+        """
+        response = await self.read_parameters(inverter_sn, 21, 1)
+        value = response.parameters.get("FUNC_EPS_EN", False)
+        return bool(value)
+
+    # ============================================================================
+    # Working Mode Controls (Issue #16)
+    # ============================================================================
+
+    async def enable_ac_charge_mode(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable AC charge mode to allow battery charging from grid.
+
+        Convenience wrapper for control_function(..., "FUNC_AC_CHARGE", True).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_ac_charge_mode("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_AC_CHARGE", True, client_type=client_type
+        )
+
+    async def disable_ac_charge_mode(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Disable AC charge mode.
+
+        Convenience wrapper for control_function(..., "FUNC_AC_CHARGE", False).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.disable_ac_charge_mode("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_AC_CHARGE", False, client_type=client_type
+        )
+
+    async def get_ac_charge_mode_status(self, inverter_sn: str) -> bool:
+        """Get current AC charge mode status.
+
+        Reads register 21 (function enable) and extracts FUNC_AC_CHARGE bit.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            bool: True if AC charge mode is enabled, False otherwise
+
+        Example:
+            >>> enabled = await client.control.get_ac_charge_mode_status("1234567890")
+            >>> if enabled:
+            >>>     print("AC charge mode is active")
+        """
+        response = await self.read_parameters(inverter_sn, 21, 1)
+        value = response.parameters.get("FUNC_AC_CHARGE", False)
+        return bool(value)
+
+    async def enable_pv_charge_priority(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable PV charge priority mode during specified hours.
+
+        Convenience wrapper for control_function(..., "FUNC_FORCED_CHG_EN", True).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_pv_charge_priority("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_FORCED_CHG_EN", True, client_type=client_type
+        )
+
+    async def disable_pv_charge_priority(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Disable PV charge priority mode.
+
+        Convenience wrapper for control_function(..., "FUNC_FORCED_CHG_EN", False).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.disable_pv_charge_priority("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_FORCED_CHG_EN", False, client_type=client_type
+        )
+
+    async def get_pv_charge_priority_status(self, inverter_sn: str) -> bool:
+        """Get current PV charge priority status.
+
+        Reads register 21 (function enable) and extracts FUNC_FORCED_CHG_EN bit.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            bool: True if PV charge priority is enabled, False otherwise
+
+        Example:
+            >>> enabled = await client.control.get_pv_charge_priority_status("1234567890")
+            >>> if enabled:
+            >>>     print("PV charge priority mode is active")
+        """
+        response = await self.read_parameters(inverter_sn, 21, 1)
+        value = response.parameters.get("FUNC_FORCED_CHG_EN", False)
+        return bool(value)
+
+    async def enable_forced_discharge(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable forced discharge mode for grid export.
+
+        Convenience wrapper for control_function(..., "FUNC_FORCED_DISCHG_EN", True).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_forced_discharge("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_FORCED_DISCHG_EN", True, client_type=client_type
+        )
+
+    async def disable_forced_discharge(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Disable forced discharge mode.
+
+        Convenience wrapper for control_function(..., "FUNC_FORCED_DISCHG_EN", False).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.disable_forced_discharge("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_FORCED_DISCHG_EN", False, client_type=client_type
+        )
+
+    async def get_forced_discharge_status(self, inverter_sn: str) -> bool:
+        """Get current forced discharge status.
+
+        Reads register 21 (function enable) and extracts FUNC_FORCED_DISCHG_EN bit.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            bool: True if forced discharge is enabled, False otherwise
+
+        Example:
+            >>> enabled = await client.control.get_forced_discharge_status("1234567890")
+            >>> if enabled:
+            >>>     print("Forced discharge mode is active")
+        """
+        response = await self.read_parameters(inverter_sn, 21, 1)
+        value = response.parameters.get("FUNC_FORCED_DISCHG_EN", False)
+        return bool(value)
+
+    async def enable_peak_shaving_mode(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable grid peak shaving mode.
+
+        Convenience wrapper for control_function(..., "FUNC_GRID_PEAK_SHAVING", True).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_peak_shaving_mode("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_GRID_PEAK_SHAVING", True, client_type=client_type
+        )
+
+    async def disable_peak_shaving_mode(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Disable grid peak shaving mode.
+
+        Convenience wrapper for control_function(..., "FUNC_GRID_PEAK_SHAVING", False).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.disable_peak_shaving_mode("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_GRID_PEAK_SHAVING", False, client_type=client_type
+        )
+
+    async def get_peak_shaving_mode_status(self, inverter_sn: str) -> bool:
+        """Get current peak shaving mode status.
+
+        Reads register 21 (function enable) and extracts FUNC_GRID_PEAK_SHAVING bit.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            bool: True if peak shaving mode is enabled, False otherwise
+
+        Example:
+            >>> enabled = await client.control.get_peak_shaving_mode_status("1234567890")
+            >>> if enabled:
+            >>>     print("Peak shaving mode is active")
+        """
+        response = await self.read_parameters(inverter_sn, 21, 1)
+        value = response.parameters.get("FUNC_GRID_PEAK_SHAVING", False)
+        return bool(value)
+
+    # ============================================================================
+    # Green Mode Controls (Off-Grid Mode in Web Monitor)
+    # ============================================================================
+
+    async def enable_green_mode(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Enable green mode (off-grid mode in the web monitoring display).
+
+        Green Mode controls the off-grid operating mode toggle visible in the
+        EG4 web monitoring interface. When enabled, the inverter operates in
+        an off-grid optimized configuration.
+
+        Note: This is FUNC_GREEN_EN in register 110, distinct from FUNC_EPS_EN
+        (battery backup/EPS mode) in register 21.
+
+        Convenience wrapper for control_function(..., "FUNC_GREEN_EN", True).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.enable_green_mode("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_GREEN_EN", True, client_type=client_type
+        )
+
+    async def disable_green_mode(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Disable green mode (off-grid mode in the web monitoring display).
+
+        Green Mode controls the off-grid operating mode toggle visible in the
+        EG4 web monitoring interface. When disabled, the inverter operates in
+        standard grid-tied configuration.
+
+        Note: This is FUNC_GREEN_EN in register 110, distinct from FUNC_EPS_EN
+        (battery backup/EPS mode) in register 21.
+
+        Convenience wrapper for control_function(..., "FUNC_GREEN_EN", False).
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            >>> result = await client.control.disable_green_mode("1234567890")
+            >>> result.success
+            True
+        """
+        return await self.control_function(
+            inverter_sn, "FUNC_GREEN_EN", False, client_type=client_type
+        )
+
+    async def get_green_mode_status(self, inverter_sn: str) -> bool:
+        """Get current green mode (off-grid mode) status.
+
+        Green Mode controls the off-grid operating mode toggle visible in the
+        EG4 web monitoring interface.
+
+        Reads register 110 (system functions) and extracts FUNC_GREEN_EN bit.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            bool: True if green mode is enabled, False otherwise
+
+        Example:
+            >>> enabled = await client.control.get_green_mode_status("1234567890")
+            >>> if enabled:
+            >>>     print("Green mode (off-grid) is active")
+        """
+        response = await self.read_parameters(inverter_sn, 110, 1)
+        value = response.parameters.get("FUNC_GREEN_EN", False)
+        return bool(value)
+
+    async def read_device_parameters_ranges(self, inverter_sn: str) -> dict[str, int | bool]:
+        """Read all device parameters across three common register ranges.
+
+        This method combines three read_parameters() calls:
+        - Range 1: 0-126 (System config, grid protection)
+        - Range 2: 127-253 (Additional config)
+        - Range 3: 240-366 (Extended parameters)
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            dict: Combined parameters from all three ranges
+
+        Example:
+            >>> params = await client.control.read_device_parameters_ranges("1234567890")
+            >>> params["HOLD_AC_CHARGE_POWER_CMD"]
+            50
+            >>> params["FUNC_EPS_EN"]
+            True
+        """
+        import asyncio
+
+        # Read all three ranges concurrently
+        range1_task = self.read_parameters(inverter_sn, 0, 127)
+        range2_task = self.read_parameters(inverter_sn, 127, 127)
+        range3_task = self.read_parameters(inverter_sn, 240, 127)
+
+        range1, range2, range3 = await asyncio.gather(
+            range1_task, range2_task, range3_task, return_exceptions=True
+        )
+
+        # Combine parameters from all ranges
+        combined: dict[str, int | bool] = {}
+
+        if not isinstance(range1, BaseException):
+            combined.update(range1.parameters)
+
+        if not isinstance(range2, BaseException):
+            combined.update(range2.parameters)
+
+        if not isinstance(range3, BaseException):
+            combined.update(range3.parameters)
+
+        return combined
+
+    # ============================================================================
+    # Battery Current Control (Added in v0.3)
+    # ============================================================================
+
+    async def set_battery_charge_current(
+        self,
+        inverter_sn: str,
+        amperes: int,
+        *,
+        validate_battery_limits: bool = True,
+    ) -> SuccessResponse:
+        """Set battery charge current limit.
+
+        Controls the maximum current allowed to charge batteries.
+
+        Common use cases:
+        - Prevent inverter throttling during high solar production
+        - Time-of-use optimization (reduce charge during peak rates)
+        - Battery health management (gentle charging)
+        - Weather-based automation (reduce on sunny days, maximize on cloudy)
+
+        Power Calculation (48V nominal system):
+        - 50A = ~2.4kW
+        - 100A = ~4.8kW
+        - 150A = ~7.2kW
+        - 200A = ~9.6kW
+        - 250A = ~12kW
+
+        Args:
+            inverter_sn: Inverter serial number
+            amperes: Charge current limit (0-250 A)
+            validate_battery_limits: Warn if value exceeds typical battery limits
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Raises:
+            ValueError: If amperes not in valid range (0-250 A)
+
+        Warning:
+            CRITICAL: Never exceed your battery's maximum charge current rating.
+            Check battery manufacturer specifications before setting high values.
+            Monitor battery temperature during high current operations.
+
+        Example:
+            >>> # Prevent throttling on sunny days (limit to ~4kW charge at 48V)
+            >>> await client.control.set_battery_charge_current("1234567890", 80)
+            SuccessResponse(success=True)
+
+            >>> # Maximum charge on cloudy days
+            >>> await client.control.set_battery_charge_current("1234567890", 200)
+            SuccessResponse(success=True)
+        """
+        if not (0 <= amperes <= 250):
+            raise ValueError(f"Battery charge current must be between 0-250 A, got {amperes}")
+
+        if validate_battery_limits and amperes > 200:
+            _LOGGER.warning(
+                "Setting battery charge current to %d A. "
+                "Ensure this does not exceed your battery's maximum rating. "
+                "Typical limits: 200A for 10kWh, 150A for 7.5kWh, 100A for 5kWh.",
+                amperes,
+            )
+
+        return await self.write_parameter(inverter_sn, "HOLD_LEAD_ACID_CHARGE_RATE", str(amperes))
+
+    async def set_battery_discharge_current(
+        self,
+        inverter_sn: str,
+        amperes: int,
+        *,
+        validate_battery_limits: bool = True,
+    ) -> SuccessResponse:
+        """Set battery discharge current limit.
+
+        Controls the maximum current allowed to discharge from batteries.
+
+        Common use cases:
+        - Preserve battery capacity during grid outages
+        - Extend battery lifespan (conservative discharge)
+        - Emergency power management
+        - Peak load management
+
+        Args:
+            inverter_sn: Inverter serial number
+            amperes: Discharge current limit (0-250 A)
+            validate_battery_limits: Warn if value exceeds typical battery limits
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Raises:
+            ValueError: If amperes not in valid range (0-250 A)
+
+        Warning:
+            Never exceed your battery's maximum discharge current rating.
+            Check battery manufacturer specifications.
+
+        Example:
+            >>> # Conservative discharge for battery longevity
+            >>> await client.control.set_battery_discharge_current("1234567890", 150)
+            SuccessResponse(success=True)
+
+            >>> # Minimal discharge during grid outage
+            >>> await client.control.set_battery_discharge_current("1234567890", 50)
+            SuccessResponse(success=True)
+        """
+        if not (0 <= amperes <= 250):
+            raise ValueError(f"Battery discharge current must be between 0-250 A, got {amperes}")
+
+        if validate_battery_limits and amperes > 200:
+            _LOGGER.warning(
+                "Setting battery discharge current to %d A. "
+                "Ensure this does not exceed your battery's maximum rating.",
+                amperes,
+            )
+
+        return await self.write_parameter(
+            inverter_sn, "HOLD_LEAD_ACID_DISCHARGE_RATE", str(amperes)
+        )
+
+    async def get_battery_charge_current(self, inverter_sn: str) -> int:
+        """Get current battery charge current limit.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            int: Current charge current limit in Amperes (0-250 A)
+
+        Example:
+            >>> current = await client.control.get_battery_charge_current("1234567890")
+            >>> print(f"Charge limit: {current} A (~{current * 0.048:.1f} kW at 48V)")
+            Charge limit: 200 A (~9.6 kW at 48V)
+        """
+        params = await self.read_device_parameters_ranges(inverter_sn)
+        return int(params.get("HOLD_LEAD_ACID_CHARGE_RATE", 200))
+
+    async def get_battery_discharge_current(self, inverter_sn: str) -> int:
+        """Get current battery discharge current limit.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            int: Current discharge current limit in Amperes (0-250 A)
+
+        Example:
+            >>> current = await client.control.get_battery_discharge_current("1234567890")
+            >>> print(f"Discharge limit: {current} A")
+            Discharge limit: 200 A
+        """
+        params = await self.read_device_parameters_ranges(inverter_sn)
+        return int(params.get("HOLD_LEAD_ACID_DISCHARGE_RATE", 200))
+
+    # ============================================================================
+    # System SOC Limit Controls
+    # ============================================================================
+
+    async def set_system_charge_soc_limit(
+        self,
+        inverter_sn: str,
+        percent: int,
+    ) -> SuccessResponse:
+        """Set the system charge SOC limit.
+
+        Controls the maximum State of Charge (SOC) percentage the battery will
+        charge to during normal operation.
+
+        Args:
+            inverter_sn: Inverter serial number
+            percent: Target SOC limit (0-101%)
+                - 0-100: Stop charging when battery reaches this SOC
+                - 101: Special value to enable top balancing (allows full charge
+                       with cell balancing for lithium batteries)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Raises:
+            ValueError: If percent not in valid range (0-101)
+
+        Note:
+            Setting 101% enables top balancing mode, which allows the battery
+            management system to fully charge and balance individual cells.
+            This is recommended periodically for lithium battery health.
+
+        Example:
+            >>> # Limit charging to 90% for daily use (extends battery life)
+            >>> await client.control.set_system_charge_soc_limit("1234567890", 90)
+            SuccessResponse(success=True)
+
+            >>> # Enable top balancing (charge to 100% with cell balancing)
+            >>> await client.control.set_system_charge_soc_limit("1234567890", 101)
+            SuccessResponse(success=True)
+        """
+        if not (0 <= percent <= 101):
+            raise ValueError(
+                f"System charge SOC limit must be between 0-101%, got {percent}. "
+                "Use 101 for top balancing mode."
+            )
+
+        return await self.write_parameter(inverter_sn, "HOLD_SYSTEM_CHARGE_SOC_LIMIT", str(percent))
+
+    async def get_system_charge_soc_limit(self, inverter_sn: str) -> int:
+        """Get the current system charge SOC limit.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            int: Current charge SOC limit (0-101%)
+                - 0-100: Normal SOC limit
+                - 101: Top balancing mode enabled
+
+        Example:
+            >>> limit = await client.control.get_system_charge_soc_limit("1234567890")
+            >>> if limit == 101:
+            >>>     print("Top balancing enabled")
+            >>> else:
+            >>>     print(f"Charge limit: {limit}%")
+        """
+        params = await self.read_device_parameters_ranges(inverter_sn)
+        return int(params.get("HOLD_SYSTEM_CHARGE_SOC_LIMIT", 100))