horiba-sdk 0.3.2__py3-none-any.whl

horiba_sdk/icl_error/error_list.json

@@ -0,0 +1,265 @@
+{
+    "errors": [
+      {
+        "number": -1,
+        "text": "ICL error: no parser found",
+        "level": "fatal"
+      },
+      {
+        "number": -2,
+        "text": "ICL error: unknown command",
+        "level": "fatal"
+      },
+      {
+        "number": -3,
+        "text": "ICL error: invalid bin mode",
+        "level": "fatal"
+      },
+      {
+        "number": -300,
+        "text": "CCD error: already initialized",
+        "level": "fatal"
+      },
+      {
+        "number": -301,
+        "text": "CCD error: already open",
+        "level": "fatal"
+      },
+      {
+        "number": -302,
+        "text": "CCD error: already closed",
+        "level": "fatal"
+      },
+      {
+        "number": -303,
+        "text": "CCD error: already uninitialized",
+        "level": "fatal"
+      },
+      {
+        "number": -304,
+        "text": "CCD error: not initialized",
+        "level": "fatal"
+      },
+      {
+        "number": -305,
+        "text": "CCD error: not open",
+        "level": "fatal"
+      },
+      {
+        "number": -306,
+        "text": "CCD error: not found",
+        "level": "fatal"
+      },
+      {
+        "number": -307,
+        "text": "CCD error: invalid device index",
+        "level": "fatal"
+      },
+      {
+        "number": -308,
+        "text": "CCD error: initialization failure",
+        "level": "fatal"
+      },
+      {
+        "number": -309,
+        "text": "CCD error: acquiring",
+        "level": "fatal"
+      },
+      {
+        "number": -310,
+        "text": "CCD error: acquisition preparation failed",
+        "level": "fatal"
+      },
+      {
+        "number": -311,
+        "text": "CCD error: not ready for acquisition",
+        "level": "fatal"
+      },
+      {
+        "number": -312,
+        "text": "CCD error: get spectra failed",
+        "level": "fatal"
+      },
+      {
+        "number": -313,
+        "text": "CCD error: go failed",
+        "level": "fatal"
+      },
+      {
+        "number": -314,
+        "text": "CCD error: no free packet",
+        "level": "fatal"
+      },
+      {
+        "number": -315,
+        "text": "CCD error: command not supported",
+        "level": "fatal"
+      },
+      {
+        "number": -316,
+        "text": "CCD error: command failed",
+        "level": "fatal"
+      },
+      {
+        "number": -317,
+        "text": "CCD error: invalid token",
+        "level": "fatal"
+      },
+      {
+        "number": -318,
+        "text": "CCD error: invalid value",
+        "level": "fatal"
+      },
+      {
+        "number": -319,
+        "text": "CCD error: capabilities read error",
+        "level": "fatal"
+      },
+      {
+        "number": -320,
+        "text": "CCD error: acquisition already running",
+        "level": "fatal"
+      },
+      {
+        "number": -321,
+        "text": "CCD error: acquisition data format error",
+        "level": "fatal"
+      },
+      {
+        "number": -322,
+        "text": "CCD error: unsupported acquisition format",
+        "level": "fatal"
+      },
+      {
+        "number": -323,
+        "text": "CCD error: command execution exception",
+        "level": "fatal"
+      },
+      {
+        "number": -324,
+        "text": "CCD error: missing parameter",
+        "level": "fatal"
+      },
+      {
+        "number": -500,
+        "text": "MONO error: already initialized",
+        "level": "fatal"
+      },
+      {
+        "number": -501,
+        "text": "MONO error: already open",
+        "level": "fatal"
+      },
+      {
+        "number": -502,
+        "text": "MONO error: already opening",
+        "level": "fatal"
+      },
+      {
+        "number": -503,
+        "text": "MONO error: already closed",
+        "level": "fatal"
+      },
+      {
+        "number": -504,
+        "text": "MONO error: already uninitialized",
+        "level": "fatal"
+      },
+      {
+        "number": -505,
+        "text": "MONO error: not initialized",
+        "level": "fatal"
+      },
+      {
+        "number": -506,
+        "text": "MONO error: not open",
+        "level": "fatal"
+      },
+      {
+        "number": -507,
+        "text": "MONO error: not found",
+        "level": "fatal"
+      },
+      {
+        "number": -508,
+        "text": "MONO error: invalid device index",
+        "level": "fatal"
+      },
+      {
+        "number": -509,
+        "text": "MONO error: initialization failure",
+        "level": "fatal"
+      },
+      {
+        "number": -510,
+        "text": "MONO error: command not supported",
+        "level": "fatal"
+      },
+      {
+        "number": -511,
+        "text": "MONO error: discovery",
+        "level": "fatal"
+      },
+      {
+        "number": -512,
+        "text": "MONO error: communication error",
+        "level": "fatal"
+      },
+      {
+        "number": -513,
+        "text": "MONO error: invalid parameter",
+        "level": "fatal"
+      },
+      {
+        "number": -514,
+        "text": "MONO error: lost USB connection",
+        "level": "fatal"
+      },
+      {
+        "number": -515,
+        "text": "MONO error: open error",
+        "level": "fatal"
+      },
+      {
+        "number": -516,
+        "text": "MONO error: error log",
+        "level": "fatal"
+      },
+      {
+        "number": -517,
+        "text": "MONO error: initialization error",
+        "level": "fatal"
+      },
+      {
+        "number": -518,
+        "text": "MONO error: get configuration",
+        "level": "fatal"
+      },
+      {
+        "number": -519,
+        "text": "MONO error: command error",
+        "level": "fatal"
+      },
+      {
+        "number": -520,
+        "text": "MONO error: communication failed",
+        "level": "fatal"
+      },
+      {
+        "number": -521,
+        "text": "MONO error: missing parameter",
+        "level": "fatal"
+      },
+      {
+        "number": -600,
+        "text": "SCD error: command not supported",
+        "level": "fatal"
+      },
+      {
+        "number": -729,
+        "text": "Missing parameter argument: ",
+        "level": "fatal"
+      }
+
+    ]
+  }

