conson-xp 1.18.0__py3-none-any.whl

xp/models/telegram/output_telegram.py

@@ -0,0 +1,103 @@
+"""XP output telegram model for console bus communication.
+
+XP output telegrams are used for controlling relay inputs on XP modules.
+Each XP24 module has 4 inputs (0-3) that can be pressed or released.
+Each XP33 module has 3 inputs (0-2) that can be pressed or released.
+Each XP31 module has 1 inputs (0-0) that can be pressed or released.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+from xp.models.telegram.action_type import ActionType
+from xp.models.telegram.system_function import SystemFunction
+from xp.models.telegram.telegram import Telegram
+
+
+@dataclass
+class OutputTelegram(Telegram):
+    """Represent a parsed XP output telegram from the console bus.
+
+    Format: <S{serial_number}F27D{input:02d}{action}{checksum}>
+    Examples: <S0012345008F27D00AAFN>
+
+    Attributes:
+        serial_number: Serial number of the device.
+        output_number: Output number (0-3 for XP24, 0-2 for XP33, 0 for XP31).
+        action_type: Type of action to perform.
+        system_function: System function code.
+        action_description: Human-readable action description.
+        input_description: Human-readable input description.
+    """
+
+    serial_number: str = ""
+    output_number: Optional[int] = (
+        None  # 0-3 for XP24 modules, 0-2 for XP33, 0 for XP31
+    )
+    action_type: Optional[ActionType] = None
+    system_function: SystemFunction = SystemFunction.ACTION
+
+    def __post_init__(self) -> None:
+        """Initialize timestamp if not provided."""
+        if self.timestamp is None:
+            self.timestamp = datetime.now()
+
+    @property
+    def action_description(self) -> str:
+        """Get human-readable action description.
+
+        Returns:
+            Human-readable description of the action.
+        """
+        descriptions = {
+            ActionType.OFF_PRESS: "Press (Make)",
+            ActionType.ON_RELEASE: "Release (Break)",
+        }
+        return (
+            descriptions.get(self.action_type, "Unknown Action")
+            if self.action_type
+            else "Unknown Action"
+        )
+
+    @property
+    def input_description(self) -> str:
+        """Get human-readable input description.
+
+        Returns:
+            Description of the input/output number.
+        """
+        return f"Input {self.output_number}"
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation of the output telegram.
+        """
+        return {
+            "serial_number": self.serial_number,
+            "system_function": self.system_function,
+            "output_number": self.output_number,
+            "input_description": self.input_description,
+            "action_type": {
+                "code": self.action_type.value if self.action_type else None,
+                "description": self.action_description,
+            },
+            "checksum": self.checksum,
+            "checksum_validated": self.checksum_validated,
+            "raw_telegram": self.raw_telegram,
+            "timestamp": self.timestamp.isoformat() if self.timestamp else None,
+        }
+
+    def __str__(self) -> str:
+        """Return human-readable string representation.
+
+        Returns:
+            Formatted string representation.
+        """
+        return (
+            f"XP Output: {self.action_description} "
+            f"on {self.input_description} "
+            f"for device {self.serial_number}"
+        )

xp/models/telegram/reply_telegram.py

