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

pylxpweb/models.py

@@ -12,6 +12,22 @@ from typing import Any
 from pydantic import BaseModel, Field, field_serializer
 
 
+class OperatingMode(str, Enum):
+    """Inverter operating modes.
+
+    These are the two valid operating states for an inverter:
+    - NORMAL: Normal operation (power on)
+    - STANDBY: Standby mode (power off)
+
+    Note: Quick Charge and Quick Discharge are not operating modes,
+    they are function controls (enable/disable) that work alongside
+    the operating mode.
+    """
+
+    NORMAL = "normal"
+    STANDBY = "standby"
+
+
 def _obfuscate_serial(serial: str) -> str:
     """Obfuscate serial number, showing only first 2 and last 2 digits."""
     if len(serial) <= 4:
@@ -43,6 +59,7 @@ class BatteryType(str, Enum):
 
     LITHIUM = "LITHIUM"
     LEAD_ACID = "LEAD_ACID"
+    NO_BATTERY = "NO_BATTERY"
 
 
 class UserRole(str, Enum):
@@ -135,23 +152,30 @@ class ParallelGroupBasic(BaseModel):
 
 
 class PlantBasic(BaseModel):
-    """Plant information from login response."""
+    """Plant information from login response.
+
+    Note: parallelGroups may not be present for all device types (e.g., 12000XP).
+    """
 
     plantId: int
     name: str
     timezoneHourOffset: int
     timezoneMinuteOffset: int
     inverters: list[InverterBasic]
-    parallelGroups: list[ParallelGroupBasic]
+    parallelGroups: list[ParallelGroupBasic] = []
 
 
 class TechInfo(BaseModel):
-    """Technical support information."""
+    """Technical support information.
+
+    Note: techInfoType2/techInfo2 are optional as some regional APIs
+    (e.g., EU Luxpower) may only return one tech info item.
+    """
 
     techInfoType1: str
     techInfo1: str
-    techInfoType2: str
-    techInfo2: str
+    techInfoType2: str | None = None
+    techInfo2: str | None = None
     techInfoCount: int
 
 
@@ -189,7 +213,7 @@ class LoginResponse(BaseModel):
     tempUnit: str
     tempUnitText: str
     dateFormat: str
-    userChartRecord: str
+    userChartRecord: str | None = None
     firewallNotificationEnable: str
     userCreateDate: str
     userCreatedDays: int
@@ -280,39 +304,124 @@ class InverterDevice(BaseModel):
         return _obfuscate_serial(value)
 
 
-class ParallelGroupDevice(BaseModel):
-    """Parallel group device information."""
+class ParallelGroupDeviceItem(BaseModel):
+    """Device in a parallel group from getParallelGroupDetails endpoint."""
 
-    parallelGroup: str
-    devices: list[InverterDevice]
+    serialNum: str
+    deviceType: int
+    subDeviceType: int
+    phase: int
+    dtc: int
+    machineType: int
+    parallelIndex: str
+    parallelNumText: str
+    lost: bool
+    roleText: str
+    # Optional runtime data fields (present for inverters, not for GridBOSS)
+    vpv1: int | None = None
+    ppv1: int | None = None
+    vpv2: int | None = None
+    ppv2: int | None = None
+    vpv3: int | None = None
+    ppv3: int | None = None
+    soc: int | None = None
+    vBat: int | None = None
+    pCharge: int | None = None
+    pDisCharge: int | None = None
+    peps: int | None = None
+
+    @field_serializer("serialNum")
+    def serialize_serial(self, value: str) -> str:
+        """Obfuscate serial number in serialized output."""
+        return _obfuscate_serial(value)
 
 
 class ParallelGroupDetailsResponse(BaseModel):
-    """Parallel group details API response."""
+    """Parallel group details API response.
+
+    Returns devices in a parallel group including GridBOSS (if present) and inverters.
+    """
 
     success: bool
-    parallelGroups: list[ParallelGroupDevice]
+    deviceType: int
+    parallelMidboxSn: str | None = None
+    total: int
+    devices: list[ParallelGroupDeviceItem]
 
 
 class InverterListResponse(BaseModel):
-    """Inverter list API response."""
+    """Inverter list API response (deprecated - use login response instead)."""
 
     success: bool
     rows: list[InverterDevice]
 
 
