SR Research Support Site
Macros | Functions | Variables
Initialize EyeLink Library

Macros

#define LINK_INITIALIZE_FAILED   -200
 
#define CONNECT_TIMEOUT_FAILED   -201
 
#define WRONG_LINK_VERSION   -202
 
#define TRACKER_BUSY   -203
 

Functions

UINT16 open_eyelink_system (UINT16 bufsize, char FARTYPE *options)
 
void eyelink_set_name (char FARTYPE *name)
 
void close_eyelink_system (void)
 
INT16 eyelink_open_node (ELINKADDR node, INT16 busytest)
 
INT16 eyelink_open (void)
 
INT16 eyelink_broadcast_open (void)
 
INT16 eyelink_dummy_open (void)
 
INT16 eyelink_close (INT16 send_msg)
 
INT16 eyelink_is_connected (void)
 
INT16 eyelink_quiet_mode (INT16 mode)
 
INT16 eyelink_poll_trackers (void)
 
INT16 eyelink_poll_remotes (void)
 
INT16 eyelink_poll_responses (void)
 
INT16 eyelink_get_node (INT16 resp, void FARTYPE *data)
 
INT16 eyelink_get_tracker_version (char FARTYPE *c)
 
void eyelink_set_tracker_node (ELINKADDR node)
 
INT16 open_eyelink_connection (INT16 mode)
 
void close_eyelink_connection (void)
 
INT16 set_eyelink_address (char *addr)
 
void eyelink_set_special_keys (int terminate_key_mask, int terminate_key, int break_key_mask, int break_key, int case_sensitive)
 

Variables

ELINKADDR eye_broadcast_address
 
ELINKADDR rem_broadcast_address
 
ELINKADDR our_address
 

Detailed Description

These methods are used to initialize the EyeLink Library.

Macro Definition Documentation

#define CONNECT_TIMEOUT_FAILED   -201

CONNECTION ERROR CODES: timed out waiting for reply

#define LINK_INITIALIZE_FAILED   -200

CONNECTION ERROR CODES: can't use link

#define TRACKER_BUSY   -203

CONNECTION ERROR CODES: tracker already connected

#define WRONG_LINK_VERSION   -202

CONNECTION ERROR CODES: wrong TSR or source version

Function Documentation

void close_eyelink_connection ( void  )

Closes any connection to the eye tracker, and closes the link.

Remarks
NEW (v2.1): Broadcast connections can be closed, but not to affect the eye tracker. If a non-broadcast (primary) connection is closed, all broadcast connections to the tracker are also closed.

Example: See open_eyelink_connection()

See also
open_eyelink_connection() and eyelink_close()
void close_eyelink_system ( void  )

Resets the EyeLink library, releases the system resources used by the millisecond clock.

Remarks
MUST DO BEFORE EXITING.

Example: See open_eyelink_system()

See also
open_eyelink_system(), eyelink_close() and set_offline_mode()
INT16 eyelink_broadcast_open ( void  )

Allows a third computer to listen in on a session between the eye tracker and a controlling remote machine. This allows it to receive data during recording and playback, and to monitor the eye tracker mode. The local computer will not be able to send commands to the eye tracker, but may be able to send messages or request the tracker time.

Remarks
May not function properly, if there are more than one Ethernet cards installed.
Returns
0 if successful.
LINK_INITIALIZE_FAILED if link could not be established.
CONNECT_TIMEOUT_FAILED if tracker did not respond.
WRONG_LINK_VERSION if the versions of the EyeLink library and tracker are incompatible.
Example:
1 // This program illustrates the use of eyelink_broadcast_open(); see the COMM_SIMPLE and
2 // BROADCAST templates for more examples
3 
4 #include <eyelink.h>
5 #include <stdio.h>
6 
7 // Initialize the EyeLink DLL
8 if(open_eyelink_connection(-1))
9  return -1;
10 
11 // set our network name
12 eyelink_set_name("Broadcast");
13 
14 ...
15 // Extra code here to check for the tracker status or
16 // wait for the go-signal from the other application
17 
18 // Starts the broadcast connection to the tracker
19 if(eyelink_broadcast_open())
20 {
21  printf("Cannot open broadcast connection to tracker");
22  return -1;
23 }
24 
25 // enable link data reception by EyeLink DLL
26 eyelink_reset_data(1);
27 // NOTE: this function can discard some link data
28 eyelink_data_switch(RECORD_LINK_SAMPLES | RECORD_LINK_EVENTS);
See also
eyelink_close(), eyelink_dummy_open(), eyelink_is_connected(), eyelink_open() and eyelink_open_node()
INT16 eyelink_close ( INT16  send_msg)

