conson-xp 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

xp/services/conbus/conbus_scan_service.py

@@ -1,7 +1,7 @@
 """Conbus Scan Service for TCP communication with Conbus servers.
 
-This service implements a TCP client that scan a Conbus servers and sends
-various types of telegrams including discover, version, and sensor data requests.
+This service implements a TCP client that scans Conbus servers and sends
+telegrams to scan modules for all datapoints by function code.
 """
 
 import logging
@@ -20,10 +20,10 @@ from xp.services.protocol import ConbusProtocol
 
 class ConbusScanService(ConbusProtocol):
     """
-    Service for querying datapoints from Conbus modules.
+    Service for scanning modules for all datapoints by function code.
 
-    Uses ConbusProtocol to provide datapoint query functionality
-    for reading sensor data and module information.
+    Uses ConbusProtocol to provide scan functionality for discovering
+    all available datapoints on a module.
     """
 
     def __init__(
@@ -31,7 +31,12 @@ class ConbusScanService(ConbusProtocol):
         cli_config: ConbusClientConfig,
         reactor: PosixReactorBase,
     ) -> None:
-        """Initialize the Conbus datapoint service"""
+        """Initialize the Conbus scan service.
+
+        Args:
+            cli_config: Conbus client configuration.
+            reactor: Twisted reactor instance.
+        """
         super().__init__(cli_config, reactor)
         self.serial_number: str = ""
         self.function_code: str = ""
@@ -49,10 +54,16 @@ class ConbusScanService(ConbusProtocol):
         self.logger = logging.getLogger(__name__)
 
     def connection_established(self) -> None:
+        """Handle connection established event."""
         self.logger.debug("Connection established, starting scan")
         self.scan_next_datacode()
 
     def scan_next_datacode(self) -> bool:
+        """Scan the next data code.
+
+        Returns:
+            True if scanning should continue, False if complete.
+        """
         self.datapoint_value += 1
         if self.datapoint_value >= 100:
             if self.finish_callback:
@@ -66,10 +77,20 @@ class ConbusScanService(ConbusProtocol):
         return True
 
     def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
         self.service_response.success = True
         self.service_response.sent_telegrams.append(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 = []
@@ -79,11 +100,21 @@ class ConbusScanService(ConbusProtocol):
             self.progress_callback(telegram_received.frame)
 
     def timeout(self) -> bool:
+        """Handle timeout event by scanning next data code.
+
+        Returns:
+            True to continue scanning, False to stop.
+        """
         self.logger.debug(f"Timeout: {self.timeout_seconds}s")
         continue_scan = self.scan_next_datacode()
         return continue_scan
 
     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()
@@ -99,21 +130,16 @@ class ConbusScanService(ConbusProtocol):
         finish_callback: Callable[[ConbusResponse], None],
         timeout_seconds: Optional[float] = None,
     ) -> None:
-        """
-        Query a specific datapoint from a module.
+        """Scan a module for all datapoints by function code.
 
         Args:
