mmcb-rs232-avt 1.0.19__py3-none-any.whl → 1.1.37__py3-none-any.whl

{mmcb_rs232 → mmcbrs232}/detect.py

@@ -19,6 +19,7 @@ expected.
 import argparse
 import collections
 import concurrent.futures as cf
+import contextlib
 import functools
 import itertools
 import json
@@ -28,16 +29,97 @@ import time
 import serial
 import serial.tools.list_ports as stlp
 
-from mmcb_rs232 import common
-from mmcb_rs232 import lexicon
+from mmcbrs232 import common
+from mmcbrs232 import lexicon
+
+
+##############################################################################
+# data structures
+##############################################################################
+
+
+class Config:
+    """
+    Container for USB-RS232 adaptor S.No. and equipment device type.
+    """
+    def __init__(self, equipment_ident):
+        self.usb_rs232_serno, self.device_type = equipment_ident
+
+    def __repr__(self):
+        return (
+            f'Config(["{self.usb_rs232_serno}","{self.device_type}"])'
+        )
+
+    def __str__(self):
+        return (
+            f'usb_rs232_serno={self.usb_rs232_serno}, '
+            f'device_type={self.device_type}'
+        )
 
 
 ##############################################################################
 # constants
 ##############################################################################
 
+
 DEBUG = False
 
+
+##############################################################################
+# file i/o
+##############################################################################
+
+
+def get_valid_lines(filepath):
+    """
+    Read configuration file.
+
+    -----------------------------------------------------------------------
+    args
+        filepath : string
+    -----------------------------------------------------------------------
+    yields : str, str
+        e.g. ('AG0K7YCQ', 'dmm_6500')
+    -----------------------------------------------------------------------
+    """
+    with open(filepath, 'r', encoding='utf-8') as infile:
+        for line in infile:
+            no_comment = line.partition('#')[0]
+            try:
+                usb_rs232_serno, device_type = (
+                    p.strip() for p in no_comment.split(',')
+                )
+            except ValueError:
+                continue
+
+            yield usb_rs232_serno, device_type
+
+
+def read_config_file(filepath):
+    """
+    Read configuration file and store contents.
+
+    -----------------------------------------------------------------------
+    args
+        filepath : string
+    -----------------------------------------------------------------------
+    returns : dict
+        e.g. {
+                 'AG0K7YCQ': Config(["AG0K7YCQ","dmm_6500"],
+                 ...
+                 'AB0MLB8N': Config(["AB0MLB8N","lvpsu_hmp4040"],
+            }
+        The next processing step will substitute the dict keys for their
+        allocated serial port name, hence the duplication of the
+        USB-RS232 adaptor serial numbers.
+    -----------------------------------------------------------------------
+    """
+    return {
+        pcfg[0]: Config(pcfg)
+        for pcfg in get_valid_lines(filepath)
+    }
+
+
 ##############################################################################
 # command line option handler
 ##############################################################################
@@ -66,17 +148,57 @@ def check_arguments():
             by other scripts in this suite.'
     )
     parser.add_argument(
-        '--nocache',
+        'config', nargs='?', metavar='config',
+        help=(
+            'Full path to configuration file that indicates which USB-RS232\
+            adaptor is associated with which piece of equipment. The file\
+            format is CSV with limited support for comments, where any text\
+            on a line after a # symbol is ignored.\
+            CSV values should be in pairs (FTDI USB-RS232 adaptor serial number,\
+            equipment type) e.g. AB0NOLFS, lvpsu_hmp4040. Available\
+            equipment types are:\
+            dmm_6500 (Keithley DMM 6500); lvpsu (Agilent E3647A, E3634A);\
+            lvpsu_hmp4040 (Hameg / Rohde & Schwarz HMP4040);\
+            hvpsu (Keithley 2410, ISEG SHQ 222M & 224M);\
+            hvpsu_2614b (Keithley 2614b);\
+            controller (Newport ESP300 & MM4006);\
+            controller_smc (Newport SMC100);\
+            ult80 (Thermo Neslab ULT80).\
+            If a path to a file is present then only a single test\
+            for the given equipment type will be attempted for each specified\
+            serial port (this should be the preferred option). Auto-detection\
+            will be attempted if no file is given (this process may be\
+            unreliable).'
+        ),
+        type=common.check_file_exists, default=None)
+    parser.add_argument(
+        '-i', '--info',
+        action='store_true',
+        help='Display a list of machine-readable serial numbers for\
+        USB-RS232 adaptors. This option provides information for use\
+        with --config, and exits the script afterwards regardless of other\
+        options given',
+    )
+    parser.add_argument(
+        '-n', '--nocache',
         action='store_true',
-        help='do not create cache file from list of detected devices',
+        help='do not create cache file after detecting devices.',
     )
     parser.add_argument(
-        '--delay_dmm6500',
+        '-d', '--delay_dmm6500',
         action='store_true',
-        help='Keithley 2614b may not be detected if tested after DMM 6500'
+        help='2614b devices may not be detected if tested after DMM 6500;\
+        This option changes the order of tests to avoid this issue.\
+        This option only applies to auto-detection, and will be ignored\
+        if a config file is specified.'
     )
 