Sends a disconnect message to the EyeLink tracker, resets the link data system.

Parameters
send_msgUsually <send_msg> is 1. However, 0 can be used to reset the eyelink system if it is listening on a broadcast session.
Returns
0 if successful, otherwise link error.

Example:

1 // This program illustrates the use of eyelink_close
2 
3 #include <eyelink.h>
4 
5 // Checks whether the tracker is still connected
6 if(eyelink_is_connected())
7 {
8  set_offline_mode(); // off-line mode
9  eyecmd_printf("close_data_file");
10  eyelink_close(1); // disconnect from tracker
11 }
See also
eyelink_broadcast_open(), eyelink_open(), eyelink_dummy_open() and eyelink_open_node()
INT16 eyelink_dummy_open ( void  )

Sets the EyeLink library to simulate an eyetracker connection. Functions will return plausible values, but no data.

Remarks
The function eyelink_is_connected() will return -1 to indicate a simulated connection.
Returns
Always returns 0.

Example:

1 // This program illustrates the use of eyelink_dummy_open
2 
3 #include <eyelink.h>
4 
5 // Initialize the EyeLink DLL; otherwise the application will crash
6 // when using the eyelink_dummy_open()function!
7 if(open_eyelink_connection(-1))
8  return -1;
9 
10 // Opens a "dummy" connection for debugging the application
11 eyelink_dummy_open();
See also
eyelink_broadcast_open(), eyelink_open() and eyelink_open_node()
INT16 eyelink_get_node ( INT16  resp,
void FARTYPE *  data 
)

Reads the responses returned by other trackers or remotes in response to eyelink_poll_trackers() or eyelink_poll_remotes(). It can also read the tracker broadcast address and remote broadcast addresses.

Parameters
respNmber of responses to read:0 gets our data, 1 get first response, 2 gets the second response, etc. -1 to read the tracker broadcast address. -2 to read remote broadcast addresses.
dataPointer to buffer of ELINKNODE type, to hold name and ELINKADDR of the respondent.
Returns
0 if OK, -1 if node response number is too high.

Example: See eyelink_poll_remotes()

See also
eyelink_node_receive(), eyelink_node_send() and eyelink_poll_remotes()
INT16 eyelink_get_tracker_version ( char FARTYPE *  c)

After connection, determines if the connected tracker is an EyeLink I or II.

Remarks
For the EyeLink II tracker, it can optionally retrieve the tracker software version.
Parameters
cNULL, or pointer to a string (at least 40 characters) to hold the version string. This will be "EYELINK I" or "EYELINK II x.xx", where "x.xx" is the software version.
Returns
0 if not connected, 1 for EyeLink I, 2 for EyeLink II 3 for EyeLink 1000.

Example:

1 // This program illustrates the use of eyelink_get_tracker_version
2 
3 #include <eyelink.h>
4 
5 int i;
6 char version_info[256];
7 
8 i = eyelink_get_tracker_version(version_info);
9 eyemsg_printf("EyeLink %d version %s", i, version_info);

Output:

1 MSG 500850 EyeLink 2 version EYELINK II 1.10
INT16 eyelink_is_connected ( void  )

Checks whether the connection to the tracker is alive.

Remarks
Call this routine during loops and wherever the experiment might lock up if the tracker is shut down. Exit the experiment (by terminating loops and returning from all calls) if this returns 0.
Returns
0 if link closed.
-1 if simulating connection.
1 for normal connection.
2 for broadcast connection (NEW for v2.1 and later).
Example:
1 // This program illustrates the use of eyelink_is_connected( when performing a pre-trial drift correction
2 
3 #include <eyelink.h>
4 
5 while(1)
6 {
7  // Checks link often so we can exit if tracker stopped
8  if(!eyelink_is_connected())
9  return ABORT_EXPT;
10 
11  // Performs drift correction with target drawn in the center
12  error = do_drift_correct(SCRWIDTH/2, SCRHEIGHT/2, 1, 1);
13 
14  // repeat if ESC was pressed to access Setup menu
15  if(error!=27) break;
16 }
See also
eyelink_close() and eyelink_open()
INT16 eyelink_open ( void  )

Attempts to open a link connection to the EyeLink tracker. Simple connect to single Eyelink tracker. Equivalent to eyelink_open_node(broadcast_address, 0).

Remarks
The tracker address can be set by calling the function set_eyelink_address(). If this address was "255.255.255.255" the call to eyelink_open() will "broadcast" a request to any tracker, however this may fail if multiple Ethernet cards are installed. For the broadcast option to work use EyeLink I v2.1 or higher, EyeLink II v1.1 or higher. Before using this command, call either open_eyelink_connection(-1) or open_eyelink_system () to prepare the link for use.
Returns
0 if successful.
LINK_INITIALIZE_FAILED if link could not be established.
CONNECT_TIMEOUT_FAILED if tracker did not respond.
WRONG_LINK_VERSION if the versions of the EyeLink library and tracker are incompatible.
Example:
1 // This program illustrates the use of eyelink_open()
2 
3 #include <eyelink.h>
4 
5 // Initialize the EyeLink DLL
6 if(open_eyelink_connection(-1))
7  return -1;
8 
9 // Set the address of the tracker
10 set_eyelink_address("100.1.1.1");
11 
12 // connect to single Eyelink tracker
13 if (eyelink_open())
14  return -1;
See also
eyelink_broadcast_open(), eyelink_close(), eyelink_dummy_open(), eyelink_open_node(), open_eyelink_connection(), open_eyelink_system() and set_eyelink_address()
INT16 eyelink_open_node ( ELINKADDR  node,
INT16  busytest 
)

Allows the computer to connect to tracker, where the tracker is on the same network.

Parameters
nodeMust be an address returned by eyelink_poll_trackers() and eyelink_poll_responses() to connect to any tracker.
busytestIf non-zero the call to eyelink_open_node() will not disconnect an existing connection.
Returns
0 if successful.
LINK_INITIALIZE_FAILED if link could not be established.
CONNECT_TIMEOUT_FAILED if tracker did not respond.
WRONG_LINK_VERSION if the versions of the EyeLink library and tracker are incompatible.
TRACKER_BUSY if <busytest> is set, and tracker is connected to another computer.
Example:
1 // This program illustrates the case of making connection using an ELINKADDR tracker node address
2 
3 ELINKADDR node; // EyeLink address node
4 
5 // Initialize the EyeLink DLL
6 if(open_eyelink_connection(-1))
7  return -1;
8 
9 // Converts tracker IP address to an EyeLink node
10 text_to_elinkaddr("100.1.1.1", node, 0);
11 
12 // Makes connection using an ELINKADDR tracker node address; checks
13 // whether the tracker is already connected with another application
14 if (eyelink_open_node(node, 1))
15  return -1;
See also
eyelink_node_receive(), eyelink_node_send(), eyelink_node_send_message() and eyelink_open()
INT16 eyelink_poll_remotes ( void  )

Asks all non-tracker computers (with EyeLink software running) on the network to send their names and node address.

Returns
OK_RESULT if successful, otherwise link error.
LINK_TERMINATED_RESULT if link error.
-1 if broadcast option is not available.

Example:

1 // This program illustrates the use of eyelink_poll_remotes(). See COMM_SIMPLE/COMM_LISTENER
2 // templates for the complete example
3 
4 #include <eyelink.h>
5 
6 ELINKADDR listener_address; // Address of listener application
7 
8 // Finds the listener application
9 int check_for_listener(void)
10 {
11  int i, n;
12  ELINKNODE node; // This will hold application name and address
13 
14  eyelink_poll_remotes(); // Polls network for EyeLink applications
15  pump_delay(500); // Gives applications time to respond
16 
17  n = eyelink_poll_responses(); // How many responses?
18  // Responses 1 to n are from other applications
19  for(i = 1; i<= n; i++)
20  {
21  if(eyelink_get_node(i, &node) < 0)
22  return -1; // error: no such data
23 
24  // Found the "Comm_listener" application
25  if(!_stricmp(node.name, "comm_listener"))
26  {
27  // Stores the listener's address
28  memcpy(listener_address, node.addr, sizeof(ELINKADDR));
29 
30  // Send a message to the listener
31  eyelink_node_send(listener_address, "NAME comm_simple", 40);
32 
33  ...
34  // Other code here to check responses from the listener
35  ...
36 
37  return 0; // all communication checks out
38  }
39  }
40  return -1; // no listener node found
41 }
See also
eyelink_poll_responses() and eyelink_poll_trackers()
INT16 eyelink_poll_responses ( void  )

Returns the count of node addresses received so far following the call of eyelink_poll_remotes() or eyelink_poll_trackers().

Remarks
You should allow about 100 milliseconds for all nodes to respond. Up to 4 node responses are saved.
Returns
Number of nodes responded. 0 if no responses.

Example: See eyelink_poll_remotes()

See also
eyelink_poll_remotes() and eyelink_poll_trackers()
INT16 eyelink_poll_trackers ( void  )

Asks all trackers (with EyeLink software running) on the network to send their names and node address.

Returns
OK_RESULT if successful, otherwise link error.
LINK_TERMINATED_RESULT if link error.
-1 if broadcast option is not available.

Example: See eyelink_poll_remotes()

See also
eyelink_poll_remotes() and eyelink_poll_responses()
INT16 eyelink_quiet_mode ( INT16  mode)

Controls the level of control an application has over the tracker.

Remarks
This is used in combination with broadcast mode (multiple applications connected to one tracker) to ensure that "listener" applications do not inadvertently send commands, key presses, or messages to the tracker. This is mostly useful when quickly converting an existing application into a listener.
Parameters
mode0 to allow all communication.
1 to block commands (allows only key presses, messages, and time or variable read requests).
2 to disable all commands, requests and messages.
-1 to just return current setting.
Returns
The previous settings.

Example:

1 // This program illustrates the use of eyelink_quiet_mode() to control message sending from a Broadcast
2 // application to the tracker
3 
4 #include <eyelink.h>
5 #include <stdio.h>
6 
7 // Starts the broadcast connection to the tracker
8 if(eyelink_broadcast_open())
9 {
10  printf("Cannot open broadcast connection to tracker");
11  return -1;
12 }
13 
14 // enable link data reception by EyeLink DLL
15 eyelink_reset_data(1);
16 // NOTE: this function can discard some link data
17 eyelink_data_switch(RECORD_LINK_SAMPLES | RECORD_LINK_EVENTS);
18 
19 // The following codes test the message sending from the BROADCAST
20 // application to tracker with eyelink_quiet_mode()
21 eyelink_quiet_mode(0); // Allows for message sending
22 eyelink_send_message("This should be recorded in the EDF file");
23 eyelink_quiet_mode(2); // Disables message sending
24 eyelink_send_message("This should not appear in the EDF file");
25 eyelink_quiet_mode(0); // Allows for message sending again
26 eyelink_send_message("This should appear in the EDF file");

Output:

1 MSG 3304947 This message should be recorded in the EDF file
2 MSG 3304947 This message should appear in the EDF file
See also
eyelink_broadcast_open() and eyelink_open()
void eyelink_set_name ( char FARTYPE *  name)

Sets the node name of this computer (up to 35 characters).

Parameters
nameString to become new name.

Example:

