Source code for thorlabs_elliptec.helper

from enum import IntEnum
import re

import serial
from serial.tools import list_ports




def find_device(vid:int=None, pid:int=None, manufacturer:str=None, product:str=None, serial_number:str=None, location:str=None):
    """
    Search attached serial ports for a specific device.

    The first device found matching the criteria will be returned.
    Because there is no consistent way to identify serial devices, the default parameters do not
    specify any selection criteria, and thus the first serial port will be returned.
    A specific device should be selected using a unique combination of the parameters.

    The USB vendor (``vid``) and product (``pid``) IDs are exact matches to the numerical values,
    for example ``vid=0x067b`` or ``vid=0x2303``. The remaining parameters are strings specifying a
    regular expression match to the corresponding field. For example ``serial_number="83"`` would
    match devices with serial numbers starting with 83, while ``serial_number=".*83$"`` would match
    devices ending in 83. A value of ``None`` means that the parameter should not be considered,
    however an empty string value (``""``) is subtly different, requiring the field to be present,
    but then matching any value.

    Be aware that different operating systems may return different data for the various fields, 
    which can complicate matching when attempting to write cross-platform code.

    To see a list of serial ports and the relevant data fields:

    .. code-block:: python

        import serial
        for p in list_ports.comports():
            print(f"{p.device}, {p.manufacturer}, {p.product}, {p.vid}, {p.pid}, {p.serial_number}, {p.location}")

    :param vid: Numerical USB vendor ID to match.
    :param pid: Numerical USB product ID to match.
    :param manufacturer: Regular expression to match to a device manufacturer string.
    :param product: Regular expression to match to a device product string.
    :param serial_number: Regular expression to match to a device serial number.
    :param location: Regular expression to match to a device physical location (eg. USB port).
    :returns: First :class:`~serial.tools.list_ports.ListPortInfo` device which matches given criteria.
    """
    for p in list_ports.comports():
        if (vid is not None) and not vid == p.vid: continue
        if (pid is not None) and not pid == p.pid: continue
        if (manufacturer is not None) and ((p.manufacturer is None) or not re.match(manufacturer, p.manufacturer)): continue
        if (product is not None) and ((p.product is None) or not re.match(product, p.product)): continue
        if (serial_number is not None) and ((p.serial_number is None) or not re.match(serial_number, p.serial_number)): continue
        if (location is not None) and ((p.location is None) or not re.match(location, p.location)): continue
        return p





def list_devices() -> str:
    """
    Return a string listing all detected serial devices and any associated identifying properties.

    The manufacturer, product, vendor ID (vid), product ID (pid), serial number, and physical
    device location are provided.
    These can be used as parameters to :meth:`find_device` or the constructor of a device class
    to identify and select a specific serial device.

    :returns: String listing all serial devices and their details.
    """
    result = ""
    for p in list_ports.comports():
        try:
            vid = f"{p.vid:#06x}"
            pid = f"{p.pid:#06x}"
        except:
            vid = p.vid
            pid = p.pid
        result += f"device={p.device}, manufacturer={p.manufacturer}, product={p.product}, vid={vid}, pid={pid}, serial_number={p.serial_number}, location={p.location}\n"
    return result.strip("\n")