+class InverterOverviewItem(BaseModel):
+    """Inverter overview/status from inverterOverview/list endpoint."""
+
+    serialNum: str
+    statusText: str
+    deviceType: int
+    deviceTypeText: str
+    phase: int
+    plantId: int
+    plantName: str
+    ppv: int  # PV power in watts
+    ppvText: str
+    pCharge: int  # Charge power in watts
+    pChargeText: str
+    pDisCharge: int  # Discharge power in watts
+    pDisChargeText: str
+    pConsumption: int  # Consumption power in watts
+    pConsumptionText: str
+    soc: str  # State of charge (e.g., "58 %")
+    vBat: int  # Battery voltage (scaled: divide by 10 for actual volts)
+    vBatText: str
+    totalYielding: int  # Total energy generated (raw: divide by 10 for kWh)
+    totalYieldingText: str
+    totalDischarging: int  # Total energy discharged (raw: divide by 10 for kWh)
+    totalDischargingText: str
+    totalExport: int  # Total energy exported (raw: divide by 10 for kWh)
+    totalExportText: str
+    totalUsage: int  # Total energy consumed (raw: divide by 10 for kWh)
+    totalUsageText: str
+    parallelGroup: str
+    parallelIndex: str
+    parallelInfo: str
+    parallelModel: str
+    endUser: str | None = None  # Account type: "guest", owner username, or installer name
+
+    @field_serializer("serialNum")
+    def serialize_serial(self, value: str) -> str:
+        """Obfuscate serial number in serialized output."""
+        return _obfuscate_serial(value)
+
+
+class InverterOverviewResponse(BaseModel):
+    """Response from inverterOverview/list endpoint."""
+
+    success: bool
+    total: int
+    rows: list[InverterOverviewItem]
+
+
 # Runtime Data Models
 
 
 class InverterRuntime(BaseModel):
     """Inverter runtime data.
 
-    Note: Many values require scaling:
-    - Voltage: divide by 100
-    - Current: divide by 100
-    - Frequency: divide by 100
+    Raw values from API. Use property methods for scaled values.
+
+    Scaling applied by property methods:
+    - Most voltages: ÷10 (vpv1-3, vacr/s/t, vepsr/s/t, vBat)
+    - Bus voltages: ÷100 (vBus1, vBus2)
+    - Frequency: ÷100 (fac, feps, genFreq)
+    - Currents: ÷100 (maxChgCurr, maxDischgCurr)
     - Power: no scaling (direct watts)
     - Temperature: no scaling (direct Celsius)
+
+    See: constants.INVERTER_RUNTIME_SCALING for complete mapping
     """
 
     success: bool
@@ -332,16 +441,20 @@ class InverterRuntime(BaseModel):
     modelText: str | None = None
     serverTime: str
     deviceTime: str
+    deviceTimeText: str | None = None  # Formatted device time (e.g., "2025/12/24")
     # PV inputs (voltage requires �100)
     vpv1: int
     vpv2: int
     vpv3: int | None = None
+    vpv4: int | None = None  # Some models have 4 PV inputs
     remainTime: int = 0
     # PV power (watts, no scaling)
     ppv1: int
     ppv2: int
     ppv3: int | None = None
+    ppv4: int | None = None  # Some models have 4 PV inputs
     ppv: int
+    ppvpCharge: int | None = None  # PV charge power (alternate field name on some models)
     # AC voltages (�100 for volts)
     vacr: int
     vacs: int
@@ -382,14 +495,17 @@ class InverterRuntime(BaseModel):
     _12KAcCoupleInverterFlow: bool = False
     _12KAcCoupleInverterData: bool = False
     acCouplePower: int = 0
+    batteryCapacity: int | None = None  # Battery capacity in Ah (int version of batCapacity)
     # Other fields
     hasEpsOverloadRecoveryTime: bool = False
-    maxChgCurr: int
-    maxDischgCurr: int
+    # Note: These fields are optional as some models (e.g., 12000XP) don't return them
+    maxChgCurr: int = 0
+    maxDischgCurr: int = 0
     maxChgCurrValue: int | None = None
     maxDischgCurrValue: int | None = None
-    bmsCharge: bool
-    bmsDischarge: bool
+    # BMS fields - optional as some models don't support BMS communication
+    bmsCharge: bool = False
+    bmsDischarge: bool = False
     bmsForceCharge: bool = False
     # Generator
     _12KUsingGenerator: bool = False