horiba_sdk/icl_error/icl_error.py

@@ -0,0 +1,30 @@
+from typing import final
+
+from loguru import logger
+from overrides import override
+
+from horiba_sdk.icl_error import AbstractError, Severity
+
+
+@final
+class ICLError(AbstractError):
+    """Represents an Error from the ICL. It has an error code, a message and severity."""
+
+    def __init__(self, code: int, message: str, severity: Severity) -> None:
+        self._code = code
+        self._message = message
+        self._severity = severity
+
+    @override
+    def log(self) -> None:
+        """Logs the error with the appropriate severity"""
+        logger.log(self._severity.name, self._message)
+
+    @override
+    def message(self) -> str:
+        """Message of error.
+
+        Returns:
+            str: message
+        """
+        return self._message

horiba_sdk/icl_error/icl_error_db.py

@@ -0,0 +1,81 @@
+import json
+from pathlib import Path
+from typing import final
+
+from loguru import logger
+from overrides import override
+
+from horiba_sdk.icl_error import AbstractError, AbstractErrorDB, ICLError, Severity, StringAsSeverity
+
+
+@final
+class ICLErrorDB(AbstractErrorDB):
+    """ICL Error Database
+
+    This class loads a error database in json format. Based on an error string from the ICL, it returns a
+    `horiba_sdk.icl_error.ICLError`
+    object.
+
+    The json databse has to look like the following example:
+
+    .. code-block:: json
+
+       {
+         "errors": [
+           {
+             "number": -1,
+             "text": "ICL error: no parser found",
+             "level": "fatal"
+           },
+           {
+             "number": -2,
+             "text": "ICL error: unknown command",
+             "level": "fatal"
+           }
+       }
+
+    A database exists in this module under :code:`horiba_sdk/icl_error/error_list.json`
+
+    """
+
+    def __init__(self, json_db_path: Path) -> None:
+        if not json_db_path.is_file():
+            raise FileNotFoundError(f'ICL Json DB does not exist at {json_db_path}')
+
+        with open(json_db_path) as file:
+            self._icl_error_db = json.load(file)
+
+    @override
+    def error_from(self, string: str) -> AbstractError:
+        """Searches an error in the database and when successfull returns a corresponding
+        `horiba_sdk.icl_error.ICLError`.
+
+        Args:
+            string (str): ICL error string in the format :code:`'[E];<error code>;<error string>'`
+
+        Returns:
+            ICLError: the corresponding error
+
+        Raises:
+            Exception: when the error string is not formatted as explained above or when no error is found with the
+            given error code.
+        """
+        parsed_error = string.split(';')
+
+        if len(parsed_error) != 3:
+            raise Exception(f'Invalid length of ICL error string, was {len(parsed_error)} should be 3')
+
+        error_code: int = int(parsed_error[1])
+        found_error = next(
+            (error for error in self._icl_error_db.get('errors', []) if error.get('number') == error_code), None
+        )
+
+        if found_error is None:
+            logger.error(f'Error with number #{error_code} not found in error db')
+            text: str = parsed_error[2]
+            return ICLError(error_code, f'Unknown error: {text}', Severity.CRITICAL)
+
+        level: str = found_error.get('level')
+        severity: Severity = StringAsSeverity(level).to_severity()
+        message: str = found_error.get('text')
+        return ICLError(error_code, message, severity)

horiba_sdk/sync/communication/__init__.py

@@ -0,0 +1,7 @@
+from .abstract_communicator import AbstractCommunicator
+from .websocket_communicator import WebsocketCommunicator
+
+__all__ = [
+    'AbstractCommunicator',
+    'WebsocketCommunicator',
+]

horiba_sdk/sync/communication/abstract_communicator.py

@@ -0,0 +1,48 @@
+from abc import ABC, abstractmethod
+
+from horiba_sdk.communication.messages import Command, Response
+
+
+class AbstractCommunicator(ABC):
+    """
+    Abstract base class for communication protocols.
+    """
+
+    @abstractmethod
+    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
+    def request_with_response(self, command: Command, time_to_wait_for_response_in_s: float = 0.1) -> Response:
+        """
+        Abstract method to fetch a response from a command.
+
+        Args:
+            command (Command): Command for which a response is desired
+            time_to_wait_for_response_in_s (float, optional): Time, in seconds, to wait between request and response.
+            Defaults to 0.1s
+
+        Returns:
+            Response: The response corresponding to the sent command.
+        """
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        """
+        Abstract method to close the connection.
+        """
+        pass

horiba_sdk/sync/communication/test_client.py

@@ -0,0 +1,16 @@
+# Closing frame is apparently not sent. Here is a minimal example to prove the point:
+# 1. First run icl.exe
+# 2. Then execute this script:
+#    poetry run python ./horiba_sdk/sync/communication/test_client.py
+from websockets.exceptions import ConnectionClosedError, ConnectionClosedOK
+from websockets.sync.client import connect
+
+websocket = connect(uri='ws://localhost:25010')
+try:
+    websocket.send('{"command":"icl_shutdown"}')
+    for message in websocket:
+        print(message)
+except ConnectionClosedOK as e:
+    print(f'Connection normally closed: {e}')
+except ConnectionClosedError as e:
+    print(f'Protocol error or network failure: {e}')

horiba_sdk/sync/communication/websocket_communicator.py

