Source code for psychopy.iohub.client

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# Part of the PsychoPy library
# Copyright (C) 2012-2020 iSolver Software Solutions (C) 2021 Open Science Tools Ltd.
# Distributed under the terms of the GNU General Public License (GPL).

import os
import sys
import time
import subprocess
import json
import signal
import atexit
from weakref import proxy

import psutil

try:
    import psychopy.logging as psycho_logging
except ImportError:
    psycho_logging = None
from ..lazy_import import lazy_import
from .. import IOHUB_DIRECTORY
from ..util import yload, yLoader
from ..errors import print2err, ioHubError, printExceptionDetailsToStdErr
from ..util import isIterable, updateDict, win32MessagePump
from ..devices import DeviceEvent, import_device
from ..devices.computer import Computer
from ..devices.experiment import MessageEvent, LogEvent
from ..constants import DeviceConstants, EventConstants
from psychopy import constants

getTime = Computer.getTime

SHUTDOWN_FUNCS = []

_currentSessionInfo = None

def windowInfoDict(win):
    windict = dict(handle=win._hw_handle, pos=win.pos, size=win.size,
                   units=win.units, useRetina=win.useRetina, monitor=None)
    if win.monitor:
        windict['monitor'] = dict(resolution=win.monitor.getSizePix(),
                                  width=win.monitor.getWidth(),
                                  distance=win.monitor.getDistance())
    return windict

def getFullClassName(klass):
    module = klass.__module__
    if module == 'builtins':
        return klass.__qualname__  # avoid outputs like 'builtins.str'
    return module + '.' + klass.__qualname__

class DeviceRPC():
    '''
    ioHubDeviceView creates an RPC interface with the iohub server. Each
    iohub device method exposed by an ioHubDeviceView is represented
    by an associated DeviceRPC instance.
    '''
    _log_time_index = DeviceEvent.EVENT_HUB_TIME_INDEX
    _log_text_index = LogEvent.CLASS_ATTRIBUTE_NAMES.index('text')
    _log_level_index = LogEvent.CLASS_ATTRIBUTE_NAMES.index('log_level')

    def __init__(self, sendToHub, device_class, method_name):
        self.device_class = device_class
        self.method_name = method_name
        self.sendToHub = sendToHub

    @staticmethod
    def _returnarg(a): # pragma: no cover
        return a

    def __call__(self, *args, **kwargs):
        # Send the device method call request to the ioHub Server and wait
        # for the method return value sent back from the ioHub Server.
        r = self.sendToHub(('EXP_DEVICE', 'DEV_RPC', self.device_class,
                            self.method_name, args, kwargs))
        
        if r is None:
            # print("r is None:",('EXP_DEVICE', 'DEV_RPC', self.device_class,
            #                 self.method_name, args, kwargs))
            return None
        
        r = r[1:]
        if len(r) == 1:
            r = r[0]

        if self.method_name != 'getEvents':
            return r

        # The result of a call to an iohub Device getEvents() method
        # gets some special handling, converting the returned events
        # into the desired object type, etc...
        asType = 'namedtuple'
        if 'asType' in kwargs:
            asType = kwargs['asType']
        elif 'as_type' in kwargs:
            asType = kwargs['as_type']

        conversionMethod = self._returnarg
        if asType == 'dict':
            conversionMethod = ioHubConnection.eventListToDict
        elif asType == 'object':
            conversionMethod = ioHubConnection.eventListToObject
        elif asType == 'namedtuple':
            conversionMethod = ioHubConnection.eventListToNamedTuple

        if self.device_class != 'Experiment':
            return [conversionMethod(el) for el in r]

        EVT_TYPE_IX = DeviceEvent.EVENT_TYPE_ID_INDEX
        LOG_EVT = LogEvent.EVENT_TYPE_ID
        toBeLogged = [el for el in r if el[EVT_TYPE_IX] == LOG_EVT]
        for l in toBeLogged:
            r.remove(l)
            if psycho_logging:
                ltime = l[self._log_time_index]
                ltext = l[self._log_text_index]
                llevel = l[self._log_level_index]
                psycho_logging.log(ltext, llevel, ltime)
        return [conversionMethod(el) for el in r]


# pylint: disable=protected-access

class ioHubDeviceView():
    """
    ioHubDeviceView is used as a client / PsychoPy process side representation
    of an ioHub device that is actually running on the separate iohub process.
    An ioHubDeviceView instance allows the PsychoPy script process to call
    public iohub device methods as if the device method calls were being made
    locally.

    The ioHubConnection class creates an ioHubDeviceView instance for each
    ioHub device being run during the experiment.

    ioHubDeviceView instances are never created directly by a user script,
    they are created for you by the ioHubConnection class when
    it connects to the ioHub Process.
    """

    def __init__(self, hubClient, device_class_path, device_class_name, device_config):
        self.hubClient = hubClient
        self.name = device_config.get('name', device_class_name.lower())
        self.device_class = device_class_name
        self.device_class_path=device_class_path

        rpc_request = ('EXP_DEVICE', 'GET_DEV_INTERFACE', device_class_name)
        r = self.hubClient._sendToHubServer(rpc_request)
        self._methods = r[1]

    def __getattr__(self, name):
        if name in self._methods:
            r = DeviceRPC(self.hubClient._sendToHubServer, self.device_class, name)
            return r
        raise AttributeError(self, name)

    def getName(self):
        """
        Gets the name given to the device in the ioHub configuration file.
        ( the device: name: property )

        Args:
            None

        Returns:
            (str): the user defined label / name of the device
        """
        return self.name

    def getIOHubDeviceClass(self, full=False):
        """
        Gets the ioHub Device class associated with the oHubDeviceView.
        This is specified for a device in the ioHub configuration file.
        ( the device: device_class: property )

        :param full:

        Returns:
            (class): ioHub Device class associated with this ioHubDeviceView

        """
        if full:
            return self.device_class_path
        return self.device_class

    def getDeviceInterface(self):
        """getDeviceInterface returns a list containing the names of all
        methods that are callable for the ioHubDeviceView object. Only public
        methods are included in the interface. Any method beginning with a
        '_' is not included.

        Args:
            None

        Returns:
            (tuple): list of method names in the ioHubDeviceView interface.

        """
        return self._methods

