microscope/controllers/toptica.py: add support for Toptica iChrome MLE (#71)

Author: carandraug

NEWS.rst

@@ -13,6 +13,10 @@ Version 0.7.0 (upcoming)
     `Camera.get_trigger_type` does not return the same as
     `Camera.trigger_type` property.
 
+* New devices supported:
+
+  * Toptica iChrome MLE
+
 * The device server logging was broken in version 0.6.0 for Windows
   and macOS (systems not using fork for multiprocessing).  This
   version fixes that issue.

doc/architecture/supported-devices.rst

@@ -26,7 +26,9 @@ Controllers
 
 - CoolLED (:class:`microscope.controllers.coolled.CoolLED`)
 - Prior ProScan III (:class:`microscope.controllers.prior.ProScanIII`)
-- Lumencor Spectra III light engine (:class:`microscope.controllers.lumencor.SpectraIIILightEngine`)
+- Lumencor Spectra III light engine
+  (:class:`microscope.controllers.lumencor.SpectraIIILightEngine`)
+- Toptica iChrome MLE (:class:`microscope.controllers.toptica.iChromeMLE`)
 - Zaber daisy chain devices
   (:class:`microscope.controllers.zaber.ZaberDaisyChain`)
 - Zaber LED controller (:class:`microscope.controllers.zaber.ZaberDaisyChain`)

microscope/controllers/toptica.py

@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+
+## Copyright (C) 2021 David Miguel Susano Pinto <carandraug@gmail.com>
+##
+## This file is part of Microscope.
+##
+## Microscope is free software: you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## Microscope is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Microscope.  If not, see <http://www.gnu.org/licenses/>.
+
+import logging
+import typing
+
+import serial
+
+import microscope
+import microscope._utils
+import microscope.abc
+
+
+_LOGGER = logging.getLogger(__name__)
+
+_QUOTATION_CODE = ord(b'"')
+
+
+def _parse_string(answer: bytes) -> str:
+    assert answer[0] == _QUOTATION_CODE and answer[-1] == _QUOTATION_CODE
+    return answer[1:-1].decode()
+
+
+def _parse_bool(answer: bytes) -> bool:
+    assert answer in [b"#f", b"#t"]
+    return answer == b"#t"
+
+
+class _iChromeConnection:
+    """Connection to the iChrome MLE.
+
+    This is a simple wrapper to the iChrome MLE interface.  It only
+    supports the parameter commands which reply with a single line
+    which is all we need to support this on Python-Microscope.
+
+    """
+
+    def __init__(self, shared_serial: microscope._utils.SharedSerial) -> None:
+        self._serial = shared_serial
+
+        self._serial.readlines()  # discard anything that may be on the line
+
+        if self.get_system_type() != "iChrome-MLE":
+            raise microscope.DeviceError("not an iChrome MLE device")
+
+    def _param_command(self, command: bytes) -> bytes:
+        """Run command and return raw answer (minus prompt and echo)."""
+        command = command + b"\r\n"
+        with self._serial.lock:
+            self._serial.write(command)
+            answer = self._serial.read_until(b"\r\n> ")
+
+        # When we read, we are reading the whole command console
+        # including the prompt and even the command is echoed back.
+        assert answer[: len(command)] == command and answer[-4:] == b"\r\n> "
+
+        # Errors are indicated by the string "Error: " at the
+        # beginning of a new line.
+        if answer[len(command) : len(command) + 7] == b"Error: ":
+            base_command = command[:-2]
+            error_msg = answer[len(command) + 8 : -4]
+            raise microscope.DeviceError(
+                "error on command '%s': %s"
+                % (base_command.decode(), error_msg.decode())
+            )
+
+        # Return the answer minus the "echoed" command and the prompt
+        # for the next command.
+        return answer[len(command) : -4]
+
+    def param_ref(self, name: bytes) -> bytes:
+        """Get parameter value (`param-ref` operator)."""
+        return self._param_command(b"(param-ref '%s)" % name)
+
+    def param_set(self, name: bytes, value: bytes) -> None:
+        """Change parameter (`param-set!` operator)."""
+        answer = self._param_command(b"(param-set! '%s %s)" % (name, value))
+        status = int(answer)
+        if status < 0:
+            raise microscope.DeviceError(
+                "Failed to set parameter %s (return value %d)"
+                % (name.decode(), status)
+            )
+
+    def get_serial_number(self) -> str:
+        return _parse_string(self.param_ref(b"serial-number"))
+
+    def get_system_type(self) -> str:
+        return _parse_string(self.param_ref(b"system-type"))
+
+
+class _iChromeLaserConnection:
+    def __init__(self, conn: _iChromeConnection, laser_number: int) -> None:
+        self._conn = conn
+        self._param_prefix = b"laser%d:" % laser_number
+
+        # We Need to confirm that indeed there is a laser at this
+        # position.  There is no command to check this, we just try to
+        # read a parameter and check if it works.
+        try:
+            self.get_label()
+        except microscope.DeviceError as ex:
+            raise microscope.DeviceError(
+                "failed to get label, probably no laser %d" % laser_number
+            ) from ex
+
+    def _param_ref(self, name: bytes) -> bytes:
+        return self._conn.param_ref(self._param_prefix + name)
+
+    def _param_set(self, name: bytes, value: bytes) -> None:
+        self._conn.param_set(self._param_prefix + name, value)
+
+    def get_label(self) -> str:
+        return _parse_string(self._param_ref(b"label"))
+
+    def get_type(self) -> str:
+        return _parse_string(self._param_ref(b"type"))
+
+    def get_delay(self) -> int:
+        return int(self._param_ref(b"delay"))
+
+    def get_enable(self) -> bool:
+        return _parse_bool(self._param_ref(b"enable"))
+
+    def set_enable(self, state: bool) -> None:
+        value = b"#t" if state else b"#f"
+        self._param_set(b"enable", value)
+
+    def get_cw(self) -> bool:
+        return _parse_bool(self._param_ref(b"cw"))
+
+    def set_cw(self, state: bool) -> None:
+        value = b"#t" if state else b"#f"
+        self._param_set(b"cw", value)
+
+    def get_use_ttl(self) -> bool:
+        return _parse_bool(self._param_ref(b"use-ttl"))
+
+    def set_use_ttl(self, state: bool) -> None:
+        value = b"#t" if state else b"#f"
+        self._param_set(b"use-ttl", value)
+
+    def get_level(self) -> float:
+        return float(self._param_ref(b"level"))
+
+    def set_level(self, level: float) -> None:
+        value = b"%.1f" % level
+        self._param_set(b"level", value)
+
+    def get_status_txt(self) -> str:
+        return _parse_string(self._param_ref(b"status-txt"))
+
+
+class _iChromeLaser(microscope.abc.LightSource):
+    def __init__(self, conn: _iChromeConnection, laser_number: int) -> None:
+        super().__init__()
+        self._conn = _iChromeLaserConnection(conn, laser_number)
+
+        # FIXME: set values to '0' because we need to pass an int as
+        # values for settings of type str.  Probably a bug on
+        # Device.set_setting.
+        self.add_setting("label", "str", self._conn.get_label, None, values=0)
+        self.add_setting("type", "str", self._conn.get_type, None, values=0)
+
+        self.add_setting(
+            "delay", "int", self._conn.get_delay, None, values=tuple()
+        )
+
+    def get_status(self) -> typing.List[str]:
+        return self._conn.get_status_txt().split()
+
+    def get_is_on(self) -> bool:
+        if self._conn.get_enable():
+            if self._conn.get_cw():
+                return True
+            else:
+                # There doesn't seem to be command to check whether
+                # the TTL line is currently high, so just return True
+                # if set that way.
+                return self._conn.get_use_ttl()
+        else:
+            return False
+
+    def _do_get_power(self) -> float:
+        return self._conn.get_level() / 100.0
+
+    def _do_set_power(self, power: float) -> None:
+        self._conn.set_level(power * 100.0)
+
+    def _do_enable(self) -> None:
+        self._conn.set_enable(True)
+
+    def _do_disable(self) -> None:
+        self._conn.set_enable(False)
+
+    def _do_shutdown(self) -> None:
+        pass  # Nothing to do
+
+    @property
+    def trigger_mode(self) -> microscope.TriggerMode:
+        return microscope.TriggerMode.BULB
+
+    @property
+    def trigger_type(self) -> microscope.TriggerType:
+        if self._conn.get_use_ttl():
+            return microscope.TriggerType.HIGH
+        else:
+            return microscope.TriggerType.SOFTWARE
+
+    def set_trigger(
+        self, ttype: microscope.TriggerType, tmode: microscope.TriggerMode
+    ) -> None:
+        if tmode is not microscope.TriggerMode.BULB:
+            raise microscope.UnsupportedFeatureError(
+                "only TriggerMode.BULB mode is supported"
+            )
+
+        # From the manual it seems that cw and ttl parameters are
+        # mutually exclusive but also still need to be set separately.
+        if ttype is microscope.TriggerType.HIGH:
+            self._conn.set_cw(False)
+            self._conn.set_use_ttl(True)
+        elif ttype is microscope.TriggerType.SOFTWARE:
+            self._conn.set_use_ttl(False)
+            self._conn.set_cw(True)
+        else:
+            raise microscope.UnsupportedFeatureError(
+                "only trigger type HIGH and SOFTWARE are supported"
+            )
+
+    def _do_trigger(self) -> None:
+        raise microscope.IncompatibleStateError(
+            "trigger does not make sense in trigger mode bulb, only enable"
+        )
+
+
+class iChromeMLE(microscope.abc.Controller):
+    """Toptica iChrome MLE (multi-laser engine).
+
+    The names of the light devices are `laser1`, `laser2`, `laser3`,
+    ...
+
+    """
+
+    def __init__(self, port: str, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._lasers: typing.Dict[str, _iChromeLaser] = {}
+
+        # Setting specified on the manual (M-051 version 03)
+        serial_conn = serial.Serial(
+            port=port,
+            baudrate=115200,
+            timeout=1,
+            bytesize=serial.EIGHTBITS,
+            stopbits=serial.STOPBITS_ONE,
+            parity=serial.PARITY_NONE,
+            xonxoff=False,
+            rtscts=False,
+            dsrdtr=False,
+        )
+        shared_serial = microscope._utils.SharedSerial(serial_conn)
+        ichrome_connection = _iChromeConnection(shared_serial)
+
+        _LOGGER.info("Connected to %s", ichrome_connection.get_serial_number())
+
+        # According to the manual the iChrome can have between 3 and 5
+        # lasers.  There doesn't seem to be a simple command to check
+        # what's installed, we'd have to parse the whole summary
+        # table.  So we try/except to each laser line.
+        for i in range(1, 6):
+            name = "laser%d" % i
+            try:
+                laser = _iChromeLaser(ichrome_connection, i)
+            except microscope.DeviceError:
+                _LOGGER.info("no %s available", name)
+                continue
+            else:
+                _LOGGER.info("found %s on iChrome MLE", name)
+                self._lasers[name] = laser
+
+    @property
+    def devices(self) -> typing.Dict[str, _iChromeLaser]:
+        return self._lasers