08-27-2020, 03:57 PM
Psychology Software Tools' E-Prime suite can be integrated with the full line of EyeLink systems in one of two ways. The first option is the E-Prime Extension for EyeLink, which enables direct access to all EyeLink eye-trackers using dedicated E-Prime Objects and allows for relatively effortless integration with Data Viewer. Please note that the Extensions are only available for E-Prime 3 and require the purchase of a license key.
The second option will work with both E-Prime 3 and E-Prime 2 (we no longer officially support the original E-Prime, though the legacy examples we provide still work with that software), and is what will be discussed in this post. This option uses E-Prime user script and inline scripts to handle integration through function calls to the EyeLink COM Interface API. This functionality requires the EyeLink Developers Kit to be installed on the same computer as E-Prime, but is otherwise completely integrated within your E-Prime script without any special toolboxes or other packages. The example scripts provided with the EyeLink Developers Kit (discussed below) should help minimize the effort of adding EyeLink integration to your projects.
Installation Instructions:
Testing your installation:
To test your installation and make sure everything works, please try running one of the E-Prime Examples (see below) for your version of E-Prime. These examples will have been automatically installed with the EyeLink Developers Kit and can be found at Windows Start menu -> All Programs -> SR Research -> EyeLink Examples -> E-Prime Examples. Running any of the scripts in E-Studio should allow you to connect to the tracker and calibrate, validate, and record data. If the script runs without error then your installation was successful. If you encounter errors, please see the common troubleshooting steps listed below.
Important Notes and Troubleshooting:
E-Prime Templates/Example Projects:
The EyeLink Developers Kit for Windows includes Example scripts to illustrate how you can integrate the EyeLink system into your E-Prime project. You can find these projects in the Windows Start menu -> All Programs -> SR Research -> EyeLink Examples -> E-Prime Examples directory after you have installed the Eyelink Developers Kit on your system.
Below is a table of contents describing each of the demos included in the SR-ResearchDemo folder (note there are individual versions of each example for E-Prime 2 and E-Prime 3):
Note all examples contain handling for the E-Prime soft-quit key combination of ctrl-shift. You can press these keys together to cleanly exit a project mid-run, allowing for proper shut down and transfer of the .edf. You may need to wait for the end of the current trial for the shut down to trigger.
Copying the User Script
The EyeLink examples all rely on various functions and global variables that are defined in the project's User Script (ALT+5 in E-Prime 2, ALT+7 in E-Prime 3). It is vital to copy the contents of the script to any new EyeLink integrated project for Camera Setup, Drift correction, and other sub-functions to work properly. Please make sure that you copy the contents of the User Script from the Examples to any new EyeLink integrated projects to ensure proper functionality.
EyeLink Data Viewer Messaging Commands and Syntax
Throughout the course of your Experiment, it will be critical to log the timing of events within your task and to log the values of dependent variables. This can be done using the following functions via inline script:
Messages sent with this command will be logged into the EDF in <1ms from when the SendMessage command was executed in your script. So it's important that these messages are sent following any important events so that we can later use them in our data analysis. Unfortunately, unless you program your presentation stimuli in E-Basic/inline scripting, then sending messages that are time-locked with the onset of the stimulus is not possible due to the limitations of E-Prime. To overcome this we can add an offset to our messages to backstamp them to the appropriate time as reported by E-Prime. The following syntax will work with Data Viewer's Protocol for EyeLink Data to Viewer Integration, but can also be adopted for use in custom programmed analysis tools.
If a message starts with an integer then Data Viewer will automatically backstamp that message by the number of milliseconds specified by that integer. You can use this feature to backstamp a message by calculating the difference between when the event occurred and when the message was sent. The following snippet of code illustrates how to backstamp the message that should correspond to the onset of a slide by sending it in an inline script after the slide has completed.
As you can see in the code above, we calculated the offset between the current time and the time the event occurred, in milliseconds, and use that as our offset value. Likewise, it's important to note that the offset be separated from the text of your message by a single space character, without this it will not be able to properly segment the message from the offset value. This feature can be combined with any of the other specially formatted messages that conform to the Data Viewer messaging protocols. 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
A readme.txt file containing more detailed information about using E-Prime with EyeLink eye trackers can be found at:
C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\E-Prime
The EyeLink COM Interface Manual documents all of the EyeLink functions available to E-Prime. It's important to note that the syntax for some of the commands in the manual may differ from how they are implemented in E-Prime, as E-Prime follows it's own syntax rules. That said, E-Prime interacts directly with the Windows COM Interface to execute these functions, so all available functions and data types of the EyeLink API for E-Prime will be documented in this manual.
EyeLink COM Interface Manual (Windows Start menu -> All Programs -> SR Research -> Manuals -> EyeLink COM Interface Manual)
The EyeLink COM Interface API is a wrapper for our C API, so if you find any of the documentation lacking, you may also find the EyeLink Programmer's Guide helpful in filling in some of the gaps. 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, but much of the functionality should be analogous.
The second option will work with both E-Prime 3 and E-Prime 2 (we no longer officially support the original E-Prime, though the legacy examples we provide still work with that software), and is what will be discussed in this post. This option uses E-Prime user script and inline scripts to handle integration through function calls to the EyeLink COM Interface API. This functionality requires the EyeLink Developers Kit to be installed on the same computer as E-Prime, but is otherwise completely integrated within your E-Prime script without any special toolboxes or other packages. The example scripts provided with the EyeLink Developers Kit (discussed below) should help minimize the effort of adding EyeLink integration to your projects.
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 and make sure everything works, please try running one of the E-Prime Examples (see below) for your version of E-Prime. These examples will have been automatically installed with the EyeLink Developers Kit and can be found at Windows Start menu -> All Programs -> SR Research -> EyeLink Examples -> E-Prime Examples. Running any of the scripts in E-Studio should allow you to connect to the tracker and calibrate, validate, and record data. If the script runs without error then your installation was successful. If you encounter errors, please see the common troubleshooting steps listed below.
Important Notes and Troubleshooting:
- If you are running E-Prime 3, you will need to run at least E-Prime 3 version 3.0.3.80 for proper compatibility.
- If you are running E-Prime 3 under Windows 10, you may need to explicitly specify a requested refresh rate in the E-Prime project settings (Edit -> Experiment -> Devices -> Display).
- If you see the error: “Error 432: File name or class name not found during OLE Automation operation” then the EyeLink Developers Kit has not been properly installed. Please download and install/reinstall the latest version.
- If the project freezes immediately before or after camera setup, please try adjusting the useSuspend and/or usePriority variables in the elConnect inline script (see below in this section for a description of these variables).
- elCameraSetup (default value 1): This variable allows you to choose between running the project with the withCam (GDICal) or noCam(busyCal) display methods. If set to 1, withCam will be used. If set to 2, busyCal will be used. These two methods affect the handling of camera setup (calibration/validation) and drift check drawing. Using withCam will allow you to transfer the camera image to the display PC when in Camera Setup mode, whereas noCam will not. The withCam handler should work best, but for some computers/setups may introduce a small delay when entering or exiting camera setup. Should this be the case for your system, busyCal can be used to mitigate the delay. If using withCam, you should ensure that the Windows desktop resolution is the same as the requested resolution of your project script before running.
- useSuspend (default value 0): Controls whether device suspend and resume calls are used. If using Windows 7 or earlier, set to 1. Otherwise, leave at 0. If issues are observed with experiment freezing, try switching this value.
- usePriority (default value 0): Controls whether thread priority changing calls are used. If using Windows 7 or earlier, set to 1. Otherwise, leave at 0. If issues are observed with experiment freezing, try switching this value. If both values lead to freezing, please set to 2 -- this enables all but the last thread priority call at the end of the elConnect script, which was seen to cause issues on a small number of Windows 10 systems.
E-Prime Templates/Example Projects:
The EyeLink Developers Kit for Windows includes Example scripts to illustrate how you can integrate the EyeLink system into your E-Prime project. You can find these projects in the Windows Start menu -> All Programs -> SR Research -> EyeLink Examples -> E-Prime Examples directory after you have installed the Eyelink Developers Kit on your system.
Below is a table of contents describing each of the demos included in the SR-ResearchDemo folder (note there are individual versions of each example for E-Prime 2 and E-Prime 3):
| Templates | Description |
|---|---|
| EyeLink_Picture | Example of basic integration with a general image viewing paradigm. |
| EyeLink_PictureMRI | EyeLink_Picture example adapted for use in an MRI environment. Here we use static trial durations and block-level recording to allow for predictable session lengths, and include a screen at the beginning of each block that waits for a scanner-provided TR pulse. |
| EyeLink_SimpleCanvasSave | Example of basic integration with a single line text paradigm. Also shows how to save the displayed trial image (useful if you are generating text stimuli on the fly instead of using screen images). |
| EyeLink_Video | Shows how to run a project that displays video trials. Contains code to log the presentation time of each video frame to the .edf for Data Viewer playback, and optionally log the same to a text file to allow for interest period specification based on frame numbers in Data Viewer (to enable the text file logging, set the logFrames variable at the top of the stopRecording inline script to True). |
| EyeLink_FixWindowFastSamples | Example showing how to poll the reported eye gaze location from the tracker to set up a gaze-based trigger. Here we use this to wait for gaze to be within a defined area for a specific duration before presenting the trial's image stimulus. Includes recalibration and recycling of the current trial if the gaze check is not completed within a given time frame, or if the ESC key is pressed prior to passing the gaze check. |
| EyeLink_GCFastSamples | Example of including a gaze-contingent display item (a filled white circle) overlaid on a background image. Polls the reported eye gaze location from the tracker to continuously update the circle location in real-time. |
| EyeLink_SaccadeEvent | Shows how to poll eye events (e.g., saccades) for use as a response trigger. Here, trials are completed by shifting gaze to a green box presented at a given screen location. |
Note all examples contain handling for the E-Prime soft-quit key combination of ctrl-shift. You can press these keys together to cleanly exit a project mid-run, allowing for proper shut down and transfer of the .edf. You may need to wait for the end of the current trial for the shut down to trigger.
Copying the User Script
The EyeLink examples all rely on various functions and global variables that are defined in the project's User Script (ALT+5 in E-Prime 2, ALT+7 in E-Prime 3). It is vital to copy the contents of the script to any new EyeLink integrated project for Camera Setup, Drift correction, and other sub-functions to work properly. Please make sure that you copy the contents of the User Script from the Examples to any new EyeLink integrated projects to ensure proper functionality.
EyeLink Data Viewer Messaging Commands and Syntax
Throughout the course of your Experiment, it will be critical to log the timing of events within your task and to log the values of dependent variables. This can be done using the following functions via inline script:
Code:
Dim myMessage as String
myMessage = 'some text';
tracker.sendMessage myMessageMessages sent with this command will be logged into the EDF in <1ms from when the SendMessage command was executed in your script. So it's important that these messages are sent following any important events so that we can later use them in our data analysis. Unfortunately, unless you program your presentation stimuli in E-Basic/inline scripting, then sending messages that are time-locked with the onset of the stimulus is not possible due to the limitations of E-Prime. To overcome this we can add an offset to our messages to backstamp them to the appropriate time as reported by E-Prime. The following syntax will work with Data Viewer's Protocol for EyeLink Data to Viewer Integration, but can also be adopted for use in custom programmed analysis tools.
If a message starts with an integer then Data Viewer will automatically backstamp that message by the number of milliseconds specified by that integer. You can use this feature to backstamp a message by calculating the difference between when the event occurred and when the message was sent. The following snippet of code illustrates how to backstamp the message that should correspond to the onset of a slide by sending it in an inline script after the slide has completed.
Code:
Dim offset As Long
offset = Clock.ReadMillisec - mySlide.OnsetTime
myMessage= offset & " mySlide_Onset"
tracker.sendMessage myMessageAs you can see in the code above, we calculated the offset between the current time and the time the event occurred, in milliseconds, and use that as our offset value. Likewise, it's important to note that the offset be separated from the text of your message by a single space character, without this it will not be able to properly segment the message from the offset value. This feature can be combined with any of the other specially formatted messages that conform to the Data Viewer messaging protocols. 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
A readme.txt file containing more detailed information about using E-Prime with EyeLink eye trackers can be found at:
C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\E-Prime
The EyeLink COM Interface Manual documents all of the EyeLink functions available to E-Prime. It's important to note that the syntax for some of the commands in the manual may differ from how they are implemented in E-Prime, as E-Prime follows it's own syntax rules. That said, E-Prime interacts directly with the Windows COM Interface to execute these functions, so all available functions and data types of the EyeLink API for E-Prime will be documented in this manual.
EyeLink COM Interface Manual (Windows Start menu -> All Programs -> SR Research -> Manuals -> EyeLink COM Interface Manual)
The EyeLink COM Interface API is a wrapper for our C API, so if you find any of the documentation lacking, you may also find the EyeLink Programmer's Guide helpful in filling in some of the gaps. 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, but much of the functionality should be analogous.