horiba-sdk 0.3.2__py3-none-any.whl

horiba_sdk/sync/devices/abstract_device_manager.py

@@ -0,0 +1,68 @@
+from abc import ABC, abstractmethod
+
+from horiba_sdk.sync.communication import AbstractCommunicator
+from horiba_sdk.sync.devices.single_devices import ChargeCoupledDevice, Monochromator
+
+
+class AbstractDeviceManager(ABC):
+    """
+    DeviceManager class manages the lifecycle and interactions with devices.
+
+    """
+
+    @abstractmethod
+    def start(self) -> None:
+        """
+        Abstract method to start the device manager.
+        """
+        pass
+
+    @abstractmethod
+    def stop(self) -> None:
+        """
+        Abstract method to stop the device manager.
+        """
+        pass
+
+    @abstractmethod
+    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/sync/devices/device_discovery.py

@@ -0,0 +1,82 @@
+import re
+from typing import Any, final
+
+from loguru import logger
+from overrides import override
+
+from horiba_sdk.communication import Command, Response
+from horiba_sdk.icl_error import AbstractErrorDB
+from horiba_sdk.sync.communication import AbstractCommunicator
+from horiba_sdk.sync.devices.abstract_device_discovery import AbstractDeviceDiscovery
+from horiba_sdk.sync.devices.single_devices import ChargeCoupledDevice, Monochromator
+
+
+@final
+class DeviceDiscovery(AbstractDeviceDiscovery):
+    def __init__(self, communicator: AbstractCommunicator, error_db: AbstractErrorDB):
+        self._communicator: AbstractCommunicator = communicator
+        self._charge_coupled_devices: list[ChargeCoupledDevice] = []
+        self._monochromators: list[Monochromator] = []
+        self._error_db: AbstractErrorDB = error_db
+        self._discovered_devices: bool = False
+
+    @override
+    def execute(self, error_on_no_device: bool = False) -> None:
+        """
+        Discovers the connected devices and saves them internally.
+        """
+        if not self._communicator.opened():
+            self._communicator.open()
+
+        # Define the commands and device types in a list of tuples for iteration
+        commands_and_types = [('ccd_discover', 'ccd_list', 'CCD'), ('mono_discover', 'mono_list', 'Monochromator')]
+
+        for discover_command, list_command, device_type in commands_and_types:
+            response: Response = self._communicator.request_with_response(Command(discover_command, {}))
+            if response.results.get('count', 0) == 0 and error_on_no_device:
+                raise Exception(f'No {device_type} connected')
+            response = self._communicator.request_with_response(Command(list_command, {}))
+
+            # as the responses of ccd_list and mono_list differ, we need to parse them separately
+            if device_type == 'CCD':
+                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}')
+            elif device_type == 'Monochromator':
+                raw_device_list = response.results['list']
+                self._monochromators = self._parse_monos(raw_device_list)
+                logger.info(f'Found {len(self._monochromators)} Monochromator devices: {self._monochromators}')
+
+    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 _parse_monos(self, raw_device_list: dict[str, Any]) -> list[Monochromator]:
+        detected_monos = []
+        for device_string in raw_device_list:
+            mono_index: int = int(device_string.split(';')[0])
+            mono_type: str = device_string.split(';')[1]
+
+            logger.info(f'Detected Monochromator: {mono_type}')
+            detected_monos.append(Monochromator(mono_index, self._communicator, self._error_db))
+
+        return detected_monos
+
+    @override
+    def charge_coupled_devices(self) -> list[ChargeCoupledDevice]:
+        return self._charge_coupled_devices
+
+    @override
+    def monochromators(self) -> list[Monochromator]:
+        return self._monochromators

horiba_sdk/sync/devices/device_manager.py

@@ -0,0 +1,209 @@
+"""
+Synchronous Device Manager Module
+
+This Device Manager uses threads instead of asyncio
+"""
+import importlib.resources
+import platform
+import subprocess
+from pathlib import Path
+from subprocess import Popen
+from typing import Optional, final
+
+import psutil
+from loguru import logger
+from overrides import override
+
+from horiba_sdk.communication import Command, CommunicationException, Response
+from horiba_sdk.icl_error import AbstractError, AbstractErrorDB, ICLErrorDB
+from horiba_sdk.sync.communication import AbstractCommunicator, WebsocketCommunicator
+from horiba_sdk.sync.devices import AbstractDeviceManager, DeviceDiscovery
+from horiba_sdk.sync.devices.single_devices import ChargeCoupledDevice, Monochromator
+
+
+@final
+class DeviceManager(AbstractDeviceManager):
+    """
+    DeviceManager class manages the lifecycle and interactions with devices.
+    """
+
+    def __init__(
+        self,
+        start_icl: bool = True,
+        websocket_ip: str = '127.0.0.1',
+        websocket_port: str = '25010',
+        enable_binary_messages: bool = True,
+    ):
+        """
+        Initializes the DeviceManager with the specified communicator class.
+
+        Args:
+            start_icl (bool) = True: If True, the ICL software is started and communication is established.
+            websocket_ip (str) = '127.0.0.1': websocket IP
+            websocket_port (str) = '25010': websocket port
+            enable_binary_messages (bool) = True: If True, binary messages are enabled.
+        """
+        super().__init__()
+        self._start_icl = start_icl
+        self._icl_communicator: WebsocketCommunicator = WebsocketCommunicator(
+            'ws://' + websocket_ip + ':' + str(websocket_port)
+        )
+        self._icl_websocket_ip: str = websocket_ip
+        self._icl_websocket_port: str = websocket_port
+        self._icl_process: Optional[Popen[bytes]] = None
+        self._binary_messages: bool = enable_binary_messages
+        self._charge_coupled_devices: list[ChargeCoupledDevice] = []
+        self._monochromators: list[Monochromator] = []
+
+        error_list_path: Path = Path(str(importlib.resources.files('horiba_sdk.icl_error') / 'error_list.json'))
+        self._icl_error_db: AbstractErrorDB = ICLErrorDB(error_list_path)
+
+    @override
+    def start(self) -> None:
+        if self._start_icl:
+            self.start_icl()
+
+        self._icl_communicator.register_binary_message_callback(self._binary_message_callback)
+        self._icl_communicator.open()
+
+        icl_info: Response = self._icl_communicator.request_with_response(Command('icl_info', {}))
+        logger.info(f'ICL info: {icl_info.results}')
+
+        if self._binary_messages:
+            self._enable_binary_messages()
+
+        self.discover_devices()
+
+    @override
+    def stop(self) -> None:
+        self.stop_icl()
+
+    def start_icl(self) -> None:
+        """
+        Starts the ICL software and establishes communication.
+        """
+        logger.info('Starting ICL software...')
+        # try:
+        if platform.system() != 'Windows':
+            logger.info('Only Windows is supported for ICL software. Skip starting of ICL...')
+            return
+
+        icl_running = 'icl.exe' in (p.name() for p in psutil.process_iter())
+        if not icl_running:
+            logger.info('icl not running, starting it...')
+            try:
+                self._icl_process = subprocess.Popen([r'C:\Program Files\HORIBA Scientific\SDK\icl.exe'])
+            except subprocess.CalledProcessError as error:
+                logger.error('Failed to start ICL software.')
+                raise Exception('Failed to start ICL software') from error
+
+    def _enable_binary_messages(self) -> None:
+        bin_mode_command: Command = Command('icl_binMode', {'mode': 'all'})
+        response: Response = self._icl_communicator.request_with_response(bin_mode_command)
+
+        if response.errors:
+            self._handle_errors(response.errors)
+
+    def _handle_errors(self, errors: list[str]) -> None:
+        for error in errors:
+            icl_error: AbstractError = self._icl_error_db.error_from(error)
+            icl_error.log()
+            # TODO: [saga] only throw depending on the log level, tbd
+            raise Exception(f'Error from the ICL: {icl_error.message()}')
+
+    def stop_icl(self) -> None:
+        """
+        Stops the communication and cleans up resources.
+        """
+        logger.info('Requesting shutdown of ICL...')
+
+        if not self._icl_communicator.opened():
+            self._icl_communicator.open()
+
+        try:
+            info_command: Command = Command('icl_info', {})
+            response: Response = self._icl_communicator.request_with_response(info_command)
+
+            logger.info(f'ICL info: {response.results}')
+            shutdown_command: Command = Command('icl_shutdown', {})
+            # _response: Response = self._icl_communicator.request_with_response(shutdown_command, timeout=10)
+            _response: Response = self._icl_communicator.request_with_response(shutdown_command)
+        except CommunicationException as e:
+            logger.debug(f'CommunicationException: {e.message}')
+
+        if self._icl_communicator.opened():
+            self._icl_communicator.close()
+
+        if self._icl_process is not None:
+            self._icl_process.terminate()
+        icl_running = 'icl.exe' in (p.name() for p in psutil.process_iter())
+        if icl_running:
+            raise Exception('Failed to shutdown ICL software.')
+
+        logger.info('icl_shutdown command sent')
+
+    def _format_icl_binary_to_string(self, message: bytes) -> str:
+        return ' '.join(format(byte, '02x') for byte in message[::-1])
+
+    def _binary_message_callback(self, message: bytes) -> None:
+        # hex_data = ' '.join(format(byte, '02x') for byte in message)
+        # if len(message) < 18:
+        #     logger.warning(f'binary message not valid: {len(message)} < 16')
+        # logger.info(f'Received binary message: {hex_data}')
+        # logger.info(f'magic number: {self._format_icl_binary_to_string(message[:2])}')
+        # logger.info(f'message type: {self._format_icl_binary_to_string(message[2:4])}')
+        # logger.info(f'element type: {self._format_icl_binary_to_string(message[4:6])}')
+        # logger.info(f'element count: {self._format_icl_binary_to_string(message[6:10])}')
+        # logger.info(f'tag 1: {self._format_icl_binary_to_string(message[10:12])}')
+        # logger.info(f'tag 2: {self._format_icl_binary_to_string(message[12:14])}')
+        # logger.info(f'tag 3: {self._format_icl_binary_to_string(message[14:16])}')
+        # logger.info(f'tag 4: {self._format_icl_binary_to_string(message[16:18])}')
+        # logger.info(f'payload: {self._format_icl_binary_to_string(message[18:])}')
+        # logger.info(f'payload as string: {str(message[18:])}')
+        pass
+
+    @override
+    def discover_devices(self, error_on_no_device: bool = False) -> None:
+        """
+        Discovers the connected devices and saves them internally.
+
+        Args:
+            error_on_no_device (bool): If True, an exception is raised if no device is connected.
+        """
+        device_discovery: DeviceDiscovery = DeviceDiscovery(self._icl_communicator, self._icl_error_db)
+        device_discovery.execute(error_on_no_device)
+        self._charge_coupled_devices = device_discovery.charge_coupled_devices()
+        self._monochromators = device_discovery.monochromators()
+
+    @property
+    @override
+    def communicator(self) -> AbstractCommunicator:
+        """
+        Getter method for the communicator attribute.
+
+        Returns:
+            horiba_sdk.communication.AbstractCommunicator: Returns a new communicator instance.
+        """
+        return self._icl_communicator
+
+    @property
+    @override
+    def monochromators(self) -> list[Monochromator]:
+        """
+        The detected monochromators, should be called after :meth:`discover_devices`
+
+        Returns:
+            List[Monochromator]: The detected monochromators
+        """
+        return self._monochromators
+
+    @property
+    @override
+    def charge_coupled_devices(self) -> list[ChargeCoupledDevice]:
+        """
+        The detected CCDs, should be called after :meth:`discover_devices`
+
+        Returns:
+            List[ChargeCoupledDevice]: The detected CCDS.
+        """
+        return self._charge_coupled_devices

horiba_sdk/sync/devices/fake_device_manager.py

@@ -0,0 +1,91 @@
+from typing import final
+
+from overrides import override
+
+from horiba_sdk.icl_error import FakeErrorDB
+from horiba_sdk.sync.communication.websocket_communicator import WebsocketCommunicator
+from horiba_sdk.sync.devices.abstract_device_manager import AbstractDeviceManager
+from horiba_sdk.sync.devices.single_devices import ChargeCoupledDevice, Monochromator
+
+
+@final
+class FakeDeviceManager(AbstractDeviceManager):
+    """
+    The FakeDeviceManager represents a `horiba_sdk.sync.devices.DeviceManager` that can be used in the unit tests.
+
+    The class should be used in a pytest fixture as follows::
+
+        fake_icl_host: str = 'localhost'
+        fake_icl_port: int = 8765
+
+        @pytest.fixture(scope='module')
+        def fake_sync_icl_exe():  # noqa: ARG001
+            sync_server = FakeSyncICLServer(fake_icl_host=fake_icl_host, fake_icl_port=fake_icl_port)
+            thread = threading.Thread(target=sync_server.start)
+            thread.start()
+
+            yield thread
+
+            sync_server.stop()
+            thread.join()
+
+
+        @pytest.fixture(scope='module')
+        def fake_sync_device_manager():  # noqa: ARG001
+            fake_device_manager = FakeSyncDeviceManager(host=fake_icl_host, port=fake_icl_port)
+            fake_device_manager.start()
+
+            yield fake_device_manager
+            fake_device_manager.stop()
+
+        def your_unit_test(fake_sync_icl_exe, fake_sync_device_manager):
+            pass
+
+    """
+
+    def __init__(self, host: str = '127.0.0.1', port: int = 25011):
+        self.host = host
+        self.port = port
+        self.error_db: FakeErrorDB = FakeErrorDB()
+        self.websocket_communicator = WebsocketCommunicator('ws://' + self.host + ':' + str(self.port))
+
+    def start(self) -> None:
+        self.websocket_communicator.open()
+
+    def stop(self) -> None:
+        self.websocket_communicator.close()
+
+    @override
+    def discover_devices(self, error_on_no_device: bool = False) -> None:
+        """
+        Does nothing.
+        """
+        pass
+
+    @property
+    @override
+    def communicator(self) -> WebsocketCommunicator:
+        """Communicator"""
+        return self.websocket_communicator
+
+    @property
+    @override
+    def monochromators(self) -> list[Monochromator]:
+        """
+        Abstract method to get the detected monochromators.
+
+        Returns:
+            List[Monochromator]: The detected monochromators
+        """
+        return [Monochromator(0, self.communicator, self.error_db)]
+
+    @property
+    @override
+    def charge_coupled_devices(self) -> list[ChargeCoupledDevice]:
+        """
+        Abstract method to get the detected CCDs.
+
+        Returns:
+            List[ChargeCoupledDevice]: The detected CCDS.
+        """
+        return [ChargeCoupledDevice(0, self.communicator, self.error_db)]

