EyeLink Task Integration

This page describes how to interact with the EyeLink Tracker from your task/code – start, stop, annotate with triggers, messages. The analysis page has tips for the next step: exploring the collected edf file data offline.

Jump to Minimal eye task for example code.

For testing and debugging, there is

• mouse simulation mode (#246) but only on the “HostPC” (need access to eye tracking computer)
• dummy mode (EyeLink(ip=None), thread #89) that allows all EyeLink code (even bad commands) to pass through so the task logic can be tested without access to a Host PC.

SR Research provides EPrime, python (Psychopy), and matlab (Psychtoolbox) examples in the SDK folder. Downloading requires forum registration (free). All the task PC download links are curated on the forum (#3) and under learning resources. The particularly useful downloads are SDK and pylink (pyschopy) . The SDK includes examples for matlab/octave, eprime, and psychopy as well as some compiled exe examples.

SRResearch also provides a plugin (thread #7525) for psychopy's drag-and-drop “builder” GUI.

Eprime documentation can be found on thread-50

SRR provides video tutorials for developing in

• 📺 psychtoolbox/MATLAB
• 📺 psychopy/python

Programmers Guide (eyelinkprogrammers_guide.pdf) from thread #185 includes annotated code examples of “templates” and sections like “Useful EyeLink Commands” (pg 173) and “Function List” (pg 189). Look here for dense reference of all programmable features.

The Data Viewer Messaging Protocol forum thread (#60) (local copy) maybe be informative. The PPT there includes references to TRIALID, !V TRIAL_VAR, BUTTON_PRESS, etc

A demo eye tracking experiment can be found on eyelinkdemo.py, part of https://github.com/NPACore/tangle-eye/

Tasks using the EyeLink at the UPitt include

• tower of london in EPrime
• anti saccade in psychopy
• anti saccade in EPrime

The lncd task python package includes pylink_help.py to wrap around common functions. Of those, seconds_36base() to set the 12-character limited Host PC .edf recording file name might be the most useful. It can be paired with the receiveDataFile wrapper get_data()

Here is a minimal exercise of key EyeLink commands using pylink_help to wrap the SDK sendMessage and sendCommand commands.

showdot.py

import time
from psychopy import visual
# https://github.com/LabNeuroCogDevel/lncdtask/blob/main/lncdtask/pylink_help.py
import lncdtask.pylink_help as camera  # pip instsall git+https://github.com/LabNeuroCogDevel/lncdtask
                                       # pip install --index-url=https://pypi.sr-research.com sr-research-pylink
 
win = visual.Window([800, 600])
dot = visual.Circle(win, radius=.1, lineColor=None, fillColor='yellow')
win.flip()
 
## ip => 100.1.1.1 in production, remove from call to use default
eye = camera.eyelink(win.size, ip=None) # sendCommand for screen_pixel_coords,
                                        #     DISPLAY_COORDS, select_parser_configuration,
                                        #     scene_camera_gazemap, pupil_size_diameter
 
# start new file, eyetracker name based on time
eye.open("sub-1_ses-1",base36enc=True)  # openDataFile('DE4DB3AF.EDF')
                                        # sendMessage("NAME: sub-1_ses-1")
eye.start()                             # startRecording(1, 1, 1, 1)
eye.trial_start("1")                    # sendMessage("TRIALID 1")
eye.var_data("show", "fix")             # sendMessage("!V TRIAL_VAR_DATA show fix");
 
dot.draw()
win.callOnFlip(eye.trigger, 'show-dot') # sendMessage("show-dot"); 
                                        # sendCommand("record_status_message show-dot")
time.sleep(1)
win.flip()
 
time.sleep(1)
eye.trial_end()                         # sendMessage(f"TRIAL OK")
 
# saves to 'sub-1_ses-1_TIME.edf' on local computer
eye.get_data()                          # endRealTimeMode(); closeDataFile();
                                        # receiveDataFile("","sub-1_ses-1_TIME.EDF")
win.close()

To install lncdtask, run pip install git+https://github.com/LabNeuroCogDevel/lncdtask. On windows inside psychopy's coder, using the python shell, that might look like

import os
os.system("pip install git+https://github.com/LabNeuroCogDevel/lncdtask")

• use dummy/ip=None to run task code without the actual tracker. More on thread #89.
• Ask Steve to schedule non-billable hours for dedicated time with the MRRC EyeLink Hardware http://www.mrctr.upmc.edu/mrsched/day.php

Psychtoolbox includes EyeLink demo's in its main distribution. You'll still need the developer toolkit (SDK) to use, but do not need it to see example code in PsychHardware -> EyelinkToolbox -> EyelinkDemos -> SR-ResearchDemos. A description of these demos is also on the SRR forum

Also MRRC notes on Psychtoolbox, namely regarding timestamp recording.

For for Debian Trixie (13), as of 2025-09, ️⚠️ sr-research.com's pipy hosted pylink is not C ABI compatible with python 3.13. Use uv to create a 3.10 virtual environment.

cd your-task-dir/
uv python install 3.10
uv python pin 3.10
uv venv --python 3.10
uv pip install --index-url=https://pypi.sr-research.com sr-research-pylink
uv pip install psychopy

Linux SDK install is documented for ubuntu on the SRR forums. For Debian bookworm (12.11), installing the SDK might look like like below. Test 2025-05.

# add eyelink repo
echo 'deb [arch=amd64] https://apt.sr-research.com SRResearch main' |
  sudo tee /etc/apt/sources.list.d/eyelink.list
sudo apt-key adv --fetch-keys https://apt.sr-research.com/SRResearch_key

# libjpeg8 dependency
wget https://archive.debian.org/debian/pool/main/libj/libjpeg8/libjpeg8_8b-1_amd64.deb
sudo dpkg -i libjpeg8_8b-1_amd64.deb


# get binaries
sudo apt update
sudo apt install eyelink-display-software

# get pylink
pip install --index-url=https://pypi.sr-research.com sr-research-pylink