@@ -0,0 +1,297 @@
+"""Reply telegram model for console bus communication.
+
+Reply telegrams are responses to system telegrams, containing the requested data
+like temperature readings, status information, etc.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Optional
+
+from xp.models.telegram.datapoint_type import DataPointType
+from xp.models.telegram.system_function import SystemFunction
+from xp.models.telegram.telegram import Telegram
+from xp.models.telegram.telegram_type import TelegramType
+
+
+@dataclass
+class ReplyTelegram(Telegram):
+    """Represents a parsed reply telegram from the console bus.
+
+    Format: <R{serial_number}F{function_code}D{data}{checksum}>
+    Format: <R{serial_number}F{function_code}D{datapoint_type}{data_value}{checksum}>
+
+    Examples:
+        - raw_telegram: <R0020012521F02D18+26,0§CIL>
+        - telegram_type : ReplyTelegram (R)
+        - serial_number: 0020012521
+        - function_code: 02
+        - data: 18+26,0§C
+        - datapoint_type: 18
+        - data_value: +26,0§C
+        - checksum: IL
+
+    Attributes:
+        serial_number: Serial number of the device.
+        system_function: System function code.
+        data: Raw data payload.
+        datapoint_type: Type of datapoint.
+        data_value: Parsed data value.
+        parse_datapoint_value: Parsed value based on datapoint type.
+    """
+
+    serial_number: str = ""
+    system_function: SystemFunction = SystemFunction.NONE
+    data: str = ""
+    datapoint_type: Optional[DataPointType] = None
+    data_value: str = ""
+
+    def __post_init__(self) -> None:
+        """Initialize timestamp and telegram type."""
+        if self.timestamp is None:
+            self.timestamp = datetime.now()
+        self.telegram_type = TelegramType.REPLY
+
+    @property
+    def parse_datapoint_value(self) -> dict[str, Any]:
+        """Parse the data value based on data point type.
+
+        Returns:
+            Dictionary containing parsed value and metadata.
+        """
+        if self.datapoint_type == DataPointType.TEMPERATURE:
+            return self._parse_temperature_value()
+        elif self.datapoint_type == DataPointType.SW_TOP_VERSION:
+            return self._parse_humidity_value()
+        elif self.datapoint_type == DataPointType.VOLTAGE:
+            return self._parse_voltage_value()
+        elif self.datapoint_type == DataPointType.MODULE_ENERGY_LEVEL:
+            return self._parse_current_value()
+        elif self.datapoint_type == DataPointType.MODULE_TYPE:
+            return self._parse_module_type_value()
+        elif self.datapoint_type == DataPointType.SW_VERSION:
+            return self._parse_sw_version_value()
+        return {"raw_value": self.data_value, "parsed": False}
+
+    def _parse_temperature_value(self) -> dict:
+        """Parse temperature value like '+26,0§C'.
+
+        Returns:
+            Dictionary containing parsed temperature value and metadata.
+        """
+        try:
+            # Remove unit indicator (§C)
+            value_part = self.data_value.replace("§C", "")
+            # Replace comma with dot for decimal
+            value_str = value_part.replace(",", ".")
+            temperature = float(value_str)
+
+            return {
+                "value": temperature,
+                "unit": "°C",
+                "formatted": f"{temperature:.1f}°C",
+                "raw_value": self.data_value,
+                "parsed": True,
+            }
+        except (ValueError, AttributeError):
+            return {
+                "raw_value": self.data_value,
+                "parsed": False,
+                "error": "Failed to parse temperature",
+            }
+
+    def _parse_humidity_value(self) -> dict:
+        """Parse humidity value like '+65,5§H'.
+
+        Returns:
+            Dictionary containing parsed humidity value and metadata.
+        """
+        try:
+            # Remove unit indicator (§H)
+            value_part = self.data_value.replace("§RH", "")
+            # Replace comma with dot for decimal
+            value_str = value_part.replace(",", ".")
+            humidity = float(value_str)
+
+            return {
+                "value": humidity,
+                "unit": "%RH",
+                "formatted": f"{humidity:.1f}%RH",
+                "raw_value": self.data_value,
+                "parsed": True,
+            }
+        except (ValueError, AttributeError):
+            return {
+                "raw_value": self.data_value,
+                "parsed": False,
+                "error": "Failed to parse humidity",
+            }
+
+    def _parse_voltage_value(self) -> dict:
+        """Parse voltage value like '+12,5§V'.
+
+        Returns:
+            Dictionary containing parsed voltage value and metadata.
+        """
+        try:
+            # Remove unit indicator (§V)
+            value_part = self.data_value.replace("§V", "")
+            # Replace comma with dot for decimal
+            value_str = value_part.replace(",", ".")
+            voltage = float(value_str)
+
+            return {
+                "value": voltage,
+                "unit": "V",
+                "formatted": f"{voltage:.1f}V",
+                "raw_value": self.data_value,
+                "parsed": True,
+            }
+        except (ValueError, AttributeError):
+            return {
+                "raw_value": self.data_value,
+                "parsed": False,
+                "error": "Failed to parse voltage",
+            }
+
+    def _parse_current_value(self) -> dict:
+        """Parse current value like '+0,25§A'.
+
+        Returns:
+            Dictionary containing parsed current value and metadata.
+        """
+        try:
+            # Remove unit indicator (§A)
+            value_part = self.data_value.replace("§A", "")
+            # Replace comma with dot for decimal
+            value_str = value_part.replace(",", ".")
+            current = float(value_str)
+
+            return {
+                "value": current,
+                "unit": "A",
+                "formatted": f"{current:.2f}A",
+                "raw_value": self.data_value,
+                "parsed": True,
+            }
+        except (ValueError, AttributeError):
+            return {
+                "raw_value": self.data_value,
+                "parsed": False,
+                "error": "Failed to parse current",
+            }
+
+    def _parse_module_type_value(self) -> dict:
+        """Parse status value.
+
+        Returns:
+            Dictionary containing parsed module type value.
+        """
+        # Status values are typically alphanumeric codes
+        return {
+            "module_type": self.data_value,
+            "raw_value": self.data_value,
+            "parsed": True,
+        }
+
+    def _parse_sw_version_value(self) -> dict:
+        """Parse version value like 'XP230_V1.00.04'.
+
+        Returns:
+            Dictionary containing parsed version information.
+        """
+        try:
+            # Version format: {PRODUCT}_{VERSION}
+            # Examples: XP230_V1.00.04, XP20_V0.01.05, XP33LR_V0.04.02, XP24_V0.34.03
+            if "_V" in self.data_value:
+                parts = self.data_value.split("_V", 1)
+                if len(parts) == 2:
+                    product = parts[0]
+                    version = parts[1]
+
+                    return {
+                        "product": product,
+                        "version": version,
+                        "full_version": self.data_value,
+                        "formatted": f"{product} v{version}",
+                        "raw_value": self.data_value,
+                        "parsed": True,
+                    }
+
+            # If format doesn't match expected pattern, treat as raw
+            return {
+                "full_version": self.data_value,
+                "formatted": self.data_value,
+                "raw_value": self.data_value,
+                "parsed": False,
+                "error": "Version format not recognized",
+            }
+
+        except (ValueError, AttributeError):
+            return {
+                "raw_value": self.data_value,
+                "parsed": False,
+                "error": "Failed to parse version",
+            }
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation of the reply telegram.
+        """
+        parsed_data = self.parse_datapoint_value
+
+        return {
+            "serial_number": self.serial_number,
+            "system_function": (
+                {
+                    "code": (
+                        self.system_function.value if self.system_function else None
+                    ),
+                    "description": (
+                        self.system_function.name if self.system_function else None
+                    ),
+                }
+                if self.system_function
+                else None
+            ),
+            "datapoint_type": (
+                {
+                    "code": self.datapoint_type.value if self.datapoint_type else None,
+                    "description": (
+                        self.datapoint_type.name if self.datapoint_type else None
+                    ),
+                }
+                if self.datapoint_type
+                else None
+            ),
+            "data_value": {"raw": self.data_value, "parsed": parsed_data},
+            "checksum": self.checksum,
+            "checksum_validated": self.checksum_validated,
+            "raw_telegram": self.raw_telegram,
+            "timestamp": self.timestamp.isoformat() if self.timestamp else None,
+            "telegram_type": self.telegram_type.value,
+        }
+
+    def __str__(self) -> str:
+        """Human-readable string representation.
+
+        Returns:
+            Formatted string representation.
+        """
+        parsed = self.parse_datapoint_value
+        if parsed.get("parsed", False) and "formatted" in parsed:
+            value_display = parsed["formatted"]
+        else:
+            value_display = self.data_value
+
+        system_func_name = (
+            self.system_function.name if self.system_function else "Unknown"
+        )
+        datapoint_name = self.datapoint_type.name if self.datapoint_type else "Unknown"
+        return (
+            f"Reply Telegram: {system_func_name}\n "
+            f"for {datapoint_name} = {value_display} "
+            f"from device {self.serial_number}"
+        )

