This provides a basic ButtonBox class, and imports the ioLab python library.

class psychopy.hardware.iolab.ButtonBox[source]

PsychoPy’s interface to ioLabs.USBBox. Voice key completely untested.

Original author: Jonathan Roberts PsychoPy rewrite: Jeremy Gray, 2013

Class to detect and report ioLab button box.

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”


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.


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.


Discard all button / voice key events.


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 a list of the buttons that are currently enabled.


Detect and return a list of all events (likely just one); no block.

Use downOnly=False to include button-release events.


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

setEnabled(buttonList=(0, 1, 2, 3, 4, 5, 6, 7), voice=False)[source]

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

setLights(lightList=(0, 1, 2, 3, 4, 5, 6, 7))[source]

Turn on the specified LEDs (None, 0..7, list of 0..7)


Disable all buttons and lights.

waitEvents(downOnly=True, timeout=0, escape='escape', wait=0.002)[source]

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).

Back to top