-            serial_number: 10-digit module serial number
-            function_code: the function code to scan
-            progress_callback: callback to handle progress
-            finish_callback: callback function to call when the datapoint is received
-            timeout_seconds: timeout in seconds
-
-        Returns:
-            ConbusDatapointResponse with operation result and datapoint value
+            serial_number: 10-digit module serial number.
+            function_code: The function code to scan.
+            progress_callback: Callback to handle progress.
+            finish_callback: Callback function to call when the scan is complete.
+            timeout_seconds: Timeout in seconds.
         """
-
-        self.logger.info("Starting query_datapoint")
+        self.logger.info("Starting scan_module")
         if timeout_seconds:
             self.timeout_seconds = timeout_seconds
 

xp/services/conbus/write_config_service.py

@@ -0,0 +1,193 @@
+"""Conbus Link Number Service for setting module link numbers.
+
+This service handles setting link numbers for modules through Conbus telegrams.
+"""
+
+import logging
+from datetime import datetime
+from typing import Callable, Optional
+
+from twisted.internet.posixbase import PosixReactorBase
+
+from xp.models import ConbusClientConfig
+from xp.models.conbus.conbus_writeconfig import ConbusWriteConfigResponse
+from xp.models.protocol.conbus_protocol import TelegramReceivedEvent
+from xp.models.telegram.datapoint_type import DataPointType
+from xp.models.telegram.system_function import SystemFunction
+from xp.models.telegram.telegram_type import TelegramType
+from xp.services.protocol import ConbusProtocol
+from xp.services.telegram.telegram_service import TelegramService
+
+
+class WriteConfigService(ConbusProtocol):
+    """
+    Service for writing module settings via Conbus telegrams.
+
+    Handles setting assignment by sending F04DXX telegrams and processing
+    ACK/NAK responses from modules.
+    """
+
+    def __init__(
+        self,
+        telegram_service: TelegramService,
+        cli_config: ConbusClientConfig,
+        reactor: PosixReactorBase,
+    ) -> None:
+        """Initialize the Conbus link number set 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.datapoint_type: Optional[DataPointType] = None
+        self.serial_number: str = ""
+        self.data_value: str = ""
+        self.write_config_finished_callback: Optional[
+            Callable[[ConbusWriteConfigResponse], None]
+        ] = None
+        self.write_config_response: ConbusWriteConfigResponse = (
+            ConbusWriteConfigResponse(
+                success=False,
+                serial_number=self.serial_number,
+            )
+        )
+
+        # Set up logging
+        self.logger = logging.getLogger(__name__)
+
+    def connection_established(self) -> None:
+        """Handle connection established event."""
+        self.logger.debug(f"Connection established, writing config {self.data_value}.")
+
+        # Validate parameters before sending
+        if not self.serial_number or len(self.serial_number) != 10:
+            self.failed(f"Serial number must be 10 digits, got: {self.serial_number}")
+            return
+
+        if len(self.data_value) < 2:
+            self.failed(f"data_value must be at least 2 bytes, got: {self.data_value}")
+            return
+
+        if not self.datapoint_type:
+            self.failed(f"datapoint_type must be defined, got: {self.datapoint_type}")
+            return
+
+        # Send WRITE_CONFIG telegram
+        # Function F04 = WRITE_CONFIG,
+        # Datapoint = D datapoint_type
+        # Data = XX
+        self.send_telegram(
+            telegram_type=TelegramType.SYSTEM,
+            serial_number=self.serial_number,
+            system_function=SystemFunction.WRITE_CONFIG,
+            data_value=f"{self.datapoint_type.value}{self.data_value}",
+        )
+
+    def telegram_sent(self, telegram_sent: str) -> None:
+        """Handle telegram sent event.
+
+        Args:
+            telegram_sent: The telegram that was sent.
+        """
+        self.write_config_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.write_config_response.received_telegrams:
+            self.write_config_response.received_telegrams = []
+        self.write_config_response.received_telegrams.append(telegram_received.frame)
+
+        if (
+            not telegram_received.checksum_valid
+            or telegram_received.telegram_type != TelegramType.REPLY
+            or telegram_received.serial_number != self.serial_number
+        ):
+            self.logger.debug("Not a reply for our serial number")
+            return
+
+        # Parse the reply telegram
+        reply_telegram = self.telegram_service.parse_reply_telegram(
+            telegram_received.frame
+        )
+
+        if not reply_telegram or reply_telegram.system_function not in (
+            SystemFunction.ACK,
+            SystemFunction.NAK,
+        ):
+            self.logger.debug("Not a write config reply")
+            return
+
+        succeed = (
+            True if reply_telegram.system_function == SystemFunction.ACK else False
+        )
+        self.finished(
+            succeed_or_failed=succeed, system_function=reply_telegram.system_function
+        )
+
+    def failed(self, message: str) -> None:
+        """Handle telegram failed event.
+
+        Args:
+            message: The error message.
+        """
+        self.logger.debug("Failed to send telegram")
+        self.finished(succeed_or_failed=False, message=message)
+
+    def finished(
+        self,
+        succeed_or_failed: bool,
+        message: Optional[str] = None,
+        system_function: Optional[SystemFunction] = None,
+    ) -> None:
+        """Handle successful link number set operation.
+
+        Args:
+            succeed_or_failed: succeed true, failed false.
+            message: error message if any.
+            system_function: The system function from the reply telegram.
+        """
+        self.logger.debug("finished writing config")
+        self.write_config_response.success = succeed_or_failed
+        self.write_config_response.error = message
+        self.write_config_response.timestamp = datetime.now()
+        self.write_config_response.serial_number = self.serial_number
+        self.write_config_response.system_function = system_function
+        self.write_config_response.datapoint_type = self.datapoint_type
+        self.write_config_response.data_value = self.data_value
+        if self.write_config_finished_callback:
+            self.write_config_finished_callback(self.write_config_response)
+
+    def write_config(
+        self,
+        serial_number: str,
+        datapoint_type: DataPointType,
+        data_value: str,
+        finish_callback: Callable[[ConbusWriteConfigResponse], None],
+        timeout_seconds: Optional[float] = None,
+    ) -> None:
+        """Write config to a specific module.
+
+        Args:
+            serial_number: 10-digit module serial number.
+            datapoint_type: the datapoint type to write to.
+            data_value: the data to write.
+            finish_callback: Callback function to call when operation completes.
+            timeout_seconds: Optional timeout in seconds.
+        """
+        self.logger.info("Starting write_config")
+        if timeout_seconds:
+            self.timeout_seconds = timeout_seconds
+        self.serial_number = serial_number
+        self.datapoint_type = datapoint_type
+        self.data_value = data_value
+        self.write_config_finished_callback = finish_callback
+        self.start_reactor()

xp/services/homekit/__init__.py

@@ -0,0 +1 @@
+"""HomeKit integration services."""

xp/services/homekit/homekit_cache_service.py

@@ -22,7 +22,12 @@ CACHE_FILE = CACHE_DIR / "homekit_cache.json"
 
 
 class CacheEntry(TypedDict):
-    """Cache entry type definition."""
+    """Cache entry type definition.
+
+    Attributes:
+        event: The cached event (OutputStateReceivedEvent or LightLevelReceivedEvent).
+        timestamp: When the event was cached.
+    """
 
     event: Union[OutputStateReceivedEvent, LightLevelReceivedEvent]
     timestamp: datetime