@@ -403,8 +519,27 @@ class InverterRuntime(BaseModel):
     pEpsL1N: int = 0
     pEpsL2N: int = 0
     haspEpsLNValue: bool = False
+    # Smart Load (12000XP and similar models)
+    smartLoadInverterFlow: bool = False
+    smartLoadInverterEnable: bool = False
+    epsLoadPowerShow: bool = False
+    gridLoadPowerShow: bool = False
+    pLoadPowerShow: bool = False
+    epsLoadPower: int = 0
+    gridLoadPower: int = 0
+    smartLoadPower: int = 0
     # Directions
     directions: dict[str, str] = Field(default_factory=dict)
+
+    @property
+    def pac(self) -> int:
+        """AC output power (alias for pToUser for convenience).
+
+        Returns:
+            Power in watts flowing to user loads
+        """
+        return self.pToUser
+
     # Quick charge/discharge status
     hasUnclosedQuickChargeTask: bool = False
     hasUnclosedQuickDischargeTask: bool = False
@@ -416,7 +551,10 @@ class InverterRuntime(BaseModel):
 class EnergyInfo(BaseModel):
     """Energy statistics data.
 
-    All energy values are in Wh (divide by 10 for kWh display).
+    Raw energy values from API are in units of 0.1 kWh:
+    - Divide by 10 to get kWh directly
+    - Example: 184 → 18.4 kWh
+
     Note: serialNum and soc are not present in parallel group energy responses.
     """
 
@@ -445,44 +583,182 @@ class EnergyInfo(BaseModel):
 class BatteryModule(BaseModel):
     """Individual battery module information.
 
-    Note: Cell voltages are in millivolts (�1000 for volts).
+    Raw values from API. Use Battery class properties for scaled values.
+
+    Scaling (applied by Battery class):
+    - totalVoltage: ÷100 (5305 → 53.05V)
+    - current: ÷10 (60 → 6.0A) **CRITICAL: Not ÷100**
+    - batMaxCellVoltage/batMinCellVoltage: ÷1000 (3317 → 3.317V)
+    - batMaxCellTemp/batMinCellTemp: ÷10 (240 → 24.0°C)
+
+    See: constants.BATTERY_MODULE_SCALING for complete mapping
     """
 
+    # Identification
     batteryKey: str
     batterySn: str
     batIndex: int
+    batteryType: str | None = None
+    batteryTypeText: str | None = None
+    batBmsModelText: str | None = None
+
+    # Status
     lost: bool
-    # Voltage (�100 for volts)
+    lastUpdateTime: str | None = None
+
+    # Voltage and Current (÷100 for volts, ÷10 for amps)
     totalVoltage: int
-    # Current (�100 for amps)
     current: int
+
+    # State of Charge/Health
     soc: int
     soh: int
+
+    # Capacity
     currentRemainCapacity: int
     currentFullCapacity: int
-    # Temperatures (�10 for Celsius)
+    currentCapacityPercent: int | None = None
+    maxBatteryCharge: int | None = None
+
+    # Temperatures (÷10 for Celsius)
     batMaxCellTemp: int
     batMinCellTemp: int
-    # Cell voltages (millivolts, �1000 for volts)
+    batMaxCellNumTemp: int | None = None
+    batMinCellNumTemp: int | None = None
+
+    # Cell Voltages (÷1000 for volts)
     batMaxCellVoltage: int
     batMinCellVoltage: int
+    batMaxCellNumVolt: int | None = None
+    batMinCellNumVolt: int | None = None
+
+    # Charge Parameters
+    batChargeMaxCur: int | None = None
+    batChargeVoltRef: int | None = None
+
+    # Cycle Count and Firmware
     cycleCnt: int
     fwVersionText: str
 
+    # Additional Metrics (may be empty strings)
+    chgCapacity: str | None = None
+    disChgCapacity: str | None = None
+    ambientTemp: str | None = None
+    mosTemp: str | None = None
+    noticeInfo: str | None = None
+
 
 class BatteryInfo(BaseModel):
-    """Battery information including individual modules."""
+    """Battery information including individual modules.
+
+    This represents the aggregate battery system data from getBatteryInfo endpoint.
+    """
 
     success: bool
     serialNum: str
+
+    # Status
+    lost: bool | None = None
+    hasRuntimeData: bool | None = None
+    statusText: str | None = None
+    batStatus: str
+
+    # State of Charge
     soc: int
+
+    # Voltage (÷10 for volts at aggregate level)
     vBat: int
