Psychology Software Tools' E-Prime suite can be integrated with the full line of EyeLink systems in two ways.
The first option, the E-Prime Extension for EyeLink, provides direct access to all EyeLink eye-trackers using dedicated E-Prime Objects. This allows for relatively effortless integration with Data Viewer. Please note that the Extension is only available for E-Prime 3 and requires a license from PST.
The second option, which is the focus of this post, works with both E-Prime 3 and E-Prime 2. This method uses E-Prime's user and inline scripts to handle integration through function calls to the EyeLink COM Interface API. It requires the EyeLink Developers Kit to be installed on the same computer as E-Prime but is otherwise fully integrated within your E-Prime script without special toolboxes or packages. The example scripts provided with the Developers Kit should help minimize the effort of adding EyeLink integration to your projects.
(Note: While we no longer officially support the original E-Prime (1.x). However, the legacy examples we provide still work with that software.)
Installation Instructions:
Testing your installation:
To test your installation, run one of the E-Prime examples that were automatically installed with the EyeLink Developers Kit.
You can find them here:
Running any of these scripts in E-Studio should allow you to connect to the tracker, calibrate, validate, and record data. If a script runs without errors, your installation was successful. If you encounter any issues, please see the troubleshooting steps below.
Important Notes & Troubleshooting
elConnect Script Settings
Each example's elConnect script contains important settings. While the default values work for most computers, you may need to adjust them. The most important variables are:
E-Prime Templates/Example Projects:
The EyeLink Developers Kit for Windows includes several example scripts to show you how to integrate the EyeLink system with your E-Prime project. After installing the kit, you can find these examples in the following directory:
Below is a description of each demo located in the SR-ResearchDemo folder. Note that each example has separate versions for E-Prime 2 and E-Prime 3.
Note: All examples include handling for E-Prime's "soft-quit" command (Ctrl+Shift). You can press these keys to safely exit an experiment mid-run. This ensures the eye-tracking data file (.edf) is properly saved and transferred. You may need to wait until the end of the current trial for the shutdown to occur.
Copying the User Script
The EyeLink example projects define essential functions and variables in the User Script. You can access this script by pressing ALT+7 in E-Prime 3 or ALT+5 in E-Prime 2.
It is critical to copy the entire contents of this User Script from an example into any new EyeLink project you create. Without this script, essential functions like Camera Setup and Drift Correction will not work.
EyeLink Data Viewer Messaging Commands and Syntax
To analyze your eye-tracking data, it's critical to log event timings and dependent variables from your task. You can do this by sending messages from an E-Prime inline script to the EyeLink data file (.edf).
Sending a Basic Message
The tracker.sendMessage command logs a text message in the .edf file with high precision (typically within 1ms of execution). For accurate analysis, you should call this command immediately after a critical event occurs in your trial via inline script.
Here's a basic example:
Correcting for Timing Delays with Backstamping
Unfortunately, due to E-Prime's structure, you often can't send a message at the exact moment a stimulus appears on screen. The message is usually sent after the stimulus presentation is complete, creating a timing delay.
To solve this, we use a technique called backstamping. You calculate the delay between the event (e.g., mySlide.OnsetTime) and the current time, and then add that delay in milliseconds to the beginning of the message string.
Data Viewer automatically recognizes this number and subtracts it from the message's timestamp, effectively "backstamping" the message to the correct moment in time.
The following code, placed in an inline script after a slide has been shown, calculates the delay and sends a correctly timestamped message.
Crucial Syntax: The offset number and the message text must be separated by a single space (e.g., "150 myMessage"). Without this space, Data Viewer cannot parse the offset correctly.
Additional Resources
This backstamping feature can be combined with other Data Viewer messaging protocols. For a complete guide on formatting these messages, please see the following resources:
Documentation
For more detailed information, please refer to the following documentation.
The first option, the E-Prime Extension for EyeLink, provides direct access to all EyeLink eye-trackers using dedicated E-Prime Objects. This allows for relatively effortless integration with Data Viewer. Please note that the Extension is only available for E-Prime 3 and requires a license from PST.
The second option, which is the focus of this post, works with both E-Prime 3 and E-Prime 2. This method uses E-Prime's user and inline scripts to handle integration through function calls to the EyeLink COM Interface API. It requires the EyeLink Developers Kit to be installed on the same computer as E-Prime but is otherwise fully integrated within your E-Prime script without special toolboxes or packages. The example scripts provided with the Developers Kit should help minimize the effort of adding EyeLink integration to your projects.
(Note: While we no longer officially support the original E-Prime (1.x). However, the legacy examples we provide still work with that software.)
Installation Instructions:
- Configure your Display PC's network connection to communicate with the EyeLink Host PC
- Install the Latest version of E-Studio
- Install the Latest version of the EyeLink Developers Kit for Windows
Testing your installation:
To test your installation, run one of the E-Prime examples that were automatically installed with the EyeLink Developers Kit.
You can find them here:
- Windows Start Menu > All Programs > SR Research > EyeLink Examples > E-Prime Examples
Running any of these scripts in E-Studio should allow you to connect to the tracker, calibrate, validate, and record data. If a script runs without errors, your installation was successful. If you encounter any issues, please see the troubleshooting steps below.
Important Notes & Troubleshooting
- E-Prime 3 Version: If you use E-Prime 3, you must have version 3.0.3.80 or newer for proper compatibility.
- Windows 10 Refresh Rate: When using E-Prime 3 on Windows 10, you may need to specify a requested refresh rate in your project settings: Edit > Experiment > Devices > Display.
- "Error 432": If you see the error, "File name or class name not found during OLE Automation operation," the EyeLink Developers Kit was not installed correctly. Please download and reinstall the latest version.
- Project Freezes: If the project freezes just before or after camera setup, try adjusting the useSuspend and usePriority variables in the elConnect inline script (details below).
elConnect Script Settings
Each example's elConnect script contains important settings. While the default values work for most computers, you may need to adjust them. The most important variables are:
- elCameraSetup (Default: 1)
This variable controls how the camera setup (calibration/validation) and drift check are drawn.- Set to 1 (withCam / GDICal): This method transfers the camera image to the display PC during setup. It works best on most systems but may cause a slight delay when entering or exiting camera setup mode. If you use this option, ensure your Windows desktop resolution matches the resolution in your E-Prime project.
- Set to 2 (busyCal / noCam): This method does not transfer the camera image. Use this option to mitigate delays if you experience them with the withCam method.
- Set to 1 (withCam / GDICal): This method transfers the camera image to the display PC during setup. It works best on most systems but may cause a slight delay when entering or exiting camera setup mode. If you use this option, ensure your Windows desktop resolution matches the resolution in your E-Prime project.
- useSuspend (Default: 0)
This controls whether device suspend and resume calls are used during setup.- Set to 1 if using Windows 7 or earlier.
- Set to 0 for newer operating systems.
- If the experiment freezes, try switching this value (e.g., from 0 to 1).
- Set to 1 if using Windows 7 or earlier.
- usePriority (Default: 0)
This controls whether thread priority changing calls are used.- Set to 1 if using Windows 7 or earlier.
- Set to 0 for newer operating systems.
- If the experiment freezes, try switching this value. If freezing persists, set the value to 2. This enables all thread priority calls except for the final one, which has been known to cause issues on a small number of Windows 10 systems.
- Set to 1 if using Windows 7 or earlier.
E-Prime Templates/Example Projects:
The EyeLink Developers Kit for Windows includes several example scripts to show you how to integrate the EyeLink system with your E-Prime project. After installing the kit, you can find these examples in the following directory:
- Windows Start Menu > All Programs > SR Research > EyeLink Examples > E-Prime Examples
Below is a description of each demo located in the SR-ResearchDemo folder. Note that each example has separate versions for E-Prime 2 and E-Prime 3.
| Templates | Description |
|---|---|
| EyeLink_Picture | A basic example of EyeLink integration for a simple image-viewing task. |
| EyeLink_PictureMRI | An adaptation of the EyeLink_Picture example designed for an MRI environment. It uses static trial durations and waits for a scanner TR pulse before starting each block. |
| EyeLink_SimpleCanvasSave | A basic example using single-line text stimuli. It also shows how to save a screenshot of the displayed trial, which is useful for stimuli generated on the fly. |
| EyeLink_Video | Demonstrates how to run a project that displays video trials. The code logs the presentation time of each video frame to the EDF file for accurate playback in Data Viewer. |
| EyeLink_FixWindowFastSamples | Shows how to create a gaze-based trigger. In this example, an image is only presented after the participant holds their gaze within a defined area for a specific duration. It also includes code to recalibrate or recycle a trial if the gaze check fails. |
| EyeLink_GCFastSamples | An example of a gaze-contingent display. It continuously polls the eye's location to update an object's position on the screen in real-time. |
| EyeLink_SaccadeEvent | Shows how to use eye events, like saccades, as a response trigger. Here, a trial is completed when the participant shifts their gaze to a target box. |
Note: All examples include handling for E-Prime's "soft-quit" command (Ctrl+Shift). You can press these keys to safely exit an experiment mid-run. This ensures the eye-tracking data file (.edf) is properly saved and transferred. You may need to wait until the end of the current trial for the shutdown to occur.
Copying the User Script
The EyeLink example projects define essential functions and variables in the User Script. You can access this script by pressing ALT+7 in E-Prime 3 or ALT+5 in E-Prime 2.
It is critical to copy the entire contents of this User Script from an example into any new EyeLink project you create. Without this script, essential functions like Camera Setup and Drift Correction will not work.
EyeLink Data Viewer Messaging Commands and Syntax
To analyze your eye-tracking data, it's critical to log event timings and dependent variables from your task. You can do this by sending messages from an E-Prime inline script to the EyeLink data file (.edf).
Sending a Basic Message
The tracker.sendMessage command logs a text message in the .edf file with high precision (typically within 1ms of execution). For accurate analysis, you should call this command immediately after a critical event occurs in your trial via inline script.
Here's a basic example:
Code:
Dim myMessage As String
myMessage = "IMAGE_ONSET"
tracker.sendMessage myMessageCorrecting for Timing Delays with Backstamping
Unfortunately, due to E-Prime's structure, you often can't send a message at the exact moment a stimulus appears on screen. The message is usually sent after the stimulus presentation is complete, creating a timing delay.
To solve this, we use a technique called backstamping. You calculate the delay between the event (e.g., mySlide.OnsetTime) and the current time, and then add that delay in milliseconds to the beginning of the message string.
Data Viewer automatically recognizes this number and subtracts it from the message's timestamp, effectively "backstamping" the message to the correct moment in time.
The following code, placed in an inline script after a slide has been shown, calculates the delay and sends a correctly timestamped message.
Code:
Dim offset As Long
Dim myMessage As String
' Calculate the delay since the slide appeared
offset = Clock.ReadMillisec - mySlide.OnsetTime
' Create the message string with the offset
myMessage = offset & " mySlide_Onset"
' Send the backstamped message
tracker.sendMessage myMessageCrucial Syntax: The offset number and the message text must be separated by a single space (e.g., "150 myMessage"). Without this space, Data Viewer cannot parse the offset correctly.
Additional Resources
This backstamping feature can be combined with other Data Viewer messaging protocols. For a complete guide on formatting these messages, please see the following resources:
- Webinar: EyeLink Data Viewer Integration Messaging Protocol
- Manual: Data Viewer User Manual (accessible via Help > Contents), under the section "Protocol for EyeLink Data to Viewer Integration."
Documentation
For more detailed information, please refer to the following documentation.
- readme.txt File
This file contains detailed information specifically about using E-Prime with EyeLink eye trackers.- C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\E-Prime
- EyeLink COM Interface Manual
This is the primary manual documenting all the EyeLink functions and data types available to E-Prime. Since E-Prime interacts directly with this interface, it is your most important resource.- Windows Start Menu > All Programs > SR Research > Manuals > EyeLink COM Interface Manual
- EyeLink Programmer's Guide
This is a more advanced guide for our core C API. If you find the COM Interface Manual is missing details, this guide can help fill in the gaps regarding core functions and data structures. The functionality will be analogous, even if the syntax differs.
Important Note on Syntax: E-Prime has its own syntax rules for calling functions. Because of this, the exact code for some commands in your E-Prime script may look different from the examples provided in the manuals.