SR Support Forum   ›   EyeLink Developers Kit - Linux Installation

EyeLink Software for Linux

Overview

The documentation below describes software support provided by SR Research for EyeLink users who are working in Linux. Currently we offer Linux support for the EyeLink Developers Kit and our data analysis software, Data Viewer.

The Developers Kit must be installed if you want to interface with EyeLink systems through scripts written in C/Python and other supported programming languages, or via third-party stimulus presentation solutions such as Psychtoolbox and PsychoPy. Data Viewer is a powerful tool for visualizing and processing .edf EyeLink Data Files.

Features

EyeLink Data Viewer

EyeLink Developers Kit

  • Provides the application programming interface (API) and related resources for integrating with SR Research eye tracking hardware in supported software environments:
    • Sample code/projects to demonstrate EyeLink integrations in supported environments
    • Dependencies required for using EyelinkToolbox (Psychtoolbox) in MATLAB
    • C API libraries for C/C++ development
    • Pylink libraries for Python development
    • edf2asc (CLI tool) to convert .edf files to ASCII text files
    • EDFConverter - Graphical user interface for the CLI edf2asc tool
    • Documentation for the supported development environments

Compatibility

Linux distributions

We provide EyeLink Developers Kit and EyeLink DataViewer support for the current long-term support (LTS) releases of Ubuntu Linux - currently Ubuntu 18.04 (Bionic Beaver) and Ubuntu 20.04 (Focal Fossa).

Our software repositories are configured to provide Debian packages built for these Ubuntu distributions, but they may also be compatible with other Debian-based Linux distributions.

Please contact us at support@sr-research.com if you require assistance with non-debian distributions such as CentOS (now AlmaLinux), Fedora or, RedHat.

Linux architectures

Our C API libraries and Data Viewer are currently supported on both 32-bit and 64-bit architectures. The support for some software environments (e.g. Python) in Debian/Ubuntu Linux is evolving at a fast pace and in the future it is likely our Linux software will support only 64-bit compatible PC architectures.

We may be able to provide support in an experimental capacity for other architectures and platforms (e.g. Raspberry Pi, NVIDIA Jetson, armv7l, aarch64). Please contact us at support@sr-research.com if you have any such requests.

Configuring SR Research Software Repository

For Ubuntu LTS

The following instructions should work on fresh installations of Ubuntu 18.04.5 or 20.04.1

1 - Ensure that Canonical's universe repository is enabled:

           If you're unsure whether your Ubuntu installation has the universe repository enabled, you can check as follows:

Desktop Method:

               Open the desktop launcher, search for Software & Updates and open the app.


Ubuntu 18.04 Software & Updates icon

Ubuntu 20.04 Software & Updates icon

               In the Ubuntu Software tab, check that Community-maintained free and open-source software (universe) is checked and enabled:

Terminal Method:

               You must first enable Canonical's universe repository, before installing the EyeLink Developers Kit for Linux: 

sudo add-apt-repository universe
sudo apt update

2 - Ensure your system trusts common Certificate Authorities

Terminal Method:

               Install and update the ca-certificates package so the Linux package manager trusts the SSL certificate used on our domain: 

sudo apt update
sudo apt install ca-certificates

3 - Add the SR Research Software Repository signing key

Desktop Method:

               First download the SR Research signing key from the following URL: https://apt.sr-research.com/SRResearch_key

               Next, open the desktop launcher, search for Software & Updates, and open the app.


Ubuntu 18.04 Software & Updates icon

Ubuntu 20.04 Software & Updates icon

               From the Authentication tab, click the Import Key File... button and the SRResearch_key downloaded in the previous step. You'll then see our repository signing key in the list.


Ubuntu 18.04 Software & Updates - Authentication icon

Ubuntu 20.04 Software & Updates - Authentication icon

Terminal Method:

           Our debian package repository is signed, and you will first have to add the public key as follows:

sudo apt-key adv --fetch-keys https://apt.sr-research.com/SRResearch_key

4 - Add our repository URL, and update the package list

Desktop Method:

               Open the desktop launcher, search for Software & Updates, select the Other Software tab, then click the Add button and enter

deb [arch=amd64] https://apt.sr-research.com SRResearch main

as shown here:

Terminal Method:
sudo add-apt-repository 'deb [arch=amd64] https://apt.sr-research.com SRResearch main'
sudo apt update

Installing SR Research Software

For Ubuntu LTS

Terminal Method:

               EyeLink Developers Kit

sudo apt install eyelink-display-software

               EyeLink Data Viewer

sudo apt install eyelink-dataviewer

Overview of the Installed Resources - EyeLink Developers Kit

The eyelink-display-software package is a meta-package, and installing will in turn install the related dependencies from our software repository. The complete set of these installed packages together comprise the EyeLink Developers Kit for Linux. The packages are described in more detail below.

Track -- A demo tracking app

The Track demo tracking application installs to

/usr/bin/track

and can be launched from the command line, or from the desktop launcher:

               We provide two utilities for handling and converting EyeLink Data Files (.edf) to ASCII text files. A third solution is also available for developing custom C/C++ applications that handle .edf files, which is discussed in a following section of this documentation. This section discusses only the tools that can be installed and are ready-to-use immediately thereafter.

