conson-xp 1.45.0__py3-none-any.whl → 1.47.0__py3-none-any.whl

xp/services/actiontable/actiontable_serializer.py

@@ -5,7 +5,9 @@ import re
 from xp.models import ModuleTypeCode
 from xp.models.actiontable.actiontable import ActionTable, ActionTableEntry
 from xp.models.telegram.input_action_type import InputActionType
+from xp.models.telegram.system_function import SystemFunction
 from xp.models.telegram.timeparam_type import TimeParam
+from xp.services.actiontable.serializer_protocol import ActionTableSerializerProtocol
 from xp.utils.serialization import (
     byte_to_unsigned,
     de_bcd,
@@ -19,8 +21,9 @@ from xp.utils.serialization import (
 )
 
 
-class ActionTableSerializer:
-    """Handles serialization/deserialization of ActionTable to/from telegrams.
+class ActionTableSerializer(ActionTableSerializerProtocol):
+    """
+    Handles serialization/deserialization of ActionTable to/from telegrams.
 
     Attributes:
         MAX_ENTRIES: Maximum number of entries in an ActionTable (96).
@@ -29,15 +32,27 @@ class ActionTableSerializer:
     MAX_ENTRIES = 96  # ActionTable must always contain exactly 96 entries
 
     @staticmethod
-    def from_data(data: bytes) -> ActionTable:
-        """Deserialize telegram data to ActionTable.
+    def download_type() -> SystemFunction:
+        """
+        Get the download system function type.
+
+        Returns:
+            The download system function: DOWNLOAD_ACTIONTABLE
+        """
+        return SystemFunction.DOWNLOAD_ACTIONTABLE
+
+    @staticmethod
+    def from_encoded_string(encoded_data: str) -> ActionTable:
+        """
+        Deserialize telegram data to ActionTable.
 
         Args:
-            data: Raw byte data from telegram
+            encoded_data: Raw byte data from telegram
 
         Returns:
             Decoded ActionTable
         """
+        data = de_nibbles(encoded_data)
         entries = []
 
         # Process data in 5-byte chunks
@@ -92,14 +107,15 @@ class ActionTableSerializer:
         return ActionTable(entries=entries)
 
     @staticmethod
-    def to_data(action_table: ActionTable) -> bytes:
-        """Serialize ActionTable to telegram byte data.
+    def to_encoded_string(action_table: ActionTable) -> str:
+        """
+        Convert ActionTable to base64-encoded string format.
 
         Args:
-            action_table: ActionTable to serialize
+            action_table: ActionTable to encode
 
         Returns:
-            Raw byte data for telegram (always 480 bytes for 96 entries)
+            Base64-encoded string representation
         """
         data = bytearray()
 
@@ -128,37 +144,12 @@ class ActionTableSerializer:
             for _ in range(ActionTableSerializer.MAX_ENTRIES - current_entries):
                 data.extend(padding_bytes)
 
-        return bytes(data)
-
-    @staticmethod
-    def to_encoded_string(action_table: ActionTable) -> str:
-        """Convert ActionTable to base64-encoded string format.
-
-        Args:
-            action_table: ActionTable to encode
-
-        Returns:
-            Base64-encoded string representation
-        """
-        data = ActionTableSerializer.to_data(action_table)
         return nibbles(data)
 
     @staticmethod
-    def from_encoded_string(encoded_data: str) -> ActionTable:
-        """Convert base64-encoded string to ActionTable.
-
-        Args:
-            encoded_data: Base64-encoded string
-
-        Returns:
-            Decoded ActionTable
+    def to_short_string(action_table: ActionTable) -> list[str]:
         """
-        data = de_nibbles(encoded_data)
-        return ActionTableSerializer.from_data(data)
-
-    @staticmethod
-    def format_decoded_output(action_table: ActionTable) -> list[str]:
-        """Format ActionTable as human-readable decoded output.
+        Format ActionTable as human-readable decoded output.
 
         Args:
             action_table: ActionTable to format
@@ -194,8 +185,9 @@ class ActionTableSerializer:
         return lines
 
     @staticmethod
-    def parse_action_string(action_str: str) -> ActionTableEntry:
-        """Parse action table entry from string format.
+    def _parse_action_string(action_str: str) -> ActionTableEntry:
+        """
+        Parse action table entry from string format.
 
         Args:
             action_str: String in format "CP20 0 0 > 1 OFF" or "CP20 0 1 > 1 ~ON"
@@ -257,8 +249,9 @@ class ActionTableSerializer:
         )
 
     @staticmethod
-    def parse_action_table(action_strings: list[str]) -> ActionTable:
-        """Parse action table from list of string entries.
+    def from_short_string(action_strings: list[str]) -> ActionTable:
+        """
+        Parse action table from short string representation.
 
         Args:
             action_strings: List of action strings from conson.yml
@@ -267,7 +260,7 @@ class ActionTableSerializer:
             Parsed ActionTable
         """
         entries = [
-            ActionTableSerializer.parse_action_string(action_str)
+            ActionTableSerializer._parse_action_string(action_str)
             for action_str in action_strings
         ]
         return ActionTable(entries=entries)

xp/services/actiontable/download_state_machine.py

@@ -0,0 +1,281 @@
+"""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 DownloadStateMachine(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

xp/services/actiontable/msactiontable_xp20_serializer.py

@@ -1,6 +1,8 @@
 """Serializer for XP20 Action Table telegram encoding/decoding."""
 
 from xp.models.actiontable.msactiontable_xp20 import InputChannel, Xp20MsActionTable
+from xp.models.telegram.system_function import SystemFunction
+from xp.services.actiontable.serializer_protocol import ActionTableSerializerProtocol
 from xp.utils.serialization import byte_to_bits, de_nibbles, nibbles
 
 # Index constants for clarity in implementation
@@ -12,24 +14,70 @@ SA_FUNCTION_INDEX: int = 11
 TA_FUNCTION_INDEX: int = 12
 
 
-class Xp20MsActionTableSerializer:
+class Xp20MsActionTableSerializer(ActionTableSerializerProtocol):
     """Handles serialization/deserialization of XP20 action tables to/from telegrams."""
 
     @staticmethod
-    def format_decoded_output(action_table: Xp20MsActionTable) -> list[str]:
-        """Serialize XP20 action table to humane compact readable format.
+    def download_type() -> SystemFunction:
+        """
+        Get the download system function type.
+
+        Returns:
+            The download system function: DOWNLOAD_MSACTIONTABLE
+        """
+        return SystemFunction.DOWNLOAD_MSACTIONTABLE
+
+    @staticmethod
+    def from_encoded_string(encoded_data: str) -> Xp20MsActionTable:
+        """
+        Deserialize telegram data to XP20 action table.
 
         Args:
-            action_table: XP20 action table to serialize
+            encoded_data: 64-character hex string with A-P encoding
 
         Returns:
-            Human-readable string describing XP20 action table
+            Decoded XP20 action table
+
+        Raises:
+            ValueError: If input length is not 64 characters
         """
-        return action_table.to_short_format()
+        raw_length = len(encoded_data)
+        if raw_length < 68:  # Minimum: 4 char prefix + 64 chars data
+            raise ValueError(
+                f"XP20 action table data must be 68 characters long, got {len(encoded_data)}"
+            )
+
+        # Remove action table count prefix (first 4 characters: AAAA, AAAB, etc.)
+        data = encoded_data[4:]
+
+        # Take first 64 chars (32 bytes) as per pseudocode
+        hex_data = data[:64]
+        raw_bytes = de_nibbles(hex_data)
+
+        # Decode input channels
+        input_channels = []
+        for input_index in range(8):
+            input_channel = Xp20MsActionTableSerializer._decode_input_channel(
+                raw_bytes, input_index
+            )
+            input_channels.append(input_channel)
+
+        # Create and return XP20 action table
+        return Xp20MsActionTable(
+            input1=input_channels[0],
+            input2=input_channels[1],
+            input3=input_channels[2],
+            input4=input_channels[3],
+            input5=input_channels[4],
+            input6=input_channels[5],
+            input7=input_channels[6],
+            input8=input_channels[7],
+        )
 
     @staticmethod
-    def to_data(action_table: Xp20MsActionTable) -> str:
-        """Serialize XP20 action table to telegram hex string format.
+    def to_encoded_string(action_table: Xp20MsActionTable) -> str:
+        """
+        Serialize XP20 action table to telegram hex string format.
 
         Args:
             action_table: XP20 action table to serialize
@@ -63,56 +111,35 @@ class Xp20MsActionTableSerializer:
         return "AAAA" + encoded_data
 
     @staticmethod
-    def from_data(msactiontable_rawdata: str) -> Xp20MsActionTable:
-        """Deserialize telegram data to XP20 action table.
+    def to_short_string(action_table: Xp20MsActionTable) -> list[str]:
+        """
+        Serialize XP20 action table to humane compact readable format.
 
         Args:
-            msactiontable_rawdata: 64-character hex string with A-P encoding
+            action_table: XP20 action table to serialize
 
         Returns:
-            Decoded XP20 action table
-
-        Raises:
-            ValueError: If input length is not 64 characters
+            Human-readable string describing XP20 action table
         """
-        raw_length = len(msactiontable_rawdata)
-        if raw_length < 68:  # Minimum: 4 char prefix + 64 chars data
-            raise ValueError(
-                f"XP20 action table data must be 68 characters long, got {len(msactiontable_rawdata)}"
-            )
-
-        # Remove action table count prefix (first 4 characters: AAAA, AAAB, etc.)
-        data = msactiontable_rawdata[4:]
-
-        # Take first 64 chars (32 bytes) as per pseudocode
-        hex_data = data[:64]
+        return action_table.to_short_format()
 
-        # Convert hex string to bytes using deNibble (A-P encoding)
-        raw_bytes = de_nibbles(hex_data)
+    @staticmethod
+    def from_short_string(action_strings: list[str]) -> Xp20MsActionTable:
+        """
+        Parse XP20 action table from short string format.
 
-        # Decode input channels
-        input_channels = []
-        for input_index in range(8):
-            input_channel = Xp20MsActionTableSerializer._decode_input_channel(
-                raw_bytes, input_index
-            )
-            input_channels.append(input_channel)
+        Args:
+            action_strings: List of short format strings to parse
 
-        # Create and return XP20 action table
-        return Xp20MsActionTable(
-            input1=input_channels[0],
-            input2=input_channels[1],
-            input3=input_channels[2],
-            input4=input_channels[3],
-            input5=input_channels[4],
-            input6=input_channels[5],
-            input7=input_channels[6],
-            input8=input_channels[7],
-        )
+        Returns:
+            Parsed XP20 action table
+        """
+        return Xp20MsActionTable.from_short_format(action_strings)
 
     @staticmethod
-    def _decode_input_channel(raw_bytes: bytearray, input_index: int) -> InputChannel:
-        """Extract input channel configuration from raw bytes.
+    def _decode_input_channel(raw_bytes: bytes, input_index: int) -> InputChannel:
+        """
+        Extract input channel configuration from raw bytes.
 
         Args:
             raw_bytes: Raw byte array from telegram
@@ -146,7 +173,8 @@ class Xp20MsActionTableSerializer:
     def _encode_input_channel(
         input_channel: InputChannel, input_index: int, raw_bytes: bytearray
     ) -> None:
-        """Encode input channel configuration into raw bytes.
+        """
+        Encode input channel configuration into raw bytes.
 
         Args:
             input_channel: Input channel configuration to encode