horiba-sdk 0.3.2__py3-none-any.whl

horiba_sdk/devices/device_manager.py

@@ -0,0 +1,250 @@
+"""
+Device Manager Module
+
+This module provides the DeviceManager class, responsible for managing the lifecycle and interactions with devices.
+
+Import Structure Explanation:
+-----------------------------
+Due to the interdependence between the AbstractDevice class and the DeviceManager class, we face a potential circular
+import issue. Specifically, the AbstractDevice class needs knowledge about the DeviceManager, and vice versa.
+
+To handle this challenge while still allowing type checking tools like mypy to function correctly, we've made use of
+Python's TYPE_CHECKING constant available in the `typing` module. This constant is `True` only when type checking is
+performed, and not during runtime. This ensures that:
+
+1. At runtime, there's no circular import, as the import statement within the TYPE_CHECKING block is effectively
+   ignored.
+
+2. During type checking (like when running mypy), the import statement is executed, allowing mypy to recognize and
+   validate types.
+
+Therefore, the `if TYPE_CHECKING:` block is a solution to maintain clean architecture while still benefiting from type
+checking capabilities.
+
+Notes:
+------
+The forward declaration method ("ClassName") is used for type hints within the module to further prevent any runtime
+circular dependencies.
+
+For more details on the TYPE_CHECKING constant and its usage, refer to:
+https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING
+"""
+
+import asyncio
+import importlib.resources
+import platform
+from pathlib import Path
+from typing import Optional, final
+
+import psutil
+from loguru import logger
+from overrides import override
+
+from horiba_sdk.communication import (
+    AbstractCommunicator,
+    Command,
+    CommunicationException,
+    Response,
+    WebsocketCommunicator,
+)
+from horiba_sdk.devices import AbstractDeviceManager
+from horiba_sdk.devices.ccd_discovery import ChargeCoupledDevicesDiscovery
+from horiba_sdk.devices.monochromator_discovery import MonochromatorsDiscovery
+from horiba_sdk.devices.single_devices import ChargeCoupledDevice, Monochromator
+from horiba_sdk.icl_error import AbstractError, AbstractErrorDB, ICLErrorDB
+
+
+@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_communicator.register_binary_message_callback(self._binary_message_callback)
+        self._icl_websocket_ip: str = websocket_ip
+        self._icl_websocket_port: str = websocket_port
+        self._icl_process: Optional[asyncio.subprocess.Process] = 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
+    async def start(self) -> None:
+        if self._start_icl:
+            await self.start_icl()
+
+        await self._icl_communicator.open()
+
+        icl_info: Response = await self._icl_communicator.request_with_response(Command('icl_info', {}))
+        logger.info(f'ICL info: {icl_info.results}')
+
+        if self._binary_messages:
+            await self._enable_binary_messages()
+
+        await self.discover_devices()
+
+    @override
+    async def stop(self) -> None:
+        await self.stop_icl()
+
+    async 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...')
+            # subprocess.Popen([r'C:\Program Files\HORIBA Scientific\SDK\icl.exe'])
+            self._icl_process = await asyncio.create_subprocess_exec(r'C:\Program Files\HORIBA Scientific\SDK\icl.exe')
+        # except subprocess.CalledProcessError:
+        #    logger.error('Failed to start ICL software.')
+        # TODO: [saga] is this the best way handle exceptions?
+        # except Exception as e:  # pylint: disable=broad-exception-caught
+        #     logger.error('Unexpected error: %s', e)
+
+    async def _enable_binary_messages(self) -> None:
+        bin_mode_command: Command = Command('icl_binMode', {'mode': 'all'})
+        response: Response = await 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()}')
+
+    async def stop_icl(self) -> None:
+        """
+        Stops the communication and cleans up resources.
+        """
+        logger.info('Requesting shutdown of ICL...')
+
+        if not self._icl_communicator.opened():
+            await self._icl_communicator.open()
+
+        try:
+            info_command: Command = Command('icl_info', {})
+            response: Response = await self._icl_communicator.request_with_response(info_command)
+
+            logger.info(f'ICL info: {response.results}')
+            shutdown_command: Command = Command('icl_shutdown', {})
+            _response: Response = await self._icl_communicator.request_with_response(shutdown_command, timeout=10)
+        except CommunicationException as e:
+            logger.debug(f'CommunicationException: {e.message}')
+
+        if self._icl_communicator.opened():
+            await self._icl_communicator.close()
+
+        if self._icl_process is not None:
+            await self._icl_process.wait()
+        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])
+
+    async 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
+    async 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.
+        """
+        ccds_discovery: ChargeCoupledDevicesDiscovery = ChargeCoupledDevicesDiscovery(
+            self._icl_communicator, self._icl_error_db
+        )
+        await ccds_discovery.execute(error_on_no_device)
+        self._charge_coupled_devices = ccds_discovery.charge_coupled_devices()
+
+        monochromators_discovery: MonochromatorsDiscovery = MonochromatorsDiscovery(
+            self._icl_communicator, self._icl_error_db
+        )
+        await monochromators_discovery.execute(error_on_no_device)
+        self._monochromators = monochromators_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/devices/fake_device_manager.py

@@ -0,0 +1,133 @@
+from typing import final
+
+from overrides import override
+
+from horiba_sdk.communication.websocket_communicator import WebsocketCommunicator
+from horiba_sdk.devices.single_devices import ChargeCoupledDevice, Monochromator
+from horiba_sdk.icl_error import FakeErrorDB
+
+from .abstract_device_manager import AbstractDeviceManager
+
+
+@final
+class FakeDeviceManager(AbstractDeviceManager):
+    """
+    The FakeDeviceManager represents a `horiba_sdk.devices.DeviceManager` that can be used in the unit tests. 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`
+
+    For other unsupported devices, it just responds with the sent command.
+
+    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_device_manager():
+            fake_device_manager = FakeDeviceManager(fake_icl_host, fake_icl_port)
+            return fake_device_manager
+
+
+        @pytest.fixture(scope='module')
+        def _run_fake_icl_server(fake_device_manager):
+            thread = threading.Thread(target=fake_device_manager.start_icl)
+            thread.start()
+            yield
+            fake_device_manager.loop.call_soon_threadsafe(fake_device_manager.server.cancel)
+            thread.join()
+
+        @pytest.mark.asyncio
+            async def your_unit_test(fake_device_manager, _run_fake_icl_server):
+            pass
+
+    """
+
+    def __init__(self, host: str = '127.0.0.1', port: int = 25011):
+        self.host = host
+        self.port = port
+        # self.websocket: Optional[WebSocketServerProtocol] = None
+        self.error_db: FakeErrorDB = FakeErrorDB()
+        self.websocket_communicator = WebsocketCommunicator('ws://' + self.host + ':' + str(self.port))
+
+    #         current_directory = os.path.dirname(__file__)
+    #         fake_responses_path = os.path.join(current_directory, 'fake_responses')
+
+    #         icl_fake_responses_path = os.path.join(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 = os.path.join(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 = os.path.join(fake_responses_path, 'ccd.json')
+    #         with open(ccd_fake_responses_path) as json_file:
+    #             self.ccd_responses = json.load(json_file)
+
+    async def start(self) -> None:
+        """
+        Does nothing.
+        """
+        await self.websocket_communicator.open()
+
+    async def stop(self) -> None:
+        """
+        Does nothing.
+        """
+        await self.websocket_communicator.close()
+
+    @override
+    async def discover_devices(self, error_on_no_device: bool = False) -> None:
+        """
+        Does nothing.
+        """
+        pass
+
+    @property
+    @override
+    def communicator(self) -> WebsocketCommunicator:
+        """Communicator"""
+        # return WebsocketCommunicator('ws://' + self.host + ':' + str(self.port))
+        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)]
+
+    # async def _echo_handler(self, websocket: WebSocketServerProtocol) -> None:
+    #     async for message in websocket:
+    #         logger.info('received: {message}', message=message)
+    #         command = json.loads(message)
+    #         if command['command'].startswith('icl_'):
+    #             response = json.dumps(self.icl_responses[command['command']])
+    #             await websocket.send(response)
+    #         elif command['command'].startswith('mono_'):
+    #             response = json.dumps(self.monochromator_responses[command['command']])
+    #             await websocket.send(response)
+    #         elif command['command'].startswith('ccd_'):
+    #             response = json.dumps(self.ccd_responses[command['command']])
+    #             await websocket.send(response)
+    #         else:
+    #             logger.info('unknown command, responding with message')
+    #             await websocket.send(message)

horiba_sdk/devices/fake_icl_server.py

@@ -0,0 +1,56 @@
+import json
+import os
+
+import websockets
+from loguru import logger
+
+
+class FakeICLServer:
+    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 = None
+
+        current_directory = os.path.dirname(__file__)
+        fake_responses_path = os.path.join(current_directory, 'fake_responses')
+
+        icl_fake_responses_path = os.path.join(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 = os.path.join(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 = os.path.join(fake_responses_path, 'ccd.json')
+        with open(ccd_fake_responses_path) as json_file:
+            self.ccd_responses = json.load(json_file)
+
+    async def echo(self, websocket):
+        async for message in websocket:
+            logger.info('received: {message}', message=message)
+            command = json.loads(message)
+            if 'command' not in command:
+                logger.info('unknown message format, responding with message')
+                await websocket.send(message)
+
+            if command['command'].startswith('icl_'):
+                response = json.dumps(self.icl_responses[command['command']])
+                await websocket.send(response)
+            elif command['command'].startswith('mono_'):
+                response = json.dumps(self.monochromator_responses[command['command']])
+                await websocket.send(response)
+            elif command['command'].startswith('ccd_'):
+                response = json.dumps(self.ccd_responses[command['command']])
+                await websocket.send(response)
+            else:
+                logger.info('unknown command, responding with message')
+                await websocket.send(message)
+
+    async def start(self):
+        self._server = await websockets.serve(self.echo, self._fake_icl_host, self._fake_icl_port)
+
+    async def stop(self):
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()

horiba_sdk/devices/fake_responses/ccd.json

@@ -0,0 +1,168 @@
+{
+  "ccd_discover": {
+    "id": 1234,
+    "command": "ccd_discover",
+    "results": {
+      "count": 1
+    },
+    "errors": []
+  },
+  "ccd_list": {
+    "id": 1234,
+    "command": "ccd_list",
+    "results": {
+      "index0: %2" : "{ productId: 13, deviceType: HORIBA Scientific Syncerity, serialNumber: Camera SN:  2244}"
+    },
+    "errors": []
+  },
+  "ccd_listCount": {
+    "id": 1234,
+    "command": "ccd_listCount",
+    "results": {
+      "count": 2
+    },
+    "errors": []
+  },
+  "ccd_open": {
+    "id": 1234,
+    "command": "ccd_open",
+    "errors": [
+    ]
+  },
+  "ccd_close": {
+    "id": 1234,
+    "command": "ccd_close",
+    "errors": [
+    ]
+  },
+  "ccd_isOpen": {
+    "id": 1234,
+    "command": "ccd_isOpen",
+    "results":{
+      "open": true
+    },
+    "errors": [
+    ]
+  },
+  "ccd_restart": {},
+  "ccd_getConfig": {},
+  "ccd_getChipSize": {
+    "id": 1234,
+    "command": "ccd_getChipSize",
+    "errors": [],
+    "results": {
+      "x": 1024,
+      "y": 256
+    }
+  },
+  "ccd_getChipTemperature": {
+    "id": 1234,
+    "command": "ccd_getChipTemperature",
+    "errors": [],
+    "results": {
+      "temperature": -31.219999313354492
+    }
+  },
+  "ccd_getNumberOfAvgs": {},
+  "ccd_setNumberOfAvgs": {},
+  "ccd_getGain": {
+    "id": 1234,
+    "command": "ccd_getGain",
+    "errors": [],
+    "results": {
+      "info": "High Light",
+      "token": 0
+    }
+  },
+  "ccd_setGain": {},
+  "ccd_getSpeed": {
+    "id": 1234,
+    "command": "ccd_getSpeed",
+    "errors": [],
+    "results": {
+      "info": "45 kHz       ",
+      "token": 0
+    }
+  },
+  "ccd_setSpeed": {},
+  "ccd_getFitParams": {
+    "id": 1234,
+    "command": "ccd_getFitParams",
+    "errors": [],
+    "results": {
+      "params": "0,1,0,0,0"
+    }
+  },
+  "ccd_setFitParams": {},
+  "ccd_getExposureTime": {
+    "id": 1234,
+    "command": "ccd_getExposureTime",
+    "errors": [],
+    "results": {
+      "time": 0
+    }
+  },
+  "ccd_setExposureTime": {},
+  "ccd_getTimerResolution": {
+    "id": 1234,
+    "command": "ccd_getTimerResolution",
+    "errors": [],
+    "results": {
+      "resolution": 1000
+    }
+  },
+  "ccd_setTimerResolution": {},
+  "ccd_setAcqFormat": {},
+  "ccd_setRoi": {},
+  "ccd_getXAxisConversionType": {
+    "command": "ccd_getXAxisConversionType",
+    "errors": [],
+    "id": 0,
+    "results": {
+      "type": 0
+    }
+  },
+  "ccd_setXAxisConversionType": {},
+  "ccd_getDataRetrievalMethod": {},
+  "ccd_setDataRetrievalMethod": {},
+  "ccd_getAcqCount": {
+    "command": "ccd_getAcqCount",
+    "errors": [],
+    "id": 0,
+    "results": {
+      "count": 1
+    }
+  },
+  "ccd_setAcqCount": {},
+  "ccd_getCleanCount": {
+    "command": "ccd_getCleanCount",
+    "errors": [],
+    "id": 0,
+    "results": {
+      "count": 1,
+      "mode": 238
+    }
+  },
+  "ccd_setCleanCount": {},
+  "ccd_getDataSize": {
+    "command": "ccd_getDataSize",
+    "errors": [],
+    "id": 0,
+    "results": {
+      "size": 1024
+    }
+  },
+  "ccd_getTriggerIn": {
+    "command": "ccd_getTriggerIn",
+    "errors": [],
+    "id": 0,
+    "results": {
+      "addressWhere": -1,
+      "eventWhen": -1,
+      "sigTypeHow": -1
+    }
+  },
+  "ccd_setTriggerIn": {},
+  "ccd_getSignalOut": {},
+  "ccd_setSignalOut": {}
+}

horiba_sdk/devices/fake_responses/icl.json

@@ -0,0 +1,29 @@
+{
+  "icl_info": {
+    "command": "icl_info",
+    "errors": [],
+    "id": 1234,
+    "results": {
+      "nodeAlias": "ICL",
+      "nodeApiVersion": 300,
+      "nodeBuilt": "Dec  5 2023-13:17:00",
+      "nodeDescription": "Instrument Control Library",
+      "nodeId": 1,
+      "nodeVersion": "2.0.0.108.d762232a"
+    }
+  },
+  "icl_shutdown": {
+    "id": 1234,
+    "command": "icl_shutdown",
+    "results": {
+      "state": "Shutting down"
+    },
+    "errors": []
+  },
+  "icl_binMode": {
+    "id": 1234,
+    "command": "icl_binMode",
+    "results": {},
+    "errors": []
+  }
+}