Tools & Utilities -- Converting .edf to ASCII text files

               We provide two utilities for handling and converting EyeLink Data Files (.edf) to ASCII text files. A third solution is also available for developing custom C/C++ applications that handle .edf files, which is discussed in a following section of this documentation. This section discusses only the tools that can be installed and are ready-to-use immediately thereafter.

Command-line edf2asc utility

                       The command-line version of our edf2asc utility is installed with the edf2asc package. This tool installs to

/usr/bin/edf2asc    # static build, does not require EDF API .so library
/usr/bin/edf2asc_s  # dynamic build, depends on and requires EDF API .so

                       Usage syntax:

edf2asc [options] <input .edf file>
edf2asc someFile.edf      # example syntax, using default options

                       To see the complete set of supported command-line syntax options when running this utility in a terminal session, run edf2asc without any arguments/parameters:

edf2asc       # which displays the following (truncated) output
EDF2ASC: EyeLink EDF file -> ASCII (text) file translator
EDF2ASC version 3.1 Linux Mar  9 2017 
(c)1995-2013 by SR Research, last modified Mar  9 2017

USAGE: edf2asc  [options] <input .edf file>
OPTIONS: -p <path> writes output with same name to <path> directory
         -p *.<ext> writes output of same name with new extension
... # many more options follow
Visual EDF2ASC Converter

                       The graphical (GUI) utility that runs in a Desktop environment for converting .edf to ASCII text files is named Visual EDF2ASC Converter, and is provided in the edfconverterlinux package.

                   The application binary and its respective resources are installed into the directory

/usr/bin/EdfConverter/

                       and is typically run from the Desktop Launcher:

C API support

Our C API is comprised of a few dynamic and static libraries, each of which provides different and complimentary functionality. In addition to the following information, related and more generalized EyeLink Developers Kit and API documentation can be found in the EyeLink Programmers Guide hosted online in HTML at https://www.sr-research.com/download/dispdoc/, on our online support forums and access additional information here: EyeLink Developers Kit. Installing the eyelink-display-software package also includes PDF and HTML copies of the EyeLink Programmer's Guide here

/usr/share/EyeLink/UserManuals/EyeLinkProgrammersGuide.pdf
/usr/share/EyeLink/UserManuals/EyeLinkProgrammersGuide-html/index.html

The EyeLink Core library and related header files -- eyelinkcore package -- is minimally required for C/C++ development of custom applications integrating EyeLink functionality that requires a network connection to the EyeLink Host PC and camera when interfacing with the EyeLink system. Besides the development of custom applications, these libraries are also required as runtime dependencies for commonly supported integrations in 3rd party environments, such as pylink for Python, Psychtoolbox & EyelinkToolbox for MATLAB, and other community-developed resources shared online from various EyeLink users. The EyeLink Core library and header files are installed as follows

/usr/lib/x86_64-linux-gnu/libeyelink_core-2.0.so.0.0.1
/usr/lib/x86_64-linux-gnu/libeyelink_core.a
/usr/lib/x86_64-linux-gnu/libeyelink_core.la
/usr/include/EyeLink/eyelink.h
/usr/include/EyeLink/eyetypes.h
/usr/include/EyeLink/eye_data.h

The EyeLink Core Graphics and SDL Util library and related header files -- eyelinkcoregraphics package -- extends the EyeLink Core library and provides SDL v1.2 functionality for developing and runtime dependencies for C/C++ applications using this graphics environment to support Display PC integrations of Camera Setup Mode (e.g. camera image transfer, calibration, validation, drift check/correct, etc) and related features. This package also includes the SDL Util library and related header files that extend the EyeLink Core Graphics functionality, to assist with SDL v1.2 implementations when stimulus display requires other features like text display, gaze contingent cursors, etc. The EyeLink Core Graphics and SDL Util library files are installed as follows

/usr/lib/x86_64-linux-gnu/libeyelink_core_graphics-2.0.so.0.0.1
/usr/lib/x86_64-linux-gnu/libeyelink_core_graphics.a
/usr/lib/x86_64-linux-gnu/libeyelink_core_graphics.la

The SDL v2 version of the Eyelink Core Graphics libraries are installed as

/usr/lib/x86_64-linux-gnu/libeyelink_core_graphics_sdl2-2.0.so.0.0.1
/usr/lib/x86_64-linux-gnu/libeyelink_core_graphics_sdl2.a
/usr/lib/x86_64-linux-gnu/libeyelink_core_graphics_sdl2.la
/usr/lib/libsdl2_util.a

The header files for these Eyelink Core Graphics libraries are installed as

/usr/include/EyeLink/core_expt.h
/usr/include/EyeLink/sdl_expt.h
/usr/include/EyeLink/fontmappings.h
/usr/include/EyeLink/sdl_text_support.h
/usr/include/EyeLink/gazecursor.h

A number of sample projects with .c source files implementing our C API for SDL v1 and v2 applications can be found here

