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

pylxpweb/devices/inverters/generic.py

@@ -0,0 +1,192 @@
+"""Generic inverter implementation for standard EG4/Luxpower models.
+
+This module provides the GenericInverter class that handles all standard
+inverter models including FlexBOSS21, FlexBOSS18, 18KPV, 12KPV, and XP.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..models import DeviceClass, Entity, StateClass
+from .base import BaseInverter
+
+if TYPE_CHECKING:
+    pass
+
+
+class GenericInverter(BaseInverter):
+    """Generic inverter for standard EG4/Luxpower models.
+
+    Handles all standard inverter models:
+    - FlexBOSS21 (21kW)
+    - FlexBOSS18 (18kW)
+    - 18KPV (18kW)
+    - 12KPV (12kW)
+    - XP (various power ratings)
+
+    Example:
+        ```python
+        inverter = GenericInverter(
+            client=client,
+            serial_number="1234567890",
+            model="FlexBOSS21"
+        )
+        await inverter.refresh()
+        print(f"Power: {inverter.power_output}W")
+        print(f"SOC: {inverter.battery_soc}%")
+        ```
+    """
+
+    def to_entities(self) -> list[Entity]:
+        """Generate entities for this inverter.
+
+        Returns:
+            List of Entity objects representing sensors for this inverter.
+        """
+        entities = []
+
+        # Power sensors
+        if self._runtime:
+            # AC Power Output
+            entities.append(
+                Entity(
+                    unique_id=f"{self.serial_number}_power",
+                    name=f"{self.model} {self.serial_number} Power",
+                    device_class=DeviceClass.POWER,
+                    state_class=StateClass.MEASUREMENT,
+                    unit_of_measurement="W",
+                    value=self.power_output,
+                )
+            )
+
+            # Battery SOC
+            if self.battery_soc is not None:
+                entities.append(
+                    Entity(
+                        unique_id=f"{self.serial_number}_soc",
+                        name=f"{self.model} {self.serial_number} Battery SOC",
+                        device_class=DeviceClass.BATTERY,
+                        state_class=StateClass.MEASUREMENT,
+                        unit_of_measurement="%",
+                        value=self.battery_soc,
+                    )
+                )
+
+            # Battery Voltage
+            if hasattr(self._runtime, "vBat") and self._runtime.vBat:
+                entities.append(
+                    Entity(
+                        unique_id=f"{self.serial_number}_battery_voltage",
+                        name=f"{self.model} {self.serial_number} Battery Voltage",
+                        device_class=DeviceClass.VOLTAGE,
+                        state_class=StateClass.MEASUREMENT,
+                        unit_of_measurement="V",
+                        value=self._runtime.vBat / 100.0,  # Scaled value
+                    )
+                )
+
+            # PV Power
+            if hasattr(self._runtime, "ppv"):
+                entities.append(
+                    Entity(
+                        unique_id=f"{self.serial_number}_pv_power",
+                        name=f"{self.model} {self.serial_number} PV Power",
+                        device_class=DeviceClass.POWER,
+                        state_class=StateClass.MEASUREMENT,
+                        unit_of_measurement="W",
+                        value=self._runtime.ppv,
+                    )
+                )
+
+            # Grid Power
+            if hasattr(self._runtime, "pToGrid"):
+                entities.append(
+                    Entity(
+                        unique_id=f"{self.serial_number}_grid_power",
+                        name=f"{self.model} {self.serial_number} Grid Power",
+                        device_class=DeviceClass.POWER,
+                        state_class=StateClass.MEASUREMENT,
+                        unit_of_measurement="W",
+                        value=self._runtime.pToGrid,
+                    )
+                )
+
+            # Load Power
+            if hasattr(self._runtime, "pToUser"):
+                entities.append(
+                    Entity(
+                        unique_id=f"{self.serial_number}_load_power",
+                        name=f"{self.model} {self.serial_number} Load Power",
+                        device_class=DeviceClass.POWER,
+                        state_class=StateClass.MEASUREMENT,
+                        unit_of_measurement="W",
+                        value=self._runtime.pToUser,
+                    )
+                )
+
+            # Battery Charge/Discharge Power
+            if hasattr(self._runtime, "batPower"):
+                entities.append(
+                    Entity(
+                        unique_id=f"{self.serial_number}_battery_power",
+                        name=f"{self.model} {self.serial_number} Battery Power",
+                        device_class=DeviceClass.POWER,
+                        state_class=StateClass.MEASUREMENT,
+                        unit_of_measurement="W",
+                        value=self._runtime.batPower,
+                    )
+                )
+
+            # Temperature sensors
+            if hasattr(self._runtime, "tinner"):
+                entities.append(
+                    Entity(
+                        unique_id=f"{self.serial_number}_temp_internal",
+                        name=f"{self.model} {self.serial_number} Internal Temperature",
+                        device_class=DeviceClass.TEMPERATURE,
+                        state_class=StateClass.MEASUREMENT,
+                        unit_of_measurement="°C",
+                        value=self._runtime.tinner,
+                    )
+                )
+
+            if hasattr(self._runtime, "tBat"):
+                entities.append(
+                    Entity(
+                        unique_id=f"{self.serial_number}_temp_battery",
+                        name=f"{self.model} {self.serial_number} Battery Temperature",
+                        device_class=DeviceClass.TEMPERATURE,
+                        state_class=StateClass.MEASUREMENT,
+                        unit_of_measurement="°C",
+                        value=self._runtime.tBat,
+                    )
+                )
+
+        # Energy sensors
+        if self._energy:
+            # Today's Production
+            entities.append(
+                Entity(
+                    unique_id=f"{self.serial_number}_energy_today",
+                    name=f"{self.model} {self.serial_number} Energy Today",
+                    device_class=DeviceClass.ENERGY,
+                    state_class=StateClass.TOTAL_INCREASING,
+                    unit_of_measurement="kWh",
+                    value=self.total_energy_today,
+                )
+            )
+
+            # Lifetime Production
+            entities.append(
+                Entity(
+                    unique_id=f"{self.serial_number}_energy_total",
+                    name=f"{self.model} {self.serial_number} Energy Total",
+                    device_class=DeviceClass.ENERGY,
+                    state_class=StateClass.TOTAL_INCREASING,
+                    unit_of_measurement="kWh",
+                    value=self.total_energy_lifetime,
+                )
+            )
+
+        return entities

pylxpweb/devices/inverters/hybrid.py

@@ -0,0 +1,274 @@
+"""Hybrid inverter implementation for grid-tied models with battery storage.
+
+This module provides the HybridInverter class for hybrid inverters that support:
+- AC charging from grid
+- Forced charge/discharge
+- EPS (backup) mode
+- Time-of-use scheduling
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .generic import GenericInverter
+
+if TYPE_CHECKING:
+    pass
+
+
+class HybridInverter(GenericInverter):
+    """Hybrid inverter with grid-tied and battery backup capabilities.
+
+    Extends GenericInverter with hybrid-specific controls:
+    - AC charging from grid
+    - Forced charge/discharge
+    - EPS/backup mode enable/disable
+    - Time-based charge/discharge scheduling
+
+    Suitable for models: FlexBOSS21, FlexBOSS18, 18KPV, 12KPV
+
+    Example:
+        ```python
+        inverter = HybridInverter(
+            client=client,
+            serial_number="1234567890",
+            model="18KPV"
+        )
+
+        # Enable AC charging at 50% power up to 100% SOC
+        await inverter.set_ac_charge(enabled=True, power_percent=50, soc_limit=100)
+
+        # Enable EPS backup mode
+        await inverter.set_eps_enabled(True)
+
+        # Set forced charge
+        await inverter.set_forced_charge(True)
+        ```
+    """
+
+    # ============================================================================
+    # Hybrid-Specific Control Operations
+    # ============================================================================
+
+    async def get_ac_charge_settings(self) -> dict[str, int | bool]:
+        """Get AC charge configuration.
+
+        Returns:
+            Dictionary with:
+            - enabled: AC charge function enabled
+            - power_percent: Charge power (0-100%)
+            - soc_limit: Target SOC (0-100%)
+            - schedule1_enabled: Time schedule 1 enabled
+            - schedule2_enabled: Time schedule 2 enabled
+
+        Example:
+            >>> settings = await inverter.get_ac_charge_settings()
+            >>> settings
+            {
+                'enabled': True,
+                'power_percent': 50,
+                'soc_limit': 100,
+                'schedule1_enabled': True,
+                'schedule2_enabled': False
+            }
+        """
+        from pylxpweb.constants import (
+            FUNC_EN_BIT_AC_CHARGE_EN,
+            FUNC_EN_REGISTER,
+            HOLD_AC_CHARGE_POWER_CMD,
+        )
+
+        # Read function enable register for AC charge bit
+        func_params = await self.read_parameters(FUNC_EN_REGISTER, 1)
+        func_value = func_params.get(f"reg_{FUNC_EN_REGISTER}", 0)
+        ac_charge_enabled = bool(func_value & (1 << FUNC_EN_BIT_AC_CHARGE_EN))
+
+        # Read AC charge parameters
+        ac_params = await self.read_parameters(HOLD_AC_CHARGE_POWER_CMD, 8)
+
+        return {
+            "enabled": ac_charge_enabled,
+            "power_percent": ac_params.get("HOLD_AC_CHARGE_POWER_CMD", 0),
+            "soc_limit": ac_params.get("HOLD_AC_CHARGE_SOC_LIMIT"),
+            "schedule1_enabled": bool(ac_params.get("HOLD_AC_CHARGE_ENABLE_1", 0)),
+            "schedule2_enabled": bool(ac_params.get("HOLD_AC_CHARGE_ENABLE_2", 0)),
+        }
+
+    async def set_ac_charge(
+        self, enabled: bool, power_percent: int | None = None, soc_limit: int | None = None
+    ) -> bool:
+        """Configure AC charging from grid.
+
+        Args:
+            enabled: Enable AC charging
+            power_percent: Charge power percentage (0-100), optional
+            soc_limit: Target SOC percentage (0-100), optional
+
+        Returns:
+            True if successful
+
+        Example:
+            >>> # Enable AC charge at 50% power to 100% SOC
+            >>> await inverter.set_ac_charge(True, power_percent=50, soc_limit=100)
+            True
+
+            >>> # Disable AC charge
+            >>> await inverter.set_ac_charge(False)
+            True
+        """
+        from pylxpweb.constants import (
+            FUNC_EN_BIT_AC_CHARGE_EN,
+            FUNC_EN_REGISTER,
+            HOLD_AC_CHARGE_POWER_CMD,
+            HOLD_AC_CHARGE_SOC_LIMIT,
+        )
+
+        # Validate parameters first (before any API calls)
+        if power_percent is not None and not 0 <= power_percent <= 100:
+            raise ValueError("power_percent must be between 0 and 100")
+
+        if soc_limit is not None and not 0 <= soc_limit <= 100:
+            raise ValueError("soc_limit must be between 0 and 100")
+
+        # Update function enable bit
+        func_params = await self.read_parameters(FUNC_EN_REGISTER, 1)
+        current_func = func_params.get(f"reg_{FUNC_EN_REGISTER}", 0)
+
+        if enabled:
+            new_func = current_func | (1 << FUNC_EN_BIT_AC_CHARGE_EN)
+        else:
+            new_func = current_func & ~(1 << FUNC_EN_BIT_AC_CHARGE_EN)
+
+        params_to_write = {FUNC_EN_REGISTER: new_func}
+
+        # Add power and SOC limit if provided (already validated)
+        if power_percent is not None:
+            params_to_write[HOLD_AC_CHARGE_POWER_CMD] = power_percent
+
+        if soc_limit is not None:
+            params_to_write[HOLD_AC_CHARGE_SOC_LIMIT] = soc_limit
+
+        return await self.write_parameters(params_to_write)
+
+    async def set_eps_enabled(self, enabled: bool) -> bool:
+        """Enable or disable EPS (backup/off-grid) mode.
+
+        Args:
+            enabled: True to enable EPS mode, False to disable
+
+        Returns:
+            True if successful
+
+        Example:
+            >>> await inverter.set_eps_enabled(True)
+            True
+        """
+        from pylxpweb.constants import FUNC_EN_BIT_EPS_EN, FUNC_EN_REGISTER
+
+        # Read current function enable register
+        params = await self.read_parameters(FUNC_EN_REGISTER, 1)
+        current_value = params.get(f"reg_{FUNC_EN_REGISTER}", 0)
+
+        if enabled:
+            new_value = current_value | (1 << FUNC_EN_BIT_EPS_EN)
+        else:
+            new_value = current_value & ~(1 << FUNC_EN_BIT_EPS_EN)
+
+        return await self.write_parameters({FUNC_EN_REGISTER: new_value})
+
+    async def set_forced_charge(self, enabled: bool) -> bool:
+        """Enable or disable forced charge mode.
+
+        Forces inverter to charge batteries regardless of time schedule.
+
+        Args:
+            enabled: True to enable forced charge, False to disable
+
+        Returns:
+            True if successful
+
+        Example:
+            >>> await inverter.set_forced_charge(True)
+            True
+        """
+        from pylxpweb.constants import FUNC_EN_BIT_FORCED_CHG_EN, FUNC_EN_REGISTER
+
+        params = await self.read_parameters(FUNC_EN_REGISTER, 1)
+        current_value = params.get(f"reg_{FUNC_EN_REGISTER}", 0)
+
+        if enabled:
+            new_value = current_value | (1 << FUNC_EN_BIT_FORCED_CHG_EN)
+        else:
+            new_value = current_value & ~(1 << FUNC_EN_BIT_FORCED_CHG_EN)
+
+        return await self.write_parameters({FUNC_EN_REGISTER: new_value})
+
+    async def set_forced_discharge(self, enabled: bool) -> bool:
+        """Enable or disable forced discharge mode.
+
+        Forces inverter to discharge batteries regardless of time schedule.
+
+        Args:
+            enabled: True to enable forced discharge, False to disable
+
+        Returns:
+            True if successful
+
+        Example:
+            >>> await inverter.set_forced_discharge(True)
+            True
+        """
+        from pylxpweb.constants import FUNC_EN_BIT_FORCED_DISCHG_EN, FUNC_EN_REGISTER
+
+        params = await self.read_parameters(FUNC_EN_REGISTER, 1)
+        current_value = params.get(f"reg_{FUNC_EN_REGISTER}", 0)
+
+        if enabled:
+            new_value = current_value | (1 << FUNC_EN_BIT_FORCED_DISCHG_EN)
+        else:
+            new_value = current_value & ~(1 << FUNC_EN_BIT_FORCED_DISCHG_EN)
+
+        return await self.write_parameters({FUNC_EN_REGISTER: new_value})
+
+    async def get_charge_discharge_power(self) -> dict[str, int]:
+        """Get charge and discharge power settings.
+
+        Returns:
+            Dictionary with:
+            - charge_power_percent: AC charge power (0-100%)
+            - discharge_power_percent: Discharge power (0-100%)
+
+        Example:
+            >>> settings = await inverter.get_charge_discharge_power()
+            >>> settings
+            {'charge_power_percent': 50, 'discharge_power_percent': 100}
+        """
+        from pylxpweb.constants import HOLD_AC_CHARGE_POWER_CMD
+
+        params = await self.read_parameters(HOLD_AC_CHARGE_POWER_CMD, 9)
+
+        return {
+            "charge_power_percent": params.get("HOLD_AC_CHARGE_POWER_CMD", 0),
+            "discharge_power_percent": params.get("HOLD_DISCHG_POWER_CMD"),
+        }
+
+    async def set_discharge_power(self, power_percent: int) -> bool:
+        """Set battery discharge power limit.
+
+        Args:
+            power_percent: Discharge power percentage (0-100)
+
+        Returns:
+            True if successful
+
+        Example:
+            >>> await inverter.set_discharge_power(80)
+            True
+        """
+        from pylxpweb.constants import HOLD_DISCHG_POWER_CMD
+
+        if not 0 <= power_percent <= 100:
+            raise ValueError("power_percent must be between 0 and 100")
+
+        return await self.write_parameters({HOLD_DISCHG_POWER_CMD: power_percent})

