horiba-sdk 0.3.2__py3-none-any.whl

horiba_sdk/__init__.py

@@ -0,0 +1,19 @@
+# mypy: disable-error-code="attr-defined"
+"""'horiba-sdk' is a package that provides source code for the development with Horiba devices"""
+
+__version__ = '0.2.0'  # It MUST match the version in pyproject.toml file
+from importlib import metadata as importlib_metadata
+
+from pint import UnitRegistry
+
+
+def get_version() -> str:
+    try:
+        return importlib_metadata.version(__name__)
+    except importlib_metadata.PackageNotFoundError:  # pragma: no cover
+        return 'unknown'
+
+
+version: str = get_version()
+
+ureg = UnitRegistry()

horiba_sdk/communication/__init__.py

@@ -0,0 +1,44 @@
+"""
+communication
+
+A package that provides tools and abstractions for communication. The package includes
+implementations for WebSocket communication, message formatting and parsing, and an abstract
+base for defining communication contracts.
+
+Modules:
+- base_communication: Contains the abstract base class defining the communication contract.
+- message_parser: Provides utility functions for message formatting and parsing.
+- websocket_client: Concrete implementation of the communication contract using WebSockets.
+
+Directly Available Imports:
+- WebSocketClient: WebSocket-based communication client.
+- MessageParsingError: Exception raised for message format errors.
+- format_message: Utility to format messages for sending.
+- parse_received_message: Utility to parse received messages into a structured format.
+
+Typical usage example:
+
+from communication import WebSocketClient, format_message, parse_received_message
+
+ws = WebSocketClient("ws://example.com")
+await ws.connect()
+await ws.send("command", {"param": "value"})
+response = await ws.receive()
+await ws.disconnect()
+"""
+
+# Necessary to make Python treat the directory as a package
+from .abstract_communicator import AbstractCommunicator
+from .communication_exception import CommunicationException
+from .messages import BinaryResponse, Command, JSONResponse, Response
+from .websocket_communicator import WebsocketCommunicator
+
+__all__ = [
+    'AbstractCommunicator',
+    'WebsocketCommunicator',
+    'CommunicationException',
+    'Command',
+    'Response',
+    'JSONResponse',
+    'BinaryResponse',
+]

horiba_sdk/communication/abstract_communicator.py