-    return parser.parse_args()
+    args = parser.parse_args()
+
+    if args.config and args.delay_dmm6500:
+        print('--delay_dmm6500 only applies to automatic detection')
+
+    return args
 
 
 ##############################################################################
@@ -84,6 +206,63 @@ def check_arguments():
 ##############################################################################
 
 
+def find_usb_rs232_adaptors():
+    """
+    Display machine-readable names for connected USB-RS232 adaptors.
+
+    Users may need this information to create the configuration file for use
+    with the --config option.
+
+    --------------------------------------------------------------------------
+    args : none
+    --------------------------------------------------------------------------
+    returns : none
+    --------------------------------------------------------------------------
+    """
+    port_mapping = {
+        com.serial_number: com.device
+        for com in stlp.comports()
+        if common.rs232_port_is_valid(com)
+    }
+    if port_mapping:
+        for serno, port in port_mapping.items():
+            print(f'USB-RS232 adaptor S.No. {serno} on port {port}')
+    else:
+        print('No FTDI USB-RS232 adaptors found')
+
+
+@contextlib.contextmanager
+def managed_serial_port(port, config):
+    """
+    A context manager for serial port handling.
+
+    --------------------------------------------------------------------------
+    args
+        port : string
+            port name
+        config : dict
+            serial port configuration
+    --------------------------------------------------------------------------
+    yields
+        ser : serial.Serial or None
+    --------------------------------------------------------------------------
+    """
+    ser = serial.Serial()
+    ser.apply_settings(config)
+    ser.port = port
+    try:
+        ser.open()
+        ser.reset_input_buffer()
+        ser.reset_output_buffer()
+        yield ser
+    except (OSError, serial.SerialException):
+        print(f'could not open port {port}, skipping.')
+        yield None
+    finally:
+        if ser.is_open:
+            ser.close()
+
+
 def find_controller(port, config):
     """
     Check if an ESP300 or mm4006 is present on the given serial port.
@@ -130,24 +309,14 @@ def find_controller(port, config):
     --------------------------------------------------------------------------
     """
     retval = (None, None, (port, None, None, None, None, None, None))
-    ser = serial.Serial()
-    ser.apply_settings(config)
-    ser.port = port
 
-    # initialise and open serial port
-    try:
-        ser.open()
-    except (OSError, serial.SerialException):
-        sys.exit(f'could not open port {port}, exiting.')
-    else:
-        ser.reset_output_buffer()
-        ser.reset_input_buffer()
+    with managed_serial_port(port, config) as ser:
+        if ser is None:
+            return retval
 
         # manually empty ESP30X's 10 item error FIFO
         # the mm4006 - like the smc100 - only holds the last error
         #
-        # FIXME
-        #
         # The commands differ: TE? (esp300), TE (mm4006).
         # This does not seem to cause problems with the mm4006, however check
         # how the mm4006 handles this. The esp300 needs to have the FIFO
@@ -170,7 +339,6 @@ def find_controller(port, config):
                 ser.readline()
             except serial.SerialException:
                 print(f'cannot access serial port {port}')
-                ser.close()
                 return retval
 
         # command string is identical for esp300 and mm4006
@@ -179,8 +347,8 @@ def find_controller(port, config):
         # get response
         try:
             controller = ser.readline().decode('utf-8').strip().lower()