# pylint: enable=protected-access

class ioHubDevices():
    """
    Provides .name access to the ioHub device's created when the ioHub
    Server is started. Each iohub device is accessible via a dynamically
    created attribute of this class, the name of which is defined by the
    device configuration 'name' setting. Each device attribute is an instance
    of the ioHubDeviceView class.

    A user script never creates an instance of this class directly, access
    is provided via the ioHubConnection.devices attribute.
    """

    def __init__(self, hubClient):
        self.hubClient = hubClient
        self._devicesByName = dict()

    def addDevice(self, name, d):
        setattr(self, name, d)
        self._devicesByName[name] = d

    def getDevice(self, name):
        return self._devicesByName.get(name)

    def getAll(self):
        return self._devicesByName.values()

    def getNames(self):
        return self._devicesByName.keys()

[docs]class ioHubConnection():
    """ioHubConnection is responsible for creating, sending requests to, and
    reading replies from the ioHub Process. This class is also used to
    shut down and disconnect the ioHub Server process.

    The ioHubConnection class is also used as the interface to any ioHub Device
    instances that have been created so that events from the device can be
    monitored. These device objects can be accessed via the ioHubConnection
    .devices attribute, providing 'dot name' access to enabled devices.
    Alternatively, the .getDevice(name) method can be used and will return
    None if the device name specified does not exist.

    Using the .devices attribute is handy if you know the name of the device
    to be accessed and you are sure it is actually enabled on the ioHub
    Process.

    An example of accessing a device using the .devices attribute::

        # get the Mouse device, named mouse
        mouse=hub.devices.mouse
        mouse_position = mouse.getPosition()

        print('mouse position: ', mouse_position)

        # Returns something like:
        # >> mouse position:  [-211.0, 371.0]
    """
    ACTIVE_CONNECTION = None

    def __init__(self, ioHubConfig=None, ioHubConfigAbsPath=None):
        if ioHubConfig:
            if not isinstance(ioHubConfig, dict):
                raise ioHubError(
                    'The provided ioHub Configuration is not a dictionary.',
                    ioHubConfig)

        if ioHubConnection.ACTIVE_CONNECTION is not None:
            raise RuntimeError('An existing ioHubConnection is already open. Use '
                                 'iohub.client.ioHubConnection.getActiveConnection() '
                                 'to access it; or use '
                                 'iohub.ioHubConnection.getActiveConnection().quit() '
                                 'to close it.')
        Computer.psychopy_process = psutil.Process()

        # udp port setup
        self.udp_client = None

        # the dynamically generated object that contains an attribute for
        # each device registered for monitoring with the ioHub server so
        # that devices can be accessed experiment process side by device name.
        self.devices = ioHubDevices(self)

        # A circular buffer used to hold events retrieved from self.getEvents()
        # during self.wait() periods.
        self.allEvents = []

        self.experimentID = None
        self.experimentSessionID = None
        self._experimentMetaData = None
        self._sessionMetaData = None
        self._server_process = None
        self._iohub_server_config = None
        self._shutdown_attempted = False
        self._cv_order = None
        self._message_cache = []
        self.iohub_status = self._startServer(ioHubConfig, ioHubConfigAbsPath)
        if self.iohub_status != 'OK':
            raise RuntimeError('Error starting ioHub server: {}'.format(self.iohub_status))

    @classmethod
    def getActiveConnection(cls):
        return cls.ACTIVE_CONNECTION

[docs]    def getDevice(self, deviceName):
        """
        Returns the ioHubDeviceView that has a matching name (based on the
        device : name property specified in the ioHub_config.yaml for the
        experiment). If no device with the given name is found, None is
        returned. Example, accessing a Keyboard device that was named 'kb' ::

            keyboard = self.getDevice('kb')
            kb_events= keyboard.getEvent()

        This is the same as using the 'natural naming' approach supported
        by the .devices attribute, i.e::

            keyboard = self.devices.kb
            kb_events= keyboard.getEvent()

        However the advantage of using getDevice(device_name) is that an
        exception is not created if you provide an invalid device name,
        or if the device is not enabled on the ioHub server; None is returned
        instead.

        Args:
            deviceName (str): Name given to the ioHub Device to be returned

        Returns:
            The ioHubDeviceView instance for deviceName.
        """
        return self.devices.getDevice(deviceName)

[docs]    def getEvents(self, device_label=None, as_type='namedtuple'):
        """Retrieve any events that have been collected by the ioHub Process
        from monitored devices since the last call to getEvents() or
        clearEvents().

        By default all events for all monitored devices are returned,
        with each event being represented as a namedtuple of all event
        attributes.

        When events are retrieved from an event buffer, they are removed from
        that buffer as well.

        If events are only needed from one device instead of all devices,
        providing a valid device name as the device_label argument will
        result in only events from that device being returned.

        Events can be received in one of several object types by providing the
        optional as_type property to the method. Valid values for as_type are
        the following str values:

            * 'list': Each event is a list of ordered attributes.
            * 'namedtuple': Each event is converted to a namedtuple object.
            * 'dict': Each event converted to a dict object.
            * 'object': Each event is converted to a DeviceEvent subclass
                        based on the event's type.

        Args:
            device_label (str): Name of device to retrieve events for.
                                If None ( the default ) returns device events
                                from all devices.

            as_type (str): Returned event object type. Default: 'namedtuple'.

        Returns:
            tuple: List of event objects; object type controlled by 'as_type'.
        """
        r = None
        if device_label is None:
            events = self._sendToHubServer(('GET_EVENTS',))[1]
            if events is None:
                r = self.allEvents
            else:
                self.allEvents.extend(events)
                r = self.allEvents
            self.allEvents = []
        else:
            r = self.devices.getDevice(device_label).getEvents()

        if r:
            if as_type == 'list':
                return r

            conversionMethod = None
            if as_type == 'namedtuple':
                conversionMethod = self.eventListToNamedTuple
            elif as_type == 'dict':
                conversionMethod = self.eventListToDict
            elif as_type == 'object':
                conversionMethod = self.eventListToObject

            if conversionMethod:
                return [conversionMethod(el) for el in r]
            return r

        return []