+    totalVoltageText: str | None = None
+
+    # Power (direct watts)
+    ppv: int | None = None  # PV power
     pCharge: int
     pDisCharge: int
-    batStatus: str
+    batPower: int | None = None  # Battery power
+    pinv: int | None = None  # Inverter power
+    prec: int | None = None  # Grid power
+    peps: int | None = None  # EPS/backup power
+
+    # Capacity (Ah)
     maxBatteryCharge: int
     currentBatteryCharge: float
+    remainCapacity: int | None = None
+    fullCapacity: int | None = None
+    capacityPercent: int | None = None
+
+    # Current
+    currentText: str | None = None
+    currentType: str | None = None  # "charge" or "discharge"
+
+    # Individual Battery Modules
     batteryArray: list[BatteryModule]
+    totalNumber: int | None = None  # Total battery count
+
+
+class BatteryListItem(BaseModel):
+    """Simplified battery item from getBatteryInfoForSet endpoint."""
+
+    batteryKey: str
+    batterySn: str
+    batIndex: int
+    lost: bool
+
+
+class BatteryListResponse(BaseModel):
+    """Response from getBatteryInfoForSet endpoint.
+
+    This endpoint returns a simplified list of batteries without detailed metrics.
+    Use get_battery_info() for full battery metrics.
+    """
+
+    success: bool
+    serialNum: str
+    totalNumber: int
+    batteryArray: list[BatteryListItem]
+
+
+class InverterDetail(BaseModel):
+    """Inverter detail information."""
+
+    deviceText: str
+    fwCode: str
+    fwCodeText: str
+
+
+class InverterInfo(BaseModel):
+    """Detailed inverter configuration and device information.
+
+    This endpoint returns static device configuration details,
+    not runtime data. Use get_inverter_runtime() for real-time metrics.
+    """
+
+    success: bool
+    lost: bool
+    datalogSn: str
+    serialNum: str
+    deviceType: int
+    phase: int
+    dtc: int
+    voltClass: int
+    fwVersion: int
+    hardwareVersion: int
+    subDeviceType: int
+    allowExport2Grid: bool
+    powerRating: int
+    machineType: int
+    deviceTypeText: str
+    inverterDetail: InverterDetail
+    deviceInfo: str
+    address: int
+    powerRatingText: str
+    batteryType: BatteryType
+    status: int
+    statusText: str
+
+    @field_serializer("serialNum", "datalogSn")
+    def serialize_serial(self, value: str) -> str:
+        """Obfuscate serial numbers in serialized output."""
+        return _obfuscate_serial(value)
 
 
 # GridBOSS/MID Device Models
@@ -491,24 +767,41 @@ class BatteryInfo(BaseModel):
 class MidboxData(BaseModel):
     """GridBOSS/MID device runtime data.
 
-    Note: Voltages, currents, and frequency require scaling (�100).
+    Note: Voltages are in decivolts (÷10), currents in centiamps (÷100),
+    frequency in centihertz (÷100). Power values are in watts (no scaling).
     """
 
     status: int
     serverTime: str
     deviceTime: str
-    # Grid voltages (�100 for volts)
+    # Grid voltages (�10 for volts, e.g., 2418 = 241.8V)
     gridRmsVolt: int
     upsRmsVolt: int
     genRmsVolt: int
     gridL1RmsVolt: int
     gridL2RmsVolt: int
-    # Grid currents (�100 for amps)
+    upsL1RmsVolt: int
+    upsL2RmsVolt: int
+    genL1RmsVolt: int
+    genL2RmsVolt: int
+    # Currents (�100 for amps)
     gridL1RmsCurr: int
     gridL2RmsCurr: int
+    loadL1RmsCurr: int
+    loadL2RmsCurr: int
+    genL1RmsCurr: int
+    genL2RmsCurr: int
+    upsL1RmsCurr: int
+    upsL2RmsCurr: int
     # Power (watts, no scaling)
     gridL1ActivePower: int
     gridL2ActivePower: int
+    loadL1ActivePower: int
+    loadL2ActivePower: int
+    genL1ActivePower: int
+    genL2ActivePower: int
+    upsL1ActivePower: int
+    upsL2ActivePower: int
     hybridPower: int
     # Smart port status
     smartPort1Status: int
@@ -570,10 +863,15 @@ class ParameterReadResponse(BaseModel):
 
 
 class QuickChargeStatus(BaseModel):