pylxpweb/devices/mid_device.py

@@ -0,0 +1,183 @@
+"""MID Device (GridBOSS) module for grid management and load control.
+
+This module provides the MIDDevice class for GridBOSS devices that handle
+grid interconnection, UPS functionality, smart loads, and AC coupling.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from pylxpweb.exceptions import LuxpowerAPIError, LuxpowerConnectionError, LuxpowerDeviceError
+
+from ._firmware_update_mixin import FirmwareUpdateMixin
+from ._mid_runtime_properties import MIDRuntimePropertiesMixin
+from .base import BaseDevice
+from .models import DeviceClass, DeviceInfo, Entity, StateClass
+
+_LOGGER = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from pylxpweb import LuxpowerClient
+    from pylxpweb.models import MidboxRuntime
+
+
+class MIDDevice(FirmwareUpdateMixin, MIDRuntimePropertiesMixin, BaseDevice):
+    """Represents a GridBOSS/MID device for grid management.
+
+    GridBOSS devices handle:
+    - Grid interconnection and UPS functionality
+    - Smart load management (4 configurable outputs)
+    - AC coupling for additional inverters/generators
+    - Load monitoring and control
+
+    Example:
+        ```python
+        # MIDDevice is typically created from parallel group data
+        mid_device = MIDDevice(
+            client=client,
+            serial_number="1234567890",
+            model="GridBOSS"
+        )
+        await mid_device.refresh()
+        print(f"Grid Power: {mid_device.grid_power}W")
+        print(f"UPS Power: {mid_device.ups_power}W")
+        ```
+    """
+
+    def __init__(
+        self,
+        client: LuxpowerClient,
+        serial_number: str,
+        model: str = "GridBOSS",
+    ) -> None:
+        """Initialize MID device.
+
+        Args:
+            client: LuxpowerClient instance for API access
+            serial_number: MID device serial number (10-digit)
+            model: Device model name (default: "GridBOSS")
+        """
+        super().__init__(client, serial_number, model)
+
+        # Runtime data (private - use properties for access)
+        self._runtime: MidboxRuntime | None = None
+
+        # Initialize firmware update detection (from FirmwareUpdateMixin)
+        self._init_firmware_update_cache()
+
+    async def refresh(self) -> None:
+        """Refresh MID device runtime data from API."""
+        try:
+            runtime_data = await self._client.api.devices.get_midbox_runtime(self.serial_number)
+            self._runtime = runtime_data
+            self._last_refresh = datetime.now()
+        except (LuxpowerAPIError, LuxpowerConnectionError, LuxpowerDeviceError) as err:
+            # Graceful error handling - keep existing cached data
+            _LOGGER.debug("Failed to fetch MID device runtime for %s: %s", self.serial_number, err)
+
+    # All properties are provided by MIDRuntimePropertiesMixin
+
+    def to_device_info(self) -> DeviceInfo:
+        """Convert to device info model.
+
+        Returns:
+            DeviceInfo with MID device metadata.
+        """
+        return DeviceInfo(
+            identifiers={("pylxpweb", f"mid_{self.serial_number}")},
+            name=f"GridBOSS {self.serial_number}",
+            manufacturer="EG4/Luxpower",
+            model=self.model,
+            sw_version=self.firmware_version,
+        )
+
+    def to_entities(self) -> list[Entity]:
+        """Generate entities for this MID device.
+
+        Returns:
+            List of Entity objects for GridBOSS monitoring.
+
+        Note: This implementation focuses on core grid/UPS monitoring.
+        Future versions will add smart loads, AC coupling, and generator sensors.
+        """
+        if self._runtime is None:
+            return []
+
+        entities = []
+
+        # Grid Voltage
+        entities.append(
+            Entity(
+                unique_id=f"{self.serial_number}_grid_voltage",
+                name=f"{self.model} {self.serial_number} Grid Voltage",
+                device_class=DeviceClass.VOLTAGE,
+                state_class=StateClass.MEASUREMENT,
+                unit_of_measurement="V",
+                value=self.grid_voltage,
+            )
+        )
+
+        # Grid Power
+        entities.append(
+            Entity(
+                unique_id=f"{self.serial_number}_grid_power",
+                name=f"{self.model} {self.serial_number} Grid Power",
+                device_class=DeviceClass.POWER,
+                state_class=StateClass.MEASUREMENT,
+                unit_of_measurement="W",
+                value=self.grid_power,
+            )
+        )
+
+        # UPS Voltage
+        entities.append(
+            Entity(
+                unique_id=f"{self.serial_number}_ups_voltage",
+                name=f"{self.model} {self.serial_number} UPS Voltage",
+                device_class=DeviceClass.VOLTAGE,
+                state_class=StateClass.MEASUREMENT,
+                unit_of_measurement="V",
+                value=self.ups_voltage,
+            )
+        )
+
+        # UPS Power
+        entities.append(
+            Entity(
+                unique_id=f"{self.serial_number}_ups_power",
+                name=f"{self.model} {self.serial_number} UPS Power",
+                device_class=DeviceClass.POWER,
+                state_class=StateClass.MEASUREMENT,
+                unit_of_measurement="W",
+                value=self.ups_power,
+            )
+        )
+
+        # Hybrid Power
+        entities.append(
+            Entity(
+                unique_id=f"{self.serial_number}_hybrid_power",
+                name=f"{self.model} {self.serial_number} Hybrid Power",
+                device_class=DeviceClass.POWER,
+                state_class=StateClass.MEASUREMENT,
+                unit_of_measurement="W",
+                value=self.hybrid_power,
+            )
+        )
+
+        # Grid Frequency
+        entities.append(
+            Entity(
+                unique_id=f"{self.serial_number}_grid_frequency",
+                name=f"{self.model} {self.serial_number} Grid Frequency",
+                device_class=DeviceClass.FREQUENCY,
+                state_class=StateClass.MEASUREMENT,
+                unit_of_measurement="Hz",
+                value=self.grid_frequency,
+            )
+        )
+
+        return entities