conson-xp 1.18.0__py3-none-any.whl

xp/services/telegram/telegram_checksum_service.py

@@ -0,0 +1,149 @@
+"""Checksum service for telegram protocol validation and generation.
+
+This service provides business logic for checksum operations,
+following the layered architecture pattern.
+"""
+
+from typing import Union
+
+from xp.models.response import Response
+from xp.utils.checksum import calculate_checksum, calculate_checksum32
+
+
+class TelegramChecksumService:
+    """Service class for checksum operations."""
+
+    def __init__(self) -> None:
+        """Initialize the checksum service."""
+        pass
+
+    @staticmethod
+    def calculate_simple_checksum(data: str) -> Response:
+        """Calculate simple XOR checksum for string data.
+
+        Args:
+            data: String data to calculate checksum for.
+
+        Returns:
+            Response object with checksum result.
+        """
+        try:
+            checksum = calculate_checksum(data)
+
+            return Response(
+                success=True,
+                data={"input": data, "checksum": checksum, "algorithm": "simple_xor"},
+                error=None,
+            )
+        except Exception as e:
+            return Response(
+                success=False, data=None, error=f"Checksum calculation failed: {e}"
+            )
+
+    @staticmethod
+    def calculate_crc32_checksum(data: Union[str, bytes]) -> Response:
+        """Calculate CRC32 checksum for data.
+
+        Args:
+            data: String or bytes data to calculate checksum for.
+
+        Returns:
+            Response object with checksum result.
+        """
+        try:
+            # Convert string to bytes if needed
+            if isinstance(data, str):
+                byte_data = data.encode("utf-8")
+            else:  # isinstance(data, bytes)
+                byte_data = data
+
+            checksum = calculate_checksum32(byte_data)
+
+            return Response(
+                success=True,
+                data={
+                    "input": data,
+                    "input_type": "string" if isinstance(data, str) else "bytes",
+                    "input_length": len(byte_data),
+                    "checksum": checksum,
+                    "algorithm": "crc32",
+                },
+                error=None,
+            )
+        except Exception as e:
+            return Response(
+                success=False,
+                data=None,
+                error=f"CRC32 checksum calculation failed: {e}",
+            )
+
+    @staticmethod
+    def validate_checksum(data: str, expected_checksum: str) -> Response:
+        """Validate data against expected simple checksum.
+
+        Args:
+            data: Original data.
+            expected_checksum: Expected checksum value.
+
+        Returns:
+            Response object with validation result.
+        """
+        try:
+            calculated_checksum = calculate_checksum(data)
+            is_valid = calculated_checksum == expected_checksum
+
+            return Response(
+                success=True,
+                data={
+                    "input": data,
+                    "calculated_checksum": calculated_checksum,
+                    "expected_checksum": expected_checksum,
+                    "is_valid": is_valid,
+                },
+                error=None,
+            )
+        except Exception as e:
+            return Response(
+                success=False, data=None, error=f"Checksum validation failed: {e}"
+            )
+
+    @staticmethod
+    def validate_crc32_checksum(
+        data: Union[str, bytes], expected_checksum: str
+    ) -> Response:
+        """Validate data against expected CRC32 checksum.
+
+        Args:
+            data: Original data (string or bytes).
+            expected_checksum: Expected CRC32 checksum value.
+
+        Returns:
+            Response object with validation result.
+        """
+        try:
+            # Convert string to bytes if needed
+            if isinstance(data, str):
+                byte_data = data.encode("utf-8")
+            else:  # isinstance(data, bytes)
+                byte_data = data
+
+            calculated_checksum = calculate_checksum32(byte_data)
+            is_valid = calculated_checksum == expected_checksum
+
+            return Response(
+                success=True,
+                data={
+                    "input_type": "string" if isinstance(data, str) else "bytes",
+                    "input_length": len(byte_data),
+                    "calculated_checksum": calculated_checksum,
+                    "expected_checksum": expected_checksum,
+                    "is_valid": is_valid,
+                },
+                error=None,
+            )
+        except Exception as e:
+            return Response(
+                success=False,
+                data=None,
+                error=f"CRC32 checksum validation failed: {e}",
+            )

xp/services/telegram/telegram_datapoint_service.py

@@ -0,0 +1,82 @@
+"""Service for processing Telegram protocol datapoint values."""
+
+
+class TelegramDatapointService:
+    """Service for processing Telegram protocol datapoint values.
+
+    Provides methods to parse and extract values from different types of
+    Telegram datapoints including autoreport status, light level outputs,
+    and link number values.
+    """
+
+    def get_autoreport_status(self, data_value: str) -> bool:
+        """Get the autoreport status value.
+
+        Args:
+            data_value: The raw autoreport status data value (PP or AA).
+
+        Returns:
+            The autoreport status: Enable (True) or disable (False).
+        """
+        status_value = True if data_value == "PP" else False
+        return status_value
+
+    def get_autoreport_status_data_value(self, status_value: bool) -> str:
+        """Get the autoreport status data_value.
+
+        Args:
+            status_value: Enable (True) or disable (False).
+
+        Returns:
+            data_value: The raw autoreport status data value (PP or AA).
+        """
+        data_value = "PP" if status_value else "AA"
+        return data_value
+
+    def get_lightlevel(self, data_value: str, output_number: int) -> int:
+        """Extract the light level for a specific output number.
+
+        Parses comma-separated output data in the format "output:level[%]"
+        and returns the level for the requested output number.
+
+        Args:
+            data_value: Comma-separated string of output:level pairs
+                       (e.g., "1:50[%],2:75[%]").
+            output_number: The output number to get the level for.
+
+        Returns:
+            The light level as an integer (0 if output not found).
+        """
+        level = 0
+        for output_data in data_value.split(","):
+            if ":" in output_data:
+                output_str, level_str = output_data.split(":")
+                if int(output_str) == output_number:
+                    level_str = level_str.replace("[%]", "")
+                    level = int(level_str)
+                    break
+        return level
+
+    def get_linknumber(self, data_value: str) -> int:
+        """Parse and return the link number value.
+
+        Args:
+            data_value: The raw link number data value as a string.
+
+        Returns:
+            The link number as an integer.
+        """
+        link_number_value = int(data_value)
+        return link_number_value
+
+    def get_modulenumber(self, data_value: str) -> int:
+        """Parse and return the module number value.
+
+        Args:
+            data_value: The raw module number data value as a string.
+
+        Returns:
+            The module number as an integer.
+        """
+        module_number_value = int(data_value)
+        return module_number_value

xp/services/telegram/telegram_discover_service.py