1 // This program illustrates the use of eyelink_set_name()
2 #include <eyelink.h>
3 
4 ELINKNODE node; // This will hold application name and address
5 
6 // Sets the EyeLink host address, if tracker IP address is different
7 // from the default "100.1.1.1"
8 if (set_eyelink_address("100.1.1.7"))
9  return -1;
10 
11 // Initializes EyeLink library, and opens connection to the tracker
12 if(open_eyelink_connection(0))
13  return -1;
14 
15 // set our EyeLink node name
16 eyelink_set_name("Newapplication");
17 
18 // Verify the name set by getting copy of node data
19 // Since we are checking our own data, set resp = 0
20 if(eyelink_get_node(0, &node) == OK_RESULT)
21  eyemsg_printf("%s", node.name);

Output:

1 MSG 2248248 Newapplication
See also
eyelink_get_node(), open_eyelink_connection() and set_eyelink_address()
void eyelink_set_special_keys ( int  terminate_key_mask,
int  terminate_key,
int  break_key_mask,
int  break_key,
int  case_sensitive 
)

Sets the alternative for special keys such as CTRL+C, ESC

Parameters
terminate_key_maskmask value for the terminate key
terminate_keyTerminate key charecter key that terminate the eyelink applicaiton
break_key_maskmask value for the break key
break_keyBreak key charecter key that terminate the eyelink applicaiton
case_sensitiveflag 1 means case sensitive 0 means not case sensitive

Example:

1 // This program illustrates the use of eyelink_set_special_keys()
2 #include <eyelink.h>
3 Eg. CTRL key can be
4 ELKMOD_NONE 0x0000 - Modifier for KeyInput.modifier; No modifier present
5 ELKMOD_LSHIFT 0x0001 - Modifier for KeyInput.modifier; Left shift
6 ELKMOD_RSHIFT 0x0002 - Modifier for KeyInput.modifier; Right shift
7 ELKMOD_LCTRL 0x0040 - Modifier for KeyInput.modifier; left conrol
8 ELKMOD_RCTRL 0x0080 - Modifier for KeyInput.modifier; Right control
9 ELKMOD_LALT 0x0100 - Modifier for KeyInput.modifier; Left Alt
10 ELKMOD_RALT 0x0200 - Modifier for KeyInput.modifier; Right alt
11 ELKMOD_LMETA 0x0400 - Modifier for KeyInput.modifier; Left Meta
12 ELKMOD_RMETA 0x0800 - Modifier for KeyInput.modifier; Right Meta
13 ELKMOD_NUM 0x1000 - Modifier for KeyInput.modifier; Number lock key
14 ELKMOD_CAPS 0x2000 - Modifier for KeyInput.modifier; Cap lock key
15 ELKMOD_MODE 0x4000 - Modifier for KeyInput.modifier; Mode key
16 
17 ELINKNODE node; // This will set and overwrite the default special keys CTRL+C and ESC
18 
19 // Sets the EyeLink special keys
20 // from the default CTRL, C and ESC to provided values
21 if (eyelink_set_special_keys(ELKMOD_LCTRL, 'C', ELKMOD_RSHIFT, 'Q', 0))
22  return -1;
23 
24 </pre>
25 \b Output:
26 <pre>
27 \code
28 MSG 2248248 Newapplication
See also
eyelink_get_node(), open_eyelink_connection() and set_eyelink_address()
void eyelink_set_tracker_node ( ELINKADDR  node)

Address used for non-connected time requests and message sends. the "proper" way to do this is with the "node" type of functions but we allow a "back door" to simplify higher level support functions. This is also the address used under Windows for looking for tracker (an IP broadcast is used on all other platforms). There is a bug in the Windows networking, causing broadcasts sent on all cards to have the IP source addres of only the first card. This means the tracker sends its connection reply to the wrong address. So the exact address or a subnet broadcast address (i.e. 100.1.1.255 for a subnet mask of 255.255.255.0) needs to be set to that of the tracker.

INT16 open_eyelink_connection ( INT16  mode)

Initializes the EyeLink library, and opens a connection to the EyeLink tracker.

Remarks
By setting <mode> to be 1, the connection can be simulated for debugging purposes. Only timing operations and simple tests should be done in simulation mode, and the Windows TCP/IP system must be installed. This function is intended for networks where a single tracker is connected to the network.
Parameters
modeMode of connection:
  • 0, opens a connection with the eye tracker;
  • 1, will create a dummy connection for simulation;
  • -1, initializes the DLL but does not open a connection.
