Python library
The Boks and documentation below is under development.
If there is a Boks plug-in in your OpenSesame experiment, the boks can be accessed as exp.boks or self.experiment.boks:
# Collect a response time with a 2000ms timeout
exp.boks.set_timeout(2000)
t1 = self.time()
button, t2 = exp.boks.get_button_press()
exp.set('response', button)
exp.set('response_time', t2-t1)
class libboks
Function overview:
__init__
button_count
close
get_button_press
get_button_release
get_button_state
get_buttons
get_sid
get_timeout
info
set_buttons
set_continuous
set_led
set_timeout
libboks.__init__(port=None, experiment=None, baudrate=115200, buttons=None, timeout=None, led=False)
Constructor. A Boks object is created automatically the first time that a Boks plug-in is prepared in OpenSesame.
Keyword arguments:
port → The port to which the device is connected, None for autodetect, or 'dummy' to use the keyboard as dummy-boks. (default=None)
experiment → An OpenSesame experiment, or None to run in plain Python mode. (default=None)
baudrate → The baudrate of the boks, or None to use default. (default=None)
buttons → A list of buttons that are used, or None to use all buttons. (default=None)
timeout → A timeout in milliseconds when collecting responses or None for no timeout. (default=None)
led → Indicates whether the LED should be switched on. (default=False)
Example:
Keyword arguments:
port → The port to which the device is connected, None for autodetect, or 'dummy' to use the keyboard as dummy-boks. (default=None)
experiment → An OpenSesame experiment, or None to run in plain Python mode. (default=None)
baudrate → The baudrate of the boks, or None to use default. (default=None)
buttons → A list of buttons that are used, or None to use all buttons. (default=None)
timeout → A timeout in milliseconds when collecting responses or None for no timeout. (default=None)
led → Indicates whether the LED should be switched on. (default=False)
Example:
# Collect a response with a 2000ms timeout
exp.boks.set_timeout(2000)
t1 = self.time()
button, t2 = exp.boks.get_button_press()
exp.set('response', button)
exp.set('response_time', t2-t1)
libboks.button_count()
Gets the number of buttons that are physically present on the device. This number includes the photodiode.
Returns:
The number of buttons
Example:
Returns:
The number of buttons
Example:
i = exp.boks.button_count()
print 'Your Boks has %d buttons' % i
libboks.close()
Neatly close the device. This will deactivate the boks and close the serial port connection. OpenSesame will do this automatically when the experiment ends.
Example:
Example:
exp.boks.close()
libboks.get_button_press()
Collect a button press
Returns:
A (button, timestamp) tuple. If a timeout occured, the button is None. Otherwise buttons are integers. The timestamp is a float value in milliseconds.
Example:
Returns:
A (button, timestamp) tuple. If a timeout occured, the button is None. Otherwise buttons are integers. The timestamp is a float value in milliseconds.
Example:
# Collect a response with a 2000ms timeout
exp.boks.set_timeout(2000)
t1 = self.time()
button, t2 = exp.boks.get_button_press()
exp.set('response', button)
exp.set('response_time', t2-t1)
libboks.get_button_release()
Collect a button release
Returns:
A (button, timestamp) tuple. If a timeout occured, the button is None. Otherwise buttons are integers. The timestamp is a float value in milliseconds.
Example:
Returns:
A (button, timestamp) tuple. If a timeout occured, the button is None. Otherwise buttons are integers. The timestamp is a float value in milliseconds.
Example:
# Collect a button release with a 2000ms timeout
exp.boks.set_timeout(2000)
t1 = self.time()
button, t2 = exp.boks.get_button_release()
exp.set('response', button)
exp.set('response_time', t2-t1)
libboks.get_button_state()
Checks which buttons are currently pressed
Returns:
A list of buttons that are currently presed
Example:
Returns:
A list of buttons that are currently presed
Example:
l = exp.boks.get_button_state()
if 1 in l:
print 'Button 1 is pressed'
libboks.get_buttons()
Retrieves the list of buttons that are 'active', i.e. that are used by get_button_press(), get_button_release(), and get_button_state().
Returns:
A list of active buttons. For example, [1,2,3,4].
Example:
Returns:
A list of active buttons. For example, [1,2,3,4].
Example:
l = exp.boks.get_buttons()
if 1 in l:
print 'Button 1 is currently being monitored'
libboks.get_sid()
Retrieves the Arduino serial ID.
Returns:
A 7 character string containing the Arduino serial ID
Example:
Returns:
A 7 character string containing the Arduino serial ID
Example:
sid = exp.boks.get_sid()
print 'The Arduino serial ID of the Boks is %s' % sid
libboks.get_timeout()
Gets the timeout used by get_button_press() and get_button_release().
Returns:
A timeout value in milliseconds or None if no timeout is set
Example:
Returns:
A timeout value in milliseconds or None if no timeout is set
Example:
exp.boks.set_timeout(2000)
t = exp.boks.get_timeout()
print 'The Boks timeout is currently set to %d ms' % t
libboks.info()
Retrieve boks device info
Returns:
A (firmware_version, model) tuple. The firmware_version is a string of the format X.Y.Z. The model is a short string.
Example:
Returns:
A (firmware_version, model) tuple. The firmware_version is a string of the format X.Y.Z. The model is a short string.
Example:
firmware, model = exp.boks.info()
print 'Boks model: %s' % model
print 'Boks firmware: %s' % firmware
libboks.set_buttons(buttons)
Sets which buttons should be used for libboks.get_button_press() and libboks.get_button_release()
Arguments:
buttons → a list of buttons, where each button is an integer. To enable all buttons (except for the photodiode), use None.
Example:
Example:
Example:
Arguments:
buttons → a list of buttons, where each button is an integer. To enable all buttons (except for the photodiode), use None.
Example:
# Only use buttons 1 and 2
exp.boks.set_buttons([1,2])
Example:
# Use all buttons except for the photodiode
exp.boks.set_buttons(None)
Example:
# Only use the photodiode (button 8)
exp.boks.set_buttons([8])
libboks.set_continuous(continuous=True)
Determines whether get_button_press() and get_button_release() are triggered only by signal changes (discontinuous) or also by continuous signals. The Boks is by default in discontinuous mode, which is generally what you want. For example, in continuous mode, get_button_release() will respond right away if any of the buttons is not pressed, whereas you are generally interested only in buttons that go from being pressed to not being pressed.
Keyword arguments:
continuous → True for continuous, False for discontinuous
(default=True)
Example:
Keyword arguments:
continuous → True for continuous, False for discontinuous
(default=True)
Example:
exp.boks.set_continuous(True)
t1 = exp.time()
# If some button is not pressed, this will return right away
button, t2 = exp.boks.get_button_release()
exp.set('response', button)
exp.set('response_time', t2-t1)
libboks.set_led(on=True)
Turns the LED on or off.
Keyword arguments:
on → Indicates whether the LED should be on (True) or off (False) (default=True)
Example:
Keyword arguments:
on → Indicates whether the LED should be on (True) or off (False) (default=True)
Example:
# Blink LED five time
for i in range(5):
exp.boks.set_led(True)
self.sleep(500)
exp.boks.set_led(False)
self.sleep(500)
libboks.set_timeout(timeout)
Sets the timeout used by get_button_press() and get_button_release()
Arguments:
timeout → a value in milliseconds. Use 0 or None to disable timeout
Example:
Arguments:
timeout → a value in milliseconds. Use 0 or None to disable timeout
Example:
exp.boks.set_timeout(2000)
t = exp.boks.get_timeout()
print 'The Boks timeout is currently set to %d ms' % t