@@ -0,0 +1,277 @@
+"""Service for device discover telegram operations.
+
+This service handles generation and parsing of device discover system telegrams
+used for enumerating all connected devices on the console bus.
+"""
+
+from typing import List, Set
+
+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 DiscoverError(Exception):
+    """Raised when discover operations fail."""
+
+    pass
+
+
+class DeviceInfo:
+    """Information about a discovered device."""
+
+    def __init__(
+        self, serial_number: str, checksum_valid: bool = True, raw_telegram: str = ""
+    ):
+        """Initialize device info.
+
+        Args:
+            serial_number: 10-digit module serial number.
+            checksum_valid: Whether the telegram checksum is valid.
+            raw_telegram: Raw telegram string.
+        """
+        self.serial_number = serial_number
+        self.checksum_valid = checksum_valid
+        self.raw_telegram = raw_telegram
+
+    def __str__(self) -> str:
+        """Return string representation of device.
+
+        Returns:
+            String with serial number and checksum status.
+        """
+        status = "✓" if self.checksum_valid else "✗"
+        return f"Device {self.serial_number} ({status})"
+
+    def __repr__(self) -> str:
+        """Return repr representation of device.
+
+        Returns:
+            DeviceInfo constructor representation.
+        """
+        return f"DeviceInfo(serial='{self.serial_number}', checksum_valid={self.checksum_valid})"
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary with device information.
+        """
+        return {
+            "serial_number": self.serial_number,
+            "checksum_valid": self.checksum_valid,
+            "raw_telegram": self.raw_telegram,
+        }
+
+
+class TelegramDiscoverService:
+    """
+    Service for generating and handling device discover telegrams.
+
+    Handles discover broadcasting and response parsing:
+    - Discover request: <S0000000000F01D00{checksum}>
+    - Discover responses: <R{serial}F01D{checksum}>
+    """
+
+    def __init__(self) -> None:
+        """Initialize the discover service."""
+        pass
+
+    @staticmethod
+    def generate_discover_telegram() -> str:
+        """
+        Generate a broadcast discover telegram to enumerate all devices.
+
+        Returns:
+            Formatted discover telegram string: "<S0000000000F01D00FA>"
+        """
+        # Build the data part of the telegram
+        # S0000000000F01D00 - Broadcast (all zeros) discover command
+        data_part = "S0000000000F01D00"
+
+        # Calculate checksum
+        checksum = calculate_checksum(data_part)
+
+        # Build complete telegram
+        telegram = f"<{data_part}{checksum}>"
+
+        return telegram
+
+    def create_discover_telegram_object(self) -> SystemTelegram:
+        """Create a SystemTelegram object for discover broadcast.
+
+        Returns:
+            SystemTelegram object representing the discover command.
+        """
+        raw_telegram = self.generate_discover_telegram()
+
+        # Extract checksum from the generated telegram
+        checksum = raw_telegram[-3:-1]  # Get checksum before closing >
+
+        telegram = SystemTelegram(
+            serial_number="0000000000",  # Broadcast address
+            system_function=SystemFunction.DISCOVERY,
+            datapoint_type=None,
+            checksum=checksum,
+            raw_telegram=raw_telegram,
+        )
+
+        return telegram
+
+    @staticmethod
+    def is_discover_response(reply_telegram: ReplyTelegram) -> bool:
+        """Check if a reply telegram is a discover response.
+
+        Args:
+            reply_telegram: Reply telegram to check.
+
+        Returns:
+            True if this is a discover response, False otherwise.
+        """
+        return reply_telegram.system_function == SystemFunction.DISCOVERY
+
+    @staticmethod
+    def _generate_discover_response(serial_number: str) -> str:
+        """Generate discover response telegram for a device.
+
+        Args:
+            serial_number: 10-digit module serial number.
+
+        Returns:
+            Formatted discover response telegram.
+        """
+        # Format: <R{serial}F01D{checksum}>
+        data_part = f"R{serial_number}F01D"
+        checksum = calculate_checksum(data_part)
+        telegram = f"<{data_part}{checksum}>"
+        return telegram
+
+    @staticmethod
+    def get_unique_devices(devices: List[DeviceInfo]) -> List[DeviceInfo]:
+        """Filter out duplicate devices based on serial number.
+
+        Args:
+            devices: List of discovered devices.
+
+        Returns:
+            List of unique devices (first occurrence of each serial number).
+        """
+        seen_serials: Set[str] = set()
+        unique_devices = []
+
+        for device in devices:
+            if device.serial_number not in seen_serials:
+                seen_serials.add(device.serial_number)
+                unique_devices.append(device)
+
+        return unique_devices
+
+    @staticmethod
+    def validate_discover_response_format(raw_telegram: str) -> bool:
+        """Validate if a raw telegram matches discover response format.
+
+        Args:
+            raw_telegram: Raw telegram string to validate.
+
+        Returns:
+            True if format matches discover response pattern.
+        """
+        # Discover response format: <R{10-digit-serial}F01D{2-char-checksum}>
+        import re
+
+        match = re.compile(r"^<R(\d{10})F01D([A-Z0-9]{2})>$").match(
+            raw_telegram.strip()
+        )
+
+        return match is not None
+
+    def generate_discover_summary(self, devices: List[DeviceInfo]) -> dict:
+        """Generate a summary of a discover results.
+
+        Args:
+            devices: List of discovered devices.
+
+        Returns:
+            Dictionary with discover statistics.
+        """
+        unique_devices = self.get_unique_devices(devices)
+        valid_devices = [d for d in unique_devices if d.checksum_valid]
+        invalid_devices = [d for d in unique_devices if not d.checksum_valid]
+
+        # Group by serial number prefixes for pattern analysis
+        serial_prefixes = {}
+        for device in unique_devices:
+            prefix = device.serial_number[:4]  # First 4 digits
+            if prefix not in serial_prefixes:
+                serial_prefixes[prefix] = 0
+            serial_prefixes[prefix] += 1
+
+        return {
+            "total_responses": len(devices),
+            "unique_devices": len(unique_devices),
+            "valid_checksums": len(valid_devices),
+            "invalid_checksums": len(invalid_devices),
+            "success_rate": (
+                (len(valid_devices) / len(unique_devices) * 100)
+                if unique_devices
+                else 0
+            ),
+            "duplicate_responses": len(devices) - len(unique_devices),
+            "serial_prefixes": serial_prefixes,
+            "device_list": [device.serial_number for device in valid_devices],
+        }
+
+    def format_discover_results(self, devices: List[DeviceInfo]) -> str:
+        """Format discover results for human-readable output.
+
+        Args:
+            devices: List of discovered devices.
+
+        Returns:
+            Formatted string summary.
+        """
+        if not devices:
+            return "No devices discovered"
+
+        summary = self.generate_discover_summary(devices)
+        unique_devices = self.get_unique_devices(devices)
+
+        lines = [
+            "=== Device Discover Results ===",
+            f"Total Responses: {summary['total_responses']}",
+            f"Unique Devices: {summary['unique_devices']}",
+            f"Valid Checksums: {summary['valid_checksums']}/{summary['unique_devices']} ({summary['success_rate']:.1f}%)",
+        ]
+
+        if summary["duplicate_responses"] > 0:
+            lines.append(f"Duplicate Responses: {summary['duplicate_responses']}")
+
+        lines.extend("\nDiscovered Devices:")
+        lines.append("-" * 40)
+
+        for device in unique_devices:
+            status_icon = "✓" if device.checksum_valid else "✗"
+            lines.append(f"{status_icon} {device.serial_number}")
+
+        if summary["serial_prefixes"]:
+            lines.append("\nSerial Number Distribution:")
+            for prefix, count in sorted(summary["serial_prefixes"].items()):
+                lines.append(f"  {prefix}xxxx: {count} device(s)")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def is_discover_request(telegram: SystemTelegram) -> bool:
+        """Check if telegram is a discover request.
+
+        Args:
+            telegram: System telegram to check.
+
+        Returns:
+            True if this is a discover request, False otherwise.
+        """
+        return (
+            telegram.system_function == SystemFunction.DISCOVERY
+            and telegram.serial_number == "0000000000"
+        )  # Broadcast address