Keyboard

To handle input from keyboard (supersedes 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'], waitRelease=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)[source]

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)[source]
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()[source]

Start recording from this keyboard

stop()[source]

Start recording from this keyboard

waitKeys(maxWait=inf, keyList=None, waitRelease=True, clear=True)[source]

Same as ~psychopy.hardware.keyboard.Keyboard.getKeys, but halts everything (including drawing) while awaiting keyboard input.

Parameters
maxWaitany numeric value.

Maximum number of seconds period and which keys to wait for. Default is float(‘inf’) which simply waits forever.

keyListNone or []

Allows the user to specify a set of keys to check for. Only keypresses from this set of keys will be removed from the keyboard buffer. If the keyList is None, all keys will be checked and the key buffer will be cleared completely. NB, pygame doesn’t return timestamps (they are always 0)

waitRelease: True or False

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

clearTrue or False

Whether to clear the keyboard event buffer (and discard preceding keypresses) before starting to monitor for new keypresses.

Returns None if times out.

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

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

Unlike keypresses from the old event.getKeys() which returned a list of strings (the names of the keys) we now return several attributes for each key:

.name: the name as a string (matching the previous pyglet name) .rt: the reaction time (relative to last clock reset) .tDown: the time the key went down in absolute time .duration: the duration of the keypress (or None if not released)

Although the keypresses are a class they will test ==, != and in based on their name. So you can still do:

kb = KeyBoard()
# wait for keypresses here
keys = kb.getKeys()
for thisKey in keys:
    if thisKey=='q':  # it is equivalent to the string 'q'
        core.quit()
    else:
        print(thisKey.name, thisKey.tDown, thisKey.rt)
psychopy.hardware.keyboard.getKeyboards()[source]

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