conson-xp 1.45.0__tar.gz → 1.46.0__tar.gz

{conson_xp-1.45.0 → conson_xp-1.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: conson-xp
-Version: 1.45.0
+Version: 1.46.0
 Summary: XP Protocol Communication Tools
 Author-Email: ldvchosal <ldvchosal@github.com>
 License: MIT License

{conson_xp-1.45.0 → conson_xp-1.46.0}/pyproject.toml

@@ -23,7 +23,7 @@ dependencies = [
 ]
 requires-python = ">=3.11"
 readme = "README.md"
-version = "1.45.0"
+version = "1.46.0"
 
 [project.license]
 file = "LICENSE"

{conson_xp-1.45.0 → conson_xp-1.46.0}/src/xp/__init__.py

@@ -3,7 +3,7 @@
 conson-xp package.
 """
 
-__version__ = "1.45.0"
+__version__ = "1.46.0"
 __manufacturer__ = "salchichon"
 __model__ = "xp.cli"
 __serial__ = "2025.09.23.000"

conson_xp-1.46.0/src/xp/services/conbus/actiontable/actiontable_download_service.py

@@ -0,0 +1,345 @@
+"""Service for downloading ActionTable via Conbus protocol."""
+
+import logging
+from dataclasses import asdict
+from typing import Any, Optional
+
+from psygnal import SignalInstance
+
+from xp.models.actiontable.actiontable import ActionTable
+from xp.models.protocol.conbus_protocol import TelegramReceivedEvent
+from xp.models.telegram.datapoint_type import DataPointType
+from xp.models.telegram.reply_telegram import ReplyTelegram
+from xp.services.actiontable.actiontable_serializer import ActionTableSerializer
+from xp.services.conbus.actiontable.actiontable_download_state_machine import (
+    MAX_ERROR_RETRIES,
+    ActionTableDownloadStateMachine,
+)
+from xp.services.protocol.conbus_event_protocol import (
+    NO_ERROR_CODE,
+    ConbusEventProtocol,
+)
+
+
+class ActionTableDownloadService(ActionTableDownloadStateMachine):
+    """Service for downloading action tables from Conbus modules via TCP.
+
+    Inherits from ActionTableDownloadStateMachine and overrides on_enter_*
+    methods to add protocol-specific behavior.
+
+    The workflow consists of three phases:
+
+    INIT phase (drain → reset → wait_ok):
+        Connection established, drain pending telegrams, query error status.
+
+    DOWNLOAD phase (request → receive chunks → EOF):
+        Request actiontable, receive and ACK chunks until EOF.
+
+    CLEANUP phase (drain → reset → wait_ok):
+        After EOF, drain remaining telegrams and verify final status.
+
+    Attributes:
+        on_progress: Signal emitted with "." for each chunk received.
+        on_error: Signal emitted with error message string.
+        on_actiontable_received: Signal emitted with (ActionTable, dict, list).
+        on_finish: Signal emitted when download and cleanup completed.
+
+    Example:
+        >>> with download_service as service:
+        ...     service.configure(serial_number="12345678")
+        ...     service.on_actiontable_received.connect(handle_result)
+        ...     service.start_reactor()
+    """
+
+    def __init__(
+        self,
+        conbus_protocol: ConbusEventProtocol,
+        actiontable_serializer: ActionTableSerializer,
+    ) -> None:
+        """Initialize the action table download service.
+
+        Args:
+            conbus_protocol: ConbusEventProtocol instance.
+            actiontable_serializer: Action table serializer.
+        """
+        self.conbus_protocol = conbus_protocol
+        self.serializer = actiontable_serializer
+        self.serial_number: str = ""
+        self.actiontable_data: list[str] = []
+        self._signals_connected: bool = False
+
+        # Service signals
+        self.on_progress: SignalInstance = SignalInstance((str,))
+        self.on_error: SignalInstance = SignalInstance((str,))
+        self.on_finish: SignalInstance = SignalInstance()
+        self.on_actiontable_received: SignalInstance = SignalInstance(
+            (ActionTable, dict[str, Any], list[str])
+        )
+
+        # Initialize state machine (must be last - triggers introspection)
+        super().__init__()
+
+        # Override logger for service-specific logging
+        self.logger = logging.getLogger(__name__)
+
+        # Connect protocol signals
+        self._connect_signals()
+
+    # Override state entry hooks with protocol behavior
+
+    def on_enter_receiving(self) -> None:
+        """Enter receiving state - wait for telegrams to drain."""
+        self.logger.debug(f"Entering RECEIVING state (phase={self.phase.value})")
+        self.conbus_protocol.wait()
+
+    def on_enter_resetting(self) -> None:
+        """Enter resetting state - send error status query."""
+        self.logger.debug(f"Entering RESETTING state (phase={self.phase.value})")
+        self.conbus_protocol.send_error_status_query(serial_number=self.serial_number)
+        self.send_error_status()
+
+    def on_enter_waiting_ok(self) -> None:
+        """Enter waiting_ok state - wait for error status response."""
+        self.logger.debug(f"Entering WAITING_OK state (phase={self.phase.value})")
+        self.conbus_protocol.wait()
+
+    def on_enter_requesting(self) -> None:
+        """Enter requesting state - send download request."""
+        self.enter_download_phase()  # Sets phase to DOWNLOAD
+        self.conbus_protocol.send_download_request(serial_number=self.serial_number)
+        self.send_download()
+
+    def on_enter_waiting_data(self) -> None:
+        """Enter waiting_data state - wait for actiontable chunks."""
+        self.logger.debug("Entering WAITING_DATA state - awaiting chunks")
+        self.conbus_protocol.wait()
+
+    def on_enter_receiving_chunk(self) -> None:
+        """Enter receiving_chunk state - send ACK."""
+        self.logger.debug("Entering RECEIVING_CHUNK state - sending ACK")
+        self.conbus_protocol.send_ack(serial_number=self.serial_number)
+        self.send_ack()
+
+    def on_enter_processing_eof(self) -> None:
+        """Enter processing_eof state - deserialize and emit result."""
+        self.logger.debug("Entering PROCESSING_EOF state - deserializing")
+        all_data = "".join(self.actiontable_data)
+        actiontable = self.serializer.from_encoded_string(all_data)
+        actiontable_dict = asdict(actiontable)
+        actiontable_short = self.serializer.format_decoded_output(actiontable)
+        self.on_actiontable_received.emit(
+            actiontable, actiontable_dict, actiontable_short
+        )
+        # Switch to CLEANUP phase
+        self.start_cleanup_phase()
+
+    def on_enter_completed(self) -> None:
+        """Enter completed state - emit finish signal."""
+        self.logger.debug("Entering COMPLETED state - download finished")
+        self.on_finish.emit()
+
+    def on_max_retries_exceeded(self) -> None:
+        """Handle max retries exceeded - emit error signal."""
+        self.logger.error(f"Max error retries ({MAX_ERROR_RETRIES}) exceeded")
+        self.on_error.emit(f"Module error persists after {MAX_ERROR_RETRIES} retries")
+
+    # Protocol event handlers
+
+    def _on_connection_made(self) -> None:
+        """Handle connection established event."""
+        self.logger.debug("Connection made")
+        if self.idle.is_active:
+            self.do_connect()
+
+    def _on_read_datapoint_received(self, reply_telegram: ReplyTelegram) -> None:
+        """Handle READ_DATAPOINT response for error status check.
+
+        Args:
+            reply_telegram: The parsed reply telegram.
+        """
+        self.logger.debug(f"Received READ_DATAPOINT in {self.current_state}")
+        if reply_telegram.serial_number != self.serial_number:
+            return
+
+        if reply_telegram.datapoint_type != DataPointType.MODULE_ERROR_CODE:
+            return
+
+        if not self.waiting_ok.is_active:
+            return
+
+        is_no_error = reply_telegram.data_value == NO_ERROR_CODE
+        if is_no_error:
+            self.handle_no_error_received()
+        else:
+            self.handle_error_received()
+
+    def _on_actiontable_chunk_received(
+        self, reply_telegram: ReplyTelegram, actiontable_chunk: str
+    ) -> None:
+        """Handle actiontable chunk telegram received.
+
+        Args:
+            reply_telegram: The parsed reply telegram containing chunk data.
+            actiontable_chunk: The chunk data.
+        """
+        self.logger.debug(f"Received actiontable chunk in {self.current_state}")
+        if reply_telegram.serial_number != self.serial_number:
+            return
+
+        if self.waiting_data.is_active:
+            self.actiontable_data.append(actiontable_chunk)
+            self.on_progress.emit(".")
+            self.receive_chunk()
+
+    def _on_eof_received(self, reply_telegram: ReplyTelegram) -> None:
+        """Handle EOF telegram received.
+
+        Args:
+            reply_telegram: The parsed reply telegram (unused).
+        """
+        self.logger.debug(f"Received EOF in {self.current_state}")
+        if reply_telegram.serial_number != self.serial_number:
+            return
+
+        if self.waiting_data.is_active:
+            self.receive_eof()
+
+    def _on_telegram_received(self, telegram_received: TelegramReceivedEvent) -> None:
+        """Handle telegram received event.
+
+        Args:
+            telegram_received: The telegram received event.
+        """
+        self.logger.debug(f"Received {telegram_received} in {self.current_state}")
+
+        # In receiving state, drain pending telegrams from pipe (discard to /dev/null).
+        # This ensures clean state before processing by clearing any stale messages.
+        if self.receiving.is_active:
+            self.filter_telegram()
+            return
+
+    def _on_timeout(self) -> None:
+        """Handle timeout event."""
+        self.logger.debug(f"Timeout occurred (phase={self.phase.value})")
+        if self.receiving.is_active:
+            self.do_timeout()  # receiving -> resetting
+        elif self.waiting_ok.is_active:
+            self.do_timeout()  # waiting_ok -> receiving (retry)
+        elif self.waiting_data.is_active:
+            self.logger.error("Timeout waiting for actiontable data")
+            self.on_error.emit("Timeout waiting for actiontable data")
+        else:
+            self.logger.debug("Timeout in non-recoverable state")
+            self.on_error.emit("Timeout")
+
+    def _on_failed(self, message: str) -> None:
+        """Handle failed connection event.
+
+        Args:
+            message: Failure message.
+        """
+        self.logger.debug(f"Failed: {message}")
+        self.on_error.emit(message)
+
+    # Public API
+
+    def configure(
+        self,
+        serial_number: str,
+        timeout_seconds: Optional[float] = 2.0,
+    ) -> None:
+        """Configure download parameters before starting.
+
+        Sets the target module serial number and timeout. Call this before
+        start_reactor() to configure the download target.
+
+        Args:
+            serial_number: Module serial number to download from.
+            timeout_seconds: Timeout in seconds for each operation (default 2.0).
+
+        Raises:
+            RuntimeError: If called while download is in progress.
+        """
+        if not self.idle.is_active:
+            raise RuntimeError("Cannot configure while download in progress")
+        self.logger.info("Configuring actiontable download")
+        self.serial_number = serial_number
+        if timeout_seconds:
+            self.conbus_protocol.timeout_seconds = timeout_seconds
+
+    def set_timeout(self, timeout_seconds: float) -> None:
+        """Set operation timeout.
+
+        Args:
+            timeout_seconds: Timeout in seconds.
+        """
+        self.conbus_protocol.timeout_seconds = timeout_seconds
+
+    def start_reactor(self) -> None:
+        """Start the reactor."""
+        self.conbus_protocol.start_reactor()
+
+    def stop_reactor(self) -> None:
+        """Stop the reactor."""
+        self.conbus_protocol.stop_reactor()
+
+    def _connect_signals(self) -> None:
+        """Connect protocol signals to handlers (idempotent)."""
+        if self._signals_connected:
+            return
+        self.conbus_protocol.on_connection_made.connect(self._on_connection_made)
+        self.conbus_protocol.on_telegram_received.connect(self._on_telegram_received)
+        self.conbus_protocol.on_read_datapoint_received.connect(
+            self._on_read_datapoint_received
+        )
+        self.conbus_protocol.on_actiontable_chunk_received.connect(
+            self._on_actiontable_chunk_received
+        )
+        self.conbus_protocol.on_eof_received.connect(self._on_eof_received)
+        self.conbus_protocol.on_timeout.connect(self._on_timeout)
+        self.conbus_protocol.on_failed.connect(self._on_failed)
+        self._signals_connected = True
+
+    def _disconnect_signals(self) -> None:
+        """Disconnect protocol signals from handlers (idempotent)."""
+        if not self._signals_connected:
+            return
+        self.conbus_protocol.on_connection_made.disconnect(self._on_connection_made)
+        self.conbus_protocol.on_telegram_received.disconnect(self._on_telegram_received)
+        self.conbus_protocol.on_read_datapoint_received.disconnect(
+            self._on_read_datapoint_received
+        )
+        self.conbus_protocol.on_actiontable_chunk_received.disconnect(
+            self._on_actiontable_chunk_received
+        )
+        self.conbus_protocol.on_eof_received.disconnect(self._on_eof_received)
+        self.conbus_protocol.on_timeout.disconnect(self._on_timeout)
+        self.conbus_protocol.on_failed.disconnect(self._on_failed)
+        self._signals_connected = False
+
+    def __enter__(self) -> "ActionTableDownloadService":
+        """Enter context manager - reset state and reconnect signals.
+
+        Returns:
+            Self for context manager protocol.
+        """
+        # Reset state for singleton reuse
+        self.actiontable_data = []
+        # Reset state machine
+        self.reset()
+        # Reconnect signals (in case previously disconnected)
+        self._connect_signals()
+        return self
+
+    def __exit__(
+        self, _exc_type: Optional[type], _exc_val: Optional[Exception], _exc_tb: Any
+    ) -> None:
+        """Exit context manager and disconnect signals."""
+        self._disconnect_signals()
+        # Disconnect service signals
+        self.on_progress.disconnect()
+        self.on_error.disconnect()
+        self.on_actiontable_received.disconnect()
+        self.on_finish.disconnect()
+        # Stop reactor
+        self.stop_reactor()

conson_xp-1.46.0/src/xp/services/conbus/actiontable/actiontable_download_state_machine.py

@@ -0,0 +1,276 @@
+"""State machine for ActionTable download workflow."""
+
+import logging
+from abc import ABCMeta, abstractmethod
+from enum import Enum
+
+from statemachine import State, StateMachine
+from statemachine.factory import StateMachineMetaclass
+
+
+class AbstractStateMachineMeta(StateMachineMetaclass, ABCMeta):
+    """Combined metaclass for abstract state machines.
+
+    Combines StateMachineMetaclass (for state machine introspection) with
+    ABCMeta (for abstract method enforcement).
+    """
+
+    pass
+
+
+# Constants
+MAX_ERROR_RETRIES = 3  # Max retries for error_status_received before giving up
+
+
+class Phase(Enum):
+    """Download workflow phases.
+
+    The download workflow consists of three sequential phases:
+    - INIT: Drain pending telegrams, query error status → proceed to DOWNLOAD
+    - DOWNLOAD: Request actiontable, receive chunks with ACK, until EOF
+    - CLEANUP: Drain pending telegrams, query error status → proceed to COMPLETED
+
+    Attributes:
+        INIT: Initial phase - drain pending telegrams and query error status.
+        DOWNLOAD: Download phase - request actiontable and receive chunks.
+        CLEANUP: Cleanup phase - drain remaining telegrams and verify status.
+    """
+
+    INIT = "init"
+    DOWNLOAD = "download"
+    CLEANUP = "cleanup"
+
+
+class ActionTableDownloadStateMachine(StateMachine, metaclass=AbstractStateMachineMeta):
+    """State machine for ActionTable download workflow.
+
+    Pure state machine with states, transitions, and guards. Subclasses can
+    override on_enter_* methods to add protocol-specific behavior.
+
+    States (9 total):
+        idle -> receiving -> resetting -> waiting_ok -> requesting
+             -> waiting_data <-> receiving_chunk -> processing_eof -> completed
+
+    Phases - INIT and CLEANUP share the same states (receiving, resetting, waiting_ok):
+
+    INIT phase (drain → reset → wait_ok):
+        idle -> receiving -> resetting -> waiting_ok --(guard: is_init_phase)--> requesting
+
+    DOWNLOAD phase (request → receive chunks → EOF):
+        requesting -> waiting_data <-> receiving_chunk -> processing_eof
+
+    CLEANUP phase (drain → reset → wait_ok):
+        processing_eof -> receiving -> resetting -> waiting_ok --(guard: is_cleanup_phase)--> completed
+
+    The drain/reset/wait_ok cycle:
+    1. Drain pending telegrams (receiving state discards telegrams)
+    2. Timeout triggers error status query (resetting)
+    3. Wait for response (waiting_ok)
+    4. On no error: guard determines target (requesting or completed)
+       On error: retry from drain step (limited by MAX_ERROR_RETRIES)
+
+    Attributes:
+        phase: Current workflow phase (INIT, DOWNLOAD, CLEANUP).
+        error_retry_count: Current error retry count.
+        idle: Initial state before connection.
+        receiving: Drain pending telegrams state (INIT or CLEANUP phase).
+        resetting: Query error status state.
+        waiting_ok: Await error status response state.
+        requesting: DOWNLOAD phase state - send download request.
+        waiting_data: DOWNLOAD phase state - await chunks.
+        receiving_chunk: DOWNLOAD phase state - process chunk.
+        processing_eof: DOWNLOAD phase state - deserialize result.
+        completed: Final state - download finished.
+        do_connect: Transition from idle to receiving.
+        filter_telegram: Self-transition in receiving state for draining.
+        do_timeout: Timeout transitions from receiving/waiting_ok.
+        send_error_status: Transition from resetting to waiting_ok.
+        error_status_received: Transition from waiting_ok to receiving on error.
+        no_error_status_received: Conditional transition based on phase.
+        send_download: Transition from requesting to waiting_data.
+        receive_chunk: Transition from waiting_data to receiving_chunk.
+        send_ack: Transition from receiving_chunk to waiting_data.
+        receive_eof: Transition from waiting_data to processing_eof.
+        do_finish: Transition from processing_eof to receiving.
+    """
+
+    # States - unified for INIT and CLEANUP phases using guards
+    idle = State(initial=True)
+    receiving = State()  # Drain telegrams (INIT or CLEANUP phase)
+    resetting = State()  # Query error status
+    waiting_ok = State()  # Await error status response
+
+    requesting = State()  # DOWNLOAD phase: send download request
+    waiting_data = State()  # DOWNLOAD phase: await chunks
+    receiving_chunk = State()  # DOWNLOAD phase: process chunk
+    processing_eof = State()  # DOWNLOAD phase: deserialize result
+
+    completed = State(final=True)
+
+    # Phase transitions - shared states with guards for phase-dependent routing
+    do_connect = idle.to(receiving)
+    filter_telegram = receiving.to(receiving)  # Self-transition: drain to /dev/null
+    do_timeout = receiving.to(resetting) | waiting_ok.to(receiving)
+    send_error_status = resetting.to(waiting_ok)
+    error_status_received = waiting_ok.to(
+        receiving, cond="can_retry"
+    )  # Retry if under limit
+
+    # Conditional transitions based on phase
+    no_error_status_received = waiting_ok.to(
+        requesting, cond="is_init_phase"
+    ) | waiting_ok.to(completed, cond="is_cleanup_phase")
+
+    # DOWNLOAD phase transitions
+    send_download = requesting.to(waiting_data)
+    receive_chunk = waiting_data.to(receiving_chunk)
+    send_ack = receiving_chunk.to(waiting_data)
+    receive_eof = waiting_data.to(processing_eof)
+
+    # Return to drain/reset cycle for CLEANUP phase
+    do_finish = processing_eof.to(receiving)
+
+    def __init__(self) -> None:
+        """Initialize the state machine."""
+        self.logger = logging.getLogger(__name__)
+        self._phase: Phase = Phase.INIT
+        self._error_retry_count: int = 0
+
+        # Initialize state machine
+        super().__init__(allow_event_without_transition=True)
+
+    @property
+    def phase(self) -> Phase:
+        """Get current phase."""
+        return self._phase
+
+    @phase.setter
+    def phase(self, value: Phase) -> None:
+        """Set current phase.
+
+        Args:
+            value: The phase value to set.
+        """
+        self._phase = value
+
+    @property
+    def error_retry_count(self) -> int:
+        """Get current error retry count."""
+        return self._error_retry_count
+
+    @error_retry_count.setter
+    def error_retry_count(self, value: int) -> None:
+        """Set error retry count.
+
+        Args:
+            value: The error retry count value to set.
+        """
+        self._error_retry_count = value
+
+    # Guard conditions for phase-dependent transitions
+
+    def is_init_phase(self) -> bool:
+        """Guard: check if currently in INIT phase.
+
+        Returns:
+            True if in INIT phase, False otherwise.
+        """
+        return self._phase == Phase.INIT
+
+    def is_cleanup_phase(self) -> bool:
+        """Guard: check if currently in CLEANUP phase.
+
+        Returns:
+            True if in CLEANUP phase, False otherwise.
+        """
+        return self._phase == Phase.CLEANUP
+
+    def can_retry(self) -> bool:
+        """Guard: check if retry is allowed (under max limit).
+
+        Returns:
+            True if retry count is under MAX_ERROR_RETRIES, False otherwise.
+        """
+        return self._error_retry_count < MAX_ERROR_RETRIES
+
+    # State entry hooks - subclasses MUST implement these
+
+    @abstractmethod
+    def on_enter_receiving(self) -> None:
+        """Enter receiving state - drain pending telegrams."""
+        ...
+
+    @abstractmethod
+    def on_enter_resetting(self) -> None:
+        """Enter resetting state - query error status."""
+        ...
+
+    @abstractmethod
+    def on_enter_waiting_ok(self) -> None:
+        """Enter waiting_ok state - awaiting error status response."""
+        ...
+
+    @abstractmethod
+    def on_enter_requesting(self) -> None:
+        """Enter requesting state - send download request."""
+        ...
+
+    @abstractmethod
+    def on_enter_waiting_data(self) -> None:
+        """Enter waiting_data state - wait for actiontable chunks."""
+        ...
+
+    @abstractmethod
+    def on_enter_receiving_chunk(self) -> None:
+        """Enter receiving_chunk state - send ACK."""
+        ...
+
+    @abstractmethod
+    def on_enter_processing_eof(self) -> None:
+        """Enter processing_eof state - deserialize and emit result."""
+        ...
+
+    @abstractmethod
+    def on_enter_completed(self) -> None:
+        """Enter completed state - download finished."""
+        ...
+
+    @abstractmethod
+    def on_max_retries_exceeded(self) -> None:
+        """Called when max error retries exceeded."""
+        ...
+
+    # Public methods for state machine control
+
+    def enter_download_phase(self) -> None:
+        """Enter requesting state - send download request."""
+        self._phase = Phase.DOWNLOAD
+
+    def handle_no_error_received(self) -> None:
+        """Handle successful error status check (no error)."""
+        self._error_retry_count = 0  # Reset on success
+        self.no_error_status_received()
+
+    def handle_error_received(self) -> None:
+        """Handle error status received - increment retry and attempt transition."""
+        self._error_retry_count += 1
+        self.logger.debug(
+            f"Error status received, retry {self._error_retry_count}/{MAX_ERROR_RETRIES}"
+        )
+        # Guard can_retry blocks transition if max retries exceeded
+        self.error_status_received()
+        # Check if guard blocked the transition (still in waiting_ok)
+        if self.waiting_ok.is_active:
+            self.on_max_retries_exceeded()
+
+    def start_cleanup_phase(self) -> None:
+        """Switch to CLEANUP phase and trigger do_finish transition."""
+        self._phase = Phase.CLEANUP
+        self.do_finish()
+
+    def reset(self) -> None:
+        """Reset state machine to initial state."""
+        self._phase = Phase.INIT
+        self._error_retry_count = 0
+        # python-statemachine uses model.state to track current state
+        self.model.state = self.idle.id