SR Support Forum   ›   Learning Resources   ›   Getting Started   ›   Getting Started with Experiment Programming   ›   Getting Started with OpenSesame

Getting Started with OpenSesame
Sam
Research Support Specialist
*******
Joined: Aug 2020
Posts: 469

#1
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, we are unable to offer technical support for Pygaze, and this guide will focus on the EyeLink plugin.

IMPORTANT NOTICE: The EyeLink Plugin is still beta software, please let us know if you run into any issues (support@sr-research.com).

Installation instructions

This plugin has been tested on Windows 10, macOS 11.3.1, and Ubuntu 20.04. but should work for any operating systems supported by OpenSesame:
  1. Configure your Display PC's network connection to communicate with the EyeLink Host PC.
  2. Download and install the latest version of the EyeLink Developers Kit
  3. Locate the OpenSesame folder within the EyeLink Developers Kit:
    • Windows:           C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\examples\OpenSesame
    • macOS:               /Applications/Eyelink/SampleExperiments/Python/examples/OpenSesame
    • Ubuntu:              /usr/share/EyeLink/SampleExperiments/Python/examples/OpenSesame
  4. Copy all the folders in the OpenSesame_plugin folder (i.e. el_CamSetup, el_Connect, …, el_StopRecording folders) to:
    • Windows:           C:\Program Files (x86)\OpenSesame\share\opensesame_plugins\
    • macOS:               /Applications/OpenSesame.app/Contents/Resources/share/opensesame_plugins/
    • Ubuntu:              /usr/share/opensesame_plugins/
    Note, on Ubuntu to ensure you have permission to copy files into these folders, you can use the terminal to copy the files using the following command:

    Code:
    sudo cp -r /usr/share/EyeLink/SampleExperiments/Python/examples/OpenSesame/OpenSesame_eyelink_plugin/el* /usr/share/opensesame_plugins/

  5. OpenSesame needs the PyLink library to communicate with the tracker. PyLink is a Python wrapper of the EyeLink API (part of the EyeLink Developers Kit). To install the PyLink library, please do the following:
    • Windows and macOS:
      Different versions of the PyLink library, for different versions of Python can be found in the following folders after the EyeLink Developers Kit has been installed:
      • Windows:           C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\64
      • macOS:               /Applications/Eyelink/SampleExperiments/Python/
      There are multiple subfolders in this folder with two-digit names (e.g., 2.7, 3.6, 3.7). The two digits in the folder name indicate the Python version it was built against (e.g., the subfolder 3.7 contains the PyLink library for Python 3.7). When you launch OpenSesame, you can see the version of Python that it is using in the Console.

      Please copy the pylink folder from the corresponding version folder and paste it to the following folder:
      • Windows:           C:\Program Files (x86)\OpenSesame\Lib\site-packages
      • macOS:               /Applications/OpenSesame/Contents/Resources/lib/[python version]/site-packages
                                    (where [python version] will reflect the Python version that OpenSesame is using, e.g., python3.7)
    • Ubuntu:
      Open up a terminal and enter the following:

      Code:
      python3 /usr/share/EyeLink/SampleExperiments/Python/install_pylink.py

Testing your installation

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

The Eyelink plugin comes with two example OpenSesame projects. Once you have followed the above instructions to install the EyeLink plugin, please run one of the example projects to test the installation.

Templates / Example Experiments

Please check the OpenSesame website (http://osdoc.cogsci.nl/) for information about OpenSesmame and general tutorials on programming in OpenSesame. Please see below for the example OpenSesame experiments provided by us.

Template Description
OpenSesame_Picture This basic example shows how to connect to and disconnect from the tracker, how to open and close data files, how to start / stop recording, and illustrates the standard messages for integration with Data Viewer software. The task shows four pictures one-by-one on each trial, and a trial terminates upon a keypress response or until 3 secs have elapsed.
OpensSesame_VW_Click A popular eye-tracking task in language studies. The inline scripts used in this project are explained in the User Manual.


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. The examples included in the EyeLink Developers Kit 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: You can also find full documentation of the protocol in the Data Viewer User Manual (Help -> Contents) under the section "Protocol for EyeLink Data to Viewer Integration".

Documentation

For more details about this plugin, please check out the OpenSesame_EyeLink_Plugin_User_Manual.pdf contained with the OpenSesame examples folder installed with the EyeLink Developers Kit.

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 in the same locations:
  • Windows:           C:/Program Files(x86)/SR Research/EyeLink/SampleExperiments/Python/
  • Mac:                    /Applications/Eyelink/SampleExperiments/Python/
  • Linux:                  /usr/share/EyeLink/SampleExperiments/Python/
Given that PyLink is a wrapper for our C API contained within the EyeLink Developers Kit, you may also find the EyeLink Programmer's Guide helpful in expanding your knowledge of given functions in the API. This document contains the complete documentation of our C API functions, data structure, and implementation. The syntax functions listed in the manual will likely differ in how they are wrapped within the PyLink library, but much of the functionality should be analogous.