xp/models/telegram/system_function.py

@@ -0,0 +1,116 @@
+"""System function enumeration for system telegrams."""
+
+from enum import Enum
+from typing import Optional
+
+
+class SystemFunction(str, Enum):
+    """System function codes for system telegrams.
+
+    Attributes:
+        NONE: Undefined function.
+        DISCOVERY: Discover function.
+        READ_DATAPOINT: Read datapoint.
+        READ_CONFIG: Read configuration.
+        WRITE_CONFIG: Write configuration.
+        BLINK: Blink LED function.
+        UNBLINK: Unblink LED function.
+        UPLOAD_FIRMWARE_START: Start upload firmware.
+        UPLOAD_FIRMWARE_STOP: Stop upload firmware.
+        UPLOAD_FIRMWARE: Upload firmware.
+        UPLOAD_ACTIONTABLE: Upload ActionTable to module.
+        DOWNLOAD_ACTIONTABLE: Download ActionTable.
+        UPLOAD_MSACTIONTABLE: Upload module specific action table to module.
+        DOWNLOAD_MSACTIONTABLE: Download module specific action table.
+        TELEGRAM_WRITE_START: Start writing telegram.
+        TELEGRAM_READ_START: Start reading telegram.
+        EOF: End of msactiontable response.
+        TELEGRAM: Module specific telegram response.
+        MSACTIONTABLE: Module specific action table response.
+        ACTIONTABLE: Module specific action table response.
+        ACK: Acknowledge response.
+        NAK: Not acknowledge response.
+        UPLOAD_TOP_FIRMWARE_START: Start upload firmware (TOP).
+        UPLOAD_TOP_FIRMWARE_STOP: Stop upload firmware (TOP).
+        UPLOAD_TOP_FIRMWARE: Upload firmware (TOP).
+        ROTATE_ENABLE: Enable rotate.
+        ROTATE_DISABLE: Disable rotate.
+        UNKNOWN_26: Used after discover, unknown purpose.
+        ACTION: Action function.
+    """
+
+    NONE = "00"  # F00D Undefined
+    DISCOVERY = "01"  # F01D Discover function
+    READ_DATAPOINT = "02"  # F02D Read datapoint
+    READ_CONFIG = "03"  # F03D Read configuration
+    WRITE_CONFIG = "04"  # F04D Write configuration
+    BLINK = "05"  # F05D Blink LED function
+    UNBLINK = "06"  # F06D Unblink LED function
+
+    UPLOAD_FIRMWARE_START = "07"  # F07D Start Upload firmware
+    UPLOAD_FIRMWARE_STOP = "08"  # F08D Stop Upload firmware
+    UPLOAD_FIRMWARE = "09"  # F09D Upload firmware
+
+    UPLOAD_ACTIONTABLE = "10"  # F10D Upload ActionTable
+    DOWNLOAD_ACTIONTABLE = "11"  # F11D Download ActionTable
+    UPLOAD_MSACTIONTABLE = "12"  # F12D Upload MsActionTable to module
+    DOWNLOAD_MSACTIONTABLE = "13"  # F13D Download MsActionTable
+
+    TELEGRAM_WRITE_START = "14"  # F14D Start writing telegram
+    TELEGRAM_READ_START = "15"  # F15D Start reading telegram
+    EOF = "16"  # F16D End of msactiontable response
+    TELEGRAM = "17"  # F17D module specific Telegram response
+    MSACTIONTABLE = "17"  # F17D module specific ms action table (Telegram) response
+    ACTIONTABLE = "17"  # F17D module specific action table (Telegram) response
+    ACK = "18"  # F18D Acknowledge / continue response
+    NAK = "19"  # F19D Not acknowledge response
+
+    UPLOAD_TOP_FIRMWARE_START = "20"  # F20D Start Upload firmware (TOP)
+    UPLOAD_TOP_FIRMWARE_STOP = "21"  # F21D Stop Upload firmware (TOP)
+    UPLOAD_TOP_FIRMWARE = "22"  # F22D Upload firmware (TOP)
+
+    ROTATE_ENABLE = "23"  # F23D Enable rotate
+    ROTATE_DISABLE = "24"  # F24D Disable rotate
+
+    UNKNOWN_26 = "26"  # F26D Used after discover, but don't know what it is
+    ACTION = "27"  # F27D Action function
+
+    def get_description(self) -> str:
+        """Get the description of the SystemFunction.
+
+        Returns:
+            Human-readable description of the function.
+        """
+        return (
+            {
+                self.DISCOVERY: "Discover function",
+                self.READ_DATAPOINT: "Read datapoint",
+                self.READ_CONFIG: "Read configuration",
+                self.WRITE_CONFIG: "Write configuration",
+                self.BLINK: "Blink LED function",
+                self.DOWNLOAD_MSACTIONTABLE: "Download the msactiontable",
+                self.DOWNLOAD_ACTIONTABLE: "Download ActionTable",
+                self.EOF: "End of msactiontable response",
+                self.ACTIONTABLE: "Actiontable response",
+                self.MSACTIONTABLE: "Msactiontable response",
+                self.UNBLINK: "Unblink LED function",
+                self.ACK: "Acknowledge response",
+                self.NAK: "Not acknowledge response",
+                self.ACTION: "Action function",
+            }
+        ).get(self, "Unknown function")
+
+    @classmethod
+    def from_code(cls, code: str) -> Optional["SystemFunction"]:
+        """Get SystemFunction from code string.
+
+        Args:
+            code: Function code string.
+
+        Returns:
+            SystemFunction instance if found, None otherwise.
+        """
+        for func in cls:
+            if func.value.lower() == code.lower():
+                return func
+        return None