-        except UnicodeDecodeError:
-            ser.close()
+        except (UnicodeDecodeError, serial.SerialException):
+            pass
         else:
             channels = ['']
             release_delay = None
@@ -225,9 +393,6 @@ def find_controller(port, config):
                     ),
                 )
 
-            # no device detected
-            ser.close()
-
     return retval
 
 
@@ -268,26 +433,17 @@ def find_controller_smc(port, config):
     --------------------------------------------------------------------------
     """
     retval = (None, None, (port, None, None, None, None, None, None))
-    ser = serial.Serial()
-    ser.apply_settings(config)
-    ser.port = port
 
-    # initialise and open serial port
-    try:
-        ser.open()
-    except (OSError, serial.SerialException):
-        sys.exit(f'could not open port {port}, exiting.')
-    else:
-        ser.reset_output_buffer()
-        ser.reset_input_buffer()
+    with managed_serial_port(port, config) as ser:
+        if ser is None:
+            return retval
 
         # the SMC100 retains a record of the last error only
         ser.write(lexicon.motion('smc', 'read error', identifier='1'))
         try:
             ser.readline()
-        except serial.SerialException:
+        except (serial.SerialException, AttributeError):
             print(f'cannot access serial port {port}')
-            ser.close()
             return retval
 
         ser.write(lexicon.motion('smc', 'read controller version', identifier='1'))
@@ -295,8 +451,8 @@ def find_controller_smc(port, config):
         # get response
         try:
             controller = ser.readline().decode('utf-8').strip().lower()
-        except UnicodeDecodeError:
-            ser.close()
+        except (UnicodeDecodeError, serial.SerialException):
+            pass
         else:
             if 'smc' in controller:
                 release_delay = None
@@ -320,9 +476,6 @@ def find_controller_smc(port, config):
                     ),
                 )
 
-            # no device detected
-            ser.close()
-
     return retval
 
 
@@ -386,29 +539,20 @@ def find_lvpsu(port, config):
     --------------------------------------------------------------------------
     """
     retval = (None, None, (port, None, None, None, None, None, None))
-    ser = serial.Serial()
-    ser.apply_settings(config)
-    ser.port = port
 
-    # initialise and open serial port
-    try:
-        ser.open()
-    except (OSError, serial.SerialException):
-        sys.exit(f'could not open port {port}, exiting.')
-    else:
-        ser.reset_input_buffer()
-        ser.reset_output_buffer()
+    with managed_serial_port(port, config) as ser:
+        if ser is None:
+            return retval
 
         # ask device to identify itself
         ser.write(lexicon.power('e3647a', 'identify'))
 
         # attempt to read back response
         try:
-            response = ser.readline()
+            response = ser.readline().lower()
         except (serial.SerialException, AttributeError):
             print(f'cannot access serial port {port}')
         else:
-            response = response.lower()
             if b'agilent' in response or b'hewlett-packard' in response:
                 parts = response.decode('utf-8').split(',')
                 manufacturer = 'agilent'
@@ -441,8 +585,6 @@ def find_lvpsu(port, config):
                 else:
                     print(f'lvpsu: unrecognised model {model}')
 
-        ser.close()
-
     return retval
 
 
@@ -498,29 +640,20 @@ def find_lvpsu_hmp4040(port, config):
     --------------------------------------------------------------------------
     """
     retval = (None, None, (port, None, None, None, None, None, None))
-    ser = serial.Serial()
-    ser.apply_settings(config)
-    ser.port = port
 
-    # initialise and open serial port
-    try:
-        ser.open()
-    except (OSError, serial.SerialException):
-        sys.exit(f'could not open port {port}, exiting.')
-    else:
-        ser.reset_input_buffer()
-        ser.reset_output_buffer()
+    with managed_serial_port(port, config) as ser:
+        if ser is None:
+            return retval
 
         # ask device to identify itself
         ser.write(lexicon.power('hmp4040', 'identify'))
 
         # attempt to read back response
         try:
-            response = ser.readline()
+            response = ser.readline().lower()
         except (serial.SerialException, AttributeError):
             print(f'cannot access serial port {port}')
         else:
-            response = response.lower()
             if b'hameg' in response or b'rohde' in response:
                 release_delay = 0.026
                 parts = response.decode('utf-8').split(',')
@@ -544,8 +677,6 @@ def find_lvpsu_hmp4040(port, config):
                     ),
                 )
 
-        ser.close()
-
     return retval
 
 
@@ -584,24 +715,18 @@ def find_hvpsu(port, config):
     --------------------------------------------------------------------------
     """
     retval = (None, None, (port, None, None, None, None, None, None))
