conson-xp 1.18.0__py3-none-any.whl

xp/services/telegram/telegram_service.py

@@ -0,0 +1,380 @@
+"""Telegram Service for parsing XP telegrams.
+
+This module provides telegram parsing functionality for event, system, and reply telegrams.
+"""
+
+import logging
+import re
+from typing import Union
+
+from xp.models import EventType
+from xp.models.telegram.datapoint_type import DataPointType
+from xp.models.telegram.event_telegram import EventTelegram
+from xp.models.telegram.output_telegram import OutputTelegram
+from xp.models.telegram.reply_telegram import ReplyTelegram
+from xp.models.telegram.system_function import SystemFunction
+from xp.models.telegram.system_telegram import SystemTelegram
+from xp.models.telegram.telegram_type import TelegramType
+from xp.utils.checksum import calculate_checksum
+
+
+class TelegramParsingError(Exception):
+    """Raised when telegram parsing fails."""
+
+    pass
+
+
+class TelegramService:
+    """Service for parsing event telegrams from the console bus.
+
+    Handles parsing of telegrams in the format:
+    <[EO]{module_type}L{link_number}I{output_number}{event_type}{checksum}>
+
+    Attributes:
+        EVENT_TELEGRAM_PATTERN: Regex pattern for event telegrams.
+        SYSTEM_TELEGRAM_PATTERN: Regex pattern for system telegrams.
+        REPLY_TELEGRAM_PATTERN: Regex pattern for reply telegrams.
+    """
+
+    # <O06L00I07MAG>
+    # <O06L00I07BAJ>
+    # <E13L12I02BAB>
+    EVENT_TELEGRAM_PATTERN = re.compile(
+        r"^<([EO])(\d{1,2})L(\d{2})I(\d{2})([MB])([A-Z0-9]{2})>$"
+    )
+
+    SYSTEM_TELEGRAM_PATTERN = re.compile(r"^<S(\d{10})F(\d{2})D(.{2,})([A-Z0-9]{2})>$")
+
+    REPLY_TELEGRAM_PATTERN = re.compile(r"^<R(\d{10})F(\d{2})(.+?)([A-Z0-9]{2})>$")
+
+    def __init__(self) -> None:
+        """Initialize the telegram service."""
+        # Set up logging
+        self.logger = logging.getLogger(__name__)
+
+    def parse_event_telegram(self, raw_telegram: str) -> EventTelegram:
+        """Parse a raw telegram string into an EventTelegram object.
+
+        Args:
+            raw_telegram: The raw telegram string (e.g., "<E14L00I02MAK>").
+
+        Returns:
+            EventTelegram object with parsed data.
+
+        Raises:
+            TelegramParsingError: If the telegram format is invalid.
+        """
+        if not raw_telegram:
+            raise TelegramParsingError("Empty telegram string")
+
+        # Validate and parse using regex
+        match = self.EVENT_TELEGRAM_PATTERN.match(raw_telegram.strip())
+        if not match:
+            raise TelegramParsingError(f"Invalid telegram format: {raw_telegram}")
+
+        try:
+            event_telegram_type = match.group(1)
+            module_type = int(match.group(2))
+            link_number = int(match.group(3))
+            output_number = int(match.group(4))
+            event_type_char = match.group(5)
+            checksum = match.group(6)
+
+            # Validate ranges
+            if event_telegram_type not in ("E", "O"):
+                raise TelegramParsingError(
+                    f"Event telegram type (E or O): {event_telegram_type}"
+                )
+
+            if not (0 <= link_number <= 99):
+                raise TelegramParsingError(
+                    f"Link number out of range (0-99): {link_number}"
+                )
+
+            if not (0 <= output_number <= 99):
+                raise TelegramParsingError(
+                    f"Input number out of range (0-99): {output_number}"
+                )
+
+            # Parse event type
+            try:
+                event_type = EventType(event_type_char)
+            except ValueError:
+                raise TelegramParsingError(f"Invalid event type: {event_type_char}")
+
+            # Create the telegram object
+            telegram = EventTelegram(
+                module_type=module_type,
+                link_number=link_number,
+                input_number=output_number,
+                event_type=event_type,
+                checksum=checksum,
+                raw_telegram=raw_telegram,
+            )
+
+            # Automatically validate checksum
+            telegram.checksum_validated = self.validate_checksum(telegram)
+
+            return telegram
+
+        except ValueError as e:
+            raise TelegramParsingError(f"Invalid numeric values in telegram: {e}")
+
+    @staticmethod
+    def validate_checksum(
+        telegram: Union[EventTelegram, ReplyTelegram, SystemTelegram, OutputTelegram],
+    ) -> bool:
+        """Validate the checksum of a parsed telegram.
+
+        Args:
+            telegram: The parsed telegram.
+
+        Returns:
+            True if checksum is valid, False otherwise.
+        """
+        if not telegram.checksum or len(telegram.checksum) != 2:
+            return False
+
+        # Extract the data part (everything between < and checksum)
+        raw = telegram.raw_telegram
+        if not raw.startswith("<") or not raw.endswith(">"):
+            return False
+
+        # Get the data part without brackets and checksum
+        data_part = raw[1:-3]  # Remove '<' and last 2 chars (checksum) + '>'
+
+        # Calculate expected checksum
+        expected_checksum = calculate_checksum(data_part)
+
+        return telegram.checksum == expected_checksum
+
+    @staticmethod
+    def format_event_telegram_summary(telegram: EventTelegram) -> str:
+        """Format a telegram for human-readable output.
+
+        Args:
+            telegram: The parsed telegram.
+
+        Returns:
+            Formatted string summary.
+        """
+        checksum_status = ""
+        if telegram.checksum_validated is not None:
+            status_indicator = "✓" if telegram.checksum_validated else "✗"
+            checksum_status = f" ({status_indicator})"
+
+        return (
+            f"Event: {telegram}\n"
+            f"Raw: {telegram.raw_telegram}\n"
+            f"Timestamp: {telegram.timestamp}\n"
+            f"Checksum: {telegram.checksum}{checksum_status}"
+        )
+
+    def parse_system_telegram(self, raw_telegram: str) -> SystemTelegram:
+        """Parse a raw system telegram string into a SystemTelegram object.
+
+        Args:
+            raw_telegram: The raw telegram string (e.g., "<S0020012521F02D18FN>").
+
+        Returns:
+            SystemTelegram object with parsed data.
+
+        Raises:
+            TelegramParsingError: If the telegram format is invalid.
+        """
+        if not raw_telegram:
+            raise TelegramParsingError("Empty telegram string")
+
+        # Validate and parse using regex
+        match = self.SYSTEM_TELEGRAM_PATTERN.match(raw_telegram.strip())
+        if not match:
+            raise TelegramParsingError(
+                f"Invalid system telegram format: {raw_telegram}"
+            )
+
+        try:
+            serial_number = match.group(1)
+            function_code = match.group(2)
+            data = match.group(3)
+            checksum = match.group(4)
+
+            # Parse system function
+            system_function = SystemFunction.from_code(function_code)
+            if system_function is None:
+                raise TelegramParsingError(
+                    f"Unknown system function code: {function_code}"
+                )
+
+            # Parse data point type
+            datapoint_type = None
+            if system_function == SystemFunction.READ_DATAPOINT:
+                datapoint_type = DataPointType.from_code(data)
+
+            # Create the telegram object
+            telegram = SystemTelegram(
+                serial_number=serial_number,
+                system_function=system_function,
+                data=data,
+                datapoint_type=datapoint_type,
+                checksum=checksum,
+                raw_telegram=raw_telegram,
+            )
+
+            # Automatically validate checksum
+            telegram.checksum_validated = self.validate_checksum(telegram)
+
+            return telegram
+
+        except ValueError as e:
+            raise TelegramParsingError(f"Invalid values in system telegram: {e}")
+
+    def parse_reply_telegram(self, raw_telegram: str) -> ReplyTelegram:
+        """Parse a raw reply telegram string into a ReplyTelegram object.
+
+        Args:
+            raw_telegram: The raw telegram string (e.g., "<R0020012521F02D18+26,0§CIL>").
+
+        Returns:
+            ReplyTelegram object with parsed data.
+
+        Raises:
+            TelegramParsingError: If the telegram format is invalid.
+        """
+        if not raw_telegram:
+            raise TelegramParsingError("Empty telegram string")
+
+        # Validate and parse using regex
+        self.logger.debug(f"Parsing reply telegram {raw_telegram}")
+        match = self.REPLY_TELEGRAM_PATTERN.match(raw_telegram.strip())
+        if not match:
+            raise TelegramParsingError(f"Invalid reply telegram format: {raw_telegram}")
+
+        try:
+            serial_number = match.group(1)
+            function_code = match.group(2)
+            full_data_value = match.group(3)
+            checksum = match.group(4)
+
+            # Parse system function
+            system_function = SystemFunction.from_code(function_code)
+            if system_function is None:
+                raise TelegramParsingError(
+                    f"Unknown system function code: {function_code}"
+                )
+
+            # Parse data point and data value from full_data_value
+            if full_data_value.startswith("D") and len(full_data_value) >= 3:
+                # Regular reply format: D{data_point}{data}
+                data = full_data_value[1:3]
+                data_value = full_data_value[3:] if len(full_data_value) > 3 else ""
+            else:
+                # ACK/NAK format: just data (like "D" for ACK/NAK)
+                data = "00"  # Default to STATUS
+                data_value = full_data_value
+
+            # Parse data point type
+            data_point_type = DataPointType.from_code(data)
+
+            # Create the telegram object
+            telegram = ReplyTelegram(
+                serial_number=serial_number,
+                system_function=system_function,
+                data=data,
+                datapoint_type=data_point_type,
+                data_value=data_value,
+                checksum=checksum,
+                raw_telegram=raw_telegram,
+            )
+
+            # Automatically validate checksum
+            telegram.checksum_validated = self.validate_checksum(telegram)
+
+            return telegram
+
+        except ValueError as e:
+            raise TelegramParsingError(f"Invalid values in reply telegram: {e}")
+
+    def parse_telegram(
+        self, raw_telegram: str
+    ) -> Union[EventTelegram, SystemTelegram, ReplyTelegram]:
+        """Auto-detect and parse any type of telegram.
+
+        Args:
+            raw_telegram: The raw telegram string.
+
+        Returns:
+            Appropriate telegram object based on type.
+
+        Raises:
+            TelegramParsingError: If the telegram format is invalid or unknown.
+        """
+        if not raw_telegram:
+            raise TelegramParsingError("Empty telegram string")
+
+        # Then check general telegram types
+        telegram_type_code = (
+            raw_telegram.strip()[1] if len(raw_telegram.strip()) > 1 else ""
+        )
+
+        if telegram_type_code in (TelegramType.EVENT.value, TelegramType.CPEVENT.value):
+            return self.parse_event_telegram(raw_telegram)
+        elif telegram_type_code == TelegramType.SYSTEM.value:
+            return self.parse_system_telegram(raw_telegram)
+        elif telegram_type_code == TelegramType.REPLY.value:
+            return self.parse_reply_telegram(raw_telegram)
+        else:
+            raise TelegramParsingError(
+                f"Unknown telegram type code: {telegram_type_code}"
+            )
+
+    @staticmethod
+    def format_system_telegram_summary(telegram: SystemTelegram) -> str:
+        """Format a system telegram for human-readable output.
+
+        Args:
+            telegram: The parsed system telegram.
+
+        Returns:
+            Formatted string summary.
+        """
+        checksum_status = ""
+        if telegram.checksum_validated is not None:
+            status_indicator = "✓" if telegram.checksum_validated else "✗"
+            checksum_status = f" ({status_indicator})"
+
+        return (
+            f"System: {telegram}\n"
+            f"Raw: {telegram.raw_telegram}\n"
+            f"Timestamp: {telegram.timestamp}\n"
+            f"Checksum: {telegram.checksum}{checksum_status}"
+        )
+
+    @staticmethod
+    def format_reply_telegram_summary(telegram: ReplyTelegram) -> str:
+        """Format a reply telegram for human-readable output.
+
+        Args:
+            telegram: The parsed reply telegram.
+
+        Returns:
+            Formatted string summary.
+        """
+        parsed_data = telegram.parse_datapoint_value
+        data_display = (
+            parsed_data.get("formatted", telegram.data_value)
+            if parsed_data.get("parsed")
+            else telegram.data_value
+        )
+
+        checksum_status = ""
+        if telegram.checksum_validated is not None:
+            status_indicator = "✓" if telegram.checksum_validated else "✗"
+            checksum_status = f" ({status_indicator})"
+
+        return (
+            f"Reply: {telegram}\n"
+            f"Data: {data_display}\n"
+            f"Raw: {telegram.raw_telegram}\n"
+            f"Timestamp: {telegram.timestamp}\n"
+            f"Checksum: {telegram.checksum}{checksum_status}"
+        )