[docs]    def clearEvents(self, device_label='all'):
        """Clears unread events from the ioHub Server's Event Buffer(s)
        so that unneeded events are not discarded.

        If device_label is 'all', ( the default ), then events from both the
        ioHub *Global Event Buffer* and all *Device Event Buffer's*
        are cleared.

        If device_label is None then all events in the ioHub
        *Global Event Buffer* are cleared, but the *Device Event Buffers*
        are unaffected.

        If device_label is a str giving a valid device name, then that
        *Device Event Buffer* is cleared, but the *Global Event Buffer* is not
        affected.

        Args:
            device_label (str): device name, 'all', or None

        Returns:
            None

        """
        if device_label and isinstance(device_label, str):
            device_label = device_label.lower()
            if device_label == 'all':
                self.allEvents = []
                self._sendToHubServer(('RPC', 'clearEventBuffer', [True, ]))
                try:
                    self.getDevice('keyboard')._clearLocalEvents()
                except:
                    pass
            else:
                d = self.devices.getDevice(device_label)
                if d:
                    d.clearEvents()
        elif device_label in [None, '', False]:
            self.allEvents = []
            self._sendToHubServer(('RPC', 'clearEventBuffer', [False, ]))
            try:
                self.getDevice('keyboard')._clearLocalEvents()
            except:
                pass
        else:
            raise ValueError(
                'Invalid device_label value: {}'.format(device_label))

[docs]    def sendMessageEvent(self, text, category='', offset=0.0, sec_time=None):
        """
        Create and send an Experiment MessageEvent to the ioHub Server
        for storage in the ioDataStore hdf5 file.

        Args:
            text (str): The text message for the message event. 128 char max.

            category (str): A str grouping code for the message. Optional.
                            32 char max.

            offset (float): Optional sec.msec offset applied to the
                            message event time stamp. Default 0.

            sec_time (float): Absolute sec.msec time stamp for the message in.
                              If not provided, or None, then the MessageEvent
                              is time stamped when this method is called
                              using the global timer (core.getTime()).
        """
        self.cacheMessageEvent(text, category, offset, sec_time)
        self._sendToHubServer(('EXP_DEVICE', 'EVENT_TX', self._message_cache))
        self._message_cache = []

[docs]    def cacheMessageEvent(self, text, category='', offset=0.0, sec_time=None):
        """
        Create an Experiment MessageEvent and store in local cache.
        Message must be sent before it is saved to hdf5 file.

        Args:
            text (str): The text message for the message event. 128 char max.

            category (str): A str grouping code for the message. Optional.
                            32 char max.

            offset (float): Optional sec.msec offset applied to the
                            message event time stamp. Default 0.

            sec_time (float): Absolute sec.msec time stamp for the message in.
                              If not provided, or None, then the MessageEvent
                              is time stamped when this method is called
                              using the global timer (core.getTime()).
        """
        self._message_cache.append(MessageEvent._createAsList(text, # pylint: disable=protected-access
                                             category=category,
                                             msg_offset=offset,
                                             sec_time=sec_time))

    def sendMessageEvents(self, messageList=[]):
        if messageList:
            self.cacheMessageEvents(messageList)
        if self._message_cache:
            self._sendToHubServer(('EXP_DEVICE', 'EVENT_TX', self._message_cache))
            self._message_cache = []

    def cacheMessageEvents(self, messageList):
        for m in messageList:
            self._message_cache.append(MessageEvent._createAsList(**m))

    def getHubServerConfig(self):
        """Returns a dict containing the current ioHub Server configuration.

        Args:
            None

        Returns:
            dict: ioHub Server configuration.

        """
        return self._iohub_server_config

    def getSessionID(self):
        return self.experimentSessionID

    def getSessionMetaData(self):
        """Returns a dict representing the experiment session data that is
        being used for the current ioHub Experiment Session. Changing values in
        the dict has no effect on the session data that has already been saved
        to the ioHub DataStore.

        Args:
            None

        Returns:
            dict: Experiment Session metadata saved to the ioHub DataStore.
                  None if the ioHub DataStore is not enabled.
        """
        return self._sessionMetaData

    def getExperimentID(self):
        return self.experimentID

    def getExperimentMetaData(self):
        """Returns a dict representing the experiment data that is being used
        for the current ioHub Experiment.

        Args:
            None

        Returns:
            dict: Experiment metadata saved to the ioHub DataStore.
                  None if the ioHub DataStore is not enabled.

        """
        return self._experimentMetaData

    def wait(self, delay, check_hub_interval=0.02):
        # TODO: Integrate iohub event collection done in this version of wait
        # with psychopy wait() and deprecate this method.
        """Pause the experiment script execution for delay seconds.
        time.sleep() is used for delays > 0.02 sec (20 msec)

        During the wait period, events are received from iohub every
        'check_hub_interval' seconds, being buffered so they can be accessed
        after the wait duration. This is done for two reasons:

            * The iohub server's global and device level event buffers
              do not start to drop events if one of the (circular) event
              buffers becomes full during the wait duration.
            * The number of events in the iohub process event buffers does
              not becaome too large, which could result in a longer than
              normal getEvents() call time.

        Args:
            delay (float): The sec.msec delay until method returns.

            check_hub_interval (float): The sec.msec interval between calls to
                                        io.getEvents() during the delay period.
        Returns:
            float: The actual duration of the delay in sec.msec format.

        """
        stime = Computer.getTime()
        targetEndTime = stime + delay

        if check_hub_interval < 0:
            check_hub_interval = 0

        if check_hub_interval > 0:
            remainingSec = targetEndTime - Computer.getTime()
            while remainingSec > check_hub_interval+0.025:
                time.sleep(check_hub_interval)
                events = self.getEvents()
                if events:
                    self.allEvents.extend(events)
                # Call win32MessagePump so PsychoPy Windows do not become
                # 'unresponsive' if delay is long.
                win32MessagePump()
                remainingSec = targetEndTime - Computer.getTime()

        time.sleep(max(0.0, targetEndTime - Computer.getTime() - 0.02))

        while (targetEndTime - Computer.getTime()) > 0.0:
            pass

        return Computer.getTime() - stime

