sqidevice 2.0.0__py3-none-any.whl

sqidevice/__init__.py

@@ -0,0 +1,18 @@
+# Public device class
+from .sqidevice import SQIDevice, CRLF
+
+# Error handling classes
+from .sqidevice import DeviceError, USBError
+
+# Helper functions
+from .sqidevice import convert_measurement, load_script
+
+# Define * imports
+__all__ = [
+    "SQIDevice",
+    "CRLF",
+    "DeviceError",
+    "USBError",
+    "convert_measurement",
+    "load_script",
+]

sqidevice/sqidevice.py

@@ -0,0 +1,801 @@
+"""
+Santec Quantum Instrument device class
+Simplifies communication and control of compatible devices
+
+(c) Santec Australia, 2016--2025
+http://www.santec.com/
+"""
+
+import logging
+import select
+import socket
+import threading
+import contextlib
+import string
+import time
+import re
+
+from typing import Union, Optional, Dict, Tuple, Generator, List
+from struct import unpack
+import functools
+import serial
+
+# Delimiter for "End of Message" (EOM)
+CRLF = b"\r\n"
+# Define convenience type that represents either a unicode string, or bytes array
+DATA = Union[str, bytes]
+
+# Specify the default level for new connections
+# This reduces verbosity when running the discovery process
+DEFAULT_LOG_LEVEL = logging.INFO
+
+UNIT_SYNONYMS = {
+    "degC": "°C",
+}
+
+
+###
+### EXCEPTION CLASSES
+###
+class DeviceError(RuntimeError):
+    """
+    Helper class representing an error response raised by the device, as distinct from a comms error during transport.
+    Retains the query string that was sent to the device, the error message response, and the device instance.
+    """
+
+    def __init__(self, resp: DATA, query: Optional[str] = None, dev: Optional["SQIDevice"] = None):
+        if isinstance(resp, bytes):
+            resp = resp.decode(errors="replace")
+        if resp.startswith("ERR:"):
+            resp = resp[4:]
+        self.resp = resp.strip()
+        self.query = None if query is None else str(query).strip()
+        self.dev = dev
+
+    def __str__(self) -> str:
+        """Returns the error message response from the device, with any "ERR" prefix removed."""
+        return self.resp
+
+    def __repr__(self) -> str:
+        """Provide a string summary of the interaction for diagnostic purposes"""
+        s = 'DeviceError("%s"' % self.resp.strip()
+        if self.query is not None:
+            s += ', tried "%s"' % self.query
+        if self.dev is not None:
+            s += ", <%s>" % self.dev.connection
+        return s + ")"
+
+
+class USBError(OSError):
+    """
+    Helper class to wrap and translate errors related to the USB interface.
+    """
+
+    def __init__(self, serialException: Union[BaseException, str]):
+        # pyserial has a very unfortunate way of expressing configuration errors as "something went wrong"
+        # this arises if there's an issue with the CDC driver (e.g. did not respond to IRQ fast enough)
+        # so replace that with a clearer error message
+        s = serialException.args[0] if isinstance(serialException, Exception) else str(serialException)
+        if "went wrong" in repr(serialException):
+            s = "Error configuring USB port; unplug USB then try again"
+        elif "ClearCommError" in s:
+            # typically if the device is unplugged/turned off, this is the error that gets raised
+            s = "Device disconnected"
+        elif s.startswith("["):
+            s = s.split("]", 1)[1]
+        else:
+            # otherwise, remove the (useless) additional information about the Windows error
+            s = s.split(":", 1)[0]
+        super().__init__(s)
+
+    @staticmethod
+    def translate(func):
+        """Decorator to transform unhandled SerialException errors into USBError instances."""
+
+        def wrapped(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except serial.SerialException as E:
+                raise USBError(E) from E
+
+        return functools.update_wrapper(wrapped, func)
+
+
+###
+### HELPER FUNCTIONS
+###
+def check_version(required_ver: str, test_ver: str):
+    """
+    Returns True if the decimal-delimited string "test_ver" is at least "required_ver".
+    Note: Deprecated by packaging.version
+    """
+    for astr, bstr in zip(required_ver.split("."), test_ver.split(".")):
+        a, b = int(astr, 10), int(bstr, 10)
+        if b > a:
+            return True
+        if b < a:
+            return False
+    return True
+
+
+def convert_measurement(
+    val: Union[str, int, float], units_out: Optional[str], default_units: str = "", type: callable = float
+):
+    """
+    Simple function for processing strings containing SI units and converting to expected units.
+    @param val: Value to be converted. Should be one of
+                - String with units (e.g. "20 kHz").
+                        Requires a space between the numeric part and the units part.
+                - String without units (e.g. "20")
+                - Numerical value (int or float)
+    @param units_out: String containing the target SI units, or None to indicate no processing
+                      should be performed.
+    @param default_units: Units to associate with `val` if it doesn't already specify units.
+                          Expected to be specified if `val` is not a string.
+    @param type: Callable to convert `val` to the target type, typically `float` or `int`
+
+    @raises ValueError: `val` is interpreted as the empty string, or the mapping between the input and output units
+                        is not implemented.
+    """
+    # split the string into usable parts
+    units_in = default_units
+    if isinstance(val, str):
+        # explicitly handle the scenario of comma-separated values
+        # e.g. "1, 2, 3" should not be interpreted as having units
+        parts = val.split(",", 1)[0].split()
+        if not parts:
+            raise ValueError("Empty string")
+        val = type(parts[0])
+        if len(parts) > 1:
+            units_in = parts[1]
+    # maybe we are ignoring units altogether
+    if units_out is None:
+        return val
+    # maybe there is no conversion to perform
+    if units_in == units_out:
+        return val
+    # we just consider differences in SI scalings
+    pows = {
+        "T": 12,
+        "G": 9,
+        "M": 6,
+        "k": 3,
+        "m": -3,
+        "u": -6,
+        "n": -9,
+        "p": -12,
+        "f": -15,
+    }
+    pow_in = pows.get(units_in[0], 0) if len(units_in) > 1 else 0
+    if pow_in:
+        units_in = units_in[1:]
+    pow_out = pows.get(units_out[0], 0) if len(units_out) > 1 else 0
+    if pow_out:
+        units_out = units_out[1:]
+    # raise an exception if the units still don't match
+    # allow synonyms to be considered equivalent
+    if UNIT_SYNONYMS.get(units_in, units_in) != UNIT_SYNONYMS.get(units_out, units_out):
+        raise ValueError("Units mismatch")
+    return val * 10 ** (pow_in - pow_out)
+
+
+###
+### USB-SERIAL INTERFACE
+###
+class SQIDeviceUSB:
+    """
+    Low-level communications wrapper for USB device communication via virtual serial port (CDC)
+    """
+
+    def __init__(self, port: str, timeout: float):
+        try:
+            self.dev = serial.Serial(
+                port,
+                baudrate=115200,
+                bytesize=8,
+                parity="N",
+                stopbits=1,
+                timeout=timeout,
+                writeTimeout=None,  # blocking on write
+            )
+        except serial.SerialException as E:
+            raise USBError(E) from E
+
+    def close(self):
+        """Close the underlying device handle"""
+        self.dev.close()
+
+    @USBError.translate
+    def pending(self) -> bool:
+        """Check whether any data is waiting to be received"""
+        return self.dev.in_waiting > 0
+
+    @USBError.translate
+    def recv(self, size: int) -> bytes:
+        """Receive a chunk of data from device"""
+        if size < 0:
+            size = max(1, self.dev.in_waiting)
+        return self.dev.read(size)
+
+    @USBError.translate
+    def send(self, data: bytes) -> None:
+        """Send bytes to device"""
+        self.dev.write(data)
+
+    @property
+    @USBError.translate
+    def timeout(self) -> float:
+        """Return the communications timeout (in seconds)"""
+        return self.dev.timeout
+
+    @timeout.setter
+    @USBError.translate
+    def timeout(self, timeout: float) -> None:
+        """Set the communications timeout (in seconds)"""
+        self.dev.timeout = timeout
+
+
+###
+### ETH-TCP INTERFACE
+###
+class SQIDeviceETH:
+    """
+    Low-level communications wrapper for ETH device communication via TCP port
+    """
+
+    def __init__(self, address: str, port: int, timeout: float):
+        dev = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        dev.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        dev.settimeout(timeout)
+        dev.connect((address, port))
+        self.dev = dev
+
+    def close(self):
+        """Close the underlying socket"""
+        self.dev.close()
+
+    def pending(self) -> bool:
+        """Check whether any data is waiting to be received"""
+        try:
+            sel = select.select([self.dev], [], [], 0)
+            return len(sel[0]) > 0
+        except (OSError, ValueError):
+            # socket is invalid or was invalidated DURING the timeout period
+            # so return False since there is no data pending
+            return False
+
+    def recv(self, size: int) -> bytes:
+        """Receive a chunk of data from device"""
+        return self.dev.recv(256 if size < 0 else size)
+
+    def send(self, data: bytes) -> None:
+        """Send bytes to device"""
+        self.dev.sendall(data)
+
+    @property
+    def timeout(self) -> float:
+        """Return the communications timeout (in seconds)"""
+        return self.dev.gettimeout()
+
+    @timeout.setter
+    def timeout(self, timeout: float) -> None:
+        """Set the communications timeout (in seconds)"""
+        self.dev.settimeout(timeout)
+
+
+###
+### DEVICE CLASS
+###
+class SQIDevice:
+    """
+    The high-level class for interacting with Santec Quantum Instruments.
+
+    Key features include
+        - Support for either socket (ETH) or COM (USB) underlying interface
+        - Handles end-of-message (EOM) termination
+        - Handles byte-encoding to/from str
+        - Caches information about the device
+        - Provides high-level queries such as ask(), ask_dict() and ask_val()
+        - Enforces mutex locking on queries to avoid multithreading issues
+        - Provides simple reconnection mechanism
+
+    @param addr: Address string, either starting with "COM" for USB COM port,
+                 else interpreted as an IP address with optional port number
+                 separated by ":".
+    @param port: Port number to use for socket connection, ignored on USB.
+                 Defaults to MOG standard port 7802, ignored if specified as part
+                 of the "addr" string.
+    @param timeout: Timeout in seconds to apply to the connection. Negative value
+                    implies "no timeout" which should not be used in GUI applications.
+    @param minver: Optional minimum version string to check for at connection.
+                   Must be of the form "{MAJ}.{MIN}.{REL}", and raises AssertionError
+                   if the version does not match.
+    @param check: Bool to indicate whether the connection should be sanity-checked,
+                  which automatically queries info_dict()
+    """
+
+    def __init__(
+        self, addr: str, port: Optional[int] = None, timeout: float = 1, minver: str = None, check: bool = True
+    ):
+        assert len(addr), "No address specified"
+        self.dev = None  # The underlying connection object
+        self._dev_info = {}  # A dict of values parsed from the INFO query
+        self._attempts = 0  # Number of connection attempts
+        self._retry_delay = 0.01  # Seconds to wait before reattempting on a RETRY error
+
+        # Regularise the device connection address
+        if addr.startswith("COM") or addr == "USB":
+            if port is not None:
+                addr = "COM%d" % port
+            addr = addr.split(" ", 1)[0]
+        elif ":" not in addr:
+            if port is None:
+                port = 7802 # Default port
+            addr = "%s:%d" % (addr, port)
+        self.connection = addr
+
+        # Create a device-specific logging instance
+        self.logger = logging.getLogger(f"[{self.connection}]")
+        self.logger.setLevel(DEFAULT_LOG_LEVEL)
+
+        # Initiate the connection to the device
+        self.lock = threading.RLock()
+        self.reconnect(timeout, check)
+        if minver is not None:
+            ver = self.versions()["UC"]
+            assert check_version(minver, ver), "Unsupported firmware version; Please update to v%s or newer" % minver
+
+    def __repr__(self) -> str:
+        """Return a string representation containing the device connection address"""
+        return 'SQIDevice("%s")' % self.connection
+
+    def close(self):
+        """Close the underlying device connection"""
+        if self.connected():
+            # NB: Deliberately don't acquire the lock here
+            # This ensures that _any_ thread calling "close" will abort any ongoing (blocking) comms operations
+            self.dev.close()
+            self.dev = None
+
+    def reconnect(self, timeout: Optional[float] = None, check: bool = True):
+        """
+        Attempt to reestablish connection with the device using the known address.
+        @param timeout: Optional timeout (in seconds) to specify for the connection.
+        @param check: If True, sanity-checks the device details after establishing the connection.
+        """
+        # close the handle if open - this is _required_ on USB
+        # ensures that self.dev is None, so connected() is False
+        with self.lock:
+            self.close()
+        # keep track of the number of unsuccessful reconnect attempts
+        self._attempts = max(self._attempts, 0) + 1
+        if timeout is not None:
+            self._timeout = timeout
+        if check:
+            self.logger.info("Connecting to %s, attempt %d", self.connection, self._attempts)
+        # perform the reconnection
+        if self.connection.startswith("COM"):
+            dev = SQIDeviceUSB(self.connection, self._timeout)
+        else:
+            addr, port = self.connection.split(":")
+            dev = SQIDeviceETH(addr, int(port), self._timeout)
+        # connection was successful, so reacquire the lock before changing state [#126]
+        # holding the lock while attempting the connection can hang other threads that would rather just fail
+        # immediately [#96], therefore only reacquire the lock upon connection complete
+        with self.lock:
+            self.dev = dev
+        # check the connection?
+        if check:
+            self._check_reconnect()
+            self.logger.name = f"[{self['serial']}-{self['type']}]"
+        else:
+            # reset the stored information
+            self._dev_info = {}
+        # connection successful, but make negative to track how many failed attempts were required
+        self._attempts = -self._attempts
+        self.logger.debug("Connected")
+
+    def _check_reconnect(self):
+        """
+        Helper function that verifies that "reconnecting" connects to the same device.
+        In particular, this handles the case where a USB port is disconnected and connected to a different product,
+        or if the DHCP lease expires and a different product is allocated the previously-connected IP address.
+
+        @raises RuntimeError: Failed to query information about the device, or does not match expected details.
+        """
+        old_dict = self._dev_info
+        try:
+            info = self.query_info()
+        except Exception as exc:
+            raise RuntimeError("Device did not respond to query") from exc
+        # sanity-check there is something to compare against
+        if not old_dict:
+            return
+        # verify that this is the same device that was connected previously [#119]
+        # note that some details may have changed because of reboot or firmware update, so don't compare
+        # the entire dict
+        if old_dict["type"] != info["type"] or old_dict["serial"] != info["serial"]:
+            self.logger.error(
+                "Device at %s is %s-%s instead of %s-%s",
+                self.connection,
+                info["type"],
+                info["serial"],
+                old_dict["type"],
+                old_dict["serial"],
+            )
+            # prevent the "intended" info from being replaced
+            self._dev_info = old_dict
+            raise RuntimeError("Reconnected to different device")
+
+    def connected(self) -> bool:
+        """
+        Returns True if a valid device connection exists, or False if the connection was closed.
+        Does not actively verify the connection, since that requires waiting for a response.
+        """
+        return self.dev is not None
+
+    def __bool__(self):
+        """Convenience wrapper for connected()"""
+        return self.connected()
+
+    def _check(self):
+        """Internal assertion check to confirm the connection is valid"""
+        assert self.connected(), "Not connected"
+
+    @contextlib.contextmanager
+    def _locked(self):
+        """Internal helper function for checking the connection around acquiring the mutex lock"""
+        # Check the connection is valid BEFORE attempting to acquire the lock
+        # Enables the caller to fail fast if a reconnect attempt is being made in another thread
+        self._check()
+        with self.lock:
+            # Check the connection is valid AFTER acquiring the lock, which might be a long time later
+            # if another thread times out on the connection.
+            # e.g. another thread holds the lock but times out
+            self._check()
+            yield
+
+    def is_iap(self) -> bool:
+        """Returns True if the device is in IAP (firmware update) mode"""
+        # Our "standard" IAP reports "IAP" in the version part of the INFO string
+        return self["is_iap"] if self._dev_info else False
+
+    def keys(self) -> List[str]:
+        """Return the keys available as part of the info query"""
+        return self._dev_info.keys()
+
+    def __getitem__(self, name: str) -> str:
+        """Convenience access to the elements of the cached info_dict() query"""
+        if not self._dev_info:
+            self.query_info()
+        return self._dev_info[name]
+
+    def query_info(self) -> Dict[str, str]:
+        """
+        Interpret the INFO statement into a dict of items to simplify processing.
+        Key strings are all lower-case.
+
+        @param query: Clear cached information and explicitly query, @see info()
+        """
+        # remove the cached info dict
+        self._dev_info = {}
+        # query the INFO statement from the device, allowing for bad EEPROM
+        info = self.ask("info", allow_bytes=True)
+        # handle the scenario where we receive unexpected garbage
+        if isinstance(info, bytes):
+            # \xFF represents an unterminated EEPROM string
+            info = info.split(b"\xff", 1)[0].decode(errors="replace")
+        # split into components, keeping serial and name together
+        parts = info.split(maxsplit=3)
+        # pad out to 4 components
+        parts += [""] * (4 - len(parts))
+
+        # the correct form is "[TYPE][-DEV] [CODE]-[MODEL]-[REV] [VER] [NAME] [SERIAL]"
+        # where TYPE is the product name (e.g. ARF, QRF, LDD)
+        #       DEV identifies an internal (DEBUG) build, not for release
+        #       CODE is the board type running this UC (e.g. B3010, B8110)
+        #       MODEL is the (optical) model-specific information (e.g. 421 for ARFs)
+        #       REV is the string containing the HARDWARE revision
+        #       VER is the version string of the RUNNING firmware (e.g. UC+FPGA or IAP as relevant)
+        #       NAME is the (optical) user-specified name of the unit
+        #       SERIAL is the serial number of the unit, containing the ASSEMBLY revision
+        # if NAME is not specified, SERIAL is used as the NAME
+
+        match = re.match(r"(\w+)\-?(\w+)?-R(\d+)", parts[1])
+        if match:
+            code = match[1]
+            model = match[2]
+            rev = int(match[3])
+        else:
+            code = None
+            model = None
+            rev = None
+
+        # the VER part tells us the CURRENTLY RUNNING code, so it must identify as IAP if we're in IAP mode
+        is_iap = "IAP" in parts[2]
+        # the device type is allowed to have an additional identifying string appended after "-"
+        # this enables us to clearly distinguish between DEBUG/RELEASE builds
+        dev_type = parts[0].split("-")[0]
+
+        # greedy combiner for NAME -- i.e. if there are any unexpected spaces, consider it part of the NAME
+        name, _, serial = parts[3].rpartition(" ")
+        if not name:
+            name = serial
+
+        # construct a dict to return
+        self._dev_info = {
+            "type": dev_type,
+            "dev": "-DEV" in parts[0],
+            "serial": serial,
+            "name": name,
+            "ver": parts[2],
+            "code": code,
+            "model": model,
+            "rev": rev,
+            "iap": is_iap,
+        }
+        return self._dev_info
+
+    def title(self) -> str:
+        """
+        Return a string identifying the device type, name and serial for window title
+        """
+        if self._dev_info:
+            return " ".join({self['type'], self['name'], self['serial']})
+        else:
+            return "Not connected"
+
+    def versions(self) -> Dict[str, str]:
+        """
+        Query the dictionary of version numbers.
+        Keys are expected to be upper-case. Depending on the product, the keys may include:
+            "UC" = Version of the microcontroller firmware
+            "IAP" = Version of the bootloader firmware
+            "DISP" = Version of the integrated display firmware and menu system
+            "FPGA" = Version of the FPGA firmware
+        """
+        verstr = self.ask("version")
+        if verstr == "Command not defined":
+            raise RuntimeError("Incompatible firmware")
+        # does the version string define components?
+        versions = {}
+        if ":" in verstr:
+            # response might be comma-separated or LF-separated (legacy)
+            tk = "," if "," in verstr else "\n"
+            for line in verstr.split(tk):
+                if line.startswith("OK"):
+                    continue
+                name, ver = line.split(":", 2)
+                if " " in ver:
+                    ver = ver.rsplit(" ", 2)[1].strip()
+                versions[name.strip()] = ver
+        else:
+            # legacy: no dictionary, just the micro version
+            versions["UC"] = verstr.strip()
+        return versions
+
+    def cmd(self, cmd: str) -> str:
+        """Send the specified command string, and sanity-check that the response is OK."""
+        resp = self.ask(cmd)
+        if resp.startswith("OK"):
+            return resp
+        elif not resp.startswith("ERR"):
+            resp = f"Invalid response: {resp!r}"
+        raise DeviceError(resp, cmd, self)
+
+    def ask(self, cmd: DATA, allow_bytes: bool = False) -> DATA:
+        """
+        Query the device by sending a query string and receiving the response, and raising a DeviceError if the
+        response string is an error message.
+
+        @param cmd: Data to send to the device, either a `bytes` or `str` object.
+        @param allow_bytes: In most cases a `str` response is expected to the query, but in some cases it may be
+                            preferable to allow returning a `bytes` instance if the reply cannot be decoded to unicode.
+                            If False, failure to decode the response raises RuntimeError.
+
+        @raises DeviceError: The device responded to the query with an "ERR" string.
+        @raises RuntimeError: The response could not be decoded and `allow_bytes` was False.
+        """
+        # check the connection before trying to acquire the lock, to fail early
+        deadline = time.monotonic() + self._timeout
+        while time.monotonic() < deadline:
+            with self._locked():
+                # remove any response waiting on the line
+                self.flush()
+                # perform combination send and receive without releasing the mutex
+                self.send(cmd)
+                # NB: call underlying receive to get a bytes object
+                resp = self.recv().strip()
+            # check if the device was busy
+            if resp == b"ERR: Retry":
+                time.sleep(self._retry_delay)
+                continue
+            break
+        # check if the response indicates an error
+        if resp.startswith(b"ERR:"):
+            raise DeviceError(resp, cmd, self)
+        # if the query was a bytes object, return a bytes object
+        if isinstance(cmd, bytes):
+            return resp
+        # try to decode to unicode
+        try:
+            return resp.decode()
+        except UnicodeError as E:
+            if allow_bytes:
+                return resp
+            raise RuntimeError("Unexpected binary response") from E
+
+    def ask_dict(self, cmd: str) -> Dict[str, str]:
+        """Send a request which returns a dictionary response, with keys and values in Unicode"""
+        resp = self.ask(cmd)
+        # require a colon in there
+        if ":" not in resp:
+            raise ValueError("Not a dictionary")
+        # response could be comma-delimited or newline-delimited (but NOT CRLF)
+        splitchar = "\n" if "\n" in resp else ","
+        # construct the dict (retains original key order)
+        vals = {}
+        # we parse on the ':' first to allow the splitchar to be in the response
+        parts = resp.split(":")
+        key = parts[0].strip()
+        for part in parts[1:-1]:
+            val, _, remainder = part.rpartition(splitchar)
+            vals[key] = val.strip(splitchar + string.whitespace)
+            key = remainder.strip()
+        # special handling for the last key
+        vals[key] = parts[-1].strip(splitchar + string.whitespace)
+        if "" in vals:
+            raise ValueError("Not a dictionary")
+        return vals
+
+    def ask_bin(self, cmd: str) -> bytes:
+        """Send a request which returns a binary response package, returned as bytes"""
+        data = b""
+        datalen = -1
+        deadline = time.monotonic() + self._timeout
+        while time.monotonic() < deadline:
+            # Deliberately release the mutex lock between retries
+            with self._locked():
+                self.flush()
+                self.send(cmd)
+                head = self.recv_raw(4)
+                # is it an error message?
+                if head == b"ERR:":
+                    # receive the rest of the message string, which is EOM-terminated
+                    msg = self.recv().strip()
+                    # the device is too busy to send the reply now, so try again
+                    if msg == b"Retry":
+                        time.sleep(self._retry_delay)
+                        continue
+                    raise DeviceError(msg, cmd, self)
+                # decode the length of the data packet
+                datalen = unpack("<L", head)[0]
+                # receive the payload
+                data = self.recv_raw(datalen)
+                break
+        if datalen < 0:
+            raise TimeoutError("timed out")
+        if len(data) != datalen:
+            raise RuntimeError("Incorrect length received")
+        return data
+
+    def ask_val(self, query: str, units: Optional[str] = None, type: callable = float):
+        """
+        Request a value from the device and convert the response, handling simple unit conversion if specified.
+        @param query: Query string to send to the device.
+        @param units: Optional string specifying the target units, for unit conversion (@see convert_measurement).
+        @param type: Callable specifying the return type.
+        """
+        return convert_measurement(self.ask(query), units, type=type)
+
+    def ask_list(self, query: str, units: Optional[str] = None, type: Optional[callable] = float) -> list:
+        """
+        Query a comma-separated list, and perform units conversion on each element if specified.
+        @param query: Query string to send to the device.
+        @param units: Optional string specifying the target units, for unit conversion (@see convert_measurement).
+        @param type: Optional callable specifying the return type.
+                     If None, returns a list of `str` objects instead of converting each entry.
+        """
+        resp = self.ask(query)
+        # Permit a trailing comma
+        if resp.endswith(","):
+            resp = resp[:-1]
+        # Return the empty list for the trivial reply
+        if not resp:
+            return []
+        parts = resp.split(",")
+        if type is None or type is str:
+            # No type conversion, only remove spaces
+            return [item.strip() for item in parts]
+        else:
+            # Perform type conversion with default units
+            return [convert_measurement(item, units, units, type) for item in parts]
+
+    def send(self, cmd: DATA) -> None:
+        """Send a payload to the device, converting to `bytes` if necessary and appending newline if not present"""
+        with self._locked():
+            if not isinstance(cmd, bytes):
+                cmd = cmd.encode()
+            if not cmd.endswith(CRLF):
+                cmd += CRLF
+            self.logger.debug("-> %r", cmd)
+            self.dev.send(cmd)
+
+    def send_raw(self, data: bytes) -> None:
+        """Send specified bytes to the device, without modification"""
+        with self._locked():
+            return self.dev.send(data)
+
+    def flush(self, timeout: float = 0) -> bytes:
+        """Flush the connection by reading whatever data is pending to be received"""
+        with self._locked():
+            dat = b""
+            deadline = time.monotonic() + timeout
+            while self.dev.pending():
+                dat += self.dev.recv(-1)
+                if time.monotonic() > deadline:
+                    break
+        if dat:
+            self.logger.debug("Flushed %d bytes", len(dat))
+        return dat
+
+    def recv(self) -> bytes:
+        """Receive a CRLF-terminated message from the device, returned as bytes"""
+        with self._locked():
+            data = b""
+            deadline = time.monotonic() + self._timeout
+            # Keep reading until there is no pending data, and the response ends in CRLF
+            while self.dev.pending() or not data.endswith(CRLF):
+                if time.monotonic() > deadline:
+                    raise TimeoutError("timed out")
+                data += self.dev.recv(-1)
+        self.logger.debug("<- %r", data)
+        return data
+
+    def recv_raw(self, size: int) -> bytes:
+        """Receive exactly the specified number of bytes from the device"""
+        with self._locked():
+            data = b""
+            deadline = time.monotonic() + self._timeout
+            while len(data) < size:
+                if time.monotonic() > deadline:
+                    raise TimeoutError("timed out")
+                data += self.dev.recv(size - len(data))
+        self.logger.debug("<- %d bytes", len(data))
+        return data
+
+    def get_timeout(self) -> float:
+        """Return the connection timeout, in seconds"""
+        if self.connected():
+            return self.dev.timeout
+        return self._timeout
+
+    def set_timeout(self, val: float) -> float:
+        """
+        Change the timeout to the specified value, in seconds.
+        Returns the previously-configured timeout, in seconds.
+        """
+        with self.lock:
+            old = self.get_timeout()
+            if self.connected():
+                self.dev.timeout = val
+            # Store the new timeout for reconnection attempts
+            self._timeout = val
+            return old
+
+
+def load_script(filename) -> Generator[Tuple[int, str], None, None]:
+    """
+    Generator function that reads the lines from a text file and removes the comments.
+    Yields a pair of values containing the line number and string contents.
+    Skips empty lines, or lines that only contain comments.
+    """
+    with open(filename) as f:  # open in universal mode
+        for linenum, rawline in enumerate(f):
+            # remove comments
+            line, _, _ = rawline.partition("#")
+            # trim spaces
+            line = line.strip()
+            # only yield non-trivial lines
+            if line:
+                yield linenum + 1, line

sqidevice-2.0.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: sqidevice
+Version: 2.0.0
+Summary: Python interface for communicating with Santec Quantum Instrument devices
+Author: Santec Australia
+License: MIT
+License-File: LICENSE.txt
+Keywords: ethernet,instrument,quantum,santec,usb
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Instrument Drivers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Requires-Dist: pyserial>=3.0
+Description-Content-Type: text/markdown
+
+# SQIDevice: Simple interface to Santec Quantum Instruments
+
+The `SQIDevice` class provides a simple interface for interacting with Santec Quantum Instruments over
+a USB or ETH connection.
+
+It handles end-of-message termination, concatenating multi-component responses, and converts error messages into exceptions to simplify error handling in the application.
+
+Helper functions are provided for common operations, such as `ask_val()` for querying a numerical value and converting SI units, and `ask_list()` to transform comma-separated values into a `list`.
+
+
+## Overview
+
+The `SQIDevice` class is instantiated with a string defining the connection instance, for example:
+```
+# TCP connection by specifying IP address and optionally server port
+SQIDevice("10.1.1.122")
+SQIDevice("10.1.1.122:7802")
+SQIDevice("10.1.1.122", port=7802)
+
+# USB connection via virtual COM port
+SQIDevice("COM3")
+SQIDevice("USB", port=3)
+```
+
+The primary functions for communicating with the device are:
+* `ask(query)`: Send the provided `query` string and return the response as a string.
+        Intended as the main mechanism for _reading_ values from the device.
+        If `query` is bytes, the return value is also bytes.
+* `ask_val(query)`: Calls `ask(query)` and performs type conversion on the response string; to `float` by default.
+        Also performs simple SI-units conversion of the response, when units are provided.
+        Recommended for querying measured values from the device, instead of type-casting the response string directly.
+* `ask_dict(query)`: Calls `ask(query)` and parses the response string into a python dictionary.
+        Intended for parsing compound responses such as `VER` and `REPORT`.
+        Does not perform type conversion of the values.
+* `ask_list(query)`: Calls `ask(query)` and parses the response as a comma-separated list of values.
+        Optionally performs unit conversion and type conversion.
+* `cmd(command)`: Send the provided command string to the device and wait for a response.
+        Commands are different from queries in that they induce an action and hence are expected to respond with an `OK` string.
+        Intended to be used when _writing_ values to the device.
+        Failing to respond in this way raises a `DeviceError`.
+* `reconnect()`: Close the connection (if applicable) and reconnect with the same parameters.
+        Recommended for handling disconnection or reboot events.
+
+
+The queries and commands are product-specific, and can be found in the appropriate Appendix of the relevant product manual.
+
+
+
+## Properties
+The `INFO` query is common across compatible devices to help identify the product at a glance.
+The `SQIDevice` parses this query at connection and stores the results as a `dict` which can be accessed directly by indexing the device instance via `__getitem__()`.
+
+The dictionary contains at least the following keys:
+- `type`: Product name string (e.g. "DDLC" or "FZW").
+- `rev`: Mainboard PCB revision, to help identify firmware compatibility.
+- `ver`: Primary version numbers for the UC (and FPGA if applicable). See also the `VER` query for additional information.
+- `serial`: Serial number of the unit.
+- `name`: User-defined name for the unit, as set with the `DEVNAME` command, or the serial number when a custom name is not set.
+- `iap`: Identifies that the devices is in firmware-update (IAP) mode.
+
+
+## Error handling
+The command and query functions of the `SQIDevice` class raise exceptions to handle error scenarios, that should be caught at the application level.
+
+### DeviceError
+A response was successfully received from the device, but that response is an error message.
+This raises an instance of `DeviceError` containing both the request that failed and the response error message.
+
+### USBError
+Particularly on the Windows(tm) operating system, the error messages raised by `pyserial` are often unintuitive and it is unclear how to resolve them.
+
+The `USBError` class is a subclass of `OSError` that translates the most common error messages into a clearer form.
+
+### TimeoutError
+Raised if no response was received, or an incomplete response was received before the timeout period elapsed.
+
+### OSError
+Typically any error at the transport level will result in a subclass of `OSError` being raised by the underlying `socket` or `serial` class instances.
+Usually this indicates that the device has been disconnected, rebooted, or powered off, and needs to be reconnected.
+
+Examples include `TimeoutError` and `USBError`.
+
+### AssertionError
+If an attempt is made to communicate with the device after closing the connection, it will cause `AssertionError` to be raised.

sqidevice-2.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+sqidevice/__init__.py,sha256=OxVVgspiHlG5Qc3-HSJXjqisyVG-ROVWGtcPLvP0GRY,370
+sqidevice/sqidevice.py,sha256=d88cKGKuR4lYBMzkVx3DEogVXn_VAJCQUJhhms8JdwM,32846
+sqidevice-2.0.0.dist-info/METADATA,sha256=t5V8b35YanJwgCW1LBOcFGR1I6AwIyyem0THsamhGVI,5421
+sqidevice-2.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+sqidevice-2.0.0.dist-info/licenses/LICENSE.txt,sha256=l3dWfXLHqaVlRK3vE5OiMGXf4wBTwecRHm22Poy280Q,1086
+sqidevice-2.0.0.dist-info/RECORD,,

sqidevice-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sqidevice-2.0.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2017 - present, Santec Australia Pty Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE