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

mmcbrs232/broker_and_workers.py

@@ -0,0 +1,582 @@
+#!/usr/bin/env python3
+"""
+Manage access to serial ports for MMCB PID control loops which are running
+asynchronously, and will compete for access to serial ports.
+
+There is one PSU/instrument for each serial port, so use one worker per port
+to serialise requests since an individual RS232 serial port will not tolerate
+concurrent access. Concurrent access to different serial ports is allowable.
+
+The clients on the left hand side represent PID loop monitoring/control. A
+broker routes traffic between the clients and workers.
+
+This script runs the broker and spawns one worker per serial port as based on
+the cached equipment configuration.
+
+                +--------+    +--------------+
+                |        |    |    worker    |
+                |        o----| /dev/ttyUSB0 |
+                |        |    +--------------+
++----------+    |        |
+| client 1 o----o        |    +--------------+
++----------+    |        |    |    worker    |
+                |        o----| /dev/ttyUSB1 |
++----------+    |        |    +--------------+
+| client 2 +----o broker |
++----------+    |        |         ......
+                |        |
++----------+    |        |    +--------------+
+| client 3 +----o        |    |    worker    |
++----------+    |        o----| /dev/ttyUSB6 |
+                +--------+    +--------------+
+"""
+
+import argparse
+import fcntl
+import multiprocessing as mp
+import queue
+import threading
+import time
+
+import serial
+import zmq
+
+from mmcbrs232 import common
+from mmcbrs232 import mdbroker
+from mmcbrs232 import psuset
+from mmcbrs232 import psustat
+from mmcbrs232 import ult80 as chiller
+from mmcbrs232 import mdwrkapi
+
+
+###############################################################################
+# command line handler
+###############################################################################
+
+
+def check_arguments():
+    """
+    handle command line options
+
+    --------------------------------------------------------------------------
+    args : none
+    --------------------------------------------------------------------------
+    returns
+        settings : dictionary
+            contains core information about the test environment
+    --------------------------------------------------------------------------
+    """
+    parser = argparse.ArgumentParser(
+        description=(
+            'ZeroMQ server (broker and workers) for the ATLAS Pixels '
+            'multi-module cycling box serial port devices. This server '
+            'manages concurrent access to serial port resources for all '
+            'attached clients. Commands line scripts emulated are psuset, '
+            'psustat and ult80. WARNING: ANY attached client has the authority '
+            'to change ANY power supply or chiller parameter at ANY time. '
+            'Clients (PID control loops) running concurrently must ensure that '
+            'they only modify their own resources, and not those of other '
+            'clients.'
+        )
+    )
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='Enable logging.'
+    )
+    parser.add_argument(
+        '-n', '--nolock',
+        action='store_true',
+        help=(
+            'Disable the use of the global rs232 lock. '
+            'For safety this script will use the global rs232 lock by default. '
+            'This lock is a coarse measure that should prevent concurrent '
+            'serial port access, even to different ports, by this server and '
+            'other command line scripts that may access serial port resources. '
+            'When running multiple concurrent asynchronous PID control '
+            'scripts, using -n allows optimal sharing of serial port resources '
+            'between those scripts.'
+        )
+    )
+
+    return parser.parse_args()
+
+
+###############################################################################
+# support for commands: psuset, psustat, ult80
+###############################################################################
+
+
+def default():
+    """
+    ---------------------------------------------------------------------------
+    args : none
+    ---------------------------------------------------------------------------
+    returns : dict
+    ---------------------------------------------------------------------------
+    """
+    return {
+        'alias': None,
+        'channel': None,
+        'current_limit': None,
+        'debug': None,
+        'decimal_places': 2,
+        'forwardbias': False,
+        'immediate': False,
+        'manufacturer': None,
+        'model': None,
+        'on': None,
+        'peltier': False,
+        'port': None,
+        'quiet': False,
+        'rear': None,
+        'reset': False,
+        'serial': None,
+        'settlingtime': 0.5,
+        'verbose': None,
+        'voltage': None,
+        'voltspersecond': 10
+    }
+
+
+def psuset_communicate(settings, pipeline, channel, setpsu):
+    """
+    Send command to power supply, do not perform checking of set values..
+
+    ---------------------------------------------------------------------------
+    args
+        settings : dict
+        pipeline : class Pipeline
+        channel : instance of class Channel
+        setpsu : dict
+            lookup table containing functions to call for high/low-voltage PSUs
+    ---------------------------------------------------------------------------
+    returns
+        success : bool
+    ---------------------------------------------------------------------------
+    """
+    with serial.Serial(port=channel.port) as ser:
+        ser.apply_settings(channel.config)
+        ser.reset_input_buffer()
+        ser.reset_output_buffer()
+        success = setpsu[channel.category](
+            settings, pipeline, ser, channel, slow=False
+        )
+
+    return success
+
+
+def handle_psuset_request(pipeline, command, psus, channels):
+    """
+    Process psuset command using the existing psuset code.
+    """
+    # common.unique only removes items from the top level dict/list but does
+    # not change the contents, hence the shallow copy.
+    local_psus = psus.copy()
+    local_channels = channels.copy()
+
+    # -------------------------------------------------------------------------
+    # parse psuset command, parameters returned in settings
+    # -------------------------------------------------------------------------
+
+    settings = default()
+    psuset.check_arguments(settings, command)
+
+    # -------------------------------------------------------------------------
+    # basic filtering
+    # -------------------------------------------------------------------------
+
+    single = common.unique(settings, local_psus, local_channels)
+
+    if not single:
+        # could not identify single PSU channel from supplied arguments
+        return False
+
+    try:
+        channel = local_channels[0]
+    except IndexError:
+        # supplied arguments could not be matched to any PSU channel
+        return False
+
+    # -------------------------------------------------------------------------
+    # single PSU channel identified: communicate with PSU
+    # -------------------------------------------------------------------------
+
+    setpsu = {'lvpsu': psuset.configure_lvpsu, 'hvpsu': psuset.configure_hvpsu}
+
+    return global_lock_wrapper(
+        pipeline.use_global_serial_port_lock,
+        lambda: psuset_communicate(settings, pipeline, channel, setpsu)
+    )
+
+
+def handle_psustat_request(pipeline, command, psus, channels):
+    """
+    Mutable variables command and psus must never be changed.
+
+    --------------------------------------------------------------------------
+    args
+        pipeline :
+        command : str
+        psus : dict
+        channels : list
+        t0 : float
+    --------------------------------------------------------------------------
+    returns
+    --------------------------------------------------------------------------
+    """
+    # common.unique only removes items from the top level dict/list but does
+    # not change the contents, hence the shallow copy.
+    local_psus = psus.copy()
+    local_channels = channels.copy()
+
+    settings = {
+        'alias': None,
+        'channel': None,
+        'manufacturer': None,
+        'model': None,
+        'port': None,
+        'serial': None,
+        'time': None,
+    }
+
+    # this call returns configuration in settings
+    psustat.check_arguments(settings, command)
+
+    # does the user-supplied command identify a single PSU channel?
+    single = common.unique(settings, local_psus, local_channels)
+
+    # If filter is False, the supplied command did not attempt to identify a
+    # single channel, and therefore should be ignored. FIXME improve this test
+    if settings['filter'] and not single:
+        print('PSUSTAT rejected')
+        return False
+
+    return global_lock_wrapper(
+        pipeline.use_global_serial_port_lock,
+        lambda: psustat.power_supply_channel_status(
+            settings, pipeline, local_psus, local_channels, common.ANSIColours
+        )
+    )
+
+
+def ult80_communicate(args):
+    """
+    Send command to the ULT80 chiller.
+
+    --------------------------------------------------------------------------
+    args
+        args : <class 'argparse.Namespace'>
+    --------------------------------------------------------------------------
+    returns
+        rval : float or None
+    --------------------------------------------------------------------------
+
+    """
+    ult80 = chiller.Ult80()
+    rval = None
+
+    if args.read_internal_temperature:
+        rval = ult80.read_internal_temperature()
+    elif args.read_setpoint:
+        rval = ult80.read_setpoint_control_point()
+    elif args.set_setpoint:
+        rval = ult80.set_setpoint_control_point(float(args.set_setpoint[0]))
+
+    return rval
+
+
+def handle_ult80_request(pipeline, command, psus, channels):
+    """
+    Process psuset command using the existing psuset code.
+
+    Protect the serial port interaction using the global serial port lock if
+    requested.
+
+    --------------------------------------------------------------------------
+    args
+        pipeline : class Production
+        command : str
+            e.g. 'ult80 -i', 'ult80 -r' or 'ult80 -s <value>'
+        psus : dict
+            Details of the PSU for this serial port (this dict will only have
+            a single entry)
+        channels : list of class Channel
+            details of the PSU channels for this serial port
+    --------------------------------------------------------------------------
+    returns
+    --------------------------------------------------------------------------
+    """
+    return global_lock_wrapper(
+        pipeline.use_global_serial_port_lock,
+        lambda: ult80_communicate(chiller.check_arguments(command))
+    )
+
+
+###############################################################################
+# workers
+###############################################################################
+
+
+def sp_worker(pipeline, port, psus, channels):
+    """
+    Serial port worker for a single specific serial port.
+
+    This will not exit until it receives something from the broker.
+
+    psuset, lvpsu
+        configure_lvpsu(settings, pipeline, ser, dev)
+            order: reset, current_limit, output on/off, voltage
+    psuset, hvpsu
+        configure_hvpsu(settings, pipeline, ser, dev)
+            order: reset, current_limit
+
+    ---------------------------------------------------------------------------
+    args
+        pipeline : class Pipeline
+        port : string
+            e.g. '/dev/ttyUSB0'
+        psus : dict
+            Details of the PSU for this serial port (this dict will only have
+            a single entry)
+        channels : list of class Channel
+            details of the PSU channels for this serial port
+    ---------------------------------------------------------------------------
+    returns : none
+    ---------------------------------------------------------------------------
+    """
+    worker = mdwrkapi.MajorDomoWorker(
+        'tcp://localhost:5556', bytes(port, encoding='utf-8'), pipeline.verbose
+    )
+
+    lut = {
+        'psuset': handle_psuset_request,
+        'psustat': handle_psustat_request,
+        'ult80': handle_ult80_request,
+    }
+
+    reply = None
+    while True:
+        try:
+            pipeline.terminate[port].get_nowait()
+        except queue.Empty:
+            pass
+        else:
+            break
+
+        #######################################################################
+        # request : list
+        # e.g. [b'psuset -10 --limit 0.005 --on --channel 1 --serial 103807']
+        #######################################################################
+
+        request = worker.recv(reply)
+        if request is None:
+            break
+
+        #######################################################################
+        # process and generate reply
+        #######################################################################
+
+        command = next(r.decode() for r in request)
+        cli = command.split(' ')[0].strip()
+
+        t0 = time.monotonic()
+        try:
+            rval = lut[cli](pipeline, command, psus, channels)
+        except KeyError:
+            print('unknown command')
+            rval = None
+
+        reply = [
+            bytes(
+                f'{command} : {rval} ({time.monotonic() - t0:.6f} s)',
+                encoding='utf-8'
+            )
+        ]
+
+
+###############################################################################
+# broker
+###############################################################################
+
+
+def sp_broker(pipeline):
+    """
+    Serial port majordomo broker.
+
+    ---------------------------------------------------------------------------
+    args
+        pipeline : class Pipeline
+    ---------------------------------------------------------------------------
+    returns : none
+    ---------------------------------------------------------------------------
+    """
+    broker = mdbroker.MajorDomoBroker(pipeline.verbose)
+    try:
+        broker.bind('tcp://*:5556')
+    except zmq.error.ZMQError:
+        print('broker could not bind to port, server may already be running')
+    else:
+        broker.mediate()
+
+
+###############################################################################
+# provision for conditional use of rs232 global lock
+###############################################################################
+
+
+def global_lock_wrapper(wrap, func):
+    """
+    Conditionally apply the global serial port lock.
+
+    The lock is enabled by default and makes this server play nicely with
+    other command line scripts that access serial ports directly. However, this
+    prevents any exploitation of safe concurrency, and the mean response latency
+    may substantially increase depending on the access pattern.
+
+    ---------------------------------------------------------------------------
+    args
+        wrap : bool
+        func : callable
+    ---------------------------------------------------------------------------
+    returns
+        rval : returned result from func()
+    ---------------------------------------------------------------------------
+    """
+    rval = None
+
+    if wrap:
+        with open(common.RS232_LOCK_GLOBAL, 'a') as lock_file:
+
+            # acquire the RS232 global lock
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+
+            rval = func()
+
+            # release the RS232 global lock
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+    else:
+        rval = func()
+
+    return rval
+
+
+###############################################################################
+# main
+###############################################################################
+
+def main():
+    """
+    """
+    args = check_arguments()
+    settings = default()
+
+    ###########################################################################
+    # read hardware configuration from cache
+    #
+    # psus = {
+    #     '/dev/ttyUSB6': (
+    #         {
+    #             'baudrate': 9600, 'bytesize': 8, 'parity': 'N',
+    #             'stopbits': 1,'xonxoff': False, 'dsrdtr': False,
+    #             'rtscts': False, 'timeout': 1, 'write_timeout': 1,
+    #             'inter_byte_timeout': None
+    #         },
+    #         'chiller', None, 'ult80', 'thermoneslab',[''], 0.01
+    #     ),
+    #     ...
+    # }
+    #
+    # channels = [
+    #     Channel(
+    #         port="/dev/ttyUSB3",
+    #         config={
+    #             'baudrate': 9600, 'bytesize': 8, 'parity': 'N',
+    #             'stopbits': 1,
+    #             'xonxoff': False, 'dsrdtr': False, 'rtscts': True,
+    #             'timeout': 1, 'write_timeout': 1,
+    #             'inter_byte_timeout': None
+    #         },
+    #         serial_number="103807", model="hmp4040", manufacturer="hameg",
+    #         channel="1", category="lvpsu", release_delay=0.026,
+    #         ident="hmp4040 103807 1"
+    #     ),
+    #     ...
+    # ]
+    #
+    ###########################################################################
+
+    psus = common.cache_read(['hvpsu', 'lvpsu', 'chiller'])
+    channels = common.ports_to_channels(settings, psus)
+    ports = sorted(psus)
+
+    ###########################################################################
+    # set up hardware
+    ###########################################################################
+
+    class Pipeline:
+        terminate = {port: mp.Queue() for port in ports}
+        verbose = args.verbose
+        portaccess = {
+            port: threading.Lock()
+            for port in ports
+        }
+        use_global_serial_port_lock = not args.nolock
+
+    pipeline = Pipeline()
+
+    ###########################################################################
+    # Check serial ports as listed in the cache are reachable. For each port
+    # clear buffers and perform basic setup.
+    ###########################################################################
+
+    global_lock_wrapper(
+        pipeline.use_global_serial_port_lock,
+        lambda: common.initial_power_supply_check(
+            settings, pipeline, psus, channels, True, False,
+        )
+    )
+
+    ###########################################################################
+    # set up broker and one worker per serial port
+    ###########################################################################
+
+    workers = {}
+    for port in ports:
+
+        psu_for_port = {k: v for k, v in psus.items() if k == port}
+        channels_for_port = [c for c in channels if c.port == port]
+
+        workers[port] = threading.Thread(
+            target=sp_worker,
+            args=(
+                pipeline, port, psu_for_port, channels_for_port,
+            )
+        )
+
+    broker = threading.Thread(target=sp_broker, args=(pipeline, ), daemon=True)
+
+    ###########################################################################
+    # launch threads
+    ###########################################################################
+
+    broker.start()
+
+    for worker in workers.values():
+        worker.start()
+
+    ###########################################################################
+    # terminate threads
+    #
+    # Kill the worker threads one-by-one. The broker daemon thread will exit
+    # automatically when it's the only thing left running.
+    ###########################################################################
+
+    # for port, worker in workers.items():
+    #     pipeline.terminate[port].put(None)
+    #     worker.join()
+
+
+###############################################################################
+if __name__ == '__main__':
+    main()