Keyboard

To handle input from keyboard (supercedes event.getKeys)

The Keyboard class was new in PsychoPy 3.1 and replaces the older event.getKeys() calls.

Psychtoolbox versus event.getKeys

On 64 bits Python3 installations it provides access to the Psychtoolbox kbQueue series of functions using the same compiled C code (available in python-psychtoolbox lib).

On 32 bit installations and Python2 it reverts to the older psychopy.event.getKeys() calls.

The new calls have several advantages:

  • the polling is performed and timestamped asynchronously with the main thread so that times relate to when the key was pressed, not when the call was made
  • the polling is direct to the USB HID library in C, which is faster than waiting for the operating system to poll and interpret those same packets
  • we also detect the KeyUp events and therefore provide the option of returning keypress duration
  • on Linux and Mac you can also distinguish between different keyboard devices (see getKeyboards())

This library makes use, where possible of the same low-level asynchronous hardware polling as in Psychtoolbox

Example usage

from psychopy.hardware import keyboard
from psychopy import core

kb = keyboard.Keyboard()

# during your trial
kb.clock.reset()  # when you want to start the timer from
keys = kb.getKeys(['right', 'left', 'quit'], waitDuration=True)
if 'quit' in keys:
    core.quit()
for key in keys:
    print(key.name, key.rt, key.duration)

Classes and functions

class psychopy.hardware.keyboard.Keyboard(device=-1, bufferSize=10000, waitForStart=False, clock=None)

The Keyboard class provides access to the Psychtoolbox KbQueue-based calls on Python3 64-bit with fall-back to event.getKeys on legacy systems.

Create the device (default keyboard or select one)

Parameters:
  • device (int or dict) – On Linux/Mac this can be a device index or a dict containing the device info (as from getKeyboards()) or -1 for all devices acting as a unified Keyboard
  • bufferSize (int) – How many keys to store in the buffer (before dropping older ones)
  • waitForStart (bool (default False)) – Normally we’ll start polling the Keyboard at all times but you could choose not to do that and start/stop manually instead by setting this to True
getKeys(keyList=None, waitRelease=True, clear=True)
Parameters:
  • keyList (list (or other iterable)) – The keys that you want to listen out for. e.g. [‘left’, ‘right’, ‘q’]
  • waitRelease (bool (default True)) – If True then we won’t report any “incomplete” keypress but all presses will then be given a duration. If False then all keys will be presses will be returned, but only those with a corresponding release will contain a duration value (others will have duration=None
  • clear (bool (default True)) – If False then keep the keypresses for further calls (leave the buffer untouched)
Returns:
Return type:

A list of Keypress objects
start()

Start recording from this keyboard

stop()

Start recording from this keyboard

class psychopy.hardware.keyboard.KeyPress(code, tDown, name=None)

Class to store key presses, as returned by Keyboard.getKeys()

psychopy.hardware.keyboard.getKeyboards()

Get info about the available keyboards.

Only really useful on Mac/Linux because on these the info can be used to select a particular physical device when calling Keyboard. On Win this function does return information correctly but the :class:Keyboard can’t make use of it.

Returns:USB Info including with name, manufacturer, id, etc for each device
Return type:A list of dicts

Back to top