08-27-2020, 04:00 PM
OpenSesame is an open-source stimulus presentation software developed by Sebastiaan Mathot (http://osdoc.cogsci.nl/). OpenSesame is based on Python and can be easily expanded through "plugins" and "extensions". In order to support EyeLink integration with OpenSesame, we have created a library of EyeLink specific plugins. While OpenSesame can also interface with EyeLink systems via the Pygaze library that is distributed with OpenSesame, this approach does not support the full range of EyeLink features, and we are unable to offer technical support for Pygaze. This Getting Started Guide will focus on the EyeLink plugin that SR Research provides.
IMPORTANT NOTICE: The EyeLink Plugin is under development, so please let us know if you run into any issues by emailing support@sr-research.com.
OpenSesame 4.* Installation Instructions
This plugin has been tested on Windows 11, and macOS 14, but should work for all operating systems supported by OpenSesame:
Testing your installation and Documentation
OpenSesame supports Pygame (legacy), Psychopy, and Expyriment as its backend. We encourage users to use the Psychopy backend, as it is robust and supports frequently used visual stimuli for visual psychophysics (e.g., gratings).
In addition to the plugin, we have provided three example OpenSesame projects that illustrate how the plugin can be used. Once you have followed the above instructions to install the EyeLink plugin, please download and extract the example projects from the link below. Then simply run one of the example projects to test the installation. Alongside the example scripts is an 'OpenSesame 4 EyeLink Plugin User Manual.pdf' which outlines in detail each plugin item and useful information on implementation.
OpenSesame4_Examples.zip (Size: 6.01 MB / Downloads: 4)
Templates / Example Experiments
Please check the OpenSesame website (http://osdoc.cogsci.nl/) for information about OpenSesame and general tutorials on programming in OpenSesame. Please see below for further information on the example OpenSesame experiments provided by us.
EyeLink Data Viewer Messaging Commands and Syntax
Throughout the course of your experiment, in addition to sending messages to the EyeLink data file (i.e., EDF file) that log the timing of events within your task, it's typically a good idea to send special messages that allow integration with Data Viewer. All of the example projects illustrate how to send special messages to the EDF to convey important information to Data Viewer, like trial starting/ending times, trial variable values, trial stimulus information, and more. You can find a webinar at the following link that covers the formatting of these messages in detail:
In addition to the GUI items included in the EyeLink plugin, inline scripts can be used in OpenSesame to access all the functions included in the PyLink library. PyLink is fully featured and all of its functions are documented in the PyLink API User Guide which is packaged with the EyeLink Developers Kit. A very useful Getting Started with Python and PyLink guide can also be found after installing the developers kit in the following directory:
Plugin Updates
If you face difficulties with the EyeLink plugin, please check that you have the latest version. Copy/paste the following update command into the console and press Enter. Once complete, please restart OpenSesame to use the latest release.
OpenSesame 3.* Legacy Installation Instructions
For users needing support for legacy OpenSesame 3 releases, please find below the instructions for installing and using an older release of the EyeLink Plugin as well as two example scripts. For more details about this older plugin, please check out the OpenSesame_EyeLink_Plugin_User_Manual.pdf within the OpenSesame_3.zip file. The plugin and pylink files described as 'found within the Developers Kit installation' may no longer be included in recent releases, so are now included in this zip file.
OpenSesame_3.zip (Size: 4.81 MB / Downloads: 1)
IMPORTANT NOTICE: The EyeLink Plugin is under development, so please let us know if you run into any issues by emailing support@sr-research.com.
OpenSesame 4.* Installation Instructions
This plugin has been tested on Windows 11, and macOS 14, but should work for all operating systems supported by OpenSesame:
- Launch OpenSesame v4.0 (and above).
- In the console type the following pip installation command and press Enter, wait for a success message.
Code:pip install opensesame-plugin-eyelink
- Close OpenSesame and then open it again, the EyeLink Plugins should now be visible in the Toolbar Items menu under the header EyeLink.
Testing your installation and Documentation
OpenSesame supports Pygame (legacy), Psychopy, and Expyriment as its backend. We encourage users to use the Psychopy backend, as it is robust and supports frequently used visual stimuli for visual psychophysics (e.g., gratings).
In addition to the plugin, we have provided three example OpenSesame projects that illustrate how the plugin can be used. Once you have followed the above instructions to install the EyeLink plugin, please download and extract the example projects from the link below. Then simply run one of the example projects to test the installation. Alongside the example scripts is an 'OpenSesame 4 EyeLink Plugin User Manual.pdf' which outlines in detail each plugin item and useful information on implementation.
OpenSesame4_Examples.zip (Size: 6.01 MB / Downloads: 4)
Templates / Example Experiments
Please check the OpenSesame website (http://osdoc.cogsci.nl/) for information about OpenSesame and general tutorials on programming in OpenSesame. Please see below for further information on the example OpenSesame experiments provided by us.
| Template | Description |
|---|---|
| OpenSesame4_Picture | This basic example shows how to to use the EyeLink Plugin components to connect to and disconnect from the tracker, to open and close data files, to start / stop recording, and illustrates the standard messages for integration with our Data Viewer analysis software. The task shows four pictures one-by-one on each trial, and a trial terminates upon a keypress response. |
| OpenSesame4_GazeTrigger | This picture based example shows how to use a gaze trigger to begin each trial when the participants look at a central fixation dot for 1 second. As with the picture example it also illustrates the standard messages for integration with Data Viewer analysis software. The task shows a fixation dot followed by four pictures one-by-one on each trial. The picture is shown when gaze is detected within the gaze-trigger region for 1 second or if the abort x key is pressed. The trial terminates upon a keypress response. |
| OpensSesame4_VW_Click | This example illustrates how to implement a Visual World task - a popular eye-tracking task in language studies which involves presenting audio stimuli as well as images. The inline scripts used in this project are explained in the the code comments. |
EyeLink Data Viewer Messaging Commands and Syntax
Throughout the course of your experiment, in addition to sending messages to the EyeLink data file (i.e., EDF file) that log the timing of events within your task, it's typically a good idea to send special messages that allow integration with Data Viewer. All of the example projects illustrate how to send special messages to the EDF to convey important information to Data Viewer, like trial starting/ending times, trial variable values, trial stimulus information, and more. You can find a webinar at the following link that covers the formatting of these messages in detail:
- EyeLink Data Viewer Integration Messaging Protocol
In addition to the GUI items included in the EyeLink plugin, inline scripts can be used in OpenSesame to access all the functions included in the PyLink library. PyLink is fully featured and all of its functions are documented in the PyLink API User Guide which is packaged with the EyeLink Developers Kit. A very useful Getting Started with Python and PyLink guide can also be found after installing the developers kit in the following directory:
- Windows: C:/Program Files(x86)/SR Research/EyeLink/SampleExperiments/Python/
- Mac: /Applications/Eyelink/SampleExperiments/Python/
- Linux: /usr/share/EyeLink/SampleExperiments/Python/
Plugin Updates
If you face difficulties with the EyeLink plugin, please check that you have the latest version. Copy/paste the following update command into the console and press Enter. Once complete, please restart OpenSesame to use the latest release.
Code:
pip install sr-research-pylink opensesame-eyelink-coregraphics opensesame-plugin-eyelink --upgradeOpenSesame 3.* Legacy Installation Instructions
For users needing support for legacy OpenSesame 3 releases, please find below the instructions for installing and using an older release of the EyeLink Plugin as well as two example scripts. For more details about this older plugin, please check out the OpenSesame_EyeLink_Plugin_User_Manual.pdf within the OpenSesame_3.zip file. The plugin and pylink files described as 'found within the Developers Kit installation' may no longer be included in recent releases, so are now included in this zip file.
OpenSesame_3.zip (Size: 4.81 MB / Downloads: 1)