@@ -0,0 +1,212 @@
+import time
+from queue import Queue
+from threading import Thread
+from types import TracebackType
+from typing import Any, Callable, Optional, final
+
+import websockets
+from loguru import logger
+from overrides import override
+from websockets.sync.client import ClientConnection
+
+from horiba_sdk.communication.communication_exception import CommunicationException
+from horiba_sdk.communication.messages import Command, JSONResponse, Response
+from horiba_sdk.sync.communication.abstract_communicator import AbstractCommunicator
+
+
+@final
+class WebsocketCommunicator(AbstractCommunicator):
+    """
+    The WebsocketCommunicator implements the `horiba_sdk.sync.communication.AbstractCommunicator` via websockets.
+    A background thread listens continuously for incoming binary data.
+    """
+
+    def __init__(self, uri: str = 'ws://127.0.0.1:25010') -> None:
+        self.uri: str = uri
+        self.websocket: Optional[ClientConnection] = None
+        self.running_listen_thread: bool = False
+        self.listen_thread: Optional[Thread] = None
+        self.running_binary_message_handling_thread: bool = False
+        self.binary_message_handling_thread: Optional[Thread] = None
+        self.json_message_queue: Queue[str] = Queue()
+        self.binary_message_queue: Queue[bytes] = Queue()
+        self.binary_message_callback: Optional[Callable[[bytes], Any]] = None
+        self.icl_info: dict[str, Any] = {}
+
+    def __enter__(self) -> 'WebsocketCommunicator':
+        self.open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_value: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    @override
+    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 = websockets.sync.client.connect(self.uri)
+        except websockets.WebSocketException as e:
+            raise CommunicationException(None, 'websocket connection issue') from e
+
+        self.running_listen_thread = True
+        self.listen_thread = Thread(target=self._receive_data)
+        self.listen_thread.start()
+
+        logger.debug(f'Websocket connection established to {self.uri}')
+
+    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()}')
+            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
+
+    def response(self) -> Response:
+        """Fetches the next response
+
+        Returns:
+            Response: The response from the server
+
+        Raises:
+            CommunicationException: When the connection terminated with an error
+        """
+        if not self.json_message_queue or self.json_message_queue.empty():
+            raise CommunicationException(None, 'No message to be received.')
+
+        logger.debug(f'#{self.json_message_queue.qsize()} messages in the queue, taking first')
+        response: str = self.json_message_queue.get()
+        logger.debug('retrieved message in queue')
+        return JSONResponse(response)
+
+    @override
+    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.websocket:
+            logger.debug('Waiting websocket close...')
+            self.websocket.close()
+
+        if self.binary_message_handling_thread:
+            logger.debug('Canceling binary listening thread...')
+            self.running_binary_message_handling_thread = False
+            self.binary_message_handling_thread.join()
+            self.binary_message_handling_thread = None
+
+        if self.listen_thread:
+            logger.debug('Canceling listening thread...')
+            self.running_listen_thread = False
+            self.listen_thread.join()
+            self.listen_thread = None
+
+        self.websocket = None
+        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."""
+        if self.binary_message_callback:
+            raise CommunicationException(None, 'Binary message callback already registered')
+
+        self.binary_message_callback = callback
+        logger.info('Binary message callback registered.')
+        self.running_binary_message_handling_thread = True
+        self.binary_message_handling_thread = Thread(target=self._run_binary_message_callback)
+        self.binary_message_handling_thread.start()
+        logger.info('Started binary message thread')
+
+    def _receive_data(self) -> None:
+        if not self.websocket:
+            raise CommunicationException(None, 'Websocket is not open')
+
+        while self.running_listen_thread:
+            try:
+                for message in self.websocket:
+                    logger.debug(f'Received message: {message!r}')
+                    if isinstance(message, str):
+                        self.json_message_queue.put(message)
+                    elif isinstance(message, bytes) and self.binary_message_callback:
+                        self.binary_message_queue.put(message)
+                    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
+
+    def _run_binary_message_callback(self) -> None:
+        if not self.binary_message_callback:
+            raise CommunicationException(None, 'No binary message callback registered')
+
+        while self.running_binary_message_handling_thread:
+            while self.binary_message_queue.empty():
+                time.sleep(0.5)
+                if not self.running_binary_message_handling_thread:
+                    return
+
+            binary_message = self.binary_message_queue.get()
+            self.binary_message_callback(binary_message)
+
+    @override
+    def request_with_response(self, command: Command, time_to_wait_for_response_in_s: float = 0.1) -> Response:
+        """
+        Concrete method to fetch a response from a command.
+
+        Args:
+            command (Command): Command for which a response is desired
+            time_to_wait_for_response_in_s (float, optional): Time, in seconds, to wait between request and response.
+            Defaults to 0.1s
+
+        Returns:
+            Response: The response corresponding to the sent command.
+        """
+        self.send(command)
+        logger.debug('sent command, waiting for response')
+        time.sleep(time_to_wait_for_response_in_s)
+        response: Response = self.response()
+
+        return response

horiba_sdk/sync/devices/__init__.py

@@ -0,0 +1,15 @@
+from .abstract_device_discovery import AbstractDeviceDiscovery
+from .abstract_device_manager import AbstractDeviceManager
+from .device_discovery import DeviceDiscovery
+from .device_manager import DeviceManager
+from .fake_device_manager import FakeDeviceManager
+from .fake_icl_server import FakeICLServer
+
+__all__ = [
+    'AbstractDeviceDiscovery',
+    'AbstractDeviceManager',
+    'DeviceDiscovery',
+    'DeviceManager',
+    'FakeDeviceManager',
+    'FakeICLServer',
+]

horiba_sdk/sync/devices/abstract_device_discovery.py

@@ -0,0 +1,17 @@
+from abc import ABC, abstractmethod
+
+from horiba_sdk.sync.devices.single_devices import ChargeCoupledDevice, Monochromator
+
+
+class AbstractDeviceDiscovery(ABC):
+    @abstractmethod
+    def execute(self, error_on_no_device: bool = False) -> None:
+        pass
+
+    @abstractmethod
+    def charge_coupled_devices(self) -> list[ChargeCoupledDevice]:
+        pass
+
+    @abstractmethod
+    def monochromators(self) -> list[Monochromator]:
+        pass