[docs]    def createTrialHandlerRecordTable(self, trials, cv_order=None):
        """
        Create a condition variable table in the ioHub data file based on
        the a psychopy TrialHandler. By doing so, the iohub data file
        can contain the DV and IV values used for each trial of an experiment
        session, along with all the iohub device events recorded by iohub
        during the session.

        Example psychopy code usage::

            # Load a trial handler and
            # create an associated table in the iohub data file
            #
            from psychopy.data import TrialHandler, importConditions

            exp_conditions=importConditions('trial_conditions.xlsx')
            trials = TrialHandler(exp_conditions, 1)

            # Inform the ioHub server about the TrialHandler
            #
            io.createTrialHandlerRecordTable(trials)

            # Read a row of the trial handler for
            # each trial of your experiment
            #
            for trial in trials:
                # do whatever...


            # During the trial, trial variable values can be updated
            #
            trial['TRIAL_START']=flip_time

            # At the end of each trial, before getting
            # the next trial handler row, send the trial
            # variable states to iohub so they can be stored for future
            # reference.
            #
            io.addTrialHandlerRecord(trial)

        """
        trial = trials.trialList[0]
        self._cv_order = cv_order
        if cv_order is None:
            self._cv_order = trial.keys()

        trial_condition_types = []

        for cond_name in self._cv_order:
            cond_val = trial[cond_name]
            if isinstance(cond_val, str):
                numpy_dtype = (cond_name, 'S', 256)
            elif isinstance(cond_val, int):
                numpy_dtype = (cond_name, 'i8')
            elif isinstance(cond_val, float):
                numpy_dtype = (cond_name, 'f8')
            else:
                numpy_dtype = (cond_name, 'S', 256)
            trial_condition_types.append(numpy_dtype)

        # pylint: disable=protected-access
        cvt_rpc = ('RPC', 'initConditionVariableTable',
                   (self.experimentID, self.experimentSessionID,
                    trial_condition_types))
        r = self._sendToHubServer(cvt_rpc)
        return r[2]

[docs]    def addTrialHandlerRecord(self, cv_row):
        """Adds the values from a TriaHandler row / record to the iohub data
        file for future data analysis use.

        :param cv_row:
        :return: None

        """
        data = []
        if isinstance(cv_row, (list, tuple)):
            data = list(cv_row)
        elif self._cv_order:
            for cv_name in self._cv_order:
                data.append(cv_row[cv_name])
        else:
            data = list(cv_row.values())

        for i, d in enumerate(data):
            if isinstance(d, str):
                data[i] = d.encode('utf-8')

        cvt_rpc = ('RPC', 'extendConditionVariableTable',
                   (self.experimentID, self.experimentSessionID, data))
        r = self._sendToHubServer(cvt_rpc)
        return r[2]

    def registerWindowHandles(self, *winHandles):
        """
        Sends 1 - n Window handles to iohub so it can determine if kb or
        mouse events were targeted at a psychopy window or other window.
        """
        r = self._sendToHubServer(('RPC', 'registerWindowHandles', winHandles))
        return r[2]

    def unregisterWindowHandles(self, *winHandles):
        """
        Sends 1 - n Window handles to iohub so it can determine if kb or
        mouse events were targeted at a psychopy window or other window.
        """
        r = self._sendToHubServer(
            ('RPC', 'unregisterWindowHandles', winHandles))
        return r[2]

    def updateWindowPos(self, win, x, y):
        r = self._sendToHubServer(('RPC', 'updateWindowPos', (win._hw_handle, (x, y))))
        return r[2]

[docs]    def getTime(self):
        """
        **Deprecated Method:** Use Computer.getTime instead. Remains here for
        testing time bases between processes only.
        """
        return self._sendToHubServer(('RPC', 'getTime'))[2]

[docs]    def syncClock(self, clock):
        """
        Synchronise ioHub's internal clock with a given instance of MonotonicClock.
        """
        params = {
            '_timeAtLastReset': clock._timeAtLastReset,
            '_epochTimeAtLastReset': clock._epochTimeAtLastReset,
            'format': clock.format,
        }
        if isinstance(params['format'], type):
            params['format'] = params['format'].__name__
        # sync clock in this process
        for key, value in params.items():
            setattr(Computer.global_clock, key, value)
        # sync clock in server process
        return self._sendToHubServer(('RPC', 'syncClock', (params,)))

[docs]    def setPriority(self, level='normal', disable_gc=False):
        """See Computer.setPriority documentation, where current process will
        be the iohub process."""
        return self._sendToHubServer(('RPC', 'setPriority',
                                      [level, disable_gc]))[2]

[docs]    def getPriority(self):
        """See Computer.getPriority documentation, where current process will
        be the iohub process."""
        return self._sendToHubServer(('RPC', 'getPriority'))[2]

[docs]    def getProcessAffinity(self):
        """
        Returns the current **ioHub Process** affinity setting,
        as a list of 'processor' id's (from 0 to getSystemProcessorCount()-1).
        A Process's Affinity determines which CPU's or CPU cores a process can
        run on. By default the ioHub Process can run on any CPU or CPU core.

        This method is not supported on OS X at this time.

        Args:
            None

        Returns:
            list: A list of integer values between 0 and
                  Computer.getSystemProcessorCount()-1, where values in the
                  list indicate processing unit indexes that the ioHub
                  process is able to run on.
        """
        r = self._sendToHubServer(('RPC', 'getProcessAffinity'))
        return r[2]

[docs]    def setProcessAffinity(self, processor_list):
        """
        Sets the **ioHub Process** Affinity based on the value of
        processor_list.

        A Process's Affinity determines which CPU's or CPU cores a process can
        run on. By default the ioHub Process can run on any CPU or CPU core.

        The processor_list argument must be a list of 'processor' id's;
        integers in the range of 0 to Computer.processing_unit_count-1,
        representing the processing unit indexes that the ioHub Server should
        be allowed to run on.

        If processor_list is given as an empty list, the ioHub Process will be
        able to run on any processing unit on the computer.

        This method is not supported on OS X at this time.

        Args:
            processor_list (list): A list of integer values between 0 and
                                   Computer.processing_unit_count-1,
                                   where values in the list indicate
                                   processing unit indexes that the ioHub
                                   process is able to run on.

        Returns:
            None
        """
        r = self._sendToHubServer(
            ('RPC', 'setProcessAffinity', processor_list))
        return r[2]

    def addDeviceToMonitor(self, device_class, device_config=None):
        """
        Normally this method should not be used, as all devices
        should be specified when the iohub server is being started.

        Adds a device to the ioHub Server for event monitoring during the
        experiment. Adding a device to the iohub server after it has been
        started can take 10'2 to 100's of msec to perform on the ioHub
        server (depending on the device type). When the device is being added,
        events from existing devices can not be monitored.

        Args:
            device_class (str): The iohub class name of the device being added.

            device_config (dict): The device configuration settings to be set.
                                  Device settings not provided in device_config
                                  will be set to the default values
                                  specified by the device.

        Returns:
            DeviceView Instance: The PsychoPy Process's view of the ioHub
                                 Device created that was created,
                                 as would be returned if a device was
                                 accessed using the .devices attribute
                                 or the .getDeviceByLabel() method.

        """
        if device_config is None:
            device_config = {}
        drpc = ('EXP_DEVICE', 'ADD_DEVICE', device_class, device_config)
        r = self._sendToHubServer(drpc)
        device_class_name, dev_name, _ = r[2]
        return self._addDeviceView(dev_name, device_class_name)

[docs]    def flushDataStoreFile(self):
        """Manually tell the iohub datastore to flush any events it has buffered in
        memory to disk. Any cached message events are sent to the iohub server
        before flushing the iohub datastore.

        Args:
            None

        Returns:
            None
        """
        self.sendMessageEvents()
        r = self._sendToHubServer(('RPC', 'flushIODataStoreFile'))
        return r

[docs]    def startCustomTasklet(self, task_name, task_class_path, **class_kwargs):
        """
        Instruct the iohub server to start running a custom tasklet given
        by task_class_path. It is important that the custom task does not block
        for any significant amount of time, or the processing of events by the
        iohub server will be negatively effected.

        See the customtask.py demo for an example of how to make a long running
        task not block the rest of the iohub server.
        """
        class_kwargs.setdefault('name', task_name)
        r = self._sendToHubServer(('CUSTOM_TASK', 'START', task_name,
                                   task_class_path, class_kwargs))
        return r

[docs]    def stopCustomTasklet(self, task_name):
        """
        Instruct the iohub server to stop the custom task that was previously
        started by calling self.startCustomTasklet(....). task_name identifies
        which custom task should be stopped and must match the task_name
        of a previously started custom task.
        """
        r = self._sendToHubServer(('CUSTOM_TASK', 'STOP', task_name))
        return r

[docs]    def shutdown(self):
        """Tells the ioHub Server to close all ioHub Devices, the ioDataStore,
        and the connection monitor between the PsychoPy and ioHub Processes.
        Then end the server process itself.

        Args:
            None

        Returns:
            None

        """
        self._shutDownServer()

[docs]    def quit(self):
        """Same as the shutdown() method, but has same name as PsychoPy
        core.quit() so maybe easier to remember."""
        self.shutdown()

    # Private Methods.....

