The Eye Tribe Tracker detects and tracks gaze coordinates allowing developers to create engaging new user experiences using eye control. The Tracker operates in the device field of view with high precision and frame rate.
The Tracker software is based upon an Open API design that allow client applications to communicate with the underlying Tracker Server to get gaze data. The communication relies on JSON messages asynchronously exchanged via TCP Sockets. Many clients may be connected to the server simultaneously. The relationship between client and server along with underlying dependencies is illustrated in Figure 1.
Figure 1. Architecture Overview
Any programming language capable of opening TCP Sockets and parsing JSON is theoretically able to connect to and interface with a running Tracker Server using the Tracker API. Find full documentation of the communication protocol in the Tracker API section.
Eye Tracking data is delivered over time in frames. The contents of each frame is summarized in the following and described in full detail in the Tracker API.
State of the eye and gaze tracking process. Indicates if a person is currently being tracking in the devices field of view as well as the associated level of detail.
If the tracked gaze is current fixated, the frame will contain information hereof. See basics for an introduction to fixation.
Gaze coordinates are the point on screen that the user is currently looking. Gaze coordinates are defined as pixels in a top-left oriented 2D coordinate system and are available in both raw and smoothed forms. Note that gaze coordinates are only available in a calibrated setup (Calibration). See Figure 2 for visual illustration.
Figure 2. Gaze coordinates in pixels in top-left oriented 2D coordinates system
Pupil coordinates are the position of a tracked persons pupil relative to the Tracker sensor. Pupil coordinates are defined in normalized relative values in a top-left oriented 2D coordinate system. See Figure 3 for visual illustration.
Figure 3. Pupil coordinates in normalized values relative to Tracker device
Through the tracker API, clients are able to tweak the settings of the Tracker Server, perform the calibration process, switch screens in a multi screen setup and more. The Tracker API documentation explains all interfacing option in detail.
A running Tracker Server with no connected clients will be in a dormant state and will not broadcast frames. The Tracker Server will be implicitly running as long as there are clients connected and these clients are sending stay-alive messages, aka. heartbeats, within a server-defined interval. To disconnect, a client may explicitly close its socket connection or simply stop sending heartbeats. The getting frame data tutorial explains the process of sending heartbeats in detail.
This section describes the advanced features of the EyeTribe Server, e.g. how to connect to the server remotely, or how to change the TCP socket port, etc.
The EyeTribe Server can be configured manually to some degree by specifying command line arguments when starting the server. The EyeTribe server can also be configured using a configuration file, see below for details.
Running the server without any arguments will initialize the system using default values. These values have been chosen to be well suited for most users.
Specifying wrong or unsupported parameters will cause the server to fail and inform about the problem. The server will also provide a list of supported parameters.
Using --help or -? parameters will also show the list of supported server parameters.
The default TCP socket port that the EyeTribe Server listens to incoming client requests is 6555. The default port can be modified to cater for special user-defined behavior and environment, for instance when port 6555 is already utilized for another service. Setting the socket port manually is done using the --port=<int> parameter. Value must be in the range from 1024 to 65535. An error will be reported during initialization of the server was not able to bind to the port (e.g. if the port is in use by another application).
By default the server only accepts local connections (same computer/IP). If you want to allow clients from other IP addresses to connect to the server you must specify the --remote=<bool> parameter with the value of true. Only true and false are accepted values.
The EyeTribe server only supports operating one tracking device at a time. Up to 8 supported devices can be present in the system, and any one of these can be utilized by the tracker. The parameter --device=<int> can be used to instruct the EyeTribe Server to utilize a different device than the first, default, device. Setting the device number manually is constrained to a number between 0 and 7. The EyeTribe Server will report an error upon initialization if the device is either not supported or not present.
The EyeTribe Server supports two frame rate modes: 30 and 60 frames per second (fps). The default frame rate is 30 fps. Running in 30 fps will allow for a larger tracking box, whereas the 60 fps mode in nature will be faster but allow for smaller head movements. To set the framerate manually use the --framerate=<int> parameter where the value is constrained to either be 30 or 60 frames per sercond.
Only 30 and 60 are valid values. If other values are specified an error will be reported upon initialization of the EyeTribe Server.
Update: from firmware version 293 and forward a 40 frames per second mode has been added.
The configuration file contains a JSON formatted structure. The config section describes the parameters that can be modified by the user. The same command line parameters supported by the server can be provided in the config file;
{
"config" : {
"device" : 0,
"remote" : false,
"framerate" : 30,
"port" : 6555
}
}
For backwards compatibility reasons the EyeTribe server will try to read a default config file when it starts up without any provided arguments. On Windows OS the default config file is placed in
C:\Users\<current_user>\AppData\Local\EyeTribe\EyeTribe.cfg
If the config file exists the server will apply the settings from it, otherwise the server will initialize itself with the default values.
The EyeTribe server can also be launched and instructed to load a specific configuration file. In this case only one argument must be provided as command line argument
EyeTribe <config.cfg file>
The config.cfg argument indicates a valid configuration file. It can be provided using either a relative or an absolute path.
It is possible to have a system with multiple concurrent EyeTribe Servers, each operating on a dedicated Tracker and on a dedicated monitor. An instance of the EyeTribe Server must be spawned per Tracker device. Utilizing individual config files per server instance will be a practicable way of setting up such a system.
The client must be able to communicate with each EyeTribe Server on different TCP socket ports. The client must also remember to specify the active monitor screen to each EyeTribe Server instance, if different monitors are to be distributed between the different trackers. The user must avoid having several trackers active simultaneously due to interfering infrared illumination. A way to control this is to disconnect the client from the EyeTribe Server (e.g., by stopping sending heartbeats) when the eyes are no longer looking at the screen.
Make sure the Tracker device is connected to a USB3 port and that the Tracker Server software is running. Open a TCP Socket in your programming language of choice and connect to “localhost” on port 6555. For a full source code example see Tutorials section.
Any connected client must send hearbeats using the Tracker API to notify the Tracker Server that the client is alive. Not doing so will disconnect the client.