pylxpweb 0.1.0__py3-none-any.whl

pylxpweb/endpoints/control.py

@@ -0,0 +1,306 @@
+"""Device control endpoints for the Luxpower API.
+
+This module provides device control functionality including:
+- Parameter reading and writing
+- Function enable/disable control
+- Quick charge operations
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pylxpweb.endpoints.base import BaseEndpoint
+from pylxpweb.models import (
+    ParameterReadResponse,
+    QuickChargeStatus,
+    SuccessResponse,
+)
+
+if TYPE_CHECKING:
+    from pylxpweb.client import LuxpowerClient
+
+
+class ControlEndpoints(BaseEndpoint):
+    """Device control endpoints for parameters, functions, and quick charge."""
+
+    def __init__(self, client: LuxpowerClient) -> None:
+        """Initialize control endpoints.
+
+        Args:
+            client: The parent LuxpowerClient instance
+        """
+        super().__init__(client)
+
+    async def read_parameters(
+        self,
+        inverter_sn: str,
+        start_register: int = 0,
+        point_number: int = 127,
+        auto_retry: bool = True,
+    ) -> ParameterReadResponse:
+        """Read configuration parameters from inverter registers.
+
+        IMPORTANT: The API returns parameters as FLAT key-value pairs with
+        descriptive names (like "HOLD_AC_CHARGE_POWER_CMD"), NOT nested under
+        a 'parameters' field or using register numbers as keys!
+
+        Common register ranges (web interface strategy):
+        - 0-126 (startRegister=0, pointNumber=127) - System config, grid protection
+        - 127-253 (startRegister=127, pointNumber=127) - Additional config
+        - 240-366 (startRegister=240, pointNumber=127) - Extended parameters
+
+        Critical registers (verified on 18KPV):
+        - Register 21: Function enable bit field (27 bits including AC charge, EPS, standby)
+        - Register 66: AC charge power command (HOLD_AC_CHARGE_POWER_CMD)
+        - Register 67: AC charge SOC limit (HOLD_AC_CHARGE_SOC_LIMIT)
+        - Register 70: AC charge schedule start (hour + minute)
+        - Register 100: Battery discharge cutoff voltage
+        - Register 110: System function bit field (14 bits including microgrid, eco mode)
+
+        Example:
+            >>> response = await client.control.read_parameters("1234567890", 66, 8)
+            >>> # Access parameters directly from response
+            >>> response.parameters["HOLD_AC_CHARGE_POWER_CMD"]
+            50
+            >>> response.parameters["HOLD_AC_CHARGE_SOC_LIMIT"]
+            100
+            >>> # Or access via model dump (includes all parameter keys at root level)
+            >>> data = response.model_dump()
+            >>> data["HOLD_AC_CHARGE_POWER_CMD"]
+            50
+
+            >>> # Read function enable register (27 bit fields)
+            >>> response = await client.control.read_parameters("1234567890", 21, 1)
+            >>> response.parameters["FUNC_AC_CHARGE"]
+            True
+            >>> response.parameters["FUNC_SET_TO_STANDBY"]
+            False
+
+        Args:
+            inverter_sn: Inverter serial number (e.g., "1234567890")
+            start_register: Starting register address
+            point_number: Number of registers to read (max 127 in practice)
+            auto_retry: Enable automatic retry on failure
+
+        Returns:
+            ParameterReadResponse: Contains inverterSn, deviceType, startRegister,
+                pointNumber, and all parameter keys as flat attributes.
+                Use .parameters property to get dict of parameter keys.
+
+        See Also:
+            - constants.REGISTER_TO_PARAM_KEYS_18KPV: Verified register→parameter mappings
+            - research/REGISTER_NUMBER_MAPPING.md: Complete register documentation
+        """
+        await self.client._ensure_authenticated()
+
+        data = {
+            "inverterSn": inverter_sn,
+            "startRegister": start_register,
+            "pointNumber": point_number,
+            "autoRetry": auto_retry,
+        }
+
+        cache_key = self._get_cache_key(
+            "params", sn=inverter_sn, start=start_register, count=point_number
+        )
+        response = await self.client._request(
+            "POST",
+            "/WManage/web/maintain/remoteRead/read",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="parameter_read",
+        )
+        return ParameterReadResponse.model_validate(response)
+
+    async def write_parameter(
+        self,
+        inverter_sn: str,
+        hold_param: str,
+        value_text: str,
+        client_type: str = "WEB",
+        remote_set_type: str = "NORMAL",
+    ) -> SuccessResponse:
+        """Write a configuration parameter to the inverter.
+
+         WARNING: This changes device configuration!
+
+        Common parameters:
+        - HOLD_SYSTEM_CHARGE_SOC_LIMIT: Battery charge limit (%)
+        - HOLD_SYSTEM_DISCHARGE_SOC_LIMIT: Battery discharge limit (%)
+        - HOLD_AC_CHARGE_POWER: AC charge power limit (W)
+        - HOLD_AC_DISCHARGE_POWER: AC discharge power limit (W)
+
+        Args:
+            inverter_sn: Inverter serial number
+            hold_param: Parameter name to write
+            value_text: Value to write (as string)
+            client_type: Client type (WEB/APP)
+            remote_set_type: Set type (NORMAL/QUICK)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            # Set battery charge limit to 90%
+            await client.control.write_parameter(
+                "1234567890",
+                "HOLD_SYSTEM_CHARGE_SOC_LIMIT",
+                "90"
+            )
+        """
+        await self.client._ensure_authenticated()
+
+        data = {
+            "inverterSn": inverter_sn,
+            "holdParam": hold_param,
+            "valueText": value_text,
+            "clientType": client_type,
+            "remoteSetType": remote_set_type,
+        }
+
+        response = await self.client._request(
+            "POST", "/WManage/web/maintain/remoteSet/write", data=data
+        )
+        return SuccessResponse.model_validate(response)
+
+    async def control_function(
+        self,
+        inverter_sn: str,
+        function_param: str,
+        enable: bool,
+        client_type: str = "WEB",
+        remote_set_type: str = "NORMAL",
+    ) -> SuccessResponse:
+        """Enable or disable a device function.
+
+         WARNING: This changes device state!
+
+        Common functions:
+        - FUNC_EPS_EN: Battery backup (EPS) mode
+        - FUNC_SET_TO_STANDBY: Standby mode
+        - FUNC_GRID_PEAK_SHAVING: Peak shaving mode
+
+        Args:
+            inverter_sn: Inverter serial number
+            function_param: Function parameter name
+            enable: Enable or disable the function
+            client_type: Client type (WEB/APP)
+            remote_set_type: Set type (NORMAL/QUICK)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            # Enable EPS mode
+            await client.control.control_function(
+                "1234567890",
+                "FUNC_EPS_EN",
+                True
+            )
+
+            # Disable standby mode
+            await client.control.control_function(
+                "1234567890",
+                "FUNC_SET_TO_STANDBY",
+                False
+            )
+        """
+        await self.client._ensure_authenticated()
+
+        data = {
+            "inverterSn": inverter_sn,
+            "functionParam": function_param,
+            "enable": "true" if enable else "false",
+            "clientType": client_type,
+            "remoteSetType": remote_set_type,
+        }
+
+        response = await self.client._request(
+            "POST", "/WManage/web/maintain/remoteSet/functionControl", data=data
+        )
+        return SuccessResponse.model_validate(response)
+
+    async def start_quick_charge(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Start quick charge operation.
+
+         WARNING: This starts charging!
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            result = await client.control.start_quick_charge("1234567890")
+            if result.success:
+                print("Quick charge started successfully")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"inverterSn": inverter_sn, "clientType": client_type}
+
+        response = await self.client._request(
+            "POST", "/WManage/web/config/quickCharge/start", data=data
+        )
+        return SuccessResponse.model_validate(response)
+
+    async def stop_quick_charge(
+        self, inverter_sn: str, client_type: str = "WEB"
+    ) -> SuccessResponse:
+        """Stop quick charge operation.
+
+         WARNING: This stops charging!
+
+        Args:
+            inverter_sn: Inverter serial number
+            client_type: Client type (WEB/APP)
+
+        Returns:
+            SuccessResponse: Operation result
+
+        Example:
+            result = await client.control.stop_quick_charge("1234567890")
+            if result.success:
+                print("Quick charge stopped successfully")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"inverterSn": inverter_sn, "clientType": client_type}
+
+        response = await self.client._request(
+            "POST", "/WManage/web/config/quickCharge/stop", data=data
+        )
+        return SuccessResponse.model_validate(response)
+
+    async def get_quick_charge_status(self, inverter_sn: str) -> QuickChargeStatus:
+        """Get current quick charge operation status.
+
+        Args:
+            inverter_sn: Inverter serial number
+
+        Returns:
+            QuickChargeStatus: Quick charge status
+
+        Example:
+            status = await client.control.get_quick_charge_status("1234567890")
+            if status.is_charging:
+                print("Quick charge is active")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"inverterSn": inverter_sn}
+
+        cache_key = self._get_cache_key("quick_charge", serialNum=inverter_sn)
+        response = await self.client._request(
+            "POST",
+            "/WManage/web/config/quickCharge/getStatusInfo",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="quick_charge_status",
+        )
+        return QuickChargeStatus.model_validate(response)

pylxpweb/endpoints/devices.py

@@ -0,0 +1,250 @@
+"""Device endpoints for the Luxpower API.
+
+This module provides device functionality including:
+- Device discovery and hierarchy
+- Real-time runtime data
+- Energy statistics
+- Battery information
+- GridBOSS/MID device data
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pylxpweb.endpoints.base import BaseEndpoint
+from pylxpweb.models import (
+    BatteryInfo,
+    EnergyInfo,
+    InverterListResponse,
+    InverterRuntime,
+    MidboxRuntime,
+    ParallelGroupDetailsResponse,
+)
+
+if TYPE_CHECKING:
+    from pylxpweb.client import LuxpowerClient
+
+
+class DeviceEndpoints(BaseEndpoint):
+    """Device endpoints for discovery, runtime data, and device information."""
+
+    def __init__(self, client: LuxpowerClient) -> None:
+        """Initialize device endpoints.
+
+        Args:
+            client: The parent LuxpowerClient instance
+        """
+        super().__init__(client)
+
+    async def get_parallel_group_details(self, plant_id: int) -> ParallelGroupDetailsResponse:
+        """Get parallel group device hierarchy for a plant.
+
+        Args:
+            plant_id: Plant/station ID
+
+        Returns:
+            ParallelGroupDetailsResponse: Parallel group structure
+
+        Example:
+            groups = await client.devices.get_parallel_group_details(12345)
+            for group in groups.rows:
+                print(f"Group ID: {group.groupId}")
+                print(f"Inverters: {len(group.inverters)}")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"plantId": plant_id}
+
+        cache_key = self._get_cache_key("parallel_groups", plantId=plant_id)
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/inverterOverview/getParallelGroupDetails",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="device_discovery",
+        )
+        return ParallelGroupDetailsResponse.model_validate(response)
+
+    async def get_devices(self, plant_id: int) -> InverterListResponse:
+        """Get list of all devices in a plant.
+
+        Args:
+            plant_id: Plant/station ID
+
+        Returns:
+            InverterListResponse: List of inverters and devices
+
+        Example:
+            devices = await client.devices.get_devices(12345)
+            for device in devices.rows:
+                print(f"Device: {device.serialNum} - {device.alias}")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"plantId": plant_id}
+
+        cache_key = self._get_cache_key("devices", plantId=plant_id)
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/inverterOverview/list",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="device_discovery",
+        )
+        return InverterListResponse.model_validate(response)
+
+    async def get_inverter_runtime(self, serial_num: str) -> InverterRuntime:
+        """Get real-time runtime data for an inverter.
+
+        Note: Many values require scaling:
+        - Voltage: divide by 100
+        - Current: divide by 100
+        - Frequency: divide by 100
+        - Power: no scaling (direct watts)
+
+        Args:
+            serial_num: 10-digit device serial number
+
+        Returns:
+            InverterRuntime: Real-time inverter metrics
+
+        Example:
+            runtime = await client.devices.get_inverter_runtime("1234567890")
+            print(f"PV Power: {runtime.ppv}W")
+            print(f"Battery SOC: {runtime.soc}%")
+            print(f"Grid Voltage: {runtime.vacr / 100}V")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"serialNum": serial_num}
+
+        cache_key = self._get_cache_key("runtime", serialNum=serial_num)
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/inverter/getInverterRuntime",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="inverter_runtime",
+        )
+        return InverterRuntime.model_validate(response)
+
+    async def get_inverter_energy(self, serial_num: str) -> EnergyInfo:
+        """Get energy statistics for an inverter.
+
+        All energy values are in Wh (divide by 1000 for kWh).
+
+        Args:
+            serial_num: 10-digit device serial number
+
+        Returns:
+            EnergyInfo: Energy production and consumption statistics
+
+        Example:
+            energy = await client.devices.get_inverter_energy("1234567890")
+            print(f"Today's Production: {energy.eInvDay / 1000}kWh")
+            print(f"Total Production: {energy.eInvAll / 1000}kWh")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"serialNum": serial_num}
+
+        cache_key = self._get_cache_key("energy", serialNum=serial_num)
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/inverter/getInverterEnergyInfo",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="inverter_energy",
+        )
+        return EnergyInfo.model_validate(response)
+
+    async def get_parallel_energy(self, serial_num: str) -> EnergyInfo:
+        """Get aggregate energy statistics for entire parallel group.
+
+        Args:
+            serial_num: Serial number of any inverter in the parallel group
+
+        Returns:
+            EnergyInfo: Aggregate energy statistics for the group
+
+        Example:
+            energy = await client.devices.get_parallel_energy("1234567890")
+            print(f"Group Total Today: {energy.eInvDay / 1000}kWh")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"serialNum": serial_num}
+
+        cache_key = self._get_cache_key("parallel_energy", serialNum=serial_num)
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/inverter/getInverterEnergyInfoParallel",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="inverter_energy",
+        )
+        return EnergyInfo.model_validate(response)
+
+    async def get_battery_info(self, serial_num: str) -> BatteryInfo:
+        """Get battery information including individual modules.
+
+        Note: Cell voltages are in millivolts (divide by 1000 for volts).
+
+        Args:
+            serial_num: Inverter serial number
+
+        Returns:
+            BatteryInfo: Battery status and individual module data
+
+        Example:
+            battery = await client.devices.get_battery_info("1234567890")
+            print(f"Battery SOC: {battery.soc}%")
+            print(f"Number of Modules: {len(battery.batteryArray)}")
+            for module in battery.batteryArray:
+                print(f"  Module {module.batIndex}: {module.vBat / 100}V")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"serialNum": serial_num}
+
+        cache_key = self._get_cache_key("battery", serialNum=serial_num)
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/battery/getBatteryInfo",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="battery_info",
+        )
+        return BatteryInfo.model_validate(response)
+
+    async def get_midbox_runtime(self, serial_num: str) -> MidboxRuntime:
+        """Get GridBOSS/MID device runtime data.
+
+        Note: Voltages, currents, and frequency require scaling (÷100).
+
+        Args:
+            serial_num: GridBOSS device serial number
+
+        Returns:
+            MidboxRuntime: GridBOSS runtime metrics
+
+        Example:
+            midbox = await client.devices.get_midbox_runtime("1234567890")
+            print(f"Grid Power: {midbox.gridPower}W")
+            print(f"Load Power: {midbox.loadPower}W")
+            print(f"Generator Power: {midbox.genPower}W")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"serialNum": serial_num}
+
+        cache_key = self._get_cache_key("midbox", serialNum=serial_num)
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/midbox/getMidboxRuntime",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="midbox_runtime",
+        )
+        return MidboxRuntime.model_validate(response)

pylxpweb/endpoints/export.py

@@ -0,0 +1,86 @@
+"""Data export endpoints for the Luxpower API.
+
+This module provides data export functionality for downloading
+historical runtime data in CSV or Excel formats.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import urljoin
+
+import aiohttp
+
+from pylxpweb.endpoints.base import BaseEndpoint
+from pylxpweb.exceptions import LuxpowerConnectionError
+
+if TYPE_CHECKING:
+    from pylxpweb.client import LuxpowerClient
+
+
+class ExportEndpoints(BaseEndpoint):
+    """Data export endpoints for downloading historical data."""
+
+    def __init__(self, client: LuxpowerClient) -> None:
+        """Initialize export endpoints.
+
+        Args:
+            client: The parent LuxpowerClient instance
+        """
+        super().__init__(client)
+
+    async def export_data(
+        self,
+        serial_num: str,
+        start_date: str,
+        end_date: str | None = None,
+    ) -> bytes:
+        """Export historical data to CSV/Excel.
+
+        Downloads historical runtime data for the specified date range.
+        Returns binary data (CSV or Excel format) for external analysis.
+
+        Args:
+            serial_num: Device serial number
+            start_date: Start date in YYYY-MM-DD format
+            end_date: Optional end date (if None, exports single day)
+
+        Returns:
+            bytes: CSV/Excel file content
+
+        Raises:
+            LuxpowerAPIError: If export fails
+
+        Example:
+            # Export single day
+            csv_data = await client.export.export_data("1234567890", "2025-11-19")
+            with open("data.csv", "wb") as f:
+                f.write(csv_data)
+
+            # Export date range
+            csv_data = await client.export.export_data(
+                "1234567890",
+                "2025-11-01",
+                "2025-11-19"
+            )
+
+        Note:
+            This is a GET request that returns binary data, not JSON.
+        """
+        await self.client._ensure_authenticated()
+
+        session = await self.client._get_session()
+        url_path = f"/WManage/web/analyze/data/export/{serial_num}/{start_date}"
+
+        if end_date:
+            url_path += f"?endDateText={end_date}"
+
+        url = urljoin(self.client.base_url, url_path)
+
+        try:
+            async with session.get(url) as response:
+                response.raise_for_status()
+                return await response.read()
+
+        except aiohttp.ClientError as err:
+            raise LuxpowerConnectionError(f"Export failed: {err}") from err