xp/models/telegram/system_telegram.py

@@ -0,0 +1,94 @@
+"""System telegram model for console bus communication.
+
+System telegrams are used for system-related information like updating firmware
+and reading temperature from modules.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Optional
+
+from xp.models.telegram.datapoint_type import DataPointType
+from xp.models.telegram.system_function import SystemFunction
+from xp.models.telegram.telegram import Telegram
+from xp.models.telegram.telegram_type import TelegramType
+
+
+@dataclass
+class SystemTelegram(Telegram):
+    """Represents a parsed system telegram from the console bus.
+
+    Format: <S{serial_number}F{function_code}D{datapoint_type}{checksum}>
+    Examples: <S0020012521F02D18FN>
+
+    Attributes:
+        serial_number: Serial number of the device (0020012521)
+        system_function: System function code (02).
+        data: Data payload (18)
+        datapoint_type: Type of datapoint (18).
+    """
+
+    serial_number: str = ""
+    system_function: Optional[SystemFunction] = None
+    data: str = ""
+    datapoint_type: Optional[DataPointType] = None
+
+    def __post_init__(self) -> None:
+        """Initialize timestamp and telegram type."""
+        if self.timestamp is None:
+            self.timestamp = datetime.now()
+        self.telegram_type = TelegramType.SYSTEM
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation of the system telegram.
+        """
+        return {
+            "serial_number": self.serial_number,
+            "system_function": (
+                {
+                    "code": (
+                        self.system_function.value if self.system_function else None
+                    ),
+                    "description": (
+                        self.system_function.name if self.system_function else None
+                    ),
+                }
+                if self.system_function
+                else None
+            ),
+            "datapoint_type": (
+                {
+                    "code": self.datapoint_type.value if self.datapoint_type else None,
+                    "description": (
+                        self.datapoint_type.name if self.datapoint_type else None
+                    ),
+                }
+                if self.datapoint_type
+                else None
+            ),
+            "checksum": self.checksum,
+            "checksum_validated": self.checksum_validated,
+            "raw_telegram": self.raw_telegram,
+            "timestamp": self.timestamp.isoformat() if self.timestamp else None,
+            "telegram_type": self.telegram_type.value,
+        }
+
+    def __str__(self) -> str:
+        """Human-readable string representation.
+
+        Returns:
+            Formatted string representation.
+        """
+        system_func_name = (
+            self.system_function.name if self.system_function else "Unknown"
+        )
+        data = self.data or "None"
+        data = self.datapoint_type.name if self.datapoint_type else data
+        return (
+            f"System Telegram: {system_func_name} "
+            f"with data {data} "
+            f"from device {self.serial_number}"
+        )