Returns
0 if success, else error code

Example:

1 // This program illustrates the use of open_eyelink_connection()
2 
3 #include <eyelink.h>
4 
5 // Sets the EyeLink host address, if tracker IP address is different
6 // from the default "100.1.1.1"
7 if (set_eyelink_address("100.1.1.7"))
8  return -1;
9 
10 //Initializes EyeLink library, and opens connection to the tracker
11 if(open_eyelink_connection(0))
12  return -1;
13 
14 ...
15 // Code for the setup, recording, and cleanups
16 close_eyelink_connection(); // disconnect from tracker
See also
close_eyelink_connection(), close_eyelink_system(), eyelink_broadcast_open(), eyelink_dummy_open(), eyelink_open() and eyelink_open_node()
UINT16 open_eyelink_system ( UINT16  bufsize,
char FARTYPE *  options 
)

Use this function to initialize the EyeLink library. This will also start the millisecond clock. No connection is attempted to the eyetracker yet. It is preferable to call open_eyelink_connection(-1) instead, as this prepares other parts of the DLL for use.

Remarks
MUST BE FIRST CALL TO LINK INTERFACE.
Parameters
bufsizeSize of sample buffer. 60000 is the maximum allowed. (0 for default)
optionsText specifying initialization options. Currently no options are supported. (NULL or "" for defaults)
Returns
0 if failed, nonzero (-1 or TSR SWI number) if success.

Example:

1 // This program shows the use of open_eyelink_system() and close_eyelink_system ()
2 
3 #include <eyelink.h>
4 int dummy = 0; // Sets the connection type
5 
6 // Initialize the EyeLink library
7 if(!open_eyelink_system(0, ""))
8 {
9  printf("\nERROR: Cannot initialize eyelink library\n");
10  return -1;
11 }
12 
13 if(dummy)
14  i = eyelink_dummy_open(); // Starts a dummy connection
15 else
16  i = eyelink_open(); // Connects to the tracker
17 
18 ...
19 // Code for the setup, recording, and cleanups
20 
21 // Now, the following code closes the eyelink connection
22 // Checks whether we still have the connection to the tracker
23 if(eyelink_is_connected())
24 {
25  // Places EyeLink tracker in off-line (idle) mode
26  set_offline_mode();
27  eyecmd_printf("close_data_file"); // close data file
28  eyelink_close(1); // disconnect from tracker
29 }
30 
31 // shut down system (MUST do before exiting)
32 close_eyelink_system();
See also
close_eyelink_connection(), close_eyelink_system(), eyelink_close() and eyelink_open()
INT16 set_eyelink_address ( char *  addr)

Sets the IP address used for connection to the EyeLink tracker. This is set to "100.1.1.1" in the DLL, but may need to be changed for some network configurations. This must be set before attempting to open a connection to the tracker.

Remarks
A "broadcast" address ("255.255.255.255") may be used if the tracker address is not known - this will work only if a single Ethernet card is installed, or if DLL version 2.1 or higher, and the latest tracker software versions (EyeLink I v2.1 or higher, EyeLink II v1.1 or higher, all version of EyeLink 1000, 1000 Plus, and Portable Duo) are installed.
Parameters
addrPointer to a string containing a "dotted" 4-digit IP address.
Returns
0 if success, -1 if could not parse address string.

Example:

1 // This program illustrates the use of set_eyelink_address()
2 
3 #include <eyelink.h>
4 
5 // Initialize the EyeLink DLL
6 if(open_eyelink_connection(-1))
7  return -1;
8 
9 // Set the address of the tracker
10 set_eyelink_address("100.1.1.1");
11 
12 // connect to single Eyelink tracker
13 if (eyelink_open())
14  return -1;
See also
eyelink_open(), eyelink_open_node(), text_to_elinkaddr()

Variable Documentation

ELINKADDR eye_broadcast_address

The broadcast address for the eye trackers.

ELINKADDR our_address

This EyeLink node's address for the link implementation.

ELINKADDR rem_broadcast_address

The broadcast address for the remotes.


Copyright ©2002-2024, SR Research Ltd.