psychopy 2024.2.1__py3-none-any.whl → 2024.2.4__py3-none-any.whl

psychopy/hardware/iolab.py.orig

@@ -0,0 +1,238 @@
+
+"""The `ioLab python library
+    <http://github.com/ioLab/python-ioLabs>`_ is now defunct and the company
+    no longer trades
+"""
+<<<<<<< Updated upstream
+#  This file can't be named ioLabs.py, otherwise "import ioLabs" doesn't work.
+# And iolabs.py (lowercase) did not solve it either, something is case
+# insensitive somewhere
+
+from numpy import ubyte
+from psychopy import core, event, logging
+
+try:
+    import ioLabs
+    from ioLabs import USBBox, REPORT, COMMAND
+except ImportError:
+    err = """Failed to import the ioLabs library. If you're using your own
+        copy of python (not the Standalone distribution of PsychoPy) then
+        try installing it with:
+           > pip install ioLabs""".replace('    ', '')
+    logging.error(err)
+
+from psychopy.constants import PRESSED, RELEASED
+btn2str = {0: '0', 1: '1', 2: '2', 3: '3', 4: '4', 5: '5', 6: '6', 7: '7',
+           64: 'voice'}
+
+# hack to fake a USBBox on ubuntu during documentation
+import sys
+if 'sphinx' in sys.modules:
+    USBBox = object
+
+class ButtonBox(USBBox):
+    """PsychoPy's interface to ioLabs.USBBox. Voice key completely untested.
+
+    Original author: Jonathan Roberts
+    PsychoPy rewrite: Jeremy Gray, 2013
+    """
+
+    def __init__(self):
+        """Class to detect and report
+        `ioLab button box <http://www.iolab.co.uk>`_.
+
+        The ioLabs library needs to be installed. It is included in the
+        *Standalone* distributions of PsychoPy as of version 1.62.01.
+        Otherwise try "pip install ioLabs"
+
+        Usage::
+
+            from psychopy.hardware import iolab
+            bbox = iolab.ButtonBox()
+
+        For examples see the demos menu of the PsychoPy Coder or go to the
+        URL above.
+
+        All times are reported in units of seconds.
+        """
+        ioLabs.USBBox.__init__(self)
+        logging.debug('init iolabs bbox')
+        self.events = []
+        self.status = None  # helps Builder
+        self._lastReset = 0.0  # time on baseclock when bbox clock was reset
+        self._baseclock = core.Clock()  # for basetime, not RT time
+        self.resetClock(log=True)  # internal clock on the bbox
+        msg = 'button box resetClock(log=True) took %.4fs'
+        logging.exp(msg % self._baseclock.getTime())
+
+        self.commands.add_callback(REPORT.KEYDN, self._onKeyDown)
+        self.commands.add_callback(REPORT.KEYUP, self._onKeyUp)
+        self.commands.add_callback(REPORT.RTCREP, self._onRtcRep)
+
+    # set up callbacks for key events ("key" = button and or voice key):
+    def _onKey(self, report):
+        report.rt = report.rtc / 1000.
+        report.btn = report.key_code  # int
+        report.key = btn2str[report.key_code]  # str
+        self.events.append(report)
+
+    def _onKeyDown(self, report):
+        report.direction = PRESSED
+        self._onKey(report)
+
+    def _onKeyUp(self, report):
+        report.direction = RELEASED
+        self._onKey(report)
+
+    def _onRtcRep(self, report):
+        # read internal clock without needing a button-press; not working
+        report.rt = self.commands.rtcget()['rtc'] / 1000.
+
+    def __del__(self):
+        # does not seem to ever get called
+        self.standby()
+        for rep in [REPORT.KEYDN, REPORT.KEYUP, REPORT.RTCREP]:
+            self.remove_callback(rep)
+        ioLabs.USBBox.__del__(self)
+
+    def standby(self):
+        """Disable all buttons and lights.
+        """
+        self.buttons.enabled = 0x00  # 8 bit pattern 0=disabled 1=enabled
+        self.leds.state = 0xFF  # leds == port2 == lights, 8 bits 0=on 1=off
+        return self
+
+    def resetClock(self, log=True):
+        """Reset the clock on the bbox internal clock, e.g., at the start
+        of a trial.
+
+        ~1ms for me; logging is much faster than the reset
+        """
+        # better / faster than self.reset_clock() (no wait for report):
+        self.commands.resrtc()
+        self._lastReset = self._baseclock.getTime()
+        if log:
+            msg = 'reset bbox internal clock at basetime = %.3f'
+            logging.exp(msg % self._lastReset)
+
+    def _getTime(self, log=False):
+        """Return the time on the bbox internal clock, relative to last reset.
+
+        Status: rtcget() not working
+
+        `log=True` will log the bbox time and elapsed CPU (python) time.
+        """
+        bboxTime = self.commands.rtcget()['rtc'] / 1000.
+        logging.debug('bbox rtc: %.3f' % bboxTime)
+        if log:
+            cpuTime = self._baseclock.getTime() - self._lastReset
+            logging.debug('cpu time: %.3f' % cpuTime)
+
+        return bboxTime
+
+    def getBaseTime(self):
+        """Return the time since init (using the CPU clock, not ioLab bbox).
+
+        Aim is to provide a similar API as for a Cedrus box.
+        Could let both clocks run for a long time to assess relative drift.
+        """
+        return self._baseclock.getTime()
+
+    def setEnabled(self, buttonList=(0, 1, 2, 3, 4, 5, 6, 7), voice=False):
+        """Set a filter to suppress events from non-enabled buttons.
+
+        The ioLabs bbox filters buttons in hardware; here we just tell it
+        what we want:
+        None - disable all buttons
+        an integer (0..7) - enable a single button
+        a list of integers (0..7) - enable all buttons in the list
+
+        Set voice=True to enable the voiceKey - gets reported as button 64
+        """
+        allInRange = all([b in range(8) for b in buttonList])
+        if not (buttonList is None or allInRange):
+            raise ValueError('buttonList needs to be a list of 0..7, or None')
+        self.buttons.enabled = _list2bits(buttonList)
+        self.int0.enabled = int(voice)
+
+    def getEnabled(self):
+        """Return a list of the buttons that are currently enabled.
+        """
+        return _bits2list(self.buttons.enabled)
+
+    def setLights(self, lightList=(0, 1, 2, 3, 4, 5, 6, 7)):
+        """Turn on the specified LEDs (None, 0..7, list of 0..7)
+        """
+        self.leds.state = ~_list2bits(lightList)
+
+    def waitEvents(self, downOnly=True, timeout=0, escape='escape',
+                   wait=0.002):
+        """Wait for and return the first button press event.
+
+        Always calls `clearEvents()` first (like PsychoPy keyboard waitKeys).
+
+        Use `downOnly=False` to include button-release events.
+
+        `escape` is a list/tuple of keyboard events that, if pressed, will
+        interrupt the bbox wait; `waitKeys` will return `None` in that case.
+
+        `timeout` is the max time to wait in seconds before returning `None`.
+        `timeout` of 0 means no time-out (= default).
+        """
+        self.clearEvents()  # e.g., removes UP from previous DOWN
+        if timeout > 0:
+            c = core.Clock()
+        if escape and not type(escape) in [list, tuple]:
+            escape = [escape]
+        while True:
+            if wait:
+                core.wait(wait, 0)  # throttle CPU; event RTs come from bbox
+            evt = self.getEvents(downOnly=downOnly)
+            if evt:
+                evt = evt[0]
+                break
+            if escape and event.getKeys(escape) or 0 < timeout < c.getTime():
+                return
+        return evt
+
+    def getEvents(self, downOnly=True):
+        """Detect and return a list of all events (likely just one); no block.
+
+        Use `downOnly=False` to include button-release events.
+        """
+        if downOnly is False:
+            raise NotImplementedError()
+        self.process_received_reports()
+        evts = []
+        for evt in self.events:
+            if evt.direction == PRESSED or not downOnly:
+                evts.append(evt)
+        return evts
+
+    def clearEvents(self):
+        """Discard all button / voice key events.
+        """
+        self.events[:] = []
+        self.commands.clear_received_reports()
+        logging.debug('bbox clear events')
+
+
+pow2 = [2**i for i in range(8)]
+
+
+def _list2bits(arg):
+    # return a numpy.ubyte with bits set based on integers 0..7 in arg
+    if type(arg) == int and 0 <= arg < 8:
+        return ubyte(pow2[arg])
+    elif hasattr(arg, '__iter__'):
+        return ubyte(sum([pow2[btn] for btn in arg]))
+    else:  # None
+        return ubyte(0)
+
+=======
+>>>>>>> Stashed changes
+
+raise DeprecationWarning("The ioLab button box is no longer being sold and the library is no"
+                         "longer supported. This library has been removed from PsychoPy as of"
+                         "version 2022.1. We would recommend you use an alternative button box"
+                         "such as the LabHackers MilliKey <https://www.labhackers.com/millikey.html>")

psychopy/hardware/manager.py

@@ -891,7 +891,7 @@ class DeviceManager:
                 win, text=str(n + 1),
                 size=1, pos=0,
                 alignment="center", anchor="center",
-                letterHeight=0.5, bold=True,
+                letterHeight=0.25, bold=True,
                 fillColor=None, color="white"
             )
             lbls.append(lbl)

psychopy/hardware/photodiode.py

@@ -155,7 +155,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         
         return channels
     
-    def findPhotodiode(self, win, channel=None):
+    def findPhotodiode(self, win, channel=None, retryLimit=5):
         """
         Draws rectangles on the screen and records photodiode responses to recursively find the location of the diode.
 
@@ -271,32 +271,46 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             # if none of these have returned, rect is too small to cover the whole photodiode, so return
             return responsive
 
-        # reset state
-        self.state = [None] * self.channels
-        self.dispatchMessages()
-        self.clearResponses()
-        # recursively shrink rect around the photodiode
-        responsive = scanQuadrants()
-        # if cancelled, warn and continue
-        if responsive is None:
-            logging.warn(
-                "`findPhotodiode` procedure cancelled by user."
-            )
-            return (
-                layout.Position(self.pos, units="norm", win=win),
-                layout.Position(self.size, units="norm", win=win),
-            )
-        # if we didn't get any responses at all, prompt to try again
-        if not responsive:
+        def handleNonResponse(label, rect, timeout=5):
+            # skip if retry limit hit
+            if retryLimit <= 0:
+                return None
+            # start a countdown
+            timer = core.CountdownTimer(start=timeout)
             # set label text to alert user
-            label.text = (
+            msg = (
                 "Received no responses from photodiode during `findPhotodiode`. Photodiode may not "
                 "be connected or may be configured incorrectly.\n"
                 "\n"
-                "To continue, use the arrow keys to move the photodiode patch and use the "
-                "plus/minus keys to resize it.\n"
-                "\n"
-                "Press ENTER when finished."
+                "To manually specify the photodiode's position, press ENTER. To quit, press "
+                "ESCAPE. Otherwise, will retry in {:.0f}s\n"
+            )
+            label.foreColor = "red"
+            # start a frame loop until they press enter
+            keys = []
+            while timer.getTime() > 0 and not keys:
+                # get keys
+                keys = kb.getKeys()
+                # skip if escape pressed
+                if "escape" in keys:
+                    return None
+                # specify manually if return pressed
+                if "return" in keys:
+                    return specifyManually(label=label, rect=rect)
+                # format label
+                label.text = msg.format(timer.getTime())
+                # show label and square
+                label.draw()
+                # flip
+                win.flip()
+            # if we timed out, retry whole find procedure
+            return self.findPhotodiode(win, channel=channel, retryLimit=retryLimit-1)
+        
+        def specifyManually(label, rect):
+            # set label text to alert user
+            label.text = (
+                "Use the arrow keys to move the photodiode patch and use the plus/minus keys to "
+                "resize it. Press ENTER when finished, or press ESCAPE to quit.\n"
             )
             label.foreColor = "red"
             # revert to defaults
@@ -306,12 +320,18 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             # start a frame loop until they press enter
             keys = []
             res = 0.05
-            while "return" not in keys:
+            while "return" not in keys and "escape" not in keys:
                 # get keys
                 keys = kb.getKeys()
                 # skip if escape pressed
                 if "escape" in keys:
                     return None
+                # finish if return pressed
+                if "return" in keys:
+                    return (
+                        layout.Position(self.pos, units="norm", win=win),
+                        layout.Position(self.size, units="norm", win=win),
+                    )
                 # move rect according to arrow keys
                 pos = list(rect.pos)
                 if "left" in keys:
@@ -335,13 +355,25 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
                 rect.draw()
                 # flip
                 win.flip()
-            # wait for a keypress
-            kb.waitKeys()
-            # return defaults
+
+        # reset state
+        self.state = [None] * self.channels
+        self.dispatchMessages()
+        self.clearResponses()
+        # recursively shrink rect around the photodiode
+        responsive = scanQuadrants()
+        # if cancelled, warn and continue
+        if responsive is None:
+            logging.warn(
+                "`findPhotodiode` procedure cancelled by user."
+            )
             return (
                 layout.Position(self.pos, units="norm", win=win),
                 layout.Position(self.size, units="norm", win=win),
             )
+        # if we didn't get any responses at all, prompt to try again
+        if not responsive:
+            handleNonResponse(label=label, rect=rect)
         # clear all the events created by this process
         self.state = [None] * self.channels
         self.dispatchMessages()

psychopy/hardware/serialport.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# Part of the PsychoPy library
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2022 Open Science Tools Ltd.
+# Distributed under the terms of the GNU General Public License (GPL).
+
+"""To connect to serial ports, e.g. to send/receive trigger pulses
+
+This is really just a subclass of the Serial class from the pyserial lib, with
+added functions for the purpose of detecting triggers.
+
+Also note that to interact with serial port *devices* with APIs such as
+photometers etc then you might be better using the psychopy.hardware.SerialDevice
+base class.
+"""
+
+import time
+import serial
+
+"""
+Note that py serial.Serial has announced deprecating camelCase for 
+snake_case as of version 3.0 but not clear when this will actually 
+be removed. We're currently sticking with camelCase since that meets
+our own style guide.  
+"""
+
+
+class SerialPort(serial.Serial):
+    """
+    """
+    def waitTriggers(self, triggers=None, maxWait=None):
+        """Waits for one of the trigger characters to be detected
+
+        If none of the characters are detected within the maxWait
+        then None is returned. Otherwise the value of the detected
+        trigger is returned.
+
+        Params
+        ------
+
+        """
+        if type(triggers) in [bytes, str]:
+            triggers = {triggers}
+        t0 = time.time()
+        # can't just use serial port timeout because check for char
+        while maxWait is None or (time.time()-t0 < maxWait):
+            chars = self.read(self.inWaiting())
+            for thisTrigger in triggers:
+                if thisTrigger in chars:
+                   return thisTrigger

psychopy/hardware/speaker.py

@@ -8,7 +8,7 @@ class SpeakerDevice(BaseDevice):
         profiles = self.getAvailableDevices()
 
         # if index is default (-1), setup a default device index
-        if not isinstance(index, (int, float)) or index < 0:
+        if not isinstance(index, (int, float)):
             index = profiles[0]['index']  # initialize as the first device
 
             # check if a default device is already set and update index
@@ -23,8 +23,8 @@ class SpeakerDevice(BaseDevice):
                         if profile['deviceName'] == defaultDevice:
                             index = profile['index']
 
-        available_index = [profile['index'] for profile in profiles]
-        if index < 0 or index not in available_index:
+        available_index = [profile['index'] for profile in profiles] + [-1]
+        if index not in available_index:
             logging.error("No speaker device found with index %d" % index)
 
         # store index
@@ -86,4 +86,4 @@ class SpeakerDevice(BaseDevice):
             }
             devices.append(device)
 
-        return devices
+        return devices