-    """Quick charge status response."""
+    """Quick charge/discharge status response.
+
+    Note: The quickCharge/getStatusInfo endpoint returns status for BOTH
+    quick charge and quick discharge operations.
+    """
 
     success: bool
     hasUnclosedQuickChargeTask: bool
+    hasUnclosedQuickDischargeTask: bool = False  # May not be present in older API versions
 
 
 class SuccessResponse(BaseModel):
@@ -683,17 +981,20 @@ class FirmwareUpdateDetails(BaseModel):
         """Obfuscate serial number in serialized output."""
         return _obfuscate_serial(value)
 
+    @property
     def has_app_update(self) -> bool:
         """Check if application firmware update is available."""
         return self.lastV1 is not None and self.v1 < self.lastV1 and self.pcs1UpdateMatch
 
+    @property
     def has_parameter_update(self) -> bool:
         """Check if parameter firmware update is available."""
         return self.lastV2 is not None and self.v2 < self.lastV2 and self.pcs2UpdateMatch
 
+    @property
     def has_update(self) -> bool:
         """Check if any firmware update is available."""
-        return self.has_app_update() or self.has_parameter_update()
+        return self.has_app_update or self.has_parameter_update
 
 
 class FirmwareUpdateCheck(BaseModel):
@@ -703,6 +1004,48 @@ class FirmwareUpdateCheck(BaseModel):
     details: FirmwareUpdateDetails
     infoForwardUrl: str | None = None
 
+    @classmethod
+    def create_up_to_date(cls, serial_num: str) -> FirmwareUpdateCheck:
+        """Create a FirmwareUpdateCheck indicating firmware is already up to date.
+
+        This is used when the API returns a "firmware is already the latest version"
+        message, which should be treated as a successful check with no update available.
+
+        Args:
+            serial_num: Device serial number
+
+        Returns:
+            FirmwareUpdateCheck with details indicating no update is available
+        """
+        # Create minimal details with no update available
+        # All version fields set to 0, no latest versions, compatibility flags False
+        details = FirmwareUpdateDetails(
+            serialNum=serial_num,
+            deviceType=0,
+            standard="",
+            firmwareType="",
+            fwCodeBeforeUpload="",
+            v1=0,  # Current version unknown
+            v2=0,
+            v3Value=0,
+            lastV1=None,  # No update available
+            lastV1FileName=None,
+            lastV2=None,
+            lastV2FileName=None,
+            m3Version=0,
+            pcs1UpdateMatch=False,  # No update match
+            pcs2UpdateMatch=False,
+            pcs3UpdateMatch=False,
+            needRunStep2=False,
+            needRunStep3=False,
+            needRunStep4=False,
+            needRunStep5=False,
+            midbox=False,
+            lowVoltBattery=False,
+            type6=False,
+        )
+        return cls(success=True, details=details, infoForwardUrl=None)
+
 
 class FirmwareDeviceInfo(BaseModel):
     """Individual device firmware update information."""
@@ -724,20 +1067,55 @@ class FirmwareDeviceInfo(BaseModel):
         """Obfuscate serial number in serialized output."""
         return _obfuscate_serial(value)
 
+    @property
     def is_in_progress(self) -> bool:
-        """Check if update is currently in progress."""
+        """Check if update is currently in progress.
+
+        Uses multiple indicators for reliable detection:
+        - updateStatus must be UPLOADING or READY
+        - isSendEndUpdate must be False (not completed yet)
+        - isSendStartUpdate should be True (update has started)
+
+        This ensures we accurately detect active updates and avoid
+        false positives from completed or failed updates.
+
+        Returns:
+            True if update is actively in progress, False otherwise
+        """
         return (
-            self.updateStatus == UpdateStatus.UPLOADING or self.updateStatus == UpdateStatus.READY
+            (self.updateStatus == UpdateStatus.UPLOADING or self.updateStatus == UpdateStatus.READY)
+            and not self.isSendEndUpdate
+            and self.isSendStartUpdate
         )
 
+    @property
     def is_complete(self) -> bool:
-        """Check if update completed successfully."""
+        """Check if update completed successfully.
+
+        Uses multiple indicators for reliable detection:
+        - updateStatus is SUCCESS or COMPLETE
+        - isSendEndUpdate is True (end notification sent)
+        - stopTime is populated (not empty string)
+
+        Returns:
+            True if update completed successfully, False otherwise
+        """
         return (
-            self.updateStatus == UpdateStatus.COMPLETE or self.updateStatus == UpdateStatus.SUCCESS
+            (
+                self.updateStatus == UpdateStatus.SUCCESS
+                or self.updateStatus == UpdateStatus.COMPLETE
+            )
+            and self.isSendEndUpdate
+            and bool(self.stopTime.strip())
         )
 
+    @property
     def is_failed(self) -> bool:
-        """Check if update failed."""
+        """Check if update failed.
+
+        Returns:
+            True if update failed, False otherwise
+        """
         return self.updateStatus == UpdateStatus.FAILED
 
 
@@ -749,9 +1127,10 @@ class FirmwareUpdateStatus(BaseModel):
     fileReady: bool
     deviceInfos: list[FirmwareDeviceInfo]
 
+    @property
     def has_active_updates(self) -> bool:
         """Check if any device has an active update."""
-        return any(device.is_in_progress() for device in self.deviceInfos)
+        return any(device.is_in_progress for device in self.deviceInfos)
 
 
 class UpdateEligibilityStatus(BaseModel):
@@ -760,6 +1139,216 @@ class UpdateEligibilityStatus(BaseModel):
     success: bool
     msg: UpdateEligibilityMessage
 
+    @property
     def is_allowed(self) -> bool:
         """Check if device is allowed to update."""
         return self.msg == UpdateEligibilityMessage.ALLOW_TO_UPDATE