-    ser = serial.Serial()
-    ser.apply_settings(config)
-    ser.port = port
 
-    # initialise and open serial port
-    try:
-        ser.open()
-    except (OSError, serial.SerialException):
-        sys.exit(f'could not open port {port}, exiting.')
-    else:
-        ser.reset_input_buffer()
-        ser.reset_output_buffer()
+    with managed_serial_port(port, config) as ser:
+        if ser is None:
+            return retval
+
+        # ask device to identify itself
         ser.write(lexicon.power('2410', 'identify'))
 
         # attempt to read back response
         try:
             response = ser.readline().lower()
-        except serial.SerialException:
+        except (serial.SerialException, AttributeError):
             print(f'cannot access serial port {port}')
         else:
             if b'keithley' in response:
@@ -670,8 +795,6 @@ def find_hvpsu(port, config):
                         ),
                     )
 
-        ser.close()
-
     return retval
 
 
@@ -712,24 +835,18 @@ def find_hvpsu_2614b(port, config):
     --------------------------------------------------------------------------
     """
     retval = (None, None, (port, None, None, None, None, None, None))
-    ser = serial.Serial()
-    ser.apply_settings(config)
-    ser.port = port
 
-    # initialise and open serial port
-    try:
-        ser.open()
-    except (OSError, serial.SerialException):
-        sys.exit(f'could not open port {port}, exiting.')
-    else:
-        ser.reset_input_buffer()
-        ser.reset_output_buffer()
+    with managed_serial_port(port, config) as ser:
+        if ser is None:
+            return retval
+
+        # ask device to identify itself
         ser.write(lexicon.power('2614b', 'identify'))
 
         # attempt to read back response
         try:
             response = ser.readline().lower()
-        except serial.SerialException:
+        except (serial.SerialException, AttributeError):
             print(f'cannot access serial port {port}')
         else:
             if b'keithley' in response:
@@ -758,8 +875,6 @@ def find_hvpsu_2614b(port, config):
                 except IndexError:
                     pass
 
-        ser.close()
-
     return retval
 
 
@@ -791,18 +906,12 @@ def find_dmm_6500(port, config):
     --------------------------------------------------------------------------
     """
     retval = (None, None, (port, None, None, None, None, None, None))
-    ser = serial.Serial()
-    ser.apply_settings(config)
-    ser.port = port
 
-    # initialise and open serial port
-    try:
-        ser.open()
-    except (OSError, serial.SerialException):
-        sys.exit(f'could not open port {port}, exiting.')
-    else:
-        ser.reset_input_buffer()
-        ser.reset_output_buffer()
+    with managed_serial_port(port, config) as ser:
+        if ser is None:
+            return retval
+
+        # ask device to identify itself
         ser.write(lexicon.instrument('dmm6500', 'identify'))
 
         # attempt to read back response
@@ -815,7 +924,7 @@ def find_dmm_6500(port, config):
                 try:
                     release_delay = 0.01
                     # ['KEITHLEY INSTRUMENTS', 'MODEL DMM6500', '04592428', '1.7.12b']
-                    parts = response.decode('utf-8').lower().split(',')
+                    parts = response.decode('utf-8').split(',')
                     manufacturer = parts[0].split()[0]
                     model = parts[1].split()[-1]
                     serial_number = parts[2]
@@ -838,7 +947,61 @@ def find_dmm_6500(port, config):
                 except IndexError:
                     pass
 