@@ -39,6 +44,12 @@ class HomeKitCacheService:
     """
 
     def __init__(self, event_bus: EventBus, enable_persistence: bool = True):
+        """Initialize the HomeKit cache service.
+
+        Args:
+            event_bus: Event bus for inter-service communication.
+            enable_persistence: Whether to persist cache to disk.
+        """
         self.logger = logging.getLogger(__name__)
         self.event_bus = event_bus
         self.cache: dict[tuple[str, DataPointType], CacheEntry] = {}
@@ -192,12 +203,14 @@ class HomeKitCacheService:
         return None
 
     def handle_read_datapoint_event(self, event: ReadDatapointEvent) -> None:
-        """
-        Handle ReadDatapointEvent by checking cache or refresh flag.
+        """Handle ReadDatapointEvent by checking cache or refresh flag.
 
         On refresh_cache=True: invalidate cache and force protocol query
         On cache hit: dispatch cached response event
         On cache miss: forward to protocol via ReadDatapointFromProtocolEvent
+
+        Args:
+            event: Read datapoint event with serial number, datapoint type, and refresh flag.
         """
         self.logger.debug(
             f"Handling ReadDatapointEvent: "
@@ -250,7 +263,11 @@ class HomeKitCacheService:
     def handle_output_state_received_event(
         self, event: OutputStateReceivedEvent
     ) -> None:
-        """Cache OutputStateReceivedEvent for future queries."""
+        """Cache OutputStateReceivedEvent for future queries.
+
+        Args:
+            event: Output state received event to cache.
+        """
         self.logger.debug(
             f"Caching OutputStateReceivedEvent: "
             f"serial={event.serial_number}, "
@@ -260,7 +277,11 @@ class HomeKitCacheService:
         self._cache_event(event)
 
     def handle_light_level_received_event(self, event: LightLevelReceivedEvent) -> None:
-        """Cache LightLevelReceivedEvent for future queries."""
+        """Cache LightLevelReceivedEvent for future queries.
+
+        Args:
+            event: Light level received event to cache.
+        """
         self.logger.debug(
             f"Caching LightLevelReceivedEvent: "
             f"serial={event.serial_number}, "
@@ -276,7 +297,11 @@ class HomeKitCacheService:
         self._save_cache()
 
     def get_cache_stats(self) -> dict[str, int]:
-        """Get cache statistics."""
+        """Get cache statistics.
+
+        Returns:
+            Dictionary with cache statistics including total_entries.
+        """
         return {
             "total_entries": len(self.cache),
         }

xp/services/homekit/homekit_conbus_service.py

@@ -1,3 +1,8 @@
+"""HomeKit Conbus Service for protocol communication.
+
+This module bridges HomeKit events with the Conbus protocol for device control.
+"""
+
 import logging
 
 from bubus import EventBus
@@ -14,11 +19,23 @@ from xp.services.protocol.telegram_protocol import TelegramProtocol
 
 
 class HomeKitConbusService:
-    """homeKitConbusService"""
+    """Service for bridging HomeKit events with Conbus protocol.
+
+    Attributes:
+        event_bus: Event bus for inter-service communication.
+        telegram_protocol: Protocol for sending telegrams.
+        logger: Logger instance.
+    """
 
     event_bus: EventBus
 
     def __init__(self, event_bus: EventBus, telegram_protocol: TelegramProtocol):
+        """Initialize the HomeKit Conbus service.
+
+        Args:
+            event_bus: Event bus instance.
+            telegram_protocol: Telegram protocol instance.
+        """
         self.logger = logging.getLogger(__name__)
         self.event_bus = event_bus
         self.telegram_protocol = telegram_protocol
@@ -33,7 +50,11 @@ class HomeKitConbusService:
     def handle_read_datapoint_request(
         self, event: ReadDatapointFromProtocolEvent
     ) -> None:
-        """Handle request to read datapoint from protocol."""
+        """Handle request to read datapoint from protocol.
+
+        Args:
+            event: Read datapoint event with serial number and datapoint type.
+        """
         self.logger.debug(f"read_datapoint_request {event}")
 
         system_function = SystemFunction.READ_DATAPOINT.value
@@ -42,6 +63,11 @@ class HomeKitConbusService:
         self.telegram_protocol.sendFrame(telegram.encode())
 
     def handle_send_write_config_event(self, event: SendWriteConfigEvent) -> None:
+        """Handle send write config event.
+
+        Args:
+            event: Write config event with configuration data.
+        """
         self.logger.debug(f"send_write_config_event {event}")
 
         # Format data as output_number:level (e.g., "02:050")
@@ -54,6 +80,11 @@ class HomeKitConbusService:
         self.telegram_protocol.sendFrame(telegram.encode())
 
     def handle_send_action_event(self, event: SendActionEvent) -> None:
+        """Handle send action event.
+
+        Args:
+            event: Send action event with action data.
+        """
         self.logger.debug(f"send_action_event {event}")
 
         action_value = (