+
+
+class FirmwareUpdateInfo(BaseModel):
+    """Home Assistant-friendly firmware update information.
+
+    This model provides all fields needed to create an Update entity in Home Assistant,
+    including required properties (installed_version, latest_version, title) and
+    optional properties (release_summary, release_url, in_progress, etc.).
+
+    Example:
+        ```python
+        update_info = await inverter.get_firmware_update_info()
+        if update_info.update_available:
+            print(f"Update: {update_info.installed_version} → {update_info.latest_version}")
+            print(f"Release notes: {update_info.release_url}")
+            print(f"Summary: {update_info.release_summary}")
+        ```
+    """
+
+    # Required HA Update Entity properties
+    installed_version: str  # Current firmware version (e.g., "IAAB-1300")
+    latest_version: str  # Latest available version
+    title: str  # Software title (e.g., "Inverter Firmware", "GridBOSS Firmware")
+
+    # Optional HA Update Entity properties
+    release_summary: str | None = None  # Brief changelog (max 255 chars)
+    release_url: str | None = None  # URL to full release notes
+    in_progress: bool = False  # Whether update is currently installing
+    update_percentage: int | None = None  # Installation progress (0-100)
+
+    # Additional metadata for HA entity configuration
+    device_class: str = "firmware"  # UpdateDeviceClass.FIRMWARE
+    supported_features: list[str] = []  # e.g., ["install", "progress", "release_notes"]
+
+    # Raw API data for advanced use
+    app_version_current: int | None = None  # v1 from API
+    app_version_latest: int | None = None  # lastV1 from API
+    param_version_current: int | None = None  # v2 from API
+    param_version_latest: int | None = None  # lastV2 from API
+    app_filename: str | None = None  # lastV1FileName from API
+    param_filename: str | None = None  # lastV2FileName from API
+
+    @property
+    def update_available(self) -> bool:
+        """Check if firmware update is available.
+
+        Returns:
+            True if latest_version is newer than installed_version.
+        """
+        return self.installed_version != self.latest_version
+
+    @property
+    def has_app_update(self) -> bool:
+        """Check if application firmware update is available.
+
+        Returns:
+            True if app firmware update is available.
+        """
+        return (
+            self.app_version_current is not None
+            and self.app_version_latest is not None
+            and self.app_version_current < self.app_version_latest
+        )
+
+    @property
+    def has_parameter_update(self) -> bool:
+        """Check if parameter firmware update is available.
+
+        Returns:
+            True if parameter firmware update is available.
+        """
+        return (
+            self.param_version_current is not None
+            and self.param_version_latest is not None
+            and self.param_version_current < self.param_version_latest
+        )
+
+    @classmethod
+    def from_api_response(
+        cls,
+        check: FirmwareUpdateCheck,
+        title: str,
+        in_progress: bool = False,
+        update_percentage: int | None = None,
+    ) -> FirmwareUpdateInfo:
+        """Create FirmwareUpdateInfo from API response.
+
+        Args:
+            check: FirmwareUpdateCheck from API
+            title: Device title (e.g., "FlexBOSS21 Firmware", "GridBOSS Firmware")
+            in_progress: Whether update is currently installing
+            update_percentage: Installation progress (0-100)
+
+        Returns:
+            FirmwareUpdateInfo instance with HA-compatible fields.
+
+        Example:
+            ```python
+            api_check = await client.firmware.check_firmware_updates(serial)
+            update_info = FirmwareUpdateInfo.from_api_response(
+                api_check,
+                title="FlexBOSS21 Firmware"
+            )
+            ```
+        """
+        details = check.details
+
+        # Construct latest version from lastV1/lastV2 (or use current if no updates)
+        # Format: {fwCode}-{v1_hex}{v2_hex} (e.g., "IAAB-1600" for v1=22, v2=0)
+        # Note: API returns decimal values, but firmware versions use hexadecimal
+        if details.has_app_update or details.has_parameter_update:
+            # Use lastV1/lastV2 if there's an actual update, otherwise use current
+            latest_v1 = details.lastV1 if details.has_app_update else details.v1
+            latest_v2 = details.lastV2 if details.has_parameter_update else details.v2
+            # Extract firmware code (e.g., "IAAB" from "IAAB-1300")
+            fw_code = (
+                details.fwCodeBeforeUpload.split("-")[0]
+                if "-" in details.fwCodeBeforeUpload
+                else details.fwCodeBeforeUpload[:4]
+            )
+            # Convert to 2-digit hex (uppercase to match API format)
+            latest_version = f"{fw_code}-{latest_v1:02X}{latest_v2:02X}"
+        else:
+            # No updates available
+            latest_version = details.fwCodeBeforeUpload
+
+        # Generate release summary (max 255 chars for HA)
+        # Format as hex to match firmware version format (e.g., IAAB-1300 means v1=0x13)
+        summary_parts = []
+        if details.has_app_update:
+            summary_parts.append(f"App firmware: v{details.v1:02X} → v{details.lastV1:02X}")
+        if details.has_parameter_update:
+            summary_parts.append(f"Parameter firmware: v{details.v2:02X} → v{details.lastV2:02X}")
+        release_summary = "; ".join(summary_parts) if summary_parts else None
+
+        # Determine supported features based on API capabilities
+        supported_features = ["install"]  # All devices support install
+        if update_percentage is not None:
+            supported_features.append("progress")
+        if check.infoForwardUrl:
+            supported_features.append("release_notes")
+
+        return cls(
+            # Required HA properties
+            installed_version=details.fwCodeBeforeUpload,
+            latest_version=latest_version,
+            title=title,
+            # Optional HA properties
+            release_summary=release_summary,
+            release_url=check.infoForwardUrl,
+            in_progress=in_progress,
+            update_percentage=update_percentage,
+            # Metadata
+            device_class="firmware",
+            supported_features=supported_features,
+            # Raw API data
+            app_version_current=details.v1,
+            app_version_latest=details.lastV1,
+            param_version_current=details.v2,
+            param_version_latest=details.lastV2,
+            app_filename=details.lastV1FileName,
+            param_filename=details.lastV2FileName,
+        )
+
+
+# Dongle Connection Status Models
+
+
+class DongleStatus(BaseModel):
+    """Dongle connection status from findOnlineDatalog endpoint.
+
+    The dongle (datalog) is the communication module that connects
+    inverters to the cloud monitoring service. This model represents
+    its current online/offline status.
+
+    The API returns:
+    - msg: "current" when dongle is actively communicating
+    - msg: "" (empty) when dongle is offline/not communicating
+
+    Example:
+        ```python
+        status = await client.devices.get_dongle_status("BC34000380")
+        if status.is_online:
+            print("Dongle is online and communicating")
+        else:
+            print("Dongle is offline - inverter data may be stale")
+        ```
+    """
+
+    success: bool
+    msg: str = ""
+
+    @property
+    def is_online(self) -> bool:
+        """Check if the dongle is currently online.
+
+        Returns:
+            True if dongle is actively communicating, False otherwise.
+        """
+        return self.msg == "current"
+
+    @property
+    def status_text(self) -> str:
+        """Get human-readable status text.
+
+        Returns:
+            "Online" or "Offline" based on dongle status.
+        """
+        return "Online" if self.is_online else "Offline"