@@ -0,0 +1,59 @@
+from abc import ABC, abstractmethod
+
+from .messages import BinaryResponse, Command, Response
+
+
+class AbstractCommunicator(ABC):
+    """
+    Abstract base class for communication protocols.
+    """
+
+    @abstractmethod
+    async def open(self) -> None:
+        """
+        Abstract method to establish a connection.
+        """
+        pass
+
+    @abstractmethod
+    def opened(self) -> bool:
+        """
+        Abstract method that says if the connection is open
+
+        Returns:
+            bool: True if the connection is open, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    async def request_with_response(self, command: Command, timeout: int = 5) -> Response:
+        """
+        Abstract method to fetch a response from a command.
+
+        Args:
+            command (Command): Command for which a response is desired
+            timeout (int, optional): Timeout [s] for waiting for the response. Defaults to 5
+
+        Returns:
+            Response: The response corresponding to the sent command.
+        """
+        pass
+
+    @abstractmethod
+    async def binary_response(self) -> BinaryResponse:
+        """
+        Abstract method that fetches the next binary response.
+
+        Returns:
+            BinaryResponse: The binary response from the server
+
+        .. todo:: `[saga]` is this still needed?
+        """
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        """
+        Abstract method to close the connection.
+        """
+        pass

horiba_sdk/communication/communication_exception.py

@@ -0,0 +1,19 @@
+from typing import Optional, final
+
+
+@final
+class CommunicationException(Exception):
+    """CommunicationException is raised for issues encountered in the communicator classes.
+
+    Specifically all subclasses of horiba_sdk.communication.AbstractCommunicator
+    """
+
+    def __init__(self, exception: Optional[Exception] = None, message: str = ''):
+        """__init__.
+
+        Args:
+            exception (Exception): the lower-level exception
+            message (str): explanation of what went wrong
+        """
+        self.exception = exception
+        self.message = message

horiba_sdk/communication/messages.py

@@ -0,0 +1,87 @@
+import json
+from itertools import count
+from typing import Any, Dict, List, Optional, final
+
+
+class Command:
+    """
+    Represents a command to be sent to the server.
+
+    Class Attributes:
+        _id_counter (iterator): An iterator to generate unique IDs.
+
+    Instance Attributes:
+        id (int): Unique identifier for the command.
+        command (str): The command string.
+        parameters (Dict[str, Any]): Parameters for the command.
+
+    Methods:
+        json(): Converts the command to a JSON string.
+    """
+
+    _id_counter = count(start=1)  # Starts counting from 1
+
+    def __init__(self, command: str, parameters: Dict[str, Any]):
+        self.id = next(self._id_counter)  # Automatically assigns the next unique ID
+        self.command = command
+        self.parameters = parameters
+
+    def json(self) -> str:
+        """Converts the command object to a JSON string."""
+        return json.dumps({'id': self.id, 'command': self.command, 'parameters': self.parameters})
+
+
+class Response:
+    """
+    Represents a response received from the server.
+
+    Attributes:
+        id (int): Unique identifier matching the command's ID.
+        command (str): The command string echoed back from the server.
+        results (Optional[Dict[str, Any]]): Results returned by the server.
+        errors (Optional[List]): List of errors returned by the server.
+    """
+
+    def __init__(
+        self, id: int, command: str, results: Optional[Dict[str, Any]] = None, errors: Optional[List[str]] = None
+    ):
+        self.id = id
+        self.command = command
+        self.results = results or {}
+        self.errors = errors or []
+
+
+@final
+class JSONResponse(Response):
+    """Represents a JSON response received from the server.
+
+    Attributes:
+        json_response (str): JSON response string
+    """
+
+    def __init__(self, json_response: str):
+        data = json.loads(json_response)
+        super().__init__(id=data['id'], command=data['command'], results=data.get('results'), errors=data.get('errors'))
+
+
+@final
+class BinaryResponse:
+    """Represents a Binary response received from the server.
+
+    Attributes:
+        binary_data (bytes): Response in binary format
+    """
+
+    def __init__(self, binary_data: bytes):
+        self._binary_data = binary_data
+
+
+# # Example usage
+# command = Command("example_command", {"key1": "value1", "key2": "value2"})
+# command_json = command.to_json()
+#
+# response_json = '{"id": 1357, "command": "example_command","results": ..
+# ..{"key1": "value1", "key2": "value2"}, "errors":[]}'
+# response = JSONResponse(response_json)
+#
+# # You can now access attributes like response.id, response.command, etc.

horiba_sdk/communication/websocket_communicator.py

@@ -0,0 +1,213 @@
+import asyncio
+import contextlib
+from types import TracebackType
+from typing import Any, Callable, Optional, final
+
+import websockets
+from loguru import logger
+from overrides import override
+from websockets.legacy.client import WebSocketClientProtocol
+
+from .abstract_communicator import AbstractCommunicator
+from .communication_exception import CommunicationException
+from .messages import BinaryResponse, Command, JSONResponse, Response
+
+
+@final
+class WebsocketCommunicator(AbstractCommunicator):
+    """
+    The WebsocketCommunicator implements the `horiba_sdk.communication.AbstractCommunicator` via websockets.
+    A background task listens continuously for incoming binary data.
+
+    It supports Asynchronous Context Managers and can be used like the following::
+
+        websocket_communicator: WebsocketCommunicator = WebsocketCommunicator(uri)
+        async with websocket_communicator:
+            assert websocket_communicator.opened()
+
+            request: str = '{"command": "some_command"}'
+            await websocket_communicator.send(request)
+            response = await websocket_communicator.response()
+            # do something with the response...
+
+    """
+
+    def __init__(self, uri: str = 'ws://127.0.0.1:25010') -> None:
+        self.uri: str = uri
+        self.websocket: Optional[WebSocketClientProtocol] = None
+        self.listen_task: Optional[asyncio.Task[Any]] = None
+        self.json_message_queue: asyncio.Queue[str] = asyncio.Queue()
+        self.binary_message_queue: asyncio.Queue[bytes] = asyncio.Queue()
+        self.binary_message_callback: Optional[Callable[[bytes], Any]] = None
+        self.icl_info: dict[str, Any] = {}
+
+    async def __aenter__(self) -> 'WebsocketCommunicator':
+        await self.open()
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException], exc_value: BaseException, traceback: Optional[TracebackType]
+    ) -> None:
+        await self.close()
+
+    @override
+    async def open(self) -> None:
+        """
+        Opens the WebSocket connection and starts listening for binary data.
+
+        Raises:
+            CommunicationException: When the websocket is already opened or
+            there is an issue with the underlying websockets connection attempt.
+        """
+        if self.opened():
+            raise CommunicationException(None, 'websocket already opened')
+
+        try:
+            self.websocket = await websockets.connect(self.uri)
+            # self.flush_incoming_messages(self)  # Flush any incoming messages (if any
+
+        except websockets.WebSocketException as e:
+            raise CommunicationException(None, 'websocket connection issue') from e
+
+        logger.debug(f'Websocket connection established to {self.uri}')
+        self.listen_task = asyncio.create_task(self._receive_data())
+
+    async def send(self, command: Command) -> None:
+        """
+        Sends a command to the WebSocket server.
+
+        Args:
+            command (Command): The command to send to the server.
+
+        Raises:
+            CommunicationException: When trying to send a command while the websocket is closed.
+
+        """
+        if not self.opened():
+            raise CommunicationException(None, 'WebSocket is not opened.')
+
+        try:
+            # mypy cannot infer the check from self.opened() done above
+            logger.debug(f'Sending JSON command: {command.json()}')
+            await self.websocket.send(command.json())  # type: ignore
+        except websockets.exceptions.ConnectionClosed as e:
+            raise CommunicationException(None, 'Trying to send data while websocket is closed') from e
+
+    @override
+    def opened(self) -> bool:
+        """
+        Returns if the websocket connection is open or not
+
+        Returns:
+            bool: True if the websocket connection is open, False otherwise
+        """
+        return self.websocket is not None and self.websocket.open
+
+    async def response(self) -> Response:
+        """Fetches the next response
+
+        Returns:
+            Response: The response from the server
+
+        Raises:
+            CommunicationException: When the connection terminated with an error
+        """
+        try:
+            response: str = await self.json_message_queue.get()
+            return JSONResponse(response)
+        except asyncio.CancelledError as e:
+            raise CommunicationException(None, 'Response reception was canceled') from e
+
+    @override
+    async def binary_response(self) -> BinaryResponse:
+        """Fetches the next binary response.
+
+        Returns:
+            BinaryResponse: The binary response from the server
+
+        Raises:
+            CommunicationException: When the connection terminated with an error
+            or the binary data failed to be processed.
+
+        .. todo:: `[saga]` is this still needed?
+        """
+        try:
+            response: bytes = await self.binary_message_queue.get()
+            logger.debug(f'Received binary response: {response!r}')
+            return BinaryResponse(response)
+        except asyncio.CancelledError as e:
+            raise CommunicationException(None, 'Response reception was canceled') from e
+
+    @override
+    async def close(self) -> None:
+        """
+        Closes the WebSocket connection.
+
+        Raises:
+            CommunicationException: When the websocket is already closed
+        """
+        if not self.opened():
+            raise CommunicationException(None, 'cannot close already closed websocket')
+        if self.binary_message_callback:
+            self.binary_message_callback = None
+        if self.websocket:
+            logger.debug('Waiting websocket close...')
+            await self.websocket.close()
+            self.websocket = None
+
+        if self.listen_task:
+            logger.debug('Canceling listening task...')
+            self.listen_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                logger.debug('Await listening task...')
+                await self.listen_task
+
+        logger.debug('Websocket connection closed')
+
+    def register_binary_message_callback(self, callback: Callable[[bytes], Any]) -> None:
+        """Registers a callback to be called with every incoming binary message."""
+        logger.info('Binary message callback registered.')
+        self.binary_message_callback = callback
+
+    async def _receive_data(self) -> None:
+        try:
+            async for message in self.websocket:  # type: ignore
+                logger.info(f'Received message: {message!r}')
+                if isinstance(message, str):
+                    await self.json_message_queue.put(message)
+                elif isinstance(message, bytes):
+                    if self.binary_message_callback:
+                        await asyncio.create_task(self.binary_message_callback(message))  # Call the callback
+                else:
+                    raise CommunicationException(None, f'Unknown type of message {type(message)}')
+        except websockets.ConnectionClosedOK:
+            logger.debug('websocket connection terminated properly')
+        except websockets.ConnectionClosedError as e:
+            raise CommunicationException(None, 'connection terminated with error') from e
+        except Exception as e:
+            raise CommunicationException(None, 'failure to process binary data') from e
+
+    @override
+    async def request_with_response(self, command: Command, timeout: int = 5) -> Response:
+        """
+        Concrete method to fetch a response from a command.
+
+        Args:
+            command (Command): Command for which a response is desired
+            timeout (int): Maximum time to wait for a response
+
+        Returns:
+            Response: The response corresponding to the sent command.
+
+        Raises:
+            Exception: When an error occurred with the communication channel
+        """
+        # send the command with the send function and wait a maximum of 5 seconds for the response
+        await self.send(command)
+        try:
+            async with asyncio.timeout(timeout):
+                response: Response = await self.response()
+        except TimeoutError as te:
+            raise CommunicationException(None, f'Timeout of {timeout}s while waiting for response.') from te
+
+        return response

horiba_sdk/core/resolution.py

@@ -0,0 +1,45 @@
+from typing import final
+
+
+@final
+class Resolution:
+    """Width x height, non-zero, non-negative resolution in pixels.
+
+    Attributes:
+        width (int): The width in pixels
+        height (int): The height in pixels
+    """
+
+    def __init__(self, width: int, height: int) -> None:
+        """Initializes a new Resolution instance
+
+        Args:
+            width (int): width
+            height (int): height
+
+        Raises:
+            Exception: when an invalid (<= 0) width or height is given
+        """
+        if width <= 0 or height <= 0:
+            raise Exception(f'Cannot have width or height less or equal to 0: {width} x {height} not allowed')
+
+        self._width = width
+        self._height = height
+
+    @property
+    def width(self) -> int:
+        """Width in pixels.
+
+        Returns:
+            int: width
+        """
+        return self._width
+
+    @property
+    def height(self) -> int:
+        """Height in pixels.
+
+        Returns:
+            int: height
+        """
+        return self._height

horiba_sdk/devices/__init__.py

@@ -0,0 +1,11 @@
+from .abstract_device_discovery import AbstractDeviceDiscovery
+from .abstract_device_manager import AbstractDeviceManager
+from .device_manager import DeviceManager
+from .fake_device_manager import FakeDeviceManager
+
+__all__ = [
+    'AbstractDeviceManager',
+    'DeviceManager',
+    'FakeDeviceManager',
+    'AbstractDeviceDiscovery',
+]

horiba_sdk/devices/abstract_device_discovery.py

@@ -0,0 +1,7 @@
+from abc import ABC, abstractmethod
+
+
+class AbstractDeviceDiscovery(ABC):
+    @abstractmethod
+    async def execute(self, error_on_no_device: bool = False) -> None:
+        pass

horiba_sdk/devices/abstract_device_manager.py

@@ -0,0 +1,68 @@
+from abc import ABC, abstractmethod
+
+from horiba_sdk.communication import AbstractCommunicator
+from horiba_sdk.devices.single_devices import ChargeCoupledDevice, Monochromator
+
+
+class AbstractDeviceManager(ABC):
+    """
+    DeviceManager class manages the lifecycle and interactions with devices.
+
+    """
+
+    @abstractmethod
+    async def start(self) -> None:
+        """
+        Abstract method to start the device manager.
+        """
+        pass
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """
+        Abstract method to stop the device manager.
+        """
+        pass
+
+    @abstractmethod
+    async def discover_devices(self, error_on_no_device: bool = False) -> None:
+        """
+        Abstract method that discovers and registers devices.
+
+        Args:
+            error_on_no_device (bool): If True, an exception is raised if no device is connected.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def communicator(self) -> AbstractCommunicator:
+        """
+        Abstract method to get the communicator attribute.
+
+        Returns:
+            AbstractCommunicator: Returns the internal communicator instance.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def monochromators(self) -> list[Monochromator]:
+        """
+        Abstract method to get the detected monochromators.
+
+        Returns:
+            List[Monochromator]: The detected monochromators
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def charge_coupled_devices(self) -> list[ChargeCoupledDevice]:
+        """
+        Abstract method to get the detected CCDs.
+
+        Returns:
+            List[ChargeCoupledDevice]: The detected CCDS.
+        """
+        pass

horiba_sdk/devices/ccd_discovery.py

@@ -0,0 +1,57 @@
+import re
+from typing import Any, final
+
+from loguru import logger
+from overrides import override
+
+from horiba_sdk.communication import AbstractCommunicator, Command, Response
+from horiba_sdk.devices.abstract_device_discovery import AbstractDeviceDiscovery
+from horiba_sdk.devices.single_devices import ChargeCoupledDevice
+from horiba_sdk.icl_error import AbstractErrorDB
+
+
+@final
+class ChargeCoupledDevicesDiscovery(AbstractDeviceDiscovery):
+    def __init__(self, communicator: AbstractCommunicator, error_db: AbstractErrorDB):
+        self._communicator: AbstractCommunicator = communicator
+        self._charge_coupled_devices: list[ChargeCoupledDevice] = []
+        self._error_db: AbstractErrorDB = error_db
+
+    @override
+    async def execute(self, error_on_no_device: bool = False) -> None:
+        """
+        Discovers the connected devices and saves them internally.
+
+        Raises:
+            Exception: When no CCDs are discovered and that `error_on_no_device` is set. Or when there is an issue
+            parsing the CCD list
+        """
+        if not self._communicator.opened():
+            await self._communicator.open()
+
+        response: Response = await self._communicator.request_with_response(Command('ccd_discover', {}))
+        if response.results.get('count', 0) == 0 and error_on_no_device:
+            raise Exception('No CCDs connected')
+        response = await self._communicator.request_with_response(Command('ccd_list', {}))
+
+        raw_device_list = response.results
+        self._charge_coupled_devices = self._parse_ccds(raw_device_list)
+        logger.info(f'Found {len(self._charge_coupled_devices)} CCD devices: {self._charge_coupled_devices}')
+
+    def _parse_ccds(self, raw_device_list: dict[str, Any]) -> list[ChargeCoupledDevice]:
+        detected_ccds: list[ChargeCoupledDevice] = []
+        for key, value in raw_device_list.items():
+            logger.debug(f'Parsing CCD: {key} - {value}')
+            ccd_index: int = int(key.split(':')[0].replace('index', '').strip())
+            ccd_type_match = re.search(r'deviceType: (.*?),', value)
+            if not ccd_type_match:
+                raise Exception(f'Failed to find ccd type "deviceType" in string "{value}"')
+            ccd_type: str = str(ccd_type_match.group(1).strip())
+
+            logger.info(f'Detected CCD: {ccd_type}')
+            detected_ccds.append(ChargeCoupledDevice(ccd_index, self._communicator, self._error_db))
+
+        return detected_ccds
+
+    def charge_coupled_devices(self) -> list[ChargeCoupledDevice]:
+        return self._charge_coupled_devices