virtual-drive 0.1.0__py3-none-any.whl

virtual_drive/__init__.py

@@ -0,0 +1,9 @@
+try:
+    from ._version import __version__  # noqa: F401
+except ModuleNotFoundError:
+    __version__ = "development"
+
+
+__all__ = [
+    "__version__",
+]

virtual_drive/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'gb9be2494f'

virtual_drive/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""Protocol adapters implemented by the runtime."""
+
+from virtual_drive.adapters.dispatcher import FrameDispatcher
+from virtual_drive.adapters.mcb import MCBAdapter
+from virtual_drive.adapters.protocol import ProtocolAdapter
+from virtual_drive.adapters.sdo import SDOAdapter
+
+__all__ = ["FrameDispatcher", "MCBAdapter", "SDOAdapter", "ProtocolAdapter"]

virtual_drive/adapters/dispatcher.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ingenialink.dictionary import Interface
+
+from virtual_drive.adapters.mcb import MCBAdapter
+from virtual_drive.adapters.protocol import (
+    OperationResult,
+    ProtocolAdapter,
+)
+from virtual_drive.adapters.sdo import SDOAdapter
+
+if TYPE_CHECKING:
+    from virtual_drive.register_service import RegisterService
+
+
+class FrameDispatcher:
+    """Dispatch incoming frames through a configured protocol adapter."""
+
+    def __init__(
+        self,
+        register_service: RegisterService,
+        protocol: Interface = Interface.ETH,
+        adapter: ProtocolAdapter | None = None,
+    ) -> None:
+        self._register_service = register_service
+        self._adapter = adapter if adapter is not None else self._build_adapter(protocol)
+
+    def dispatch(self, frame: bytes) -> bytes | None:
+        """Return the response for a frame, or ``None`` if it cannot be handled.
+
+        Args:
+            frame: Incoming frame to be dispatched.
+
+        Returns:
+            The response frame, or ``None`` if the frame cannot be handled.
+
+        """
+        try:
+            request = self._adapter.parse_request(frame)
+        except Exception:
+            return None
+
+        if self._adapter.is_unknown_operation(request):
+            result = OperationResult(success=False, value=None)
+            return self._adapter.build_response(request, result)
+        register = None
+        operation_error = None
+        try:
+            register = self._adapter.resolve_register(self._register_service, request)
+            if self._adapter.is_write_operation(request):
+                value = self._adapter.decode_write_value(register, request)
+                self._register_service.write(register, value)
+                result = OperationResult(success=True, value=None)
+            else:
+                value = self._register_service.read(register)
+                result = OperationResult(success=True, value=value)
+        except Exception as error:
+            operation_error = error
+            result = OperationResult(success=False, value=None)
+
+        return self._adapter.build_response(request, result, register, operation_error)
+
+    @staticmethod
+    def _build_adapter(protocol: Interface) -> ProtocolAdapter:
+        """Instantiate the adapter for the selected protocol.
+
+        Args:
+            protocol: Interface value used to select the protocol adapter.
+
+        Returns:
+            ProtocolAdapter: Adapter instance for the configured protocol.
+
+        Raises:
+            ValueError: If the interface is not supported.
+
+        """
+        if protocol == Interface.ETH:
+            return MCBAdapter()
+        if protocol in (Interface.ECAT, Interface.CAN):
+            return SDOAdapter()
+        raise ValueError(f"Unsupported protocol interface '{protocol.name}'.")

virtual_drive/adapters/mcb.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from ingenialink.utils._utils import convert_bytes_to_dtype, convert_dtype_to_bytes
+from ingenialink.utils.mcb import MCB
+
+if TYPE_CHECKING:
+    from ingenialink.register import Register
+
+    from virtual_drive.register_service import RegisterService
+    from virtual_drive.register_service.register_value import RegisterValue
+
+from virtual_drive.adapters.protocol import (
+    MCBOperationRequest,
+    MCBOperationType,
+    OperationRequest,
+    OperationResult,
+    ProtocolAdapter,
+)
+from virtual_drive.exceptions import OPERATION_NOT_EXECUTED_ERROR_CODE, VirtualDriveError
+
+
+class MCBCommand(Enum):
+    """Enum of the MCB commands."""
+
+    READ = 1
+    WRITE = 2
+    ACK = 3
+    ERROR_READ = 5
+    ERROR_WRITE = 6
+
+
+class MCBAdapter(ProtocolAdapter):
+    """Simple adapter that understands the IngeniaLink MCB/UDP protocol."""
+
+    def parse_request(self, frame: bytes) -> OperationRequest:
+        """Parse the MCB request frame into an operation request.
+
+        Returns:
+            OperationRequest: Parsed operation request data.
+
+        """
+        address, axis, command, data = MCB.read_mcb_frame(frame)
+        if command == MCBCommand.WRITE.value:
+            operation = MCBOperationType.WRITE
+        elif command == MCBCommand.READ.value:
+            operation = MCBOperationType.READ
+        else:
+            operation = MCBOperationType.UNKNOWN
+        return MCBOperationRequest(axis=axis, address=address, operation=operation, data=data)
+
+    def is_unknown_operation(self, request: OperationRequest) -> bool:
+        """Return whether the request operation is unsupported."""
+        mcb_request = self._as_mcb_request(request)
+        return mcb_request.operation is MCBOperationType.UNKNOWN
+
+    def is_write_operation(self, request: OperationRequest) -> bool:
+        """Return whether the request operation writes a register value."""
+        mcb_request = self._as_mcb_request(request)
+        return mcb_request.operation is MCBOperationType.WRITE
+
+    def resolve_register(
+        self,
+        register_service: RegisterService,
+        request: OperationRequest,
+    ) -> Register:
+        """Resolve the addressed register from an MCB request.
+
+        Returns:
+            Register: Register identified by axis/address in the request.
+
+        """
+        mcb_request = self._as_mcb_request(request)
+        return register_service.get_register_by_address(mcb_request.axis, mcb_request.address)
+
+    def decode_write_value(self, register: Register, request: OperationRequest) -> RegisterValue:
+        """Decode the write payload into a register value.
+
+        Returns:
+            RegisterValue: The decoded register value.
+
+        """
+        return convert_bytes_to_dtype(request.data, register.dtype)
+
+    def build_response(
+        self,
+        request: OperationRequest,
+        result: OperationResult,
+        register: Register | None = None,
+        error: Exception | None = None,
+    ) -> bytes:
+        """Return the response frame for the provided MCB request."""
+        mcb_request = self._as_mcb_request(request)
+        axis, address = mcb_request.axis, mcb_request.address
+        if not result.success:
+            return self._build_error_frame(mcb_request, error)
+        if mcb_request.operation is MCBOperationType.WRITE:
+            payload = mcb_request.data[:8]
+            return MCB.build_mcb_frame(MCBCommand.ACK.value, axis, address, payload)
+        if register is None or result.value is None:
+            return self._build_error_frame(mcb_request, None)
+        payload = self._encode_read_value(register, result.value)
+        return MCB.build_mcb_frame(MCBCommand.ACK.value, axis, address, payload)
+
+    @staticmethod
+    def _as_mcb_request(request: OperationRequest) -> MCBOperationRequest:
+        if not isinstance(request, MCBOperationRequest):
+            raise TypeError("MCBAdapter requires MCBOperationRequest")
+        return request
+
+    @staticmethod
+    def _encode_read_value(register: Register, value: RegisterValue) -> bytes:
+        if isinstance(value, bytes):
+            return value
+        return convert_dtype_to_bytes(value, register.dtype)
+
+    def _build_error_frame(
+        self,
+        request: MCBOperationRequest,
+        error: Exception | None,
+    ) -> bytes:
+        """Build an MCB error response with an embedded protocol error code.
+
+        Args:
+            request: Original parsed MCB request.
+            error: The operation error that triggered the failure, if any.
+
+        Returns:
+            bytes: MCB error frame with the 32-bit error code in config payload.
+
+        """
+        command = self._resolve_error_command(request.operation)
+        payload = self._build_error_payload(self._resolve_error_code(error))
+        return MCB.build_mcb_frame(command.value, request.axis, request.address, payload)
+
+    @staticmethod
+    def _resolve_error_command(operation: MCBOperationType) -> MCBCommand:
+        """Resolve the MCB error command to be used in the error response frame.
+
+        Args:
+            operation: The type of the original request operation that failed.
+
+        Returns:
+            The corresponding MCB error command for the failed operation.
+
+        """
+        if operation is MCBOperationType.WRITE:
+            return MCBCommand.ERROR_WRITE
+        return MCBCommand.ERROR_READ
+
+    @staticmethod
+    def _build_error_payload(error_code: int) -> bytes:
+        """Build the MCB error frame payload containing the 32-bit error code.
+
+        Args:
+            error_code: The protocol-specific error code to be embedded in the frame.
+
+        Returns:
+            A bytes object of length 8, where the first 4 bytes represent the error code
+            in little-endian format, and the remaining 4 bytes are padding.
+
+        """
+        return error_code.to_bytes(8, byteorder="little", signed=False)
+
+    @staticmethod
+    def _resolve_error_code(error: Exception | None) -> int:
+        """Resolve the protocol error code to be embedded in the MCB error frame.
+
+        Args:
+            error: The original exception that caused the operation to fail, if any.
+
+        Returns:
+            The protocol-specific error code extracted from the exception, or a default
+             code if the error is not a VirtualDriveError or is None.
+
+        """
+        if isinstance(error, VirtualDriveError):
+            return error.error_code
+        return OPERATION_NOT_EXECUTED_ERROR_CODE

virtual_drive/adapters/protocol.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Protocol, Union
+
+if TYPE_CHECKING:
+    from ingenialink.register import Register
+
+    from virtual_drive.register_service import RegisterService
+    from virtual_drive.register_service.register_value import RegisterValue
+
+
+class MCBOperationType(Enum):
+    """Register operations represented by incoming MCB frames."""
+
+    READ = "read"
+    WRITE = "write"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class MCBOperationRequest:
+    """Operation extracted from an MCB protocol frame.
+
+    Attributes:
+        axis: Target axis/subnode from the frame.
+        address: Register address to access.
+        operation: Register operation to execute.
+        data: Raw protocol payload associated with the request.
+
+    """
+
+    axis: int
+    address: int
+    operation: MCBOperationType
+    data: bytes
+
+
+class SDOOperationType(Enum):
+    """Register operations represented by incoming SDO frames."""
+
+    READ = "read"
+    WRITE = "write"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class SDOOperationRequest:
+    """Operation extracted from an SDO protocol frame.
+
+    Attributes:
+        index: Object dictionary index.
+        subindex: Object dictionary subindex.
+        operation: Register operation to execute.
+        data: Raw protocol payload associated with the request.
+
+    """
+
+    index: int
+    subindex: int
+    operation: SDOOperationType
+    data: bytes
+
+
+OperationRequest = Union[MCBOperationRequest, SDOOperationRequest]
+
+
+@dataclass(frozen=True)
+class OperationResult:
+    """Result of executing a normalized register operation.
+
+    Attributes:
+        success: Whether the operation completed successfully.
+        value: Read value for successful read operations, otherwise ``None``.
+
+    """
+
+    success: bool
+    value: RegisterValue | None
+
+
+class ProtocolAdapter(Protocol):
+    """Adapter contract for translating frames to/from register operations.
+
+    Implementations are responsible for protocol-specific parsing, payload
+    conversion, and response encoding.
+
+    """
+
+    def parse_request(self, frame: bytes) -> OperationRequest:
+        """Decode ``frame`` into a normalized :class:`OperationRequest`."""
+        ...
+
+    def is_unknown_operation(self, request: OperationRequest) -> bool:
+        """Return whether ``request`` represents an unsupported operation."""
+        ...
+
+    def is_write_operation(self, request: OperationRequest) -> bool:
+        """Return whether ``request`` represents a write operation."""
+        ...
+
+    def resolve_register(
+        self,
+        register_service: RegisterService,
+        request: OperationRequest,
+    ) -> Register:
+        """Resolve the target register for ``request`` using ``register_service``."""
+        ...
+
+    def decode_write_value(self, register: Register, request: OperationRequest) -> RegisterValue:
+        """Decode the write payload in ``request`` into a register value.
+
+        Args:
+            register: Target register metadata (dtype, etc.) used for decoding.
+            request: Parsed write request containing protocol payload bytes.
+
+        Returns:
+            RegisterValue: Value ready to be persisted by the register service.
+
+        """
+        ...
+
+    def build_response(
+        self,
+        request: OperationRequest,
+        result: OperationResult,
+        register: Register | None = None,
+        error: Exception | None = None,
+    ) -> bytes:
+        """Encode an outgoing response frame for ``request``.
+
+        Args:
+            request: Original normalized request that triggered the operation.
+            result: Execution outcome used to build ACK/NACK and payload.
+            register: Register metadata, when needed to encode result values.
+            error: Original execution error, when operation failed.
+
+        Returns:
+            bytes: Protocol-specific response frame.
+
+        """
+        ...
+
+
+def is_unknown_operation(request: OperationRequest) -> bool:
+    """Return ``True`` when the request operation is not supported."""
+    if isinstance(request, MCBOperationRequest):
+        return (
+            isinstance(request.operation, MCBOperationType)
+            and request.operation is MCBOperationType.UNKNOWN
+        )
+    return (
+        isinstance(request.operation, SDOOperationType)
+        and request.operation is SDOOperationType.UNKNOWN
+    )
+
+
+def is_write_operation(request: OperationRequest) -> bool:
+    """Return ``True`` when the request is a write operation."""
+    if isinstance(request, MCBOperationRequest):
+        return (
+            isinstance(request.operation, MCBOperationType)
+            and request.operation is MCBOperationType.WRITE
+        )
+    return (
+        isinstance(request.operation, SDOOperationType)
+        and request.operation is SDOOperationType.WRITE
+    )

virtual_drive/adapters/sdo.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ingenialink.utils._utils import convert_bytes_to_dtype, convert_dtype_to_bytes
+
+if TYPE_CHECKING:
+    from ingenialink.register import Register
+
+    from virtual_drive.register_service import RegisterService
+    from virtual_drive.register_service.register_value import RegisterValue
+
+from ingenialink.virtual.codec import deserialize_sdo_frame, serialize_sdo_frame
+
+from virtual_drive.adapters.protocol import (
+    OperationRequest,
+    OperationResult,
+    ProtocolAdapter,
+    SDOOperationRequest,
+    SDOOperationType,
+)
+from virtual_drive.exceptions import (
+    OPERATION_NOT_EXECUTED_ERROR_CODE,
+    InvalidCommandError,
+    VirtualDriveError,
+)
+
+
+class SDOAdapter(ProtocolAdapter):
+    """Adapter for serialized SDO read/write JSON frames."""
+
+    def parse_request(self, frame: bytes) -> OperationRequest:
+        """Parse a serialized SDO JSON request frame.
+
+        Args:
+            frame: Serialized request frame.
+
+        Returns:
+            OperationRequest: Parsed and normalized operation request.
+
+        Raises:
+            InvalidCommandError: If the frame is not a valid serialized SDO request
+                or if the payload type is invalid.
+
+        """
+        try:
+            request = deserialize_sdo_frame(frame)
+        except (UnicodeDecodeError, ValueError, TypeError) as e:
+            raise InvalidCommandError("Invalid serialized SDO frame") from e
+
+        command = request.get("command")
+        if command == "read":
+            operation = SDOOperationType.READ
+        elif command == "write":
+            operation = SDOOperationType.WRITE
+        else:
+            operation = SDOOperationType.UNKNOWN
+
+        index, has_valid_index = self._parse_object_address_field(request, "index")
+        subindex, has_valid_subindex = self._parse_object_address_field(request, "subindex")
+        if not (has_valid_index and has_valid_subindex):
+            operation = SDOOperationType.UNKNOWN
+
+        payload: bytes
+        raw_data = request.get("data", b"")
+        if raw_data is None:
+            payload = b""
+        elif isinstance(raw_data, bytes):
+            payload = raw_data
+        elif isinstance(raw_data, bytearray):
+            payload = bytes(raw_data)
+        else:
+            raise InvalidCommandError("SDO write payload must be bytes")
+
+        return SDOOperationRequest(
+            index=index,
+            subindex=subindex,
+            operation=operation,
+            data=payload,
+        )
+
+    def is_unknown_operation(self, request: OperationRequest) -> bool:
+        """Return whether the request operation is unsupported."""
+        sdo_request = self._as_sdo_request(request)
+        return sdo_request.operation is SDOOperationType.UNKNOWN
+
+    def is_write_operation(self, request: OperationRequest) -> bool:
+        """Return whether the request operation writes a register value."""
+        sdo_request = self._as_sdo_request(request)
+        return sdo_request.operation is SDOOperationType.WRITE
+
+    def resolve_register(
+        self,
+        register_service: RegisterService,
+        request: OperationRequest,
+    ) -> Register:
+        """Resolve the target register from an SDO request.
+
+        Returns:
+            Register: Register identified by index/subindex in the request.
+
+        """
+        sdo_request = self._as_sdo_request(request)
+        return register_service.get_register_by_index_subindex(
+            index=sdo_request.index,
+            subindex=sdo_request.subindex,
+        )
+
+    def decode_write_value(self, register: Register, request: OperationRequest) -> RegisterValue:
+        """Decode the write payload into a register value.
+
+        Args:
+            register: Register metadata used for dtype conversion.
+            request: Parsed request containing the write payload bytes.
+
+        Returns:
+            RegisterValue: Value converted to the register dtype.
+
+        """
+        return convert_bytes_to_dtype(request.data, register.dtype)
+
+    def build_response(
+        self,
+        request: OperationRequest,
+        result: OperationResult,
+        register: Register | None = None,
+        error: Exception | None = None,
+    ) -> bytes:
+        """Build a serialized SDO JSON response frame.
+
+        Args:
+            request: Original parsed operation request.
+            result: Operation outcome.
+            register: Register metadata used to encode read values.
+            error: Original execution error, when operation fails.
+
+        Returns:
+            bytes: Serialized response payload.
+
+        """
+        sdo_request = self._as_sdo_request(request)
+        response: dict[str, Any] = {
+            "command": sdo_request.operation.value,
+            "index": sdo_request.index,
+            "subindex": sdo_request.subindex,
+        }
+        if not result.success:
+            response["error_code"] = self._resolve_error_code(error)
+            return serialize_sdo_frame(response)
+
+        if sdo_request.operation is SDOOperationType.READ:
+            if register is None or result.value is None:
+                response["error_code"] = OPERATION_NOT_EXECUTED_ERROR_CODE
+                return serialize_sdo_frame(response)
+            response["data"] = self._encode_read_value(register, result.value)
+        return serialize_sdo_frame(response)
+
+    @staticmethod
+    def _as_sdo_request(request: OperationRequest) -> SDOOperationRequest:
+        if not isinstance(request, SDOOperationRequest):
+            raise TypeError("SDOAdapter requires SDOOperationRequest")
+        return request
+
+    @staticmethod
+    def _parse_object_address_field(request: dict[str, Any], key: str) -> tuple[int, bool]:
+        raw_value = request.get(key)
+        if raw_value is None:
+            return 0, False
+        try:
+            return int(raw_value), True
+        except (TypeError, ValueError):
+            return 0, False
+
+    @staticmethod
+    def _encode_read_value(register: Register, value: RegisterValue) -> bytes:
+        if isinstance(value, bytes):
+            return value
+        return convert_dtype_to_bytes(value, register.dtype)
+
+    @staticmethod
+    def _resolve_error_code(error: Exception | None) -> int:
+        """Resolve the protocol error code to be embedded in the SDO response.
+
+        Args:
+            error: The original exception that caused the operation to fail, if any.
+
+        Returns:
+            The protocol-specific error code extracted from the exception, or a default
+             code if the error is not a VirtualDriveError or is None.
+
+        """
+        if isinstance(error, VirtualDriveError):
+            return error.error_code
+        return OPERATION_NOT_EXECUTED_ERROR_CODE