Now Shipping! – The EyeLink 3; combined head and eye tracking at up to 1000 Hz.

SR Support Forum   ›   Learning Resources   ›   Getting Started   ›   Getting Started with Experiment Programming   ›   Getting Started with Psychtoolbox (Matlab and Octave)
Getting Started with Psychtoolbox (Matlab and Octave)
Sam
Research Support Specialist
*******
Joined: Aug 2020
Posts: 1,039

#1
08-27-2020, 15:55 PM (This post was last modified: 10-06-2025, 14:36 PM by Dan.)
Psychtoolbox for Matlab and Octave natively supports EyeLink eye trackers through its built-in EyeLink Toolbox. This toolbox is a complete wrapper for the EyeLink API. To use it, you must first install the free EyeLink Developers Kit on your computer (Windows, macOS, or Linux). Once installed, the toolbox is fully integrated within Psychtoolbox.

Please note that while the EyeLink Developers Kit is cross-platform (Windows, macOS, and LinuxWindows, macOS, and Linux), Psychtoolbox has its own specific system requirements. Always check the official Psychtoolbox documentation for compatibility.


Installation Instructions:
  1. Configure your Display PC's network connection to communicate with the EyeLink Host PC.
  2. Install the latest version of Psychtoolbox within Matlab or Octave.
  3. Install the latest version of the EyeLink Developers Kit for your operating system.

    The EyeLink Developers Kit installs the EyelinkToolbox and the necessary mex files in the following location:
    • Windows:         C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\MATLAB Psychtoolbox
    • macOS:             /Applications/Eyelink/SampleExperiments/MATLAB Psychtoolbox
    • Linux:                /usr/share/EyeLink/SampleExperiments/MATLAB Psychtoolbox
Testing your installation

To verify your setup, you can list all available EyeLink Toolbox functions and then run an example script.

Important Note: Recent versions of Psychtoolbox require you to run the InitializePsychSound command in MATLAB before our example scripts will work correctly. Please do this first.

Testing Your Installation
  • List Functions: To see all available commands, type Eyelink into the MATLAB command window and press Enter.
  • Run an Example: To confirm everything is working, run one of the example scripts described below.

EyeLink Toolbox Templates / Example Projects:

The EyeLink Toolbox includes several demos to show you how to integrate its functions into your Psychtoolbox projects.

We strongly recommend you use the official examples located in the SR-ResearchDemos folder. Other user-created demos in the parent EyelinkDemos folder may use outdated functions and are not compatible with Data Viewer's integration protocols.
  • <Psychtoolbox>/PsychHardware/EyelinkToolbox/EyelinkDemos/SR-ResearchDemos
The following example scripts are provided:
 
Templates Description
SimplePicture A basic demo that records eye movements while an image is displayed. The trial ends on a keypress.
StereoPicture Records eye movements during stereo stimulus presentation (supports split-screen or dual monitors).
PursuitTarget A smooth pursuit task where the user tracks a target moving in a sine-wave pattern for 5 seconds per trial.
SimpleVideo Records eye movements while a video plays until the spacebar is pressed. Includes animated calibration targets.
MRI_BlockRecord Simulates an fMRI study. It uses block-level recording and waits for a keyboard trigger ('t') to begin trials within a block (2 blocks of 3 trials). Trial duration is 5.5s during which a 4s stimulus is presented with a fixed ITI where a fixation cross is presented between trials.
GazeContingent -> FixWindowBufferedSamples EyeLink gaze-contingent demo that shows how to retrieve online gaze samples from a buffer. In each trial central crosshairs are shown until gaze is detected continuously within a central square window for 500ms or until the space bar is pressed. An image is then presented until the space bar is pressed to end the trial.
GazeContingent -> FixWindowFastSamples EyeLink gaze-contingent demo showing how to retrieve fast gaze samples online. In each trial central crosshairs are shown until gaze is detected continuously within a central square window for 500ms or until the space bar is pressed. An image is then presented until the space bar is pressed to end the trial.
GazeContingent -> GCBufferedEvents -> BufferedEndSacEvents A simple EyeLink gaze-contingent demo showing how to retrieve online events from a buffer. In each trial an image is presented with a red gaze-contingent dot overlaid on top. The dot's location is updated online based on the end x, y coordinates of each saccade detected. Each trial ends when the space bar is pressed.
GazeContingent -> GCBufferedEvents -> BufferedFixUpdateEvents A simple EyeLink gaze-contingent demo showing how to retrieve online events from a buffer. In each trial an image is presented with a red gaze-contingent dot overlaid on top. The dot's location is based on the average x, y coordinates of fixations updated online every 50ms via a FIXUPDATE event.
GazeContingent -> GCFastSamples A simple EyeLink gaze-contingent demo showing how to retrieve fast online samples. In each trial an image is presented with a red gaze-contingent dot overlaid on top. The dot's location is updated online based on the x, y coordinates of the latest gaze sample retrieved online. Each trial ends when the space bar is pressed.


EyeLink Data Viewer Messaging Commands and Syntax:
Beyond just marking event times, it's highly recommended to send specially formatted messages to your EyeLink Data File (.edf) to improve integration with Data Viewer.

These messages allow Data Viewer to automatically parse your experiment's structure, including:
  • Trial start and end times
  • Trial variables (e.g., condition, accuracy)
  • Stimulus information
The example scripts included with the Developers Kit show you exactly how to format and send these messages.

Additional Resources
For a complete guide on the messaging protocol, please see the following:

Documentation:

Here are some key resources for learning how to use the EyeLink Toolbox with MATLAB/Psychtoolbox.
  • EyeLink Programmer's Guide
    The EyeLink Toolbox is a Matlab based wrapper for our core C API contained within the EyeLink Developers Kit. This guide is the complete documentation for that C API, detailing all its functions, data structures, and implementation.

    Note on Syntax: While the function names and syntax in this guide will differ from the MATLAB implementation, the core logic and functionality are analogous. It is an excellent resource for understanding what's happening "under the hood."

  • Video Tutorials & Webinars