-        ser.close()
+    return retval
+
+
+def find_ult80(port, config):
+    """
+    "Find ULT80", this does not have a machine-readable ID, so just return
+    an empty result.
+
+    --------------------------------------------------------------------------
+    args
+        port : string
+            port name
+        config : dict
+            serial port configuration
+    --------------------------------------------------------------------------
+    returns
+        retval : tuple
+            (category : string,
+             settings : dict,
+             (port : string,
+              manufacturer : string,
+              model : string,
+              serial_number : string,
+              detected : bool,
+              channels : list,
+              release_delay : float))
+    --------------------------------------------------------------------------
+    """
+    retval = (None, None, (port, None, None, None, None, None, None))
+
+    with managed_serial_port(port, config) as ser:
+        if ser is None:
+            return retval
+
+        # arbitrary value...
+        release_delay = 0.01
+        manufacturer = 'thermoneslab'
+        model = 'ult80'
+        serial_number = None
+        detected = True
+        channels = ['']
+        settings = ser.get_settings()
+        retval = (
+            'chiller',
+            settings,
+            (
+                port,
+                manufacturer,
+                model,
+                serial_number,
+                detected,
+                channels,
+                release_delay,
+            ),
+        )
 
     return retval
 
@@ -888,6 +1051,36 @@ def detect_device_on_port(port, tests, configs):
     return retval
 
 
+def detect_device_type_on_port(port, test_func, config):
+    """
+    try all tests on the given port in a bid to identify which category of
+    device is present
+
+    --------------------------------------------------------------------------
+    args
+        port : string
+            port name
+        test_func : dict
+            contains the function to call for each category of device
+        config : dict of dicts
+            {device_type: serial_port_configuration, ...}
+    --------------------------------------------------------------------------
+    returns
+        retval : tuple
+            (category : string,
+             settings : dict,
+             (port : string,
+              manufacturer : string,
+              model : string,
+              serial_number : string,
+              detected : bool,
+              channels : list,
+              release_delay : float))
+    --------------------------------------------------------------------------
+    """
+    return test_func(port, config)
+
+
 ##############################################################################
 # format detail for detected device
 ##############################################################################
@@ -923,17 +1116,106 @@ def display_found(device_type, value, padding):
 
 
 ##############################################################################
-# main
+# autodetect or user specified
 ##############################################################################
 
 
-def main():
+def user_specified(args, configs, found):
     """
-    detect devices present on the serial ports, that are attached via
-    FTDI USB to RS232 adaptors
+    Detect devices present on the serial ports, that are attached via FTDI USB
+    to RS232 adaptors. This method uses a user-supplied config file that
+    gives the relationship between USB-RS232 adaptors (specified by their
+    machine-readable serial numbers). This function obtains the relationship
+    between the USB-RS232 adaptors and port names. This provides a mapping
+    between port name and the type of equipment present on the port, which
+    enables just a single test to be run for each serial port.
+
+    --------------------------------------------------------------------------
+    args
+        args : <class 'argparse.Namespace'>
+        configs : dict
+        found : dict
+    --------------------------------------------------------------------------
+    returns
+        found : dict
+    --------------------------------------------------------------------------
     """
-    args = check_arguments()
+    # usb_rs232_serno, make, model, serno
+    # {pcfg[0]: Config(pcfg)}
+    cfg = read_config_file(args.config)
+
+    # get port to USB-RS232 mapping : {'AG0K7YCQ': '/dev/ttyUSB0', ...}
+    port_mapping = {
+        com.serial_number: com.device
+        for com in stlp.comports()
+        if common.rs232_port_is_valid(com)
+    }
+    if not port_mapping:
+        all_ports = ', '.join(com.device for com in stlp.comports())
+        sys.exit(f'No usable serial ports found: {all_ports}')
+
+    # sort by USB-RS232 adaptor serial number
+    port_mapping = dict(
+        sorted(port_mapping.items(), key=lambda x: x[1])
+    )
+
+    model_to_detect_func = {
+        'dmm_6500': find_dmm_6500,
+        'lvpsu': find_lvpsu,
+        'lvpsu_hmp4040': find_lvpsu_hmp4040,
+        'hvpsu': find_hvpsu,
+        'hvpsu_2614b': find_hvpsu_2614b,
+        'controller': find_controller,
+        'controller_smc': find_controller_smc,
+        'ult80': find_ult80,
+    }
 
