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

psychopy/hardware/joystick/backend_pyglet.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# Part of the PsychoPy library
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
+# Distributed under the terms of the GNU General Public License (GPL).
+
+"""Pyglet backend for joystick support.
+
+"""
+
+__all__ = ['JoystickInterfacePyglet']
+
+try:
+    from pyglet import input as pyglet_input  # pyglet 1.2+
+    from pyglet import app as pyglet_app
+    havePyglet = True
+except Exception:
+    havePyglet = False
+
+from psychopy import logging, visual
+from psychopy.hardware.joystick._base import BaseJoystickInterface
+
+if havePyglet:
+    class PygletDispatcher:
+        def dispatch_events(self):
+            pyglet_app.platform_event_loop.step(timeout=0.001)
+
+    pyglet_dispatcher = PygletDispatcher()
+
+
+class JoystickInterfacePyglet(BaseJoystickInterface):
+    """Class for defining an interface for joystick and gamepad devices using
+    the Pyglet library.
+
+    Parameters
+    ----------
+    device : str or int
+        The name or index of the joystick to control.
+
+    """
+    _inputLib = 'pyglet'
+    def __init__(self, device, **kwargs):
+        super(JoystickInterfacePyglet, self).__init__(device, **kwargs)
+
+        joys = pyglet_input.get_joysticks()  # enum all joysticks
+
+        if isinstance(device, str):   # get index by string name
+            if device in ('None', 'default'):
+                self._device = 0  # use first device
+            else:
+                # find the device by name
+                for i, joy in enumerate(joys):
+                    if joy.device.name == device:
+                        self._device = i
+                        break
+                else:
+                    logging.error(
+                        "No joystick found with the name '%s'" % device)
+        elif isinstance(device, int):  # get by index
+            if device >= len(joys):
+                logging.error(
+                    "You don't have that many joysticks attached (remember "
+                    "that the first joystick has deviceIndex=0 etc...)")
+
+            self._device = joys[device]
+
+        self._isOpen = False
+
+        try:
+            self.open()  # open the device
+        except pyglet_input.DeviceOpenException as e:
+            pass
+
+        if len(visual.openWindows) == 0:
+            logging.error(
+                "You need to open a window before creating your joystick")
+        else:
+           for win in visual.openWindows:
+               win()._eventDispatchers.append(pyglet_dispatcher)
+
+    @staticmethod
+    def getAvailableDevices():
+        """Return a list of available joystick devices.
+
+        This method is used by `DeviceManager` to get a list of available
+        devices.
+
+        Returns
+        -------
+        list
+            A list of available joystick devices.
+
+        """
+        joys = pyglet_input.get_joysticks()
+
+        if not joys:
+            return []
+
+        deviceList = []
+        for i, joy in enumerate(joys):
+            config = {}
+            config['index'] = i
+            config['name'] = joy.device.name
+            deviceList.append(config)
+
+        return deviceList
+
+    @property
+    def hasTracking(self):
+        """Check if the joystick has tracking capabilities.
+
+        Returns
+        -------
+        bool
+            True if the joystick has tracking capabilities, False otherwise.
+
+        """
+        return False
+    
+    def open(self):
+        """Open the joystick device.
+
+        """
+        self._device.open()
+        self._isOpen = True
+
+    @property
+    def isOpen(self):
+        """Check if the joystick device is open.
+
+        Returns
+        -------
+        bool
+            True if the joystick device is open, False otherwise.
+
+        """
+        # return self._device.device.is_open
+        return self._isOpen
+
+    def close(self):
+        """Close the joystick device.
+
+        """
+        if hasattr(self._device, 'close'):
+            self._device.close()
+
+        self._isOpen = False
+
+    def __del__(self):
+        """Close the joystick device when the object is deleted.
+
+        """
+        if hasattr(self, '_device'):
+            self.close()
+
+    def getName(self):
+        """Get the manufacturer-defined name describing the device.
+
+        Returns
+        -------
+        str
+            The name of the joystick.
+
+        """
+        return self._device.device.name
+
+    def getNumButtons(self):
+        """Number of digital buttons on the device.
+
+        Returns
+        -------
+        int
+            The number of buttons on the joystick.
+
+        """
+        return len(self._device.buttons)
+
+    def getButton(self, buttonId):
+        """Get the state of a given button.
+
+        buttonId should be a value from 0 to the number of buttons-1
+
+        Parameters
+        ----------
+        buttonId : int
+            The button ID to get the state of.
+
+        Returns
+        -------
+        bool
+            True if the button is pressed, False otherwise.
+
+        """
+        return self._device.buttons[buttonId]
+
+    def getAllButtons(self):
+        """Get the state of all buttons.
+
+        Returns
+        -------
+        list
+            A list of button states.
+
+        """
+        return self._device.buttons
+
+    def getAllHats(self):
+        """Get the current values of all available hats as a list of tuples.
+
+        Returns
+        -------
+        list
+            A list of tuples representing the state of each hat. Each value is
+            a tuple (x, y) where x and y can be -1, 0, +1.
+
+        """
+        hats = []
+        for ctrl in self._device.device.get_controls():
+            if ctrl.name != None and 'hat' in ctrl.name:
+                hats.append((self._device.hat_x, self._device.hat_y))
+        return hats
+
+    def getNumHats(self):
+        """Get the number of hats on this joystick.
+
+        Returns
+        -------
+        int
+            The number of hats on the joystick.
+
+        """
+        return len(self.getAllHats())
+
+    def getHat(self, hatId=0):
+        """Get the position of a particular hat.
+
+        Returns
+        -------
+        tuple
+            The position of the hat as an (x, y) tuple where x and y can be -1,
+            0, or +1.
+
+        """
+        if hatId == 0:
+            return self._device.hat_x, self._device.hat_y
+        else:
+            return self.getAllHats()[hatId]
+    
+    def getX(self):
+        """Return the X axis value (equivalent to joystick.getAxis(0))."""
+        return self._device.x
+
+    def getY(self):
+        """Return the Y axis value (equivalent to joystick.getAxis(1))."""
+        return self._device.y
+
+    def getZ(self):
+        """Return the Z axis value (equivalent to joystick.getAxis(2))."""
+        return self._device.z
+
+    def getAllAxes(self):
+        """Get a list of all current axis values."""
+        names = ['x', 'y', 'z', 'rx', 'ry', 'rz', ]
+        axes = []
+        for axName in names:
+            if hasattr(self._device, axName):
+                axes.append(getattr(self._device, axName))
+        return axes
+    
+    def getNumAxes(self):
+        """Number of joystick axes found.
+
+        Returns
+        -------
+        int
+            The number of axes found on the joystick.
+
+        """
+        return len(self.getAllAxes())
+
+    def getAxis(self, axisId):
+        """Get the value of an axis by an integer id.
+
+        (from 0 to number of axes - 1)
+        """
+        val = self.getAllAxes()[axisId]
+        return 0 if val is None else val
+
+    def poll(self):
+        """Check for new joystick events.
+
+        Returns
+        -------
+        bool
+            True if there are new joystick events, False otherwise.
+
+        """
+        return self._device.poll()
+
+    def update(self):
+        """Update the joystick state.
+
+        """
+        pass  # NOP, automatically done by pyglet event dispatching loop
+
+
+if __name__ == "__main__":
+    pass

psychopy/hardware/joystick/mappings.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# Part of the PsychoPy library
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
+# Distributed under the terms of the GNU General Public License (GPL).
+
+"""Mappings for common joystick and gamepad devices.
+"""
+
+__all__ = ['getAvailableInputSchemes', 'getInputScheme']
+
+from psychopy import logging
+
+inputMappings = {}  # mappings are stored here
+
+# Default joystick mapping
+inputMappings['default'] = {
+    'name': 'Default Joystick',
+    'mappings': {
+        'generic': {
+            'axes': {
+                'X': 0,
+                'Y': 1,
+                'Z': 2,
+                'XY': (0, 1),
+                'RX': 3,
+                'RY': 4,
+                'RZ': 5
+            },
+            'buttons': {
+                'A': 0,
+                'B': 1,
+                'X': 2,
+                'Y': 3
+            },
+            'hats': {}
+        }
+    }
+}
+
+# Xbox 360 controller
+inputMappings['xbox'] = {
+    'name': 'Xbox 360',
+    'mappings': {
+        'generic': {
+            'axes': {
+                'leftX': 0,
+                'leftY': 1,
+                'left': (0, 1),
+                'thumbL': (0, 1),  # same as left, just more explicit
+                'rightX': 2,
+                'rightY': 3,
+                'right': (2, 3),
+                'thumbR': (2, 3),
+                'triggerL': 4,
+                'triggerR': 5,
+                'triggers': (4, 5)
+            },
+            'buttons': {
+                'A': 0,
+                'B': 1,
+                'X': 2,
+                'Y': 3,
+                'shoulderL': 4,
+                'shoulderR': 5,
+                'back': 6,
+                'start': 7,
+                'stickL': 8,
+                'stickR': 9,
+                'up': 10,  # hat
+                'down': 11,
+                'left': 12,
+                'right': 13
+            },
+            'hats': {}
+        }
+    }
+}
+
+# PS3 controller
+inputMappings['ps3'] = {
+    'name': 'PS3 Dual-Shock',
+    'mappings': {
+        'generic': {
+            'axes': {
+                'leftX': 0,
+                'leftY': 1,
+                'left': (0, 1),
+                'thumbL': (0, 1),  # same as left, just more explicit
+                'rightX': 2,
+                'rightY': 3,
+                'right': (2, 3),
+                'thumbR': (2, 3),
+                'triggerL': 4,
+                'triggerR': 5,
+                'triggers': (4, 5)
+            },
+            'buttons': {
+                'cross': 0,
+                'circle': 1,
+                'square': 2,
+                'triangle': 3,
+                'shoulderL': 4,
+                'shoulderR': 5,
+                'select': 6,
+                'start': 7,
+                'stickL': 8,
+                'stickR': 9,
+                'up': 10,  # hat
+                'down': 11,
+                'left': 12,
+                'right': 13
+            },
+            'hats': {}
+        }
+    }
+}
+
+# Logitech F310 controller
+inputMappings['f310'] = {
+    'name': 'Logitech F310',
+    'mappings': {
+        'generic': {
+            'axes': {
+                'leftX': 0,
+                'leftY': 1,
+                'left': (0, 1),
+                'thumbL': (0, 1),  # same as left, just more explicit
+                'rightX': 2,
+                'rightY': 3,
+                'right': (2, 3),
+                'thumbR': (2, 3),
+                'triggerL': 4,
+                'triggerR': 5,
+                'triggers': (4, 5)
+            },
+            'buttons': {
+                'A': 0,
+                'B': 1,
+                'X': 2,
+                'Y': 3,
+                'shoulderL': 4,
+                'shoulderR': 5,
+                'back': 6,
+                'start': 7,
+                'stickL': 8,
+                'stickR': 9,
+                'up': 10,  # hat
+                'down': 11,
+                'left': 12,
+                'right': 13
+            },
+            'hats': {}
+        }
+    }
+}
+
+# same as f310, but with different name
+inputMappings['f710'] = {
+    'name': 'Logitech F710 Controller',
+    'mappings': {
+        'generic': {
+            'axes': inputMappings['f310']['mappings']['generic']['axes'],
+            'buttons': inputMappings['f310']['mappings']['generic']['buttons'],
+            'hats': inputMappings['f310']['mappings']['generic']['hats']
+        }
+    }
+}
+
+# Thrustmaster T-Flight Hotas X
+# Aliases for buttons as they appear on the device are provided
+inputMappings['hotasx'] = {
+    'name': 'Thrustmaster T-Flight Hotas X',
+    'mappings': {
+        'generic': {
+            'axes': {
+                'X': 0,
+                'Y': 1,
+                'Z': 2, 'rudderL': 2, 'slider': 2,
+                'XY': (0, 1), 'stick': (0, 1),
+                'RX': 3, 'throttle': 3,
+                'RY': 4,
+                'RZ': 5, 'rudderR': 5
+            },
+            'buttons': {
+                'button1': 0, 'trigger': 0,
+                'button2': 1, 'L1': 1,
+                'button3': 2, 'R3': 2,           
+                'button4': 3, 'L3': 3,
+                'button5': 4, 'square': 4,
+                'button6': 5, 'X': 5,
+                'button7': 6, 'circle': 6,
+                'button8': 7, 'triangle': 7,
+                'button9': 8, 'R2': 8,
+                'button10': 9, 'L2': 9,
+                'button11': 10, 'select': 10,
+                'button12': 11, 'start': 11
+            },
+            'hats': {
+                'hat': 0  # joystick hat
+            }
+        }
+    }
+}
+
+# Oculus Rift and Quest Touch controllers
+inputMappings['ovrtouch'] = {
+    'name': 'Oculus Touch',
+    'mappings': {
+        'generic': {
+            'axes': {
+                'thumbLX': 0,
+                'thumbLY': 1,
+                'thumbL': (0, 1),
+                'thumbRX': 2,
+                'thumbRY': 3,
+                'thumbR': (2, 3),
+                'triggerL': 4,
+                'triggerR': 5,
+                'triggers': (4, 5)
+            },
+            'buttons': {
+                'A': 0,
+                'B': 1,
+                'X': 2,
+                'Y': 3,
+                'shoulderL': 4,
+                'shoulderR': 5,
+                'thumbL': 6,
+                'thumbR': 7,
+                'up': 8,  # hat
+                'down': 9,
+                'left': 10,
+                'right': 11
+            },
+            'hats': {}
+        }
+    }
+}
+
+
+def getAvailableInputSchemes():
+    """Get a list of available input schemes.
+
+    Returns
+    -------
+    list
+        A list of available input schemes.
+
+    """
+    return list(inputMappings.keys())
+
+
+def getInputScheme(name, backend=None):
+    """Get an input scheme by name.
+
+    Parameters
+    ----------
+    name : str
+        The name of the input scheme to get.
+    backend : str or None
+        The backend to get the input scheme for. Defaults to `None` which 
+        returns the generic configuration.
+
+    Returns
+    -------
+    dict or None
+        The input scheme. None if the input scheme does not exist.
+
+    """
+    if name not in inputMappings.keys():
+        raise ValueError("Input scheme '{}' not found.".format(name))
+    
+    inputMapping = inputMappings[name]['mappings']
+
+    if backend not in inputMapping.keys() or backend is None:
+        logging.info(
+            "Input scheme '{}' does not have specific settings for backend "
+            "'{}', using generic configuration.".format(name, backend))
+        backend = 'generic'
+
+    return inputMapping[backend]
+
+
+if __name__ == "__main__":
+    pass

psychopy/hardware/keyboard.py

@@ -55,7 +55,7 @@ Example usage
 """
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 from __future__ import absolute_import, division, print_function
@@ -151,6 +151,8 @@ class KeyPress(BaseResponse):
             else:
                 self.name = keyNames[code]
         elif KeyboardDevice._backend == 'iohub':
+            if name is None:
+                name = code
             self.name = name
         # get value
         value = self.name
@@ -405,7 +407,7 @@ class KeyboardDevice(BaseResponseDevice, aliases=["keyboard"]):
             True if the two objects represent the same physical device
         """
         # all Keyboards are the same device
-        return True
+        return isinstance(other, (KeyboardDevice, dict))
 
     @classmethod
     def getBackend(self):

psychopy/hardware/labhackers.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """This provides basic LabHackers (www.labhackers.com) device classes.

psychopy/hardware/labjacks.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 """This provides a basic LabJack U3 class that can write a full byte of data, by
@@ -13,18 +13,14 @@ These are optional components that can be obtained by installing the
 
 """
 
-import psychopy.logging as logging
 
-try:
-    from psychopy_labjack import U3
-except (ModuleNotFoundError, ImportError):
-    logging.error(
-        "Support for LabJack hardware is not available this session. Please "
-        "install `psychopy-labjack` and restart the session to enable support.")
-except Exception as e:
-    logging.error(
-        "Error encountered while loading `psychopy-labjack`. Check logs for "
-        "more information.")
+from psychopy.plugins import PluginStub
 
-if __name__ == "__main__":
+
+class U3(
+    PluginStub,
+    plugin="psychopy-labjack",
+    docsHome="http://psychopy.github.io/psychopy-labjack",
+    docsRef="/labjacks.html#psychopy_labjack.labjacks.U3"
+):
     pass