[docs]    def _startServer(self, ioHubConfig=None, ioHubConfigAbsPath=None):
        """Starts the ioHub Process, storing it's process id, and creating the
        experiment side device representation for IPC access to public device
        methods."""
        experiment_info = None
        session_info = None
        hub_defaults_config = {}
        rootScriptPath = os.path.dirname(sys.argv[0])
        if len(rootScriptPath)<=1:
            rootScriptPath = os.path.abspath(".")
        # >>>>> Load / Create / Update iohub config file.....
        cfpath = os.path.join(IOHUB_DIRECTORY, 'default_config.yaml')
        with open(cfpath, 'r') as config_file:
            hub_defaults_config = yload(config_file, Loader=yLoader)

        if ioHubConfigAbsPath is None and ioHubConfig is None:
            ioHubConfig = dict(monitor_devices=[dict(Keyboard={}),
                                                dict(Display={}),
                                                dict(Mouse={})])
        elif ioHubConfig is not None and ioHubConfigAbsPath is None:
            if 'monitor_devices' not in ioHubConfig:
                raise KeyError("ioHubConfig must be provided with "
                               "'monitor_devices' key:value.")
            if 'data_store' in ioHubConfig:
                iods = ioHubConfig['data_store']
                if 'experiment_info' in iods and 'session_info' in iods:
                    experiment_info = iods['experiment_info']
                    session_info = iods['session_info']
                else:
                    raise KeyError("ERROR: ioHubConfig:ioDataStore must "
                                   "contain both a 'experiment_info' and a "
                                   "'session_info' entry.")
        elif ioHubConfigAbsPath is not None and ioHubConfig is None:
            with open(ioHubConfigAbsPath, 'r') as config_file:
                ioHubConfig = yload(config_file, Loader=yLoader)
        else:
            raise ValueError('Both a ioHubConfig dict object AND a path to an '
                             'ioHubConfig file can not be provided.')

        if ioHubConfig:
            updateDict(ioHubConfig, hub_defaults_config)

        if ioHubConfig and ioHubConfigAbsPath is None:
            if isinstance(ioHubConfig.get('monitor_devices'), dict):
                # short hand device spec is being used. Convert dict of
                # devices in a list of device dicts.
                devs = ioHubConfig.get('monitor_devices')
                devsList = [{dname: dc} for dname, dc in devs.items()]
                ioHubConfig['monitor_devices'] = devsList

            import tempfile
            with tempfile.NamedTemporaryFile(mode='w', suffix='iohub',
                                             delete=False) as tfile:
                tfile.write(json.dumps(ioHubConfig))
                ioHubConfigAbsPath = os.path.abspath(tfile.name)
        # <<<<< Finished Load / Create / Update iohub config file.

        self._iohub_server_config = ioHubConfig

        if sys.platform == 'darwin':
            self._osxKillAndFreePort()

        # >>>> Start iohub subprocess
        run_script = os.path.join(IOHUB_DIRECTORY, 'start_iohub_process.py')
        subprocessArgList = [sys.executable,
                             run_script,
                             '%.6f' % Computer.global_clock.getLastResetTime(),
                             rootScriptPath,
                             ioHubConfigAbsPath,
                             "{}".format(Computer.current_process.pid)]

        # To enable coverage in the iohub process, set the iohub\default_config
        # setting 'coverage_env_var' to the name of the coverage
        # config file that exists in the psychopy\iohub site-packages folder.
        # For example:
        #   coverage_env_var: .coveragerc
        #
        # If coverage_env_var is None or the file is not found,
        # coverage of ioHub Server process is disabled.
        coverage_env_var = self._iohub_server_config.get('coverage_env_var')

        envars = dict(os.environ)
        if coverage_env_var not in [None, 'None']:
            coverage_env_var = "{}".format(coverage_env_var)
            cov_config_path = os.path.join(IOHUB_DIRECTORY, coverage_env_var)
            if os.path.exists(cov_config_path):
                print("Coverage enabled for ioHub Server Process.")
            else:
                print("ioHub Process Coverage conf file not found: %s",
                      cov_config_path)
            envars['COVERAGE_PROCESS_START'] = coverage_env_var

        self._server_process = subprocess.Popen(subprocessArgList,
                                                env=envars,
                                                cwd=IOHUB_DIRECTORY,
                                                # set sub process stderr to be stdout so PsychoPy Runner
                                                # shows errors from iohub
                                                stderr=subprocess.STDOUT,
                                                )

        # Get iohub server pid and psutil process object
        # for affinity and process priority setting.
        Computer.iohub_process_id = self._server_process.pid
        Computer.iohub_process = psutil.Process(self._server_process.pid)

        global SHUTDOWN_FUNCS
        SHUTDOWN_FUNCS.append(self._shutDownServer)

        # >>>>> Create open UDP port to ioHub Server
        server_udp_port = self._iohub_server_config.get('udp_port', 9000)
        from ..net import UDPClientConnection
        # initially open with a timeout so macOS does not hang.        
        self.udp_client = UDPClientConnection(remote_port=server_udp_port, timeout=0.1)

        # If ioHub server does not respond correctly,
        # terminate process and exit the program.
        if self._waitForServerInit() is False:
            self._server_process.terminate()
            return "ioHub startup failed."
        
        # close and reopen blocking version of socket
        self.udp_client.close()
        self.udp_client = UDPClientConnection(remote_port=server_udp_port)
        # <<<<< Done Creating open UDP port to ioHub Server

        # <<<<< Done starting iohub subprocess

        ioHubConnection.ACTIVE_CONNECTION = proxy(self)
        # Send iohub server any existing open psychopy window handles.
        try:
            from psychopy.visual import window
            window.IOHUB_ACTIVE = True
            if window.openWindows:
                whs = []
                # pylint: disable=protected-access
                for w in window.openWindows:
                    winfo = windowInfoDict(w())
                    whs.append(winfo)
                    w().backend.onMoveCallback = self.updateWindowPos
                self.registerWindowHandles(*whs)
        except ImportError:
            pass

        # Sending experiment_info if available.....
        if experiment_info:
            self._sendExperimentInfo(experiment_info)
        # Sending session_info if available.....
        if session_info:
            # print 'Sending session_info: {0}'.format(session_info)
            self._sendSessionInfo(session_info)

        # >>>> Creating client side iohub device wrappers...
        self._createDeviceList(ioHubConfig['monitor_devices'])

        return 'OK'

    def _waitForServerInit(self):
        # >>>> Wait for iohub server ready signal ....
        hubonline = False
        # timeout if ioServer does not reply in 30 seconds
        timeout_duration = self._iohub_server_config.get('start_process_timeout', 30.0)
        timeout_time = Computer.getTime() + timeout_duration
        while hubonline is False and Computer.getTime() < timeout_time:
            r = self._sendToHubServer(['GET_IOHUB_STATUS', ])
            if r:
                hubonline = r[1] == 'RUNNING'
            time.sleep(0.1)
        return hubonline

        # # <<<< Finished wait for iohub server ready signal ....

[docs]    def _createDeviceList(self, monitor_devices_config):
        """Create client side iohub device views.
        """
        # get the list of devices registered with the ioHub
        for device_config_dict in monitor_devices_config:
            device_class_name = list(device_config_dict.keys())[0]
            device_config = list(device_config_dict.values())[0]
            if device_config.get('enable', True) is True:
                try:
                    self._addDeviceView(device_class_name, device_config)
                except Exception: # pylint: disable=broad-except
                    print2err('_createDeviceList: Error adding class. ')
                    printExceptionDetailsToStdErr()