xp/services/telegram/telegram_version_service.py

@@ -0,0 +1,288 @@
+"""Version service for handling version information parsing and validation.
+
+This service provides business logic for version operations,
+following the layered architecture pattern.
+"""
+
+import re
+
+from xp.models.response import Response
+from xp.models.telegram.datapoint_type import DataPointType
+from xp.models.telegram.reply_telegram import ReplyTelegram
+from xp.models.telegram.system_function import SystemFunction
+from xp.models.telegram.system_telegram import SystemTelegram
+from xp.utils.checksum import calculate_checksum
+
+
+class VersionParsingError(Exception):
+    """Raised when version parsing fails."""
+
+    pass
+
+
+class VersionService:
+    """Service class for version-related operations."""
+
+    def __init__(self) -> None:
+        """Initialize the version service."""
+        pass
+
+    @staticmethod
+    def parse_version_string(version_string: str) -> Response:
+        """Parse a version string into its components.
+
+        Args:
+            version_string: Version string in format 'XP230_V1.00.04'
+
+        Returns:
+            Response object with 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 version_string:
+                parts = version_string.split("_V", 1)
+                if len(parts) == 2:
+                    product = parts[0]
+                    version = parts[1]
+
+                    # Validate version format (should be like 1.00.04)
+                    version_pattern = re.compile(r"^\d+\.\d+\.\d+$")
+                    if version_pattern.match(version):
+                        return Response(
+                            success=True,
+                            data={
+                                "product": product,
+                                "version": version,
+                                "full_version": version_string,
+                                "formatted": f"{product} v{version}",
+                                "raw_value": version_string,
+                                "valid_format": True,
+                            },
+                            error=None,
+                        )
+                    else:
+                        return Response(
+                            success=True,
+                            data={
+                                "product": product,
+                                "version": version,
+                                "full_version": version_string,
+                                "formatted": f"{product} v{version}",
+                                "raw_value": version_string,
+                                "valid_format": False,
+                                "warning": "Version format doesn't match expected pattern x.xx.xx",
+                            },
+                            error=None,
+                        )
+
+            # If format doesn't match expected pattern
+            return Response(
+                success=False,
+                data={"raw_value": version_string, "valid_format": False},
+                error="Version format not recognized. Expected format: PRODUCT_Vx.xx.xx",
+            )
+
+        except Exception as e:
+            return Response(
+                success=False, data=None, error=f"Version parsing failed: {e}"
+            )
+
+    @staticmethod
+    def generate_version_request_telegram(serial_number: str) -> Response:
+        """Generate a system telegram to request version information.
+
+        Args:
+            serial_number: 10-digit serial number of the device
+
+        Returns:
+            Response object with generated telegram
+        """
+        try:
+            if len(serial_number) != 10 or not serial_number.isdigit():
+                return Response(
+                    success=False,
+                    data=None,
+                    error="Serial number must be exactly 10 digits",
+                )
+
+            # Build telegram: S{serial_number}F{function}D{data_point}
+            # Function 02 = Read Data point, Data Point 02 = Version
+            data_part = f"S{serial_number}F02D02"
+
+            # Calculate checksum
+            checksum = calculate_checksum(data_part)
+
+            # Complete telegram
+            telegram = f"<{data_part}{checksum}>"
+
+            return Response(
+                success=True,
+                data={
+                    "telegram": telegram,
+                    "serial_number": serial_number,
+                    "function_code": "02",
+                    "datapoint_code": "02",
+                    "checksum": checksum,
+                    "operation": "version_request",
+                },
+                error=None,
+            )
+
+        except Exception as e:
+            return Response(
+                success=False,
+                data=None,
+                error=f"Version request telegram generation failed: {e}",
+            )
+
+    @staticmethod
+    def validate_version_telegram(telegram: SystemTelegram) -> Response:
+        """Validate if a system telegram is a valid version request.
+
+        Args:
+            telegram: Parsed system telegram
+
+        Returns:
+            Response object with validation result
+        """
+        try:
+            is_version_request = (
+                telegram.system_function == SystemFunction.READ_DATAPOINT
+                and telegram.datapoint_type == DataPointType.SW_VERSION
+            )
+
+            return Response(
+                success=True,
+                data={
+                    "is_version_request": is_version_request,
+                    "serial_number": telegram.serial_number,
+                    "function": (
+                        telegram.system_function.value
+                        if telegram.system_function
+                        else None
+                    ),
+                    "data_point": (
+                        telegram.datapoint_type.value
+                        if telegram.datapoint_type
+                        else None
+                    ),
+                    "function_description": (
+                        telegram.system_function.name
+                        if telegram.system_function
+                        else None
+                    ),
+                    "data_point_description": (
+                        telegram.datapoint_type.name
+                        if telegram.datapoint_type
+                        else None
+                    ),
+                },
+                error=None,
+            )
+
+        except Exception as e:
+            return Response(
+                success=False,
+                data=None,
+                error=f"Version telegram validation failed: {e}",
+            )
+
+    @staticmethod
+    def parse_version_reply(telegram: ReplyTelegram) -> Response:
+        """Parse version information from a reply telegram.
+
+        Args:
+            telegram: Parsed reply telegram containing version data
+
+        Returns:
+            Response object with version information
+        """
+        try:
+            # Check if this is a version reply
+            if telegram.datapoint_type != DataPointType.SW_VERSION:
+                return Response(
+                    success=False,
+                    data=None,
+                    error=f"Not a version reply telegram. "
+                    f"Data point: "
+                    f"{telegram.datapoint_type.name if telegram.datapoint_type else 'Unknown'}",
+                )
+
+            # Parse the version using the telegram's built-in parser
+            parsed_data = telegram.parse_datapoint_value
+
+            if parsed_data.get("parsed", False):
+                return Response(
+                    success=True,
+                    data={
+                        "serial_number": telegram.serial_number,
+                        "version_info": parsed_data,
+                        "checksum_valid": telegram.checksum_validated,
+                        "raw_telegram": telegram.raw_telegram,
+                    },
+                    error=None,
+                )
+            else:
+                return Response(
+                    success=False,
+                    data={
+                        "serial_number": telegram.serial_number,
+                        "raw_value": telegram.data_value,
+                        "checksum_valid": telegram.checksum_validated,
+                        "raw_telegram": telegram.raw_telegram,
+                    },
+                    error=parsed_data.get(
+                        "error", "Failed to parse version information"
+                    ),
+                )
+
+        except Exception as e:
+            return Response(
+                success=False,
+                data=None,
+                error=f"Version reply parsing failed: {e}",
+            )
+
+    @staticmethod
+    def format_version_summary(version_data: dict) -> str:
+        """Format version information for human-readable output.
+
+        Args:
+            version_data: Version information dictionary
+
+        Returns:
+            Formatted string summary
+        """
+        try:
+            if "version_info" in version_data:
+                version_info = version_data["version_info"]
+                serial = version_data.get("serial_number", "Unknown")
+
+                if version_info.get("parsed", False):
+                    product = version_info.get("product", "Unknown")
+                    version = version_info.get("version", "Unknown")
+
+                    summary = "Device Version Information:\n"
+                    summary += f"Serial Number: {serial}\n"
+                    summary += f"Product: {product}\n"
+                    summary += f"Version: {version}\n"
+                    summary += (
+                        f"Full Version: {version_info.get('full_version', 'Unknown')}\n"
+                    )
+
+                    checksum_status = ""
+                    if "checksum_valid" in version_data:
+                        status = "✓" if version_data["checksum_valid"] else "✗"
+                        checksum_status = f" ({status})"
+
+                    summary += f"Checksum: Valid{checksum_status}"
+
+                    return summary
+                else:
+                    return f"Version parsing failed for device {serial}: {version_info.get('error', 'Unknown error')}"
+            else:
+                return "No version information available"
+
+        except Exception as e:
+            return f"Error formatting version summary: {e}"

xp/utils/__init__.py

@@ -0,0 +1,12 @@
+"""Utility functions for XP CLI tool."""
+
+from xp.utils.checksum import calculate_checksum
+from xp.utils.event_helper import get_first_response
+from xp.utils.time_utils import TimeParsingError, parse_log_timestamp
+
+__all__ = [
+    "calculate_checksum",
+    "parse_log_timestamp",
+    "TimeParsingError",
+    "get_first_response",
+]