xp/models/telegram/telegram.py

@@ -0,0 +1,28 @@
+"""Base telegram model for console bus communication."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+from xp.models.telegram.telegram_type import TelegramType
+
+
+@dataclass
+class Telegram:
+    """Represents an abstract telegram from the console bus.
+
+    Can be an EventTelegram, SystemTelegram or ReplyTelegram.
+
+    Attributes:
+        checksum: Telegram checksum value.
+        raw_telegram: Raw telegram string.
+        checksum_validated: Whether checksum validation passed.
+        timestamp: Timestamp when telegram was received.
+        telegram_type: Type of telegram (EVENT, SYSTEM, or REPLY).
+    """
+
+    checksum: str
+    raw_telegram: str
+    checksum_validated: Optional[bool] = None
+    timestamp: Optional[datetime] = None
+    telegram_type: TelegramType = TelegramType.EVENT

xp/models/telegram/telegram_type.py

@@ -0,0 +1,19 @@
+"""Telegram type enumeration for console bus communication."""
+
+from enum import Enum
+
+
+class TelegramType(str, Enum):
+    """Enumeration of telegram types in the console bus system.
+
+    Attributes:
+        EVENT: Event telegram (E).
+        REPLY: Reply telegram (R).
+        SYSTEM: System telegram (S).
+        CPEVENT: CP event telegram (O).
+    """
+
+    EVENT = "E"
+    REPLY = "R"
+    SYSTEM = "S"
+    CPEVENT = "O"