/usr/share/EyeLink/SampleExperiments/sdl
/usr/share/EyeLink/SampleExperiments/sdl2

These example projects include demos for a variaty of concepts, including text/picture display, gaze-contingent feedback (i.e. accessing real-time data over the Ethernet link), etc.

Also included therein are the source files for the SDL v1 and v2 Util libraries are also available and installed to

/usr/share/EyeLink/SampleExperiments/sdl/shared
/usr/share/EyeLink/SampleExperiments/sdl2/shared

A number of Sample Experiments are also available -- eyelink_capi_samples package -- that demonstrate the use of the EyeLink Core and Core Graphics libraries. These C applications include pre-built binaries that are ready to run, as well as source files and a makefile to use for easily testing integrations of our C API support, modifying those template projects to test custom extensions thereof, and adapting code snippets from into more complete custom applications as required. These sample experiments files are installed here

/usr/share/EyeLink/SampleExperiments/

The EDF Access API includes support for developing custom C/C++ applications that directly handle .edf EyeLink Data Files, and is installed with the edfapi package. The EDF Access API documentation is installed to

/usr/share/EyeLink/EDF_Access_API/docs/EDF Access C API user manual.pdf

along with the EDF Access API library and header files

/usr/lib/x86_64-linux-gnu/libedfapi.a
/usr/lib/x86_64-linux-gnu/libedfapi.so
/usr/include/edf.h
/usr/include/edftypes.h
/usr/include/edf_data.h

and also includes C and Java source files for an example project that demonstrates the use of our EDF Access API as it is used for a simplified version of our edf2asc command-line utility, installed here

/usr/share/EyeLink/EDF_Access_API

pylink for Python

Support for 64-bit (x86_64) versions of Python include 2.7, 3.6, 3.7, 3.8 and 3.9 on Linux are included with this EyeLink Developers Kit for Linux. If you are interested in pylink support for Python versions or system architectures other than these, please contact support@sr-research.com with details and we can investigate the feasibility of providing such additional support to match your needs.

     pylink Documentation

/usr/share/EyeLink/SampleExperiments/Python/Getting started with Python and Pylink.pdf
/usr/share/EyeLink/SampleExperiments/Python/Pylink api userguide.pdf
/usr/share/EyeLink/SampleExperiments/Python/examples/README.md

     pylink Installation

A few methods of installation are supported. First and foremose, please check https://pypi.sr-support.com for information about using pip to install pylink from our PyPi package server.

Wheel files for local installation can be found here

/usr/share/EyeLink/SampleExperiments/Python/wheels

We also provide a custom installer script for local installations

/usr/share/EyeLink/SampleExperiments/Python/install_pylink.py

     pylink Sample Projects

/usr/share/EyeLink/SampleExperiments/Python/examples

EyelinkToolbox for MATLAB & Psychtoolbox

Psychtoolbox for MATLAB c.f. http://psychtoolbox.org/ includes the EyelinkToolbox providing support for integrations with EyeLink systems. The EyeLinkToolbox module is open source, and authored by a combination of maintainers from the Psychtoolbox and EyeLink communities, inclduing contributions from SR Research. The version of EyeLink Toolbox resources (included demo projects) included with this EyeLink Developers Kit for Linux and other supported operations systems currently includes more up-to-date versions of the toolbox resources from SR Research as compared with what is distributed in the official Psychtoolbox distributions. Our updates will always have pull-requests submitted for inclusion in the official Psychtoolbox releases. However, copies of our SR Research-specific versions of these EyelinkToolbox resources are included herewith. More specifically, our versions of these EyelinkToolbox resources are sure to include demos and examples following the integration conventions we recommend for using EyeLink systems, which in contrast to some 3rd party maintained materials differ in some respects.

Our EyelinkToolbox resources are installed to

/usr/share/EyeLink/SampleExperiments/MATLAB Psychtoolbox

     EyelinkToolbox Documentation

Online documentation for .m scripts and demo projects, as well as for MEX'd Eyelink(…) functionality wrapping our C API can be found here: https://www.sr-support.com/docs.php?topic=EyelinkToolbox An offline/local HTML version of this documentation is also included with the EyeLink Developers Kit installation, here

/usr/share/EyeLink/SampleExperiments/MATLAB Psychtoolbox/EyelinkToolbox-Documentation.html

     EyelinkToolbox Installation

The complete Psychtoolbox set of directories, sub-directories, and files found in

/usr/share/EyeLink/SampleExperiments/MATLAB Psychtoolbox/Psychtoolbox

is intended to replace the contents of the files and directories they match in your existing Psychtoolbox installation (i.e. at path PsychtoolboxRoot()). Installation can be done manually by copying these directories and files into your PsychtoolboxRoot path, thereafter running <PsychtoolboxRoot>/SetupPsychtoolbox() to apply these changes.

For automated installation we also provide a .m script to run from within MATLAB, so long as you already have an existing Psychtoolbox installation configured. You can run MATLAB, and navigate to the working directory and run this installation script from here

/usr/share/EyeLink/SampleExperiments/MATLAB Psychtoolbox/SetupSREyelinkToolbox.m