horiba_sdk/sync/devices/fake_icl_server.py

@@ -0,0 +1,79 @@
+import importlib.resources
+import json
+from pathlib import Path
+from typing import Optional
+
+from loguru import logger
+from websockets.sync.server import WebSocketServer, serve
+
+
+class FakeICLServer:
+    """The FakeICLServer is a synchronous fake ICL server that sends only dummy data.
+
+    It starts a local websocket server and returns the predefined response located in
+    `horiba_sdk/devices/fake_responses/*.json`.
+    Currently supported devices for fake responses are:
+    - The ICL itself
+    - The :class:`Monochromator`
+    - The :class:`ChargeCoupledDevice`
+
+    For other unsupported devices, it just responds with the sent command.
+
+    """
+
+    def __init__(self, fake_icl_host: str = 'localhost', fake_icl_port: int = 8765):
+        self._fake_icl_host: str = fake_icl_host
+        self._fake_icl_port: int = fake_icl_port
+        self._server: Optional[WebSocketServer] = None
+
+        fake_responses_path: Path = Path(str(importlib.resources.files('horiba_sdk.devices'))) / Path('fake_responses')
+
+        icl_fake_responses_path = fake_responses_path / 'icl.json'
+        with open(icl_fake_responses_path) as json_file:
+            self.icl_responses = json.load(json_file)
+
+        monochromator_fake_responses_path = fake_responses_path / 'monochromator.json'
+        with open(monochromator_fake_responses_path) as json_file:
+            self.monochromator_responses = json.load(json_file)
+
+        ccd_fake_responses_path = fake_responses_path / 'ccd.json'
+        with open(ccd_fake_responses_path) as json_file:
+            self.ccd_responses = json.load(json_file)
+
+    def echo(self, websocket):
+        for message in websocket:
+            logger.info('received: {message}', message=message)
+            command = json.loads(message)
+
+            if 'shutdown' in command['command']:
+                logger.info('Shutting down websocket')
+                websocket.close()
+                continue
+
+            if 'command' not in command:
+                logger.info('unknown message format, responding with message')
+                websocket.send(message)
+                continue
+            if command['command'].startswith('icl_'):
+                response = json.dumps(self.icl_responses[command['command']])
+                websocket.send(response)
+            elif command['command'].startswith('mono_'):
+                response = json.dumps(self.monochromator_responses[command['command']])
+                websocket.send(response)
+            elif command['command'].startswith('ccd_'):
+                response = json.dumps(self.ccd_responses[command['command']])
+                websocket.send(response)
+            else:
+                logger.info('unknown command, responding with message')
+                websocket.send(message)
+
+    def start(self):
+        self._server = serve(self.echo, host=self._fake_icl_host, port=self._fake_icl_port)
+        self._server.serve_forever()
+
+    def stop(self):
+        if self._server:
+            logger.info('shutting down websocket server...')
+            self._server.shutdown()
+            self._server = None
+            logger.info('shutdown websocket server')

horiba_sdk/sync/devices/single_devices/__init__.py

@@ -0,0 +1,5 @@
+from .abstract_device import AbstractDevice
+from .ccd import ChargeCoupledDevice
+from .monochromator import Monochromator
+
+__all__ = ['AbstractDevice', 'Monochromator', 'ChargeCoupledDevice']

horiba_sdk/sync/devices/single_devices/abstract_device.py

@@ -0,0 +1,83 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from horiba_sdk.communication import Command, Response
+from horiba_sdk.icl_error import AbstractError, AbstractErrorDB
+from horiba_sdk.sync.communication.abstract_communicator import AbstractCommunicator
+
+
+class AbstractDevice(ABC):
+    """
+    Abstract base class representing a generic device.
+
+    This class provides an interface for device-specific operations. Concrete implementations should provide specific
+    functionalities for each of the abstract methods.
+
+    Attributes:
+        _id (int):
+        _communicator (WebsocketCommunicator):
+    """
+
+    def __init__(self, device_id: int, communicator: AbstractCommunicator, error_db: AbstractErrorDB) -> None:
+        self._id: int = device_id
+        self._error_db: AbstractErrorDB = error_db
+        self._communicator: AbstractCommunicator = communicator
+
+    @abstractmethod
+    def open(self) -> None:
+        """
+        Open a connection to the device.
+
+        Returns:
+            Result: Result object indicating success or failure.
+        """
+        if not self._communicator.opened():
+            self._communicator.open()
+
+    @abstractmethod
+    def close(self) -> None:
+        """
+        Close the connection to the device.
+
+        Returns:
+            Result: Result object indicating success or failure.
+        """
+        pass
+
+    def _execute_command(
+        self, command_name: str, parameters: dict[Any, Any], time_to_wait_for_response_in_s: float = 0.1
+    ) -> Response:
+        """
+        Creates a command from the command name, and it's parameters
+        Executes a command and handles the response.
+
+        Args:
+            command_name (str): The name of the command to execute.
+            parameters (dict): The parameters for the command.
+            time_to_wait_for_response_in_s (float, optional): The time to wait for the response. Defaults to 0.1
+
+        Returns:
+            Response: The response from the device.
+
+        Raises:
+            Exception: When an error occurred on the device side.
+        """
+        response: Response = self._communicator.request_with_response(
+            Command(command_name, parameters), time_to_wait_for_response_in_s
+        )
+        if response.errors:
+            self._handle_errors(response.errors)
+        return response
+
+    def _handle_errors(self, errors: list[str]) -> None:
+        """
+        Handles errors, logs them, and may take corrective actions.
+
+        Args:
+            errors (Exception): The exception or error to handle.
+        """
+        for error in errors:
+            icl_error: AbstractError = self._error_db.error_from(error)
+            icl_error.log()
+            # TODO: [saga] only throw depending on the log level, tbd
+            raise Exception(f'Error from the ICL: {icl_error.message()}')