conson-xp 1.0.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

xp/services/conbus/actiontable/__init__.py

@@ -0,0 +1 @@
+"""Action table services for Conbus."""

xp/services/conbus/actiontable/actiontable_service.py

@@ -30,7 +30,14 @@ class ActionTableService(ConbusProtocol):
         actiontable_serializer: ActionTableSerializer,
         telegram_service: TelegramService,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus client send service.
+
+        Args:
+            cli_config: Conbus client configuration.
+            reactor: Twisted reactor instance.
+            actiontable_serializer: Action table serializer.
+            telegram_service: Telegram service for parsing.
+        """
         super().__init__(cli_config, reactor)
         self.serializer = actiontable_serializer
         self.telegram_service = telegram_service
@@ -43,6 +50,7 @@ class ActionTableService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug("Connection established, sending discover telegram")
         self.send_telegram(
             telegram_type=TelegramType.SYSTEM,
@@ -52,9 +60,19 @@ class ActionTableService(ConbusProtocol):
         )
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         self.logger.debug(f"Telegram sent: {telegram_sent}")
 
     def telegram_received(self, telegram_received: TelegramReceivedEvent) -> None:
+        """Handle telegram received event.
+
+        Args:
+            telegram_received: The telegram received event.
+        """
         self.logger.debug(f"Telegram received: {telegram_received}")
         if (
             not telegram_received.checksum_valid
@@ -95,6 +113,11 @@ class ActionTableService(ConbusProtocol):
                 self.finish_callback(actiontable)
 
     def failed(self, message: str) -> None:
+        """Handle failed connection event.
+
+        Args:
+            message: Failure message.
+        """
         self.logger.debug(f"Failed: {message}")
         if self.error_callback:
             self.error_callback(message)
@@ -107,7 +130,15 @@ class ActionTableService(ConbusProtocol):
         finish_callback: Callable[[ActionTable], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """Run reactor in dedicated thread with its own event loop"""
+        """Run reactor in dedicated thread with its own event loop.
+
+        Args:
+            serial_number: Module serial number.
+            progress_callback: Callback for progress updates.
+            error_callback: Callback for errors.
+            finish_callback: Callback when download completes.
+            timeout_seconds: Optional timeout in seconds.
+        """
         self.logger.info("Starting actiontable")
         self.serial_number = serial_number
         if timeout_seconds:

xp/services/conbus/actiontable/msactiontable_service.py

@@ -26,7 +26,7 @@ from xp.services.telegram.telegram_service import TelegramService
 
 
 class MsActionTableError(Exception):
-    """Raised when XP24 action table operations fail"""
+    """Raised when XP24 action table operations fail."""
 
     pass
 
@@ -48,7 +48,16 @@ class MsActionTableService(ConbusProtocol):
         xp33ms_serializer: Xp33MsActionTableSerializer,
         telegram_service: TelegramService,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus client send service.
+
+        Args:
+            cli_config: Conbus client configuration.
+            reactor: Twisted reactor instance.
+            xp20ms_serializer: XP20 MS action table serializer.
+            xp24ms_serializer: XP24 MS action table serializer.
+            xp33ms_serializer: XP33 MS action table serializer.
+            telegram_service: Telegram service for parsing.
+        """
         super().__init__(cli_config, reactor)
         self.xp20ms_serializer = xp20ms_serializer
         self.xp24ms_serializer = xp24ms_serializer
@@ -73,6 +82,7 @@ class MsActionTableService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug("Connection established, sending discover telegram")
         self.send_telegram(
             telegram_type=TelegramType.SYSTEM,
@@ -82,9 +92,19 @@ class MsActionTableService(ConbusProtocol):
         )
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         self.logger.debug(f"Telegram sent: {telegram_sent}")
 
     def telegram_received(self, telegram_received: TelegramReceivedEvent) -> None:
+        """Handle telegram received event.
+
+        Args:
+            telegram_received: The telegram received event.
+        """
         self.logger.debug(f"Telegram received: {telegram_received}")
         if (
             not telegram_received.checksum_valid
@@ -124,6 +144,11 @@ class MsActionTableService(ConbusProtocol):
                 self.finish_callback(msactiontable)
 
     def failed(self, message: str) -> None:
+        """Handle failed connection event.
+
+        Args:
+            message: Failure message.
+        """
         self.logger.debug(f"Failed: {message}")
         if self.error_callback:
             self.error_callback(message)
@@ -139,7 +164,19 @@ class MsActionTableService(ConbusProtocol):
         ],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """Run reactor in dedicated thread with its own event loop"""
+        """Run reactor in dedicated thread with its own event loop.
+
+        Args:
+            serial_number: Module serial number.
+            xpmoduletype: XP module type (xp20, xp24, xp33).
+            progress_callback: Callback for progress updates.
+            error_callback: Callback for errors.
+            finish_callback: Callback when download completes.
+            timeout_seconds: Optional timeout in seconds.
+
+        Raises:
+            MsActionTableError: If unsupported module type is provided.
+        """
         self.logger.info("Starting msactiontable")
         self.serial_number = serial_number
         self.xpmoduletype = xpmoduletype

xp/services/conbus/actiontable/msactiontable_xp24_serializer.py

@@ -11,7 +11,14 @@ class Xp24MsActionTableSerializer:
 
     @staticmethod
     def to_data(action_table: Xp24MsActionTable) -> str:
-        """Serialize action table to telegram format."""
+        """Serialize action table to telegram format.
+
+        Args:
+            action_table: XP24 MS action table to serialize.
+
+        Returns:
+            Serialized action table data string.
+        """
         data_parts: list[str] = []
 
         # Encode all 4 input actions
@@ -46,13 +53,22 @@ class Xp24MsActionTableSerializer:
 
     @staticmethod
     def from_data(msactiontable_rawdata: str) -> Xp24MsActionTable:
-        """Deserialize action table from raw data parts."""
+        """Deserialize action table from raw data parts.
+
+        Args:
+            msactiontable_rawdata: Raw action table data string.
+
+        Returns:
+            Deserialized XP24 MS action table.
 
+        Raises:
+            ValueError: If data length is not 68 bytes.
+        """
         raw_length = len(msactiontable_rawdata)
         if raw_length != 68:
             raise ValueError(f"Msactiontable is not 68 bytes long ({raw_length})")
 
-        # Remove action table count AAAA, AAAB ...
+        # Remove action table count AAAA, AAAB .
         data = msactiontable_rawdata[4:]
 
         # Take first 64 chars (32 bytes) as per pseudocode
@@ -84,6 +100,15 @@ class Xp24MsActionTableSerializer:
 
     @staticmethod
     def _decode_input_action(raw_bytes: bytearray, pos: int) -> InputAction:
+        """Decode input action from raw bytes.
+
+        Args:
+            raw_bytes: Raw byte array containing action data.
+            pos: Position of the action to decode.
+
+        Returns:
+            Decoded input action.
+        """
         function_id = raw_bytes[2 * pos]
         param_id = raw_bytes[2 * pos + 1]
 
@@ -95,7 +120,14 @@ class Xp24MsActionTableSerializer:
 
     @staticmethod
     def from_telegrams(ms_telegrams: str) -> Xp24MsActionTable:
-        """Legacy method for backward compatibility. Use from_data() instead."""
+        """Legacy method for backward compatibility. Use from_data() instead.
+
+        Args:
+            ms_telegrams: Telegram data string.
+
+        Returns:
+            Deserialized XP24 MS action table.
+        """
         # For backward compatibility, assume full telegrams and extract data
         data_parts = ms_telegrams[16:84]
 

xp/services/conbus/actiontable/msactiontable_xp33_serializer.py

@@ -37,7 +37,14 @@ class Xp33MsActionTableSerializer:
 
     @staticmethod
     def to_data(action_table: Xp33MsActionTable) -> str:
-        """Serialize action table to telegram format."""
+        """Serialize action table to telegram format.
+
+        Args:
+            action_table: XP33 MS action table to serialize.
+
+        Returns:
+            Serialized action table data string.
+        """
         # Create 32-byte array
         raw_bytes = bytearray(32)
 
@@ -99,7 +106,17 @@ class Xp33MsActionTableSerializer:
 
     @staticmethod
     def from_data(msactiontable_rawdata: str) -> Xp33MsActionTable:
-        """Deserialize action table from raw data parts."""
+        """Deserialize action table from raw data parts.
+
+        Args:
+            msactiontable_rawdata: Raw action table data string.
+
+        Returns:
+            Deserialized XP33 MS action table.
+
+        Raises:
+            ValueError: If data length is less than 68 characters.
+        """
         raw_length = len(msactiontable_rawdata)
         if raw_length < 68:  # Minimum: 4 char prefix + 64 chars data
             raise ValueError(
@@ -138,7 +155,15 @@ class Xp33MsActionTableSerializer:
 
     @staticmethod
     def _decode_output(raw_bytes: bytearray, output_index: int) -> Xp33Output:
-        """Extract output configuration from raw bytes."""
+        """Extract output configuration from raw bytes.
+
+        Args:
+            raw_bytes: Raw byte array containing output data.
+            output_index: Index of the output to decode.
+
+        Returns:
+            Decoded XP33 output configuration.
+        """
         # Read min/max levels from appropriate offsets
         min_level = Xp33MsActionTableSerializer._byte_to_percentage(
             raw_bytes[2 * output_index]
@@ -184,7 +209,15 @@ class Xp33MsActionTableSerializer:
 
     @staticmethod
     def _decode_scene(raw_bytes: bytearray, scene_index: int) -> Xp33Scene:
-        """Extract scene configuration from raw bytes."""
+        """Extract scene configuration from raw bytes.
+
+        Args:
+            raw_bytes: Raw byte array containing scene data.
+            scene_index: Index of the scene to decode.
+
+        Returns:
+            Decoded XP33 scene configuration.
+        """
         # Calculate scene offset: 6 + (4 * scene_index)
         offset = 6 + (4 * scene_index)
 
@@ -209,7 +242,14 @@ class Xp33MsActionTableSerializer:
 
     @staticmethod
     def from_telegrams(ms_telegrams: str) -> Xp33MsActionTable:
-        """Legacy method for backward compatibility. Use from_data() instead."""
+        """Legacy method for backward compatibility. Use from_data() instead.
+
+        Args:
+            ms_telegrams: Telegram data string.
+
+        Returns:
+            Deserialized XP33 MS action table.
+        """
         # For backward compatibility, assume full telegrams and extract data
         data_parts = ms_telegrams[16:152]  # Adjusted for XP33 length
 

xp/services/conbus/conbus_autoreport_get_service.py

@@ -17,10 +17,10 @@ from xp.services.telegram.telegram_service import TelegramService
 
 class ConbusAutoreportGetService(ConbusDatapointService):
     """
-    Service for receiving telegrams from Conbus servers.
+    Service for getting auto report status from Conbus modules.
 
-    Uses composition with ConbusService to provide receive-only functionality
-    for collecting waiting event telegrams from the server.
+    Uses ConbusProtocol to provide auto report status query functionality
+    for reading the current auto report configuration from modules.
     """
 
     def __init__(
@@ -29,7 +29,13 @@ class ConbusAutoreportGetService(ConbusDatapointService):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus autoreport get service.
+
+        Args:
+            telegram_service: Telegram service for parsing.
+            cli_config: Conbus client configuration.
+            reactor: Twisted reactor instance.
+        """
         super().__init__(telegram_service, cli_config, reactor)
         self.service_callback: Optional[Callable[[ConbusAutoreportResponse], None]] = (
             None
@@ -41,7 +47,11 @@ class ConbusAutoreportGetService(ConbusDatapointService):
     def finish_service_callback(
         self, datapoint_response: ConbusDatapointResponse
     ) -> None:
+        """Handle finished service callback.
 
+        Args:
+            datapoint_response: Datapoint response from service.
+        """
         self.logger.debug("Parsing datapoint response")
         autoreport_status = ""
         if datapoint_response.success and datapoint_response.datapoint_telegram:
@@ -70,10 +80,9 @@ class ConbusAutoreportGetService(ConbusDatapointService):
         Get the current auto report status for a specific module.
 
         Args:
-            :param  serial_number: 10-digit module serial number
-            :param  finish_callback: callback function to call when the linknumber status is
-            :param  timeout_seconds: timeout in seconds
-
+            serial_number: 10-digit module serial number
+            finish_callback: callback function to call when the auto report status is received
+            timeout_seconds: timeout in seconds
         """
         self.logger.info("Starting get_autoreport_status")
         if timeout_seconds:

xp/services/conbus/conbus_autoreport_set_service.py

@@ -20,10 +20,10 @@ from xp.services.protocol import ConbusProtocol
 
 class ConbusAutoreportSetService(ConbusProtocol):
     """
-    Service for receiving telegrams from Conbus servers.
+    Service for setting auto report status on Conbus modules.
 
-    Uses composition with ConbusService to provide receive-only functionality
-    for collecting waiting event telegrams from the server.
+    Uses ConbusProtocol to provide auto report configuration functionality
+    for enabling/disabling automatic reporting on modules.
     """
 
     def __init__(
@@ -31,7 +31,12 @@ class ConbusAutoreportSetService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus autoreport set service.
+
+        Args:
+            cli_config: Conbus client configuration.
+            reactor: Twisted reactor instance.
+        """
         super().__init__(cli_config, reactor)
         self.serial_number: str = ""
         self.status: bool = False
@@ -47,6 +52,7 @@ class ConbusAutoreportSetService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         # Convert boolean to appropriate value
         status_value = "PP" if self.status else "AA"
         status_text = "on" if self.status else "off"
@@ -60,11 +66,20 @@ class ConbusAutoreportSetService(ConbusProtocol):
         )
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         self.logger.debug("Autoreport reply telegram sent %s", telegram_sent)
         self.service_response.sent_telegram = telegram_sent
 
     def telegram_received(self, telegram_received: TelegramReceivedEvent) -> None:
+        """Handle telegram received event.
 
+        Args:
+            telegram_received: The telegram received event.
+        """
         self.logger.debug(f"Telegram received: {telegram_received}")
         if not self.service_response.received_telegrams:
             self.service_response.received_telegrams = []
@@ -90,6 +105,11 @@ class ConbusAutoreportSetService(ConbusProtocol):
             self.finish_callback(self.service_response)
 
     def failed(self, message: str) -> None:
+        """Handle failed connection event.
+
+        Args:
+            message: Failure message.
+        """
         self.logger.debug(f"Failed with message: {message}")
         self.service_response.success = False
         self.service_response.error = message
@@ -104,20 +124,13 @@ class ConbusAutoreportSetService(ConbusProtocol):
         finish_callback: Callable[[ConbusAutoreportResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Set the auto report status for a specific module.
+        """Set the auto report status for a specific module.
 
         Args:
-            serial_number: 10-digit module serial number
-            status: True for ON, False for OFF
-            finish_callback: callback function to call when the autoreport status is
-            timeout_seconds: timeout in seconds
-
-        Returns:
-            ConbusAutoreportResponse with operation result
-
-        Raises:
-            ConbusAutoreportError: If parameters are invalid
+            serial_number: 10-digit module serial number.
+            status: True for ON, False for OFF.
+            finish_callback: Callback function to call when operation completes.
+            timeout_seconds: Timeout in seconds.
         """
         self.logger.info("Starting set_autoreport_status")
         if timeout_seconds:

xp/services/conbus/conbus_blink_all_service.py

@@ -1,7 +1,7 @@
-"""Conbus Client Send Service for TCP communication with Conbus servers.
+"""Conbus Blink All Service for TCP communication with Conbus servers.
 
 This service implements a TCP client that connects to Conbus servers and sends
-various types of telegrams including discover, version, and sensor data requests.
+blink/unblink telegrams to all discovered modules on the network.
 """
 
 import logging
@@ -21,10 +21,10 @@ from xp.services.telegram.telegram_service import TelegramService
 
 class ConbusBlinkAllService(ConbusProtocol):
     """
-    Service for receiving telegrams from Conbus servers.
+    Service for blinking all modules on Conbus servers.
 
-    Uses composition with ConbusService to provide receive-only functionality
-    for collecting waiting event telegrams from the server.
+    Uses ConbusProtocol to provide blink/unblink functionality
+    for all discovered modules on the network.
     """
 
     def __init__(
@@ -33,7 +33,13 @@ class ConbusBlinkAllService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus client send service"""
+        """Initialize the Conbus blink all service.
+
+        Args:
+            telegram_service: Service for parsing telegrams.
+            cli_config: Configuration for Conbus client connection.
+            reactor: Twisted reactor for event loop.
+        """
         super().__init__(cli_config, reactor)
         self.telegram_service = telegram_service
         self.serial_number: str = ""
@@ -51,7 +57,8 @@ class ConbusBlinkAllService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
-        self.logger.debug("Connection established, send discover telegram...")
+        """Handle connection established event."""
+        self.logger.debug("Connection established, send discover telegram.")
         self.send_telegram(
             telegram_type=TelegramType.SYSTEM,
             serial_number="0000000000",
@@ -62,7 +69,12 @@ class ConbusBlinkAllService(ConbusProtocol):
             self.progress_callback(".")
 
     def send_blink(self, serial_number: str) -> None:
-        self.logger.debug("Device discovered, send blink...")
+        """Send blink or unblink telegram to a discovered module.
+
+        Args:
+            serial_number: 10-digit module serial number.
+        """
+        self.logger.debug("Device discovered, send blink.")
 
         # Blink is 05, Unblink is 06
         system_function = SystemFunction.UNBLINK
@@ -82,11 +94,20 @@ class ConbusBlinkAllService(ConbusProtocol):
             self.progress_callback(".")
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         system_telegram = self.telegram_service.parse_system_telegram(telegram_sent)
         self.service_response.sent_telegram = system_telegram
 
     def telegram_received(self, telegram_received: TelegramReceivedEvent) -> None:
+        """Handle telegram received event.
 
+        Args:
+            telegram_received: The telegram received event.
+        """
         self.logger.debug(f"Telegram received: {telegram_received}")
         if not self.service_response.received_telegrams:
             self.service_response.received_telegrams = []
@@ -124,6 +145,11 @@ class ConbusBlinkAllService(ConbusProtocol):
         self.logger.debug("Received unexpected response")
 
     def failed(self, message: str) -> None:
+        """Handle failed connection event.
+
+        Args:
+            message: Failure message.
+        """
         self.logger.debug(f"Failed with message: {message}")
         self.service_response.success = False
         self.service_response.timestamp = datetime.now()
@@ -138,22 +164,15 @@ class ConbusBlinkAllService(ConbusProtocol):
         finish_callback: Callable[[ConbusBlinkResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Get the current auto report status for a specific module.
+        """Send blink command to all discovered modules.
 
         Args:
-            on_or_off: blink or unblink device
-            finish_callback: callback function to call when the autoreport status is
-            timeout_seconds: timeout in seconds
-
-        Returns:
-            ConbusAutoreportResponse with operation result and auto report status
-
-        Raises:
-            ConbusAutoreportError: If the operation fails
+            on_or_off: "on" to blink or "off" to unblink all devices.
+            progress_callback: Callback function to call with progress updates.
+            finish_callback: Callback function to call when the operation completes.
+            timeout_seconds: Timeout in seconds.
         """
-
-        self.logger.info("Starting get_autoreport_status")
+        self.logger.info("Starting send_blink_all_telegram")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds
         self.progress_callback = progress_callback