+    # {serial_port_name: (test_func, serial_port_config), ...}
+    tasks = {
+        port_mapping[serial_number]: (
+            model_to_detect_func[config_details.device_type],
+            configs[config_details.device_type],
+        )
+        for serial_number, config_details in cfg.items()
+    }
+
+    padding = max(map(len, model_to_detect_func))
+
+    # detect devices on ports
+    _ddtop_pf = functools.partial(detect_device_type_on_port)
+    with cf.ThreadPoolExecutor() as executor:
+        detected = (
+            executor.submit(_ddtop_pf, port_name, tfun, tcfg)
+            for port_name, (tfun, tcfg) in tasks.items()
+        )
+        for future in cf.as_completed(detected):
+            key, settings, value = future.result()
+            if key not in found:
+                found[key] = (settings, [value])
+            else:
+                found[key][1].append(value)
+
+            display_found(key, value, padding)
+
+    return found
+
+
+def auto_detect(args, configs, found):
+    """
+    Detect devices attached to serial ports.
+
+    Run all tests for known equipment on all serial ports.
+
+    --------------------------------------------------------------------------
+    args
+        args : <class 'argparse.Namespace'>
+        configs : dict
+        found : dict
+    --------------------------------------------------------------------------
+    returns
+        found : dict
+    --------------------------------------------------------------------------
+    """
     ports = [
         com.device
         for com in stlp.comports()
@@ -968,6 +1250,43 @@ def main():
             }
         )
 
+    padding = max(map(len, tests))
+
+    # store creation platform in cache
+    found = {'platform': sys.platform.lower()}
+
+    # detect devices on ports
+    _ddop_pf = functools.partial(detect_device_on_port, tests=tests, configs=configs)
+    with cf.ThreadPoolExecutor() as executor:
+        detected = (executor.submit(_ddop_pf, port) for port in ports)
+        for future in cf.as_completed(detected):
+            key, settings, value = future.result()
+            if key not in found:
+                found[key] = (settings, [value])
+            else:
+                found[key][1].append(value)
+
+            display_found(key, value, padding)
+
+    return found
+
+
+##############################################################################
+# main
+##############################################################################
+
+
+def main():
+    """
+    detect devices present on the serial ports, that are attached via
+    FTDI USB to RS232 adaptors
+    """
+    args = check_arguments()
+
+    if args.info:
+        find_usb_rs232_adaptors()
+        return
+
     # define serial port connection settings for each device
     # see https://pyserial.readthedocs.io/en/latest/pyserial_api.html
     common_configuration = {
@@ -1015,6 +1334,11 @@ def main():
             'xonxoff': False,
             'rtscts': True,
         },
+        'ult80': {
+            'baudrate': 9600,
+            'xonxoff': False,
+            'rtscts': False,
+        },
     }
     # create unions of common and device-specific configurations
     configs = {
@@ -1022,30 +1346,28 @@ def main():
         for device, device_specific_configuration in configs.items()
     }
 
-    padding = max(map(len, tests))
-
-    # store creation platform in cache
     found = {'platform': sys.platform.lower()}
 
-    # detect devices on ports
-    _ddop_pf = functools.partial(detect_device_on_port, tests=tests, configs=configs)
-    with cf.ThreadPoolExecutor() as executor:
-        detected = (executor.submit(_ddop_pf, port) for port in ports)
-        for future in cf.as_completed(detected):
-            key, settings, value = future.result()
-            if key not in found:
-                found[key] = (settings, [value])
-            else:
-                found[key][1].append(value)
-
-            display_found(key, value, padding)
+    if args.config:
+        # config file guided process
+        user_specified(args, configs, found)
+    else:
+        # attempt auto-detection of devices attached to serial ports
+        found = auto_detect(args, configs, found)
 
     # JSON output
     if args.nocache:
         print(f'\nJSON:\n\n{json.dumps(found)}')
     else:
-        common.configcache_write(found, common.DEVICE_CACHE)
-        print(f'\nWrote detected configuration to: {common.DEVICE_CACHE}')
+        try:
+            common.configcache_write(found, common.DEVICE_CACHE)
+        except PermissionError:
+            print(
+                f'\nERROR Could not write to {common.DEVICE_CACHE}: '
+                'check file permissions'
+            )
+        else:
+            print(f'\nWrote detected configuration to: {common.DEVICE_CACHE}')
 
 
 ##############################################################################