====== EyeLink Task Integration ====== This page describes how to interact with the [[hardware:eyetracking:eyelink|EyeLink Tracker]] from your task/code -- start, stop, annotate with triggers, messages. The [[hardware:eyetracking:eyelink:analysis|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 * [[https://www.sr-research.com/support/thread-246.html|mouse simulation mode (#246)]] but only on the "HostPC" (need access to eye tracking computer) * ''dummy'' mode (''EyeLink(ip=None)'', [[https://www.sr-research.com/support/thread-89.html|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. ===== From SR Research ===== SR Research provides EPrime, python ([[:mr:task:psychopy|Psychopy]]), and matlab ([[:mr:task:psychtoolbox|Psychtoolbox]]) examples in the SDK folder. Downloading requires forum registration (free). All the task PC download links are curated [[https://www.sr-research.com/support/forum-3.html|on the forum (#3)]] and under [[https://www.sr-research.com/support-options/learning-resources/|learning resources]]. The particularly useful downloads are [[https://www.sr-research.com/support/thread-13.html|SDK]] and [[https://www.sr-research.com/support/thread-8291.html|pylink]] (pyschopy) . The SDK includes examples for matlab/octave, eprime, and psychopy as well as some compiled exe examples. {{.:pasted:20251013-130151.png?x50|}} SRResearch also [[https://www.sr-research.com/support/thread-7525.html|provides a plugin (thread #7525)]] for psychopy's drag-and-drop "builder" GUI. Eprime documentation can be found on [[https://www.sr-research.com/support/thread-50.html|thread-50]] SRR provides video tutorials for developing in * [[https://www.youtube.com/watch?v=GjHZjgDbedQ|📺 psychtoolbox/MATLAB]] * [[https://www.youtube.com/watch?v=1tLJHVktrEk|📺 psychopy/python]] [[https://www.sr-research.com/support/attachment.php?aid=67|Programmers Guide]] ({{ :hardware:eyetracking:eyelink:eyelinkprogrammers_guide.pdf|}}) from [[https://www.sr-research.com/support/thread-185.html|thread #185]] includes annotated code examples of "templates" and sections like "Useful EyeLink Commands" ({{:hardware:eyetracking:eyelink:eyelinkprogrammers_guide.pdf#page=173|pg 173}}) and "Function List" ({{:hardware:eyetracking:eyelink:eyelinkprogrammers_guide.pdf#page=189|pg 189}}). Look here for dense reference of all programmable features. The Data Viewer Messaging Protocol [[https://www.sr-research.com/support/showthread.php?tid=60|forum thread (#60)]] ({{ :hardware:eyetracking:eyelink:dataviewerintegrationmessagingprotocol_retrived20509222.pdf|local copy}}) maybe be informative. The PPT there includes references to ''TRIALID'', ''!V TRIAL_VAR'', ''BUTTON_PRESS'', etc ===== Examples ===== A demo eye tracking experiment can be found on [[https://github.com/NPACore/tangle-eye/blob/main/eyelinkdemo.py|eyelinkdemo.py]], part of [[https://github.com/NPACore/tangle-eye/]] Tasks using the EyeLink at the UPitt include * [[https://github.com/NPACore/mri-tasks/|tower of london in EPrime]] * [[https://github.com/LabNeuroCogDevel/lncdtask|anti saccade in psychopy]] * [[https://github.com/LabNeuroCogDevel/RingRewardEP|anti saccade in EPrime]] The [[https://github.com/LabNeuroCogDevel/lncdtask|lncd task]] python package includes [[https://github.com/LabNeuroCogDevel/lncdtask/blob/main/lncdtask/pylink_help.py|pylink_help.py]] to wrap around common functions. Of those, ''[[https://github.com/LabNeuroCogDevel/lncdtask/blob/main/lncdtask/pylink_help.py#L21|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()'' ==== Minimal eye task ==== Here is a minimal exercise of key EyeLink commands using [[https://github.com/LabNeuroCogDevel/lncdtask/blob/main/lncdtask/pylink_help.py|pylink_help]] to wrap the SDK ''sendMessage'' and ''sendCommand'' commands. 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() === lncdtask install === 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") {{.:pasted:20250922-145205.png?300}} ===== Developing ===== * use ''dummy''/''ip=None'' to run task code without the actual tracker. More on [[https://www.sr-research.com/support/thread-89.html|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 ===== Matlab/psychtoolbox ===== Psychtoolbox includes EyeLink demo's in its main distribution. You'll still need the developer toolkit ([[https://www.sr-research.com/support/thread-13.html|SDK]]) to use, but do not need it to see example code in ''[[https://github.com/Psychtoolbox-3/Psychtoolbox-3/tree/master/Psychtoolbox/PsychHardware/EyelinkToolbox|PsychHardware -> EyelinkToolbox -> EyelinkDemos -> SR-ResearchDemos]]''. A [[https://www.sr-research.com/support/thread-49.html|description of these demos is also on the SRR forum]] Also MRRC notes on [[mr:task:psychtoolbox]], namely regarding timestamp recording. ===== Debian/psychopy ===== ==== Debian 13 ==== For for Debian Trixie (13), as of 2025-09 /* 2025-09-00 */, ️⚠️ sr-research.com's pipy hosted ''pylink'' is not C ABI compatible with python 3.13. Use ''[[https://docs.astral.sh/uv/|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 ==== Debian 12 ==== Linux SDK install is [[https://www.sr-research.com/support/docs.php?topic=linuxsoftware|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