[docs]    def _addDeviceView(self, dev_cls_name, dev_config):
        """Add an iohub device view to self.devices"""
        try:
            name = dev_config.get('name', dev_cls_name.lower())
            dev_cls_name = "{}".format(dev_cls_name)
            dev_name = dev_cls_name.lower()
            cls_name_start = dev_name.rfind('.')
            dev_mod_pth = 'psychopy.iohub.devices.'
            if cls_name_start > 0:
                dev_mod_pth2 = dev_name[:cls_name_start]
                dev_mod_pth = '{0}{1}'.format(dev_mod_pth, dev_mod_pth2)
                dev_cls_name = dev_cls_name[cls_name_start + 1:]
            else:
                dev_mod_pth = '{0}{1}'.format(dev_mod_pth, dev_name)
            # try to import EyeTracker class from given path
            try:
                dev_import_result = import_device(dev_mod_pth, dev_cls_name)
            except ModuleNotFoundError:
                # if not found, try importing from root (may have entry point)
                dev_import_result = import_device("psychopy.iohub.devices", dev_cls_name)
            dev_cls, dev_cls_name, evt_cls_list = dev_import_result

            DeviceConstants.addClassMapping(dev_cls)

            device_event_ids = []
            for ev in list(evt_cls_list.values()):
                if ev.EVENT_TYPE_ID:
                    device_event_ids.append(ev.EVENT_TYPE_ID)
            EventConstants.addClassMappings(device_event_ids, evt_cls_list)

            name_start = name.rfind('.')
            if name_start > 0:
                name = name[name_start + 1:]

            from .. import client as iohubclientmod
            local_class = None
            local_module = getattr(iohubclientmod, dev_cls_name.lower(), False)
            if local_module:
                # need to touch local_module since it was lazy loaded

                # pylint: disable=exec-used
                exec('import psychopy.iohub.client.{}'.format(dev_cls_name.lower()))
                local_class = getattr(local_module, dev_cls_name, False)

            if local_class:
                d = local_class(self, dev_cls_name, dev_config)
            else:
                d = ioHubDeviceView(self, dev_mod_pth + "." + dev_cls_name, dev_cls_name, dev_config)

            self.devices.addDevice(name, d)
            return d
        except Exception: # pylint: disable=broad-except
            print2err('_addDeviceView: Error adding class. ')
            printExceptionDetailsToStdErr()
        return None

    def _convertDict(self, d):
        r = {}
        for k, v in d.items():
            if isinstance(v, bytes):
                v = str(v, 'utf-8')
            elif isinstance(v, list) or  isinstance(v, tuple):
                v = self._convertList(v)
            elif isinstance(v, dict):
                v = self._convertDict(v)
        
            if isinstance(k, bytes):
                k = str(k, 'utf-8')
            r[k]=v
        return r

    def _convertList(self, l):
        r = []
        for i in l:
            if isinstance(i, bytes):
                r.append(str(i, 'utf-8'))
            elif isinstance(i, list) or  isinstance(i, tuple):
                r.append(self._convertList(i))
            elif isinstance(i, dict):
                r.append(self._convertDict(i))
            else:
                r.append(i)
        return r

[docs]    def _sendToHubServer(self, tx_data):
        """General purpose local <-> iohub server process UDP based
        request - reply code. The method blocks until the request is fulfilled
        and and a response is received from the ioHub server.

        Args:
            tx_data (tuple): data to send to iohub server

        Return (object): response from the ioHub Server process.
        """
        try:
            # send request to host, return is # bytes sent.
            #print("SEND:",tx_data)
            self.udp_client.sendTo(tx_data)
        except Exception as e: # pylint: disable=broad-except
            import traceback
            traceback.print_exc()
            self.shutdown()
            raise e
        
        result = None
        
        try:
            # wait for response from ioHub server, which will be the
            # result data and iohub server address (ip4,port).
            result = self.udp_client.receive()
            if result:
                result, _ = result
            #print("RESULT:",result)
        except Exception as e: # pylint: disable=broad-except
            import traceback
            traceback.print_exc()
            self.shutdown()
            raise e

        # check if the reply is an error or not. If it is, raise the error.
        # TODO: This is not really working as planned, in part because iohub
        #       server does not consistently return error responses when needed
        errorReply = self._isErrorReply(result)
        if errorReply:           
            raise ioHubError(result)
        # Otherwise return the result
        
        if result is not None:
            # Use recursive conversion funcs                     
            if isinstance(result, list) or  isinstance(result, tuple):
                result = self._convertList(result)
            elif isinstance(result, dict):
                result = self._convertDict(result)
        return result

[docs]    def _sendExperimentInfo(self, experimentInfoDict):
        """Sends the experiment info from the experiment config file to the
        ioHub Server, which passes it to the ioDataStore, determines if the
        experiment already exists in the hdf5 file based on 'experiment_code',
        and returns a new or existing experiment ID based on that criteria.
        """
        fieldOrder = (('experiment_id', 0), ('code', ''), ('title', ''),
                      ('description', ''), ('version', ''))
        values = []
        for key, defaultValue in fieldOrder:
            if key in experimentInfoDict:
                values.append(experimentInfoDict[key])
            else:
                values.append(defaultValue)
                experimentInfoDict[key] = defaultValue

        r = self._sendToHubServer(('RPC', 'setExperimentInfo', (values,)))
        self.experimentID = r[2]
        experimentInfoDict['experiment_id'] = self.experimentID
        self._experimentMetaData = experimentInfoDict
        return r[2]

[docs]    def _sendSessionInfo(self, sess_info):
        """Sends the experiment session info from the experiment config file
        and the values entered into the session dialog to the ioHub Server,
        which passes it to the ioDataStore.

        The dataStore determines if the session already exists in the
        experiment file based on 'session_code', and returns a new
        session ID  if session_code is not in use by the experiment.
        """
        if self.experimentID is None:
            raise RuntimeError("Experiment ID must be set by calling"
                               " _sendExperimentInfo before calling"
                               " _sendSessionInfo.")
        if 'code' not in sess_info:
            raise ValueError("Code must be provided in sessionInfoDict"
                             " ( StringCol(24) ).")
        if 'name' not in sess_info:
            sess_info['name'] = ''
        if 'comments' not in sess_info:
            sess_info['comments'] = ''
        if 'user_variables' not in sess_info:
            sess_info['user_variables'] = {}

        org_sess_info = sess_info['user_variables']

        sess_info['user_variables'] = json.dumps(sess_info['user_variables'])
        r = self._sendToHubServer(('RPC', 'createExperimentSessionEntry',
                                   (sess_info,))
                                 )

        self.experimentSessionID = r[2]
        sess_info['user_variables'] = org_sess_info
        sess_info['session_id'] = self.experimentSessionID
        self._sessionMetaData = sess_info
        return sess_info['session_id']

    @staticmethod
    def eventListToObject(evt_data):
        """Convert an ioHub event currently in list value format into the
        correct ioHub.devices.DeviceEvent subclass for the given event type."""
        evt_type = evt_data[DeviceEvent.EVENT_TYPE_ID_INDEX]
        return EventConstants.getClass(evt_type).createEventAsClass(evt_data)

    @staticmethod
    def eventListToDict(evt_data):
        """Convert an ioHub event currently in list value format into
        the event as a dictionary of attribute name, attribute values."""
        if isinstance(evt_data, dict):
            return evt_data
        etype = evt_data[DeviceEvent.EVENT_TYPE_ID_INDEX]
        return EventConstants.getClass(etype).createEventAsDict(evt_data)


    @staticmethod
    def eventListToNamedTuple(evt_data):
        """Convert an ioHub event currently in list value format into the
         namedtuple format for an event."""
        if not isinstance(evt_data, list):
            return evt_data
        etype = evt_data[DeviceEvent.EVENT_TYPE_ID_INDEX]
        return EventConstants.getClass(etype).createEventAsNamedTuple(evt_data)

    # client utility methods.
    def _getDeviceList(self):
        r = self._sendToHubServer(('EXP_DEVICE', 'GET_DEVICE_LIST'))
        return r[2]

    def _shutDownServer(self):
        if self._shutdown_attempted is False:
            # send any cached experiment messages
            self.sendMessageEvents()

            try:
                from psychopy.visual import window
                window.IOHUB_ACTIVE = False
            except ImportError:
                pass

            self._shutdown_attempted = True
            TimeoutError = psutil.TimeoutExpired
            try:
                if self.udp_client:  # if it isn't already garbage-collected
                    self.udp_client.sendTo(('STOP_IOHUB_SERVER',))
                    self.udp_client.close()
                if Computer.iohub_process:
                    # This wait() used to have timeout=5, removing it to allow
                    # sufficient time for all iohub devices to be closed.
                    r = Computer.iohub_process.wait()
                    print('ioHub Server Process Completed With Code: ', r)
            except TimeoutError:
                print('Warning: TimeoutExpired, Killing ioHub Server process.')
                Computer.iohub_process.kill()
            except Exception:  # pylint: disable=broad-except
                print("Warning: Unhandled Exception. "
                      "Killing ioHub Server process.")
                if Computer.iohub_process:
                    Computer.iohub_process.kill()
                printExceptionDetailsToStdErr()
            finally:
                ioHubConnection.ACTIVE_CONNECTION = None
                self._server_process = None
                Computer.iohub_process_id = None
                Computer.iohub_process = None
            return True

[docs]    @staticmethod
    def _isErrorReply(data):
        """
        Check if an iohub server reply contains an error that should be raised
        by the local process.
        """
        # is it an ioHub error object?
        if isinstance(data, ioHubError):
            return True

        if isIterable(data) and len(data) > 0:
            d0 = data[0]
            if isIterable(d0):
                return False
            else:
                if isinstance(d0, str) and d0.find('ERROR') >= 0:
                    return data
                return False
        else:
            return data #'Invalid Response Received from ioHub Server'


    def _osxKillAndFreePort(self):
        server_udp_port = self._iohub_server_config.get('udp_port', 9000)
        p = subprocess.Popen(['lsof', '-i:%d'%server_udp_port, '-P'],
                             stdout=subprocess.PIPE,
                             encoding='utf-8')
        lines = p.communicate()[0]
        for line in lines.splitlines():
            if line.startswith('Python'):
                PID, userID = line.split()[1:3]
                # could verify same userID as current user, probably not needed
                os.kill(int(PID), signal.SIGKILL)
                print('Called  os.kill(int(PID),signal.SIGKILL): ', PID, userID)

    def __del__(self):
        try:
            self._shutDownServer()
            ioHubConnection.ACTIVE_CONNECTION = None
        except Exception: # pylint: disable=broad-except
            pass

##############################################################################

class ioEvent():
    """
    Parent class for all events generated by a psychopy.iohub.client
    Device wrapper.
    """
    _attrib_index = dict()
    _attrib_index['id'] = DeviceEvent.EVENT_ID_INDEX
    _attrib_index['time'] = DeviceEvent.EVENT_HUB_TIME_INDEX
    _attrib_index['type'] = DeviceEvent.EVENT_TYPE_ID_INDEX

    def __init__(self, ioe_array, device=None):
        self._time = ioe_array[ioEvent._attrib_index['time']]
        self._id = ioe_array[ioEvent._attrib_index['id']]
        self._type = ioe_array[ioEvent._attrib_index['type']]
        self._device = device

    @property
    def device(self):
        """
        The ioHubDeviceView that is associated with the event, i.e. the
        iohub device view for the device that generated the event.

        :return: ioHubDeviceView

        """
        return self._device

    @property
    def time(self):
        """
        The time stamp of the event. Uses the same time base that is used by
        psychopy.core.getTime()

        :return: float
        """
        return self._time

    @property
    def id(self):
        """The unique id for the event; in some cases used to track associated
        events.

        :return: int

        """
        return self._id

    @property
    def type(self):
        """The event type string constant.

        :return: str

        """
        return EventConstants.getName(self._type)

    @property
    def dict(self):
        d = {}
        for k in self._attrib_index:
            d[k] = getattr(self, k)
        return d

    def __str__(self):
        return 'time: %.3f, type: %s, id: %d' % (self.time,
                                                 self.type,
                                                 self.id)


def shutdownActiveConnections():
    """Shutdown any active ioHub connections that are currently running.
    """
    activeConnection = ioHubConnection.getActiveConnection()
    if activeConnection is not None and hasattr(activeConnection, 'shutdown'):
        activeConnection.shutdown()
    

atexit.register(shutdownActiveConnections)

_lazyImports = """
from psychopy.iohub.client.connect import launchHubServer
from psychopy.iohub.client import keyboard
from psychopy.iohub.client import wintab
"""

try:
    lazy_import(globals(), _lazyImports)
except Exception as e: #pylint: disable=broad-except
    print2err('lazy_import Exception:', e)
    exec(_lazyImports) #pylint: disable=exec-used