conson-xp 1.46.0__py3-none-any.whl → 1.48.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/{conbus/actiontable/actiontable_download_state_machine.py → actiontable/download_state_machine.py}

@@ -9,10 +9,11 @@ from statemachine.factory import StateMachineMetaclass
 
 
 class AbstractStateMachineMeta(StateMachineMetaclass, ABCMeta):
-    """Combined metaclass for abstract state machines.
+    """
+    Combined metaclass for abstract state machines.
 
-    Combines StateMachineMetaclass (for state machine introspection) with
-    ABCMeta (for abstract method enforcement).
+    Combines StateMachineMetaclass (for state machine introspection) with ABCMeta (for
+    abstract method enforcement).
     """
 
     pass
@@ -23,7 +24,8 @@ MAX_ERROR_RETRIES = 3  # Max retries for error_status_received before giving up
 
 
 class Phase(Enum):
-    """Download workflow phases.
+    """
+    Download workflow phases.
 
     The download workflow consists of three sequential phases:
     - INIT: Drain pending telegrams, query error status → proceed to DOWNLOAD
@@ -41,8 +43,9 @@ class Phase(Enum):
     CLEANUP = "cleanup"
 
 
-class ActionTableDownloadStateMachine(StateMachine, metaclass=AbstractStateMachineMeta):
-    """State machine for ActionTable download workflow.
+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.
@@ -146,7 +149,8 @@ class ActionTableDownloadStateMachine(StateMachine, metaclass=AbstractStateMachi
 
     @phase.setter
     def phase(self, value: Phase) -> None:
-        """Set current phase.
+        """
+        Set current phase.
 
         Args:
             value: The phase value to set.
@@ -160,7 +164,8 @@ class ActionTableDownloadStateMachine(StateMachine, metaclass=AbstractStateMachi
 
     @error_retry_count.setter
     def error_retry_count(self, value: int) -> None:
-        """Set error retry count.
+        """
+        Set error retry count.
 
         Args:
             value: The error retry count value to set.

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,65 @@ 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 < 64:  # Minimum: 4 char prefix + 64 chars data
+            raise ValueError(
+                f"XP20 action table data must be 64 characters long, got {len(encoded_data)}"
+            )
+
+        raw_bytes = de_nibbles(encoded_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
@@ -60,59 +103,38 @@ class Xp20MsActionTableSerializer:
 
         encoded_data = nibbles(raw_bytes)
         # Convert raw bytes to hex string with A-P encoding
-        return "AAAA" + encoded_data
+        return 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 +168,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

xp/services/actiontable/msactiontable_xp24_serializer.py

@@ -2,34 +2,77 @@
 
 from xp.models.actiontable.msactiontable_xp24 import InputAction, Xp24MsActionTable
 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 de_nibbles, nibbles
 
 
-class Xp24MsActionTableSerializer:
+class Xp24MsActionTableSerializer(ActionTableSerializerProtocol):
     """Handles serialization/deserialization of XP24 action tables to/from telegrams."""
 
     @staticmethod
-    def format_decoded_output(action_table: Xp24MsActionTable) -> list[str]:
-        """Serialize XP24 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) -> Xp24MsActionTable:
+        """
+        Deserialize action table from raw data parts.
 
         Args:
-            action_table: XP24 action table to serialize
+            encoded_data: Raw action table data string.
 
         Returns:
-            Human-readable string describing XP24 action table
+            Deserialized XP24 MS action table.
+
+        Raises:
+            ValueError: If data length is not 68 bytes.
         """
-        return action_table.to_short_format()
+        raw_length = len(encoded_data)
+        if raw_length != 64:
+            raise ValueError(
+                f"Msactiontable is not 64 bytes long ({raw_length}): {encoded_data}"
+            )
+
+        # Convert hex string to bytes using deNibble (A-P encoding)
+        data = de_nibbles(encoded_data)
+
+        # Decode input actions from positions 0-3 (2 bytes each)
+        input_actions = []
+        for pos in range(4):
+            input_action = Xp24MsActionTableSerializer._decode_input_action(data, pos)
+            input_actions.append(input_action)
+
+        action_table = Xp24MsActionTable(
+            input1_action=input_actions[0],
+            input2_action=input_actions[1],
+            input3_action=input_actions[2],
+            input4_action=input_actions[3],
+            mutex12=data[8] != 0,  # With A-P encoding: AA=0 (False), AB=1 (True)
+            mutex34=data[9] != 0,
+            mutual_deadtime=data[10],
+            curtain12=data[11] != 0,
+            curtain34=data[12] != 0,
+        )
+        return action_table
 
     @staticmethod
-    def to_data(action_table: Xp24MsActionTable) -> str:
-        """Serialize action table to telegram format.
+    def to_encoded_string(action_table: Xp24MsActionTable) -> str:
+        """
+        Serialize action table to telegram format.
 
         Args:
             action_table: XP24 MS action table to serialize.
 
         Returns:
-            Serialized action table data string (68 characters).
+            Serialized action table data string (64 characters).
         """
         # Build byte array for the action table (32 bytes total)
         raw_bytes = bytearray()
@@ -56,64 +99,40 @@ class Xp24MsActionTableSerializer:
         # Add padding to reach 32 bytes (19 more bytes needed)
         raw_bytes.extend([0x00] * 19)
 
-        # Encode to A-P nibbles (32 bytes -> 64 chars)
-        encoded_data = nibbles(bytes(raw_bytes))
-
+        # Build byte array for the action table (32 bytes total)
         # Prepend action table count "AAAA" (4 chars) -> total 68 chars
-        return "AAAA" + encoded_data
+        return nibbles(raw_bytes)
 
     @staticmethod
-    def from_data(msactiontable_rawdata: str) -> Xp24MsActionTable:
-        """Deserialize action table from raw data parts.
+    def to_short_string(action_table: Xp24MsActionTable) -> list[str]:
+        """
+        Serialize XP24 action table to humane compact readable format.
 
         Args:
-            msactiontable_rawdata: Raw action table data string.
+            action_table: XP24 action table to serialize
 
         Returns:
-            Deserialized XP24 MS action table.
-
-        Raises:
-            ValueError: If data length is not 68 bytes.
+            Human-readable string describing XP24 action table
         """
-        raw_length = len(msactiontable_rawdata)
-        if raw_length != 68:
-            raise ValueError(
-                f"Msactiontable is not 68 bytes long ({raw_length}): {msactiontable_rawdata}"
-            )
-
-        # Remove action table count AAAA, AAAB .
-        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]) -> Xp24MsActionTable:
+        """
+        Serialize XP24 action table to humane compact readable format.
 
-        # Decode input actions from positions 0-3 (2 bytes each)
-        input_actions = []
-        for pos in range(4):
-            input_action = Xp24MsActionTableSerializer._decode_input_action(
-                raw_bytes, pos
-            )
-            input_actions.append(input_action)
+        Args:
+            action_strings: XP24 action table to serialize
 
-        action_table = Xp24MsActionTable(
-            input1_action=input_actions[0],
-            input2_action=input_actions[1],
-            input3_action=input_actions[2],
-            input4_action=input_actions[3],
-            mutex12=raw_bytes[8] != 0,  # With A-P encoding: AA=0 (False), AB=1 (True)
-            mutex34=raw_bytes[9] != 0,
-            mutual_deadtime=raw_bytes[10],
-            curtain12=raw_bytes[11] != 0,
-            curtain34=raw_bytes[12] != 0,
-        )
-        return action_table
+        Returns:
+            Human-readable string describing XP24 action table
+        """
+        return Xp24MsActionTable.from_short_format(action_strings)
 
     @staticmethod
-    def _decode_input_action(raw_bytes: bytearray, pos: int) -> InputAction:
-        """Decode input action from raw bytes.
+    def _decode_input_action(raw_bytes: bytes, pos: int) -> InputAction:
+        """
+        Decode input action from raw bytes.
 
         Args:
             raw_bytes: Raw byte array containing action data.

xp/services/actiontable/msactiontable_xp33_serializer.py

@@ -5,16 +5,29 @@ from xp.models.actiontable.msactiontable_xp33 import (
     Xp33Output,
     Xp33Scene,
 )
+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 bits_to_byte, byte_to_bits, de_nibbles, nibbles
 
 
-class Xp33MsActionTableSerializer:
+class Xp33MsActionTableSerializer(ActionTableSerializerProtocol):
     """Handles serialization/deserialization of XP33 action tables to/from telegrams."""
 
     @staticmethod
-    def format_decoded_output(action_table: Xp33MsActionTable) -> list[str]:
-        """Serialize XP33 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 to_short_string(action_table: Xp33MsActionTable) -> list[str]:
+        """
+        Serialize XP33 action table to humane compact readable format.
 
         Args:
             action_table: XP33 action table to serialize
@@ -24,6 +37,19 @@ class Xp33MsActionTableSerializer:
         """
         return action_table.to_short_format()
 
+    @staticmethod
+    def from_short_string(action_strings: list[str]) -> Xp33MsActionTable:
+        """
+        Serialize XP33 action table to humane compact readable format.
+
+        Args:
+            action_strings: XP33 action table to serialize
+
+        Returns:
+            Human-readable string describing XP33 action table
+        """
+        return Xp33MsActionTable.from_short_format(action_strings)
+
     @staticmethod
     def _percentage_to_byte(percentage: int) -> int:
         """Convert percentage (0-100) to byte value for telegram encoding."""
@@ -48,8 +74,9 @@ class Xp33MsActionTableSerializer:
             return TimeParam.NONE
 
     @staticmethod
-    def to_data(action_table: Xp33MsActionTable) -> str:
-        """Serialize action table to telegram format.
+    def to_encoded_string(action_table: Xp33MsActionTable) -> str:
+        """
+        Serialize action table to telegram format.
 
         Args:
             action_table: XP33 MS action table to serialize.
@@ -112,11 +139,12 @@ class Xp33MsActionTableSerializer:
         encoded_data = nibbles(raw_bytes)
 
         # Convert raw bytes to hex string with A-P encoding
-        return "AAAA" + encoded_data
+        return encoded_data
 
     @staticmethod
-    def from_data(msactiontable_rawdata: str) -> Xp33MsActionTable:
-        """Deserialize action table from raw data parts.
+    def from_encoded_string(msactiontable_rawdata: str) -> Xp33MsActionTable:
+        """
+        Deserialize action table from raw data parts.
 
         Args:
             msactiontable_rawdata: Raw action table data string.
@@ -125,22 +153,16 @@ class Xp33MsActionTableSerializer:
             Deserialized XP33 MS action table.
 
         Raises:
-            ValueError: If data length is less than 68 characters.
+            ValueError: If data length is less than 64 characters.
         """
         raw_length = len(msactiontable_rawdata)
-        if raw_length < 68:  # Minimum: 4 char prefix + 64 chars data
+        if raw_length < 64:  # Minimum: 4 char prefix + 64 chars data
             raise ValueError(
-                f"Msactiontable is too short ({raw_length}), minimum 68 characters required"
+                f"Msactiontable is too short ({raw_length}), minimum 64 characters required"
             )
 
-        # 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]
-
         # Convert hex string to bytes using deNibble (A-P encoding)
-        raw_bytes = de_nibbles(hex_data)
+        raw_bytes = de_nibbles(msactiontable_rawdata)
 
         # Decode outputs
         output1 = Xp33MsActionTableSerializer._decode_output(raw_bytes, 0)
@@ -165,7 +187,8 @@ 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.
@@ -219,7 +242,8 @@ 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.