conson-xp 1.18.0__py3-none-any.whl

xp/services/telegram/telegram_link_number_service.py

@@ -0,0 +1,216 @@
+"""Service for link number telegram operations.
+
+This service handles generation and parsing of link number system telegrams
+used for setting and reading module link numbers.
+"""
+
+from contextlib import suppress
+from typing import Optional
+
+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 LinkNumberError(Exception):
+    """Raised when link number operations fail."""
+
+    pass
+
+
+class LinkNumberService:
+    """
+    Service for generating and handling link number system telegrams.
+
+    Handles telegrams for setting module link numbers using the F04D04 format:
+    <S{serial_number}F04D04{link_number}{checksum}>
+    """
+
+    def __init__(self) -> None:
+        """Initialize the link number service."""
+        pass
+
+    @staticmethod
+    def generate_set_link_number_telegram(serial_number: str, link_number: int) -> str:
+        """Generate a telegram to set a module's link number.
+
+        Args:
+            serial_number: The 10-digit module serial number.
+            link_number: The link number to set (0-99).
+
+        Returns:
+            Formatted telegram string (e.g., "<S0012345005F04D0425FO>").
+
+        Raises:
+            LinkNumberError: If parameters are invalid.
+        """
+        # Validate serial number
+        if not serial_number or len(serial_number) != 10:
+            raise LinkNumberError(
+                f"Serial number must be 10 digits, got: {serial_number}"
+            )
+
+        if not serial_number.isdigit():
+            raise LinkNumberError(
+                f"Serial number must contain only digits: {serial_number}"
+            )
+
+        # Validate link number range
+        if not (0 <= link_number <= 99):
+            raise LinkNumberError(
+                f"Link number must be between 0-99, got: {link_number}"
+            )
+
+        # Format link number with leading zero if needed
+        link_number_str = f"{link_number:02d}"
+
+        # Build the data part of the telegram
+        data_part = f"S{serial_number}F04D04{link_number_str}"
+
+        # Calculate checksum
+        checksum = calculate_checksum(data_part)
+
+        # Build complete telegram
+        telegram = f"<{data_part}{checksum}>"
+
+        return telegram
+
+    @staticmethod
+    def generate_read_link_number_telegram(serial_number: str) -> str:
+        """Generate a telegram to read a module's current link number.
+
+        Args:
+            serial_number: The 10-digit module serial number.
+
+        Returns:
+            Formatted telegram string for reading link number.
+
+        Raises:
+            LinkNumberError: If serial number is invalid.
+        """
+        # Validate serial number
+        if not serial_number or len(serial_number) != 10:
+            raise LinkNumberError(
+                f"Serial number must be 10 digits, got: {serial_number}"
+            )
+
+        if not serial_number.isdigit():
+            raise LinkNumberError(
+                f"Serial number must contain only digits: {serial_number}"
+            )
+
+        # Build the data part for reading (F03D04 - READ_CONFIG, LINK_NUMBER)
+        data_part = f"S{serial_number}F03D04"
+
+        # Calculate checksum
+        checksum = calculate_checksum(data_part)
+
+        # Build complete telegram
+        telegram = f"<{data_part}{checksum}>"
+
+        return telegram
+
+    def create_set_link_number_telegram_object(
+        self, serial_number: str, link_number: int
+    ) -> SystemTelegram:
+        """Create a SystemTelegram object for setting link number.
+
+        Args:
+            serial_number: The 10-digit module serial number.
+            link_number: The link number to set (0-99).
+
+        Returns:
+            SystemTelegram object representing the set link number command.
+        """
+        raw_telegram = self.generate_set_link_number_telegram(
+            serial_number, link_number
+        )
+
+        # Extract checksum from the generated telegram
+        checksum = raw_telegram[-3:-1]  # Get checksum before closing >
+
+        telegram = SystemTelegram(
+            serial_number=serial_number,
+            system_function=SystemFunction.WRITE_CONFIG,
+            datapoint_type=DataPointType.LINK_NUMBER,
+            checksum=checksum,
+            raw_telegram=raw_telegram,
+        )
+
+        return telegram
+
+    def create_read_link_number_telegram_object(
+        self, serial_number: str
+    ) -> SystemTelegram:
+        """Create a SystemTelegram object for reading link number.
+
+        Args:
+            serial_number: The 10-digit module serial number.
+
+        Returns:
+            SystemTelegram object representing the read link number command.
+        """
+        raw_telegram = self.generate_read_link_number_telegram(serial_number)
+
+        # Extract checksum from the generated telegram
+        checksum = raw_telegram[-3:-1]  # Get checksum before closing >
+
+        telegram = SystemTelegram(
+            serial_number=serial_number,
+            system_function=SystemFunction.READ_CONFIG,
+            datapoint_type=DataPointType.LINK_NUMBER,
+            checksum=checksum,
+            raw_telegram=raw_telegram,
+        )
+
+        return telegram
+
+    @staticmethod
+    def parse_link_number_from_reply(reply_telegram: ReplyTelegram) -> Optional[int]:
+        """Parse the link number value from a reply telegram.
+
+        Args:
+            reply_telegram: Reply telegram containing link number data.
+
+        Returns:
+            Link number if successfully parsed, None otherwise.
+        """
+        if (
+            reply_telegram.datapoint_type != DataPointType.LINK_NUMBER
+            or not reply_telegram.data_value
+        ):
+            return None
+
+        with suppress(ValueError, TypeError):
+            # The data value should contain the link number
+            link_number = int(reply_telegram.data_value)
+            if 0 <= link_number <= 99:
+                return link_number
+
+        return None
+
+    @staticmethod
+    def is_ack_response(reply_telegram: ReplyTelegram) -> bool:
+        """Check if a reply telegram is an ACK response.
+
+        Args:
+            reply_telegram: Reply telegram to check.
+
+        Returns:
+            True if this is an ACK response (F18D), False otherwise.
+        """
+        return reply_telegram.system_function == SystemFunction.ACK
+
+    @staticmethod
+    def is_nak_response(reply_telegram: ReplyTelegram) -> bool:
+        """Check if a reply telegram is a NAK response.
+
+        Args:
+            reply_telegram: Reply telegram to check.
+
+        Returns:
+            True if this is a NAK response (F19D), False otherwise.
+        """
+        return reply_telegram.system_function == SystemFunction.NAK

xp/services/telegram/telegram_output_service.py

@@ -0,0 +1,322 @@
+"""XP output service for handling XP output device operations."""
+
+import re
+from typing import Dict
+
+from xp.models.telegram.action_type import ActionType
+from xp.models.telegram.datapoint_type import DataPointType
+from xp.models.telegram.output_telegram import OutputTelegram
+from xp.models.telegram.system_function import SystemFunction
+from xp.services.telegram.telegram_service import TelegramService
+from xp.utils.checksum import calculate_checksum
+
+
+class XPOutputError(Exception):
+    """Raised when XP24 action operations fail."""
+
+    pass
+
+
+class TelegramOutputService:
+    """Service for XP action operations.
+
+    Handles parsing and validation of XP24 action telegrams,
+    status queries, and action command generation.
+
+    Attributes:
+        MAX_OUTPUTS: Maximum number of outputs supported.
+        XP_OUTPUT_PATTERN: Regex pattern for XP24 action telegrams.
+        XP_ACK_NAK_PATTERN: Regex pattern for ACK/NAK response telegrams.
+        telegram_service: TelegramService instance for parsing.
+    """
+
+    MAX_OUTPUTS = 99
+
+    # Regex pattern for XP24 action telegrams
+    XP_OUTPUT_PATTERN = re.compile(r"^<S(\d{10})F27D(\d{2})(A[AB])([A-Z0-9]{2})>$")
+    XP_ACK_NAK_PATTERN = re.compile(r"^<R(\d{10})F(1[89])D([A-Z0-9]{2})>$")
+
+    def __init__(self, telegram_service: TelegramService) -> None:
+        """Initialize the XP output service.
+
+        Args:
+            telegram_service: TelegramService instance for parsing operations.
+        """
+        self.telegram_service = telegram_service
+
+    def validate_output_number(self, output_number: int) -> None:
+        """Validate XP24 output number according to architecture constraints.
+
+        Args:
+            output_number: Output number to validate (0-3).
+
+        Raises:
+            XPOutputError: If output number is invalid.
+        """
+        if not isinstance(output_number, int):
+            raise XPOutputError(
+                f"Output number must be integer, got {type(output_number)}"
+            )
+
+        if not (0 <= output_number <= self.MAX_OUTPUTS):
+            raise XPOutputError(
+                f"Invalid output number: {output_number}. "
+                f"XP24 supports outputs 0-{self.MAX_OUTPUTS}"
+            )
+
+    @staticmethod
+    def validate_serial_number(serial_number: str) -> None:
+        """Validate serial number format.
+
+        Args:
+            serial_number: Serial number to validate.
+
+        Raises:
+            XPOutputError: If serial number is invalid.
+        """
+        if not isinstance(serial_number, str):
+            raise XPOutputError(
+                f"Serial number must be string, got {type(serial_number)}"
+            )
+
+        if len(serial_number) != 10 or not serial_number.isdigit():
+            raise XPOutputError(
+                f"Invalid serial number: {serial_number}. "
+                "Serial number must be exactly 10 digits"
+            )
+
+    def generate_system_action_telegram(
+        self, serial_number: str, output_number: int, action: ActionType
+    ) -> str:
+        """Generate XP24 action telegram string.
+
+        Args:
+            serial_number: Target module serial number.
+            output_number: Output number (0-3).
+            action: Action type (PRESS/RELEASE).
+
+        Returns:
+            Complete telegram string with checksum.
+
+        Raises:
+            XPOutputError: If parameters are invalid.
+        """
+        # Validate outputs according to architecture constraints
+        self.validate_serial_number(serial_number)
+        self.validate_output_number(output_number)
+
+        if not isinstance(action, ActionType):
+            raise XPOutputError(f"Invalid action type: {action}")
+
+        function_code = SystemFunction.ACTION.value
+        # Build data part without checksum
+        data_part = (
+            f"S{serial_number}F{function_code}D{output_number:02d}{action.value}"
+        )
+
+        # Calculate checksum
+        checksum = calculate_checksum(data_part)
+
+        # Return complete telegram
+        return f"<{data_part}{checksum}>"
+
+    def generate_system_status_telegram(self, serial_number: str) -> str:
+        """Generate XP output status query telegram.
+
+        Args:
+            serial_number: Target module serial number.
+
+        Returns:
+            Complete status query telegram string.
+        """
+        # Validate outputs
+        self.validate_serial_number(serial_number)
+        function_code = SystemFunction.READ_DATAPOINT.value
+        datapoint_code = DataPointType.MODULE_OUTPUT_STATE.value
+
+        # Build data part without checksum
+        data_part = f"S{serial_number}F{function_code}D{datapoint_code}"
+
+        # Calculate checksum
+        checksum = calculate_checksum(data_part)
+
+        # Return complete telegram
+        return f"<{data_part}{checksum}>"
+
+    def parse_reply_telegram(self, raw_telegram: str) -> OutputTelegram:
+        """Parse a raw XP output response telegram string.
+
+        Args:
+            raw_telegram: The raw telegram string (e.g., "<R0012345003F18DFF>").
+
+        Returns:
+            XPOutputTelegram object with parsed data.
+
+        Raises:
+            XPOutputError: If telegram format is invalid.
+        """
+        if not raw_telegram:
+            raise XPOutputError("Empty telegram string")
+
+        # Validate and parse using regex
+        match = self.XP_ACK_NAK_PATTERN.match(raw_telegram.strip())
+        if not match:
+            raise XPOutputError(
+                f"Invalid XP24 response telegram format: {raw_telegram}"
+            )
+
+        try:
+            serial_number = match.group(1)
+            ack_nak = match.group(2)
+            checksum = match.group(3)
+
+            # Parse action type
+            system_function = SystemFunction.from_code(ack_nak)
+            if system_function is None:
+                raise XPOutputError(f"Unknown system_function: {ack_nak}")
+
+            # Create telegram object
+            telegram = OutputTelegram(
+                serial_number=serial_number,
+                system_function=system_function,
+                checksum=checksum,
+                raw_telegram=raw_telegram,
+            )
+
+            # Validate checksum
+            telegram.checksum_validated = self.telegram_service.validate_checksum(
+                telegram
+            )
+
+            return telegram
+
+        except ValueError as e:
+            raise XPOutputError(f"Invalid values in XP24 action telegram: {e}")
+
+    def parse_system_telegram(self, raw_telegram: str) -> OutputTelegram:
+        """Parse a raw XP output telegram string.
+
+        Args:
+            raw_telegram: The raw telegram string (e.g., "<S0012345008F27D00AAFN>").
+
+        Returns:
+            XPOutputTelegram object with parsed data.
+
+        Raises:
+            XPOutputError: If telegram format is invalid.
+        """
+        if not raw_telegram:
+            raise XPOutputError("Empty telegram string")
+
+        # Validate and parse using regex
+        match = self.XP_OUTPUT_PATTERN.match(raw_telegram.strip())
+        if not match:
+            raise XPOutputError(f"Invalid XP24 action telegram format: {raw_telegram}")
+
+        try:
+            serial_number = match.group(1)
+            output_number = int(match.group(2))
+            action_code = match.group(3)
+            checksum = match.group(4)
+
+            # Validate output number
+            self.validate_output_number(output_number)
+
+            # Parse action type
+            action_type = ActionType.from_code(action_code)
+            if action_type is None:
+                raise XPOutputError(f"Unknown action code: {action_code}")
+
+            # Create telegram object
+            telegram = OutputTelegram(
+                serial_number=serial_number,
+                output_number=output_number,
+                action_type=action_type,
+                checksum=checksum,
+                raw_telegram=raw_telegram,
+            )
+
+            # Validate checksum
+            telegram.checksum_validated = self.telegram_service.validate_checksum(
+                telegram
+            )
+
+            return telegram
+
+        except ValueError as e:
+            raise XPOutputError(f"Invalid values in XP24 action telegram: {e}")
+
+    def parse_status_response(self, raw_telegram: str) -> list[bool]:
+        """Parse XP24 status response telegram to extract output states.
+
+        Args:
+            raw_telegram: Raw reply telegram (e.g., "<R0012345008F02D12xxxx1110FJ>").
+
+        Returns:
+            Dictionary mapping output numbers (0-3) to their states (True=ON, False=OFF).
+
+        Raises:
+            XPOutputError: If output telegram is invalid.
+        """
+        if not raw_telegram:
+            raise XPOutputError("Empty status response telegram")
+
+        # Look for status pattern in reply telegram
+        reply_telegram = self.telegram_service.parse_reply_telegram(raw_telegram)
+        if not reply_telegram or not reply_telegram.data_value:
+            raise XPOutputError("Not a reply telegram")
+
+        if (
+            not reply_telegram.datapoint_type
+            or not reply_telegram.datapoint_type == DataPointType.MODULE_OUTPUT_STATE
+        ):
+            raise XPOutputError("Not a DataPoint telegram")
+
+        status_bits = reply_telegram.data_value.replace("xxxx", "")[::-1][0:4]
+        if len(status_bits) != 4:
+            raise XPOutputError("Not a module_output_state telegram")
+
+        status = [False, False, False, False]
+        for i in range(4):
+            status[i] = status_bits[i] == "1"
+
+        return status
+
+    @staticmethod
+    def format_status_summary(status: Dict[int, bool]) -> str:
+        """Format status dictionary into human-readable summary.
+
+        Args:
+            status: Dictionary mapping output numbers to states.
+
+        Returns:
+            Formatted status summary string.
+        """
+        lines = ["XP24 Output Status:"]
+        for output_num in sorted(status.keys()):
+            state = "ON" if status[output_num] else "OFF"
+            lines.append(f"  Output {output_num}: {state}")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def format_action_summary(telegram: OutputTelegram) -> str:
+        """Format XP24 action telegram for human-readable output.
+
+        Args:
+            telegram: The parsed action 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"XP Output: {telegram}\n"
+            f"Raw: {telegram.raw_telegram}\n"
+            f"Timestamp: {telegram.timestamp}\n"
+            f"Checksum: {telegram.checksum}{checksum_status}"
+        )