The BSS OpenSesame Plugin Collection

The OpenSesame plugin collection for sending stimulus synchronization triggers and response collection through Event Exchanger (EVT-2) USB-devices.

Copyright 2010-2024 Mark Span (m.m.span@rug.nl) and M. Stokroos (m.stokroos@rug.nl), University of Groningen.

Contributions: This code is based on the work of E. Hoekstra and M.M. Span. The code has been debugged and rewritten for OpenSesame 4 by M. Stokroos.

1. About

The BSS Research Support OpenSesame Plugin Collection for use with Event Exchanger (EVT-2) USB-devices.

EVT-devices and the associated plugins are developed by the Research Support department from the faculty of Behavioural and Social Sciences from the University of Groningen.

The currently supported OpenSesame version is: 4.1.xx

The following plugins are available:

icon	plugin	Description	OpenSesame back-end	operating system	Status
	evt_trigger	plugin for event exchanger EVT-2,3 and 4 variants for generating triggers	PyGame, PsychoPy	Windows	ok
	response_box	plugin for all of the RSP12x button response box variants with 1-8 buttons	PyGame, PsychoPy	Windows	ok
	rsp_pygame	plugin for RSP12x button response box variants with 1-8 buttons	PyGame	Windows, Linux	ok
	tactile_stimulator	plugin for the Electrotactile Stimulator (SHK-1B) 0-5mA	PyGame	Windows	ok
	vas_evt	A Visual Analog Slider plugin controlled via an encoder knob connected to the EVT-2	PyGame	Windows	planned
	vas_gui	A Visual Analog Slider plugin controlled via the PC-mouse on a predefined canvas (sketchpad)	PyGame	Windows, Linux	Mouse response not ok in Linux.
	rgb_led_control	plugin for multi-color LED response boxes	PyGame	Windows	not validated

Package dependencies

The plugins are dependent on the Python API pyevt and hidapi.

pyevt and hidapi are installed from the Python Console in OpenSesame with the single command:

pip install --user pyevt

Installing the plugin Package

The current package version is: 0.2.2

pip install --user evt-plugins

Environmental settings

By default, the OpenSesame 4.x plugins are installed as python site-package and automatically loaded at the startup. When the plugins are located somewhere else, add your path to the python-path of OpenSesame in the environment.yaml file in the OpenSesame program directory (The OPENSESAME_plugin_PATH is old style). See for the instructions here: https://rapunzel.cogsci.nl/manual/environment/

Bug Fixes

plugin	version	date	fixes
vas_gui	0.2.1	July 2026	Set time-out on mouse click. Change vas_response variable round-off.

2. Plugin Descriptions

evt_trigger

The evt_trigger plugin supports the following output manipulator functions:

• Clear all outputs
• Write output line(s)
• Invert output line(s)
• Pulse output line(s)

response_box

response_box Collects responses from a 1 to 8 button RSP-12x response box.

After the prepare phase of the plugin, a workspace variable connected_device_plugin_instance_name is created to check if the actual tactile-stimulator device is really detected and connected to the plugin.

rsp_pygame

This response box type plugin works for EVT devices as well for joystick devices. It makes use of the pygame joystick API and is platform independent.

tactile_stimulator

The tactile_stimulator plugin operates in two parts. Usually two instances of this plugin are used in the OpenSesame experiment. The use of the Calibration instance should always precede the Stimulate instance from the plugin. In Calibration-mode, the upper limit of stimulus-current threshold is set between 0 and 5mA rms. In the Stimulate-mode, a percentage of the preveously set stimulus-current upper limit is to be applied to the subject. The Calibration instance can be used standalone, for example to precondition the subject. The pulse duration can be extended up to 2000ms.

After the prepare phase of the plugin, a workspace variable connected_device_plugin_instance_name is created to check if the actual tactile-stimulator device is really detected and connected to the plugin.

Here below follows a list of variables that appear in the OpenSesame variable inspector when using the tactile_stimulator plugin:

variable name	description
tactstim_calibration_perc	The percentage of the slider setting for the stimulus current of up to 5mA rms max.
tactstim_calibration_milliamp	The calibration value of the stimulus current in mA's. This is the max. current applied to the subject.
tactstim_calibration_value	The byte value representation of the calibrated current.
tactstim_pulse_milliamp	The actual current in mA's, applied to the subject when pulsing.
tactstim_pulse_value	The actual byte value representation that is sent to the tactile stimulator.
tactstim_pulse_duration_ms	The pulse duration time in ms.
tactstim_time_last_pulse	Unique time stamp in seconds from the moment of the shock.

vas_evt

A Visual Analog Slider plugin controlled by an EVT rotary or linear encoder. The vas_evt plugin does not work standalone, but requires a linkage to a custom designed sketchpad screen.

vas_gui

A Visual Analog Slider plugin. The vas_gui plugin does not work standalone, but requires a linkage to a custom designed sketchpad screen with an analog slider design.

Here below is the list of the variables that will appear in the OpenSesame variable inspector when using the vas_gui plugin:

variable name	description
vas_response	This value is the reading from the VAS object, ranging from 0 to 100.
vas_response_time	this is the repsonse time in ms. The value -1 means that the timeout period was reached.

rgb_led_control

This plugin works for the RSP-LT device, a response-box with RGB-controlled LED buttons.

3. LICENSE

The evt-plugins collection is distributed under the terms of the GNU General Public License 3. The full license should be included in the file COPYING, or can be obtained from

http://www.gnu.org/licenses/gpl.txt

This plugin collection contains the work of others.

4. Documentation

Installation instructions and documentation on OpenSesame are available on the documentation website:

http://osdoc.cogsci.nl/

Evt-plugin information:

https://markspan.github.io/evtplugins/