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

pylxpweb/endpoints/devices.py

@@ -15,8 +15,11 @@ from typing import TYPE_CHECKING
 from pylxpweb.endpoints.base import BaseEndpoint
 from pylxpweb.models import (
     BatteryInfo,
+    BatteryListResponse,
+    DongleStatus,
     EnergyInfo,
-    InverterListResponse,
+    InverterInfo,
+    InverterOverviewResponse,
     InverterRuntime,
     MidboxRuntime,
     ParallelGroupDetailsResponse,
@@ -37,26 +40,29 @@ class DeviceEndpoints(BaseEndpoint):
         """
         super().__init__(client)
 
-    async def get_parallel_group_details(self, plant_id: int) -> ParallelGroupDetailsResponse:
-        """Get parallel group device hierarchy for a plant.
+    async def get_parallel_group_details(self, serial_num: str) -> ParallelGroupDetailsResponse:
+        """Get parallel group device hierarchy for a specific device.
+
+        Note: This endpoint requires a device serial number, not a plant ID.
+        Use the GridBOSS/MID device serial number for parallel group details.
 
         Args:
-            plant_id: Plant/station ID
+            serial_num: Serial number of GridBOSS or any device in the parallel group
 
         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)}")
+            groups = await client.devices.get_parallel_group_details("4524850115")
+            print(f"Total devices: {groups.total}")
+            for device in groups.devices:
+                print(f"  {device.serialNum}: {device.roleText}")
         """
         await self.client._ensure_authenticated()
 
-        data = {"plantId": plant_id}
+        data = {"serialNum": serial_num}
 
-        cache_key = self._get_cache_key("parallel_groups", plantId=plant_id)
+        cache_key = self._get_cache_key("parallel_groups", serialNum=serial_num)
         response = await self.client._request(
             "POST",
             "/WManage/api/inverterOverview/getParallelGroupDetails",
@@ -66,23 +72,71 @@ class DeviceEndpoints(BaseEndpoint):
         )
         return ParallelGroupDetailsResponse.model_validate(response)
 
-    async def get_devices(self, plant_id: int) -> InverterListResponse:
-        """Get list of all devices in a plant.
+    async def sync_parallel_groups(self, plant_id: int) -> bool:
+        """Trigger automatic parallel group detection and synchronization.
+
+        This endpoint initializes/syncs parallel group data for all inverters
+        in a plant. Required when parallel group data is not available, such as:
+        - After firmware updates that reset parallel group settings
+        - When `get_parallel_group_details` returns empty/no data
+        - Initial setup of parallel inverter configurations with GridBOSS
+
+        Note:
+            This is a write operation that modifies parallel group configuration.
+            May take several seconds to complete as it communicates with all inverters.
+            Should be called once per plant, not per inverter.
+
+        Args:
+            plant_id: Plant/station ID to sync parallel data for
+
+        Returns:
+            bool: True if sync was successful, False otherwise
+
+        Example:
+            # If GridBOSS detected but no parallel groups
+            success = await client.api.devices.sync_parallel_groups(12345)
+            if success:
+                # Re-fetch parallel group details
+                groups = await client.api.devices.get_parallel_group_details(gridboss_serial)
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"plantId": plant_id}
+
+        try:
+            response = await self.client._request(
+                "POST",
+                "/WManage/api/inverter/autoParallel",
+                data=data,
+            )
+            # Response should have success field
+            return bool(response.get("success", False))
+        except Exception:
+            return False
+
+    async def get_devices(self, plant_id: int) -> InverterOverviewResponse:
+        """Get overview/status of all devices in a plant.
 
         Args:
             plant_id: Plant/station ID
 
         Returns:
-            InverterListResponse: List of inverters and devices
+            InverterOverviewResponse: Overview data for inverters and devices
 
         Example:
             devices = await client.devices.get_devices(12345)
             for device in devices.rows:
-                print(f"Device: {device.serialNum} - {device.alias}")
+                print(f"Device: {device.serialNum} - {device.statusText}")
         """
         await self.client._ensure_authenticated()
 
-        data = {"plantId": plant_id}
+        data = {
+            "page": 1,
+            "rows": 30,
+            "plantId": plant_id,
+            "searchText": "",
+            "statusText": "all",
+        }
 
         cache_key = self._get_cache_key("devices", plantId=plant_id)
         response = await self.client._request(
@@ -92,7 +146,40 @@ class DeviceEndpoints(BaseEndpoint):
             cache_key=cache_key,
             cache_endpoint="device_discovery",
         )
-        return InverterListResponse.model_validate(response)
+        return InverterOverviewResponse.model_validate(response)
+
+    async def get_inverter_info(self, serial_num: str) -> InverterInfo:
+        """Get detailed inverter configuration and device information.
+
+        This endpoint returns static device configuration, firmware versions,
+        and hardware details. For real-time operational data, use get_inverter_runtime().
+
+        Args:
+            serial_num: Inverter serial number
+
+        Returns:
+            InverterInfo: Detailed device configuration
+
+        Example:
+            info = await client.devices.get_inverter_info("1234567890")
+            print(f"Device: {info.deviceTypeText}")
+            print(f"Firmware: {info.inverterDetail.fwCode}")
+            print(f"Power Rating: {info.powerRatingText}")
+            print(f"Battery Type: {info.batteryType}")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"serialNum": serial_num}
+
+        cache_key = self._get_cache_key("inverter_info", serialNum=serial_num)
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/inverter/getInverterInfo",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="device_discovery",  # Static data, cache like device discovery
+        )
+        return InverterInfo.model_validate(response)
 
     async def get_inverter_runtime(self, serial_num: str) -> InverterRuntime:
         """Get real-time runtime data for an inverter.
@@ -218,6 +305,39 @@ class DeviceEndpoints(BaseEndpoint):
         )
         return BatteryInfo.model_validate(response)
 
+    async def get_battery_list(self, serial_num: str) -> BatteryListResponse:
+        """Get simplified battery list for an inverter.
+
+        This endpoint returns only battery identification and status without detailed metrics.
+        Use get_battery_info() for full battery metrics including voltage, current, SOC, etc.
+
+        Args:
+            serial_num: Inverter serial number
+
+        Returns:
+            BatteryListResponse: Simplified battery list with keys and status
+
+        Example:
+            batteries = await client.devices.get_battery_list("1234567890")
+            print(f"Total batteries: {batteries.totalNumber}")
+            for battery in batteries.batteryArray:
+                status = "Online" if not battery.lost else "Offline"
+                print(f"  Battery {battery.batIndex}: {battery.batterySn} ({status})")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"serialNum": serial_num}
+
+        cache_key = self._get_cache_key("battery_list", serialNum=serial_num)
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/battery/getBatteryInfoForSet",
+            data=data,
+            cache_key=cache_key,
+            cache_endpoint="battery_info",
+        )
+        return BatteryListResponse.model_validate(response)
+
     async def get_midbox_runtime(self, serial_num: str) -> MidboxRuntime:
         """Get GridBOSS/MID device runtime data.
 
@@ -248,3 +368,116 @@ class DeviceEndpoints(BaseEndpoint):
             cache_endpoint="midbox_runtime",
         )
         return MidboxRuntime.model_validate(response)
+
+    async def get_dongle_status(self, datalog_serial: str) -> DongleStatus:
+        """Get dongle (datalog) connection status.
+
+        The dongle is the communication module that connects inverters to the
+        cloud monitoring service. This endpoint checks if the dongle is currently
+        online and communicating.
+
+        Use this to determine if device data is current or potentially stale.
+        When the dongle is offline, the inverter data shown in the API may be
+        outdated since no new data is being received from the device.
+
+        Note: The datalog serial number is different from the inverter serial number.
+        You can get the datalog serial from InverterInfo.datalogSn.
+
+        Args:
+            datalog_serial: Dongle/datalog serial number (e.g., "BC34000380")
+
+        Returns:
+            DongleStatus: Dongle connection status with is_online property
+
+        Example:
+            # Get dongle serial from inverter info
+            info = await client.devices.get_inverter_info("4512670118")
+            datalog_sn = info.datalogSn
+
+            # Check if dongle is online
+            status = await client.devices.get_dongle_status(datalog_sn)
+            if status.is_online:
+                print("Dongle is online - data is current")
+            else:
+                print("Dongle is offline - data may be stale")
+        """
+        await self.client._ensure_authenticated()
+
+        data = {"serialNum": datalog_serial}
+
+        response = await self.client._request(
+            "POST",
+            "/WManage/api/system/cluster/search/findOnlineDatalog",
+            data=data,
+        )
+        return DongleStatus.model_validate(response)
+
+    # ============================================================================
+    # Convenience Methods
+    # ============================================================================
+
+    async def get_all_device_data(
+        self, plant_id: int
+    ) -> dict[str, InverterOverviewResponse | dict[str, InverterRuntime] | dict[str, BatteryInfo]]:
+        """Get all device discovery and runtime data in a single call.
+
+        This method combines multiple API calls into one convenient method:
+        1. Device discovery (get_devices)
+        2. Runtime data for all inverters (get_inverter_runtime)
+        3. Battery info for all inverters (get_battery_info)
+
+        All API calls are made concurrently for optimal performance.
+
+        Args:
+            plant_id: Station/plant ID
+
+        Returns:
+            dict: Combined data with keys:
+                - "devices": InverterOverviewResponse (device hierarchy)
+                - "runtime": dict[serial_num, InverterRuntime] (runtime data)
+                - "batteries": dict[serial_num, BatteryInfo] (battery data)
+
+        Example:
+            >>> data = await client.devices.get_all_device_data(12345)
+            >>> devices = data["devices"]
+            >>> for inverter in devices.inverters:
+            >>>     runtime = data["runtime"].get(inverter["serialNum"])
+            >>>     if runtime:
+            >>>         print(f"Inverter {inverter['serialNum']}: {runtime.pac}W")
+        """
+        import asyncio
+
+        # Get device list first
+        devices = await self.get_devices(plant_id)
+
+        # Extract all inverter serial numbers (excluding MID devices)
+        inverter_serials: list[str] = []
+        for device in devices.rows:
+            # Filter for actual inverters (not GridBOSS/MID devices)
+            if "Grid Boss" not in device.deviceTypeText:
+                inverter_serials.append(device.serialNum)
+
+        # Fetch runtime and battery data concurrently for all inverters
+        runtime_tasks = [self.get_inverter_runtime(sn) for sn in inverter_serials]
+        battery_tasks = [self.get_battery_info(sn) for sn in inverter_serials]
+
+        runtime_results = await asyncio.gather(*runtime_tasks, return_exceptions=True)
+        battery_results = await asyncio.gather(*battery_tasks, return_exceptions=True)
+
+        # Build result dictionaries
+        runtime_data: dict[str, InverterRuntime] = {}
+        battery_data: dict[str, BatteryInfo] = {}
+
+        for sn, runtime in zip(inverter_serials, runtime_results, strict=True):
+            if not isinstance(runtime, BaseException):
+                runtime_data[sn] = runtime
+
+        for sn, battery in zip(inverter_serials, battery_results, strict=True):
+            if not isinstance(battery, BaseException):
+                battery_data[sn] = battery
+
+        return {
+            "devices": devices,
+            "runtime": runtime_data,
+            "batteries": battery_data,
+        }

pylxpweb/endpoints/firmware.py

@@ -9,9 +9,11 @@ This module provides firmware update functionality including:
 
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING
 
 from pylxpweb.endpoints.base import BaseEndpoint
+from pylxpweb.exceptions import LuxpowerAPIError
 from pylxpweb.models import (
     FirmwareUpdateCheck,
     FirmwareUpdateStatus,
@@ -21,6 +23,15 @@ from pylxpweb.models import (
 if TYPE_CHECKING:
     from pylxpweb.client import LuxpowerClient
 
+_LOGGER = logging.getLogger(__name__)
+
+# Messages that indicate firmware is already up to date (not an error)
+FIRMWARE_UP_TO_DATE_MESSAGES = (
+    "already the latest version",
+    "firmware is already the latest",
+    "already up to date",
+)
+
 
 class FirmwareEndpoints(BaseEndpoint):
     """Firmware update endpoints for checking and managing device firmware."""
@@ -39,22 +50,27 @@ class FirmwareEndpoints(BaseEndpoint):
         This is a READ-ONLY operation that checks if firmware updates are available
         and returns information about the current and available firmware versions.
 
+        When firmware is already up to date, the API returns success=false with a
+        message like "The current machine firmware is already the latest version".
+        This method handles that case gracefully by returning a FirmwareUpdateCheck
+        with success=True and details indicating no update is available.
+
         Args:
             serial_num: Device serial number (10-digit string)
 
         Returns:
             FirmwareUpdateCheck object containing:
-                - success: Boolean indicating success
+                - success: Boolean indicating the check completed successfully
                 - details: Detailed firmware information including:
                     - Current firmware versions (v1, v2, v3)
-                    - Latest available versions (lastV1, lastV2)
+                    - Latest available versions (lastV1, lastV2) - None if up to date
                     - Update compatibility flags
                     - Device type information
                 - infoForwardUrl: URL to firmware changelog/release notes (optional)
 
         Raises:
             LuxpowerAuthError: If authentication fails
-            LuxpowerAPIError: If API returns an error
+            LuxpowerAPIError: If API returns an actual error (not "up to date" message)
             LuxpowerConnectionError: If connection fails
 
         Example:
@@ -62,18 +78,35 @@ class FirmwareEndpoints(BaseEndpoint):
             if update_info.details.has_update():
                 print(f"Update available: {update_info.details.lastV1FileName}")
                 print(f"Changelog: {update_info.infoForwardUrl}")
+            else:
+                print("Firmware is already up to date")
         """
         await self.client._ensure_authenticated()
 
         data = {"serialNum": serial_num}
 
-        response = await self.client._request(
-            "POST",
-            "/WManage/web/maintain/standardUpdate/checkUpdates",
-            data=data,
-        )
-
-        return FirmwareUpdateCheck.model_validate(response)
+        try:
+            response = await self.client._request(
+                "POST",
+                "/WManage/web/maintain/standardUpdate/checkUpdates",
+                data=data,
+            )
+            return FirmwareUpdateCheck.model_validate(response)
+
+        except LuxpowerAPIError as err:
+            # Check if this is an "already up to date" message (not a real error)
+            error_msg = str(err).lower()
+            if any(msg in error_msg for msg in FIRMWARE_UP_TO_DATE_MESSAGES):
+                _LOGGER.debug(
+                    "Firmware is already up to date for device %s",
+                    serial_num,
+                )
+                # Return a FirmwareUpdateCheck indicating no update available
+                # We create minimal details since we don't have full version info
+                return FirmwareUpdateCheck.create_up_to_date(serial_num)
+
+            # Re-raise if it's a different error
+            raise
 
     async def get_firmware_update_status(self) -> FirmwareUpdateStatus:
         """Get firmware update status for all devices in user's account.

pylxpweb/endpoints/plants.py

@@ -10,6 +10,7 @@ This module provides plant/station functionality including:
 
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING, Any
 
 from pylxpweb.endpoints.base import BaseEndpoint
@@ -18,6 +19,8 @@ from pylxpweb.models import PlantListResponse
 if TYPE_CHECKING:
     from pylxpweb.client import LuxpowerClient
 
+_LOGGER = logging.getLogger(__name__)
+
 
 class PlantEndpoints(BaseEndpoint):
     """Plant/Station endpoints for discovery, configuration, and overview."""
@@ -83,15 +86,14 @@ class PlantEndpoints(BaseEndpoint):
                 - name: Station name
                 - nominalPower: Solar PV power rating (W)
                 - timezone: Timezone string (e.g., "GMT -8")
+                - currentTimezoneWithMinute: Timezone offset in minutes
                 - daylightSavingTime: DST enabled (boolean)
-                - continent: Continent enum value
-                - region: Region enum value
-                - country: Country enum value
-                - longitude: Geographic coordinate
-                - latitude: Geographic coordinate
+                - country: Country name
                 - createDate: Plant creation date
                 - address: Physical address
 
+            Note: Latitude and longitude coordinates are NOT included in the API response.
+
         Raises:
             LuxpowerAPIError: If plant not found or API error occurs
 
@@ -147,10 +149,8 @@ class PlantEndpoints(BaseEndpoint):
             LuxpowerAPIError: If country cannot be found in locale API
         """
         import json
-        from logging import getLogger
 
-        _LOGGER = getLogger(__name__)
-        _LOGGER.info(
+        _LOGGER.debug(
             "Country '%s' not in static mapping, fetching from locale API",
             country_human,
         )
@@ -190,7 +190,7 @@ class PlantEndpoints(BaseEndpoint):
                 # Check if our country is in this region
                 for country in countries:
                     if country["text"] == country_human:
-                        _LOGGER.info(
+                        _LOGGER.debug(
                             "Found country '%s' in locale API: continent=%s, region=%s",
                             country_human,
                             continent_enum,
@@ -226,16 +226,12 @@ class PlantEndpoints(BaseEndpoint):
             ValueError: If unable to map required fields
             LuxpowerAPIError: If dynamic fetch fails
         """
-        from logging import getLogger
-
         from pylxpweb.constants import (
             COUNTRY_MAP,
             TIMEZONE_MAP,
             get_continent_region_from_country,
         )
 
-        _LOGGER = getLogger(__name__)
-
         # Required fields for POST
         data: dict[str, Any] = {
             "plantId": str(plant_details["plantId"]),
@@ -268,7 +264,7 @@ class PlantEndpoints(BaseEndpoint):
             )
         except ValueError:
             # Slow path: dynamic fetch from locale API
-            _LOGGER.info(
+            _LOGGER.debug(
                 "Country '%s' not in static mapping, fetching from locale API",
                 country_human,
             )
@@ -284,7 +280,7 @@ class PlantEndpoints(BaseEndpoint):
         # Apply any overrides
         data.update(overrides)
 
-        _LOGGER.info(
+        _LOGGER.debug(
             "Prepared plant update data for plant %s: timezone=%s, country=%s, "
             "continent=%s, region=%s, dst=%s",
             plant_details["plantId"],
@@ -336,13 +332,13 @@ class PlantEndpoints(BaseEndpoint):
         await self.client._ensure_authenticated()
 
         # Get current configuration from API (human-readable values)
-        _LOGGER.info("Fetching plant details for plant %s", plant_id)
+        _LOGGER.debug("Fetching plant details for plant %s", plant_id)
         plant_details = await self.get_plant_details(plant_id)
 
         # Prepare POST data using hybrid approach (static + dynamic mapping)
         data = await self._prepare_plant_update_data(plant_details, **kwargs)
 
-        _LOGGER.info(
+        _LOGGER.debug(
             "Updating plant %s configuration: %s",
             plant_id,
             dict(kwargs),
@@ -350,7 +346,7 @@ class PlantEndpoints(BaseEndpoint):
 
         response = await self.client._request("POST", "/WManage/web/config/plant/edit", data=data)
 
-        _LOGGER.info("Plant %s configuration updated successfully", plant_id)
+        _LOGGER.debug("Plant %s configuration updated successfully", plant_id)
         return response
 
     async def set_daylight_saving_time(self, plant_id: int | str, enabled: bool) -> dict[str, Any]:
@@ -378,7 +374,7 @@ class PlantEndpoints(BaseEndpoint):
         from logging import getLogger
 
         _LOGGER = getLogger(__name__)
-        _LOGGER.info(
+        _LOGGER.debug(
             "Setting Daylight Saving Time to %s for plant %s",
             "enabled" if enabled else "disabled",
             plant_id,

pylxpweb/exceptions.py

@@ -21,3 +21,7 @@ class LuxpowerAPIError(LuxpowerError):
 
 class LuxpowerDeviceError(LuxpowerError):
     """Raised when there's an issue with device operations."""
+
+
+class LuxpowerDeviceOfflineError(LuxpowerDeviceError):
+    """Raised when a device is offline or unreachable."""