The EyeLink trackers and the EyeLink Developers Kit libraries (and similar EyeLink application libraries for other platforms) support connecting multiple computers to one eye tracker, and communication between EyeLink applications. All of the computers should be connected via a network switch, with the IP addresses in the range of 100.1.1.x and subnet mask 255.255.255.0.
When reading the following, keep in mind the kind of configuration you will need. Some examples are:
In the usual EyeLink experiment, an eye tracker communicates only with the application that first opened a connection to it. If a second computer tries to connect, the connection to the first application was closed. For multiple connections, the EyeLink system uses broadcast connections, where data from the eye tracker is sent to all computers on the local network (that is, on the same network cable or connected to the same hub as the eye tracker).
One computer still has the primary connection, but up to 4 other computers can also have broadcast connections to the eye tracker. This primary connection has full control over the eye tracker - broadcast connections are closed when a primary connection is opened or closed, whereas a primary connection is unaffected by broadcast connections. This means that a primary connection should always be opened before a broadcast connection is made from another computer. Therefore it is critical that a "listening" application wait for a primary connection to be made before opening a broadcast connection - the templates comm_simple and comm_listener exchange messages for this purpose, while the broadcast template checks the connection status of the tracker directly. Closing a broadcast connection does not affect the primary connection or any other broadcast connections.
A broadcast connection allows other computers to listen in on real-time data sent from the eye tracker to the primary computer. In addition, broadcast connections allow computers to monitor the eye tracker's state, draw calibration targets, and even send commands and messages to the eye tracker. Some functions are not available with broadcast connections, including camera image display, data playback, and file transfers.
Some functions are also available without opening any connection to the eye tracker. These include sending key presses and messages to the eye tracker, and requesting updates on tracker status and the current tracker time. This capability is designed to allow multiple computers to synchronize their clocks or place synchronizing messages in the tracker's data file. Another use (used in the broadcast template) is to allow computers to wait for a primary connection before attempting to open a broadcast connection to the tracker.
Before a connection can be opened, the EyeLink DLL and networking system must be initialized. The function open_eyelink_connection()
does this initialization and, if called with an argument of 0, immediately opens a connection. If the argument is -1, it simply initializes the DLL. This allows the application to perform unconnected operations or to open a broadcast session later. Finally, if called with an argument of 1, it "opens" a "dummy" connection, which can be used for debugging applications without the need for a tracker (or even a network).
The network (IP) address of the tracker is usually "100.1.1.1", set in the eyenet.ini file on the Host PC. If the eye tracker is not at this address, or if multiple eye trackers are present at different addresses, the tracker address can be specified by calling set_eyelink_address()
before calling open_eyelink_connection(1)
. This address is also used for tracker communication if a connection has not been opened, to request tracker status or time or to send messages.
If the tracker address is set to "255.255.255.255", then the DLL will broadcast the connection request to all computers, expecting that the eye tracker will respond. This does not work properly with earlier versions of the eyelink_exptkit DLL, due to problems with broadcasting when multiple network adapters were installed under Windows. Newer tracker and DLL versions use subnet broadcasting, which works properly with all versions of Windows.
If the DLL was initialized with open_eyelink_connection(-1)
, a primary connection to the tracker can be opened later with eyelink_open()
, or a broadcast connection opened with eyelink_broadcast_open()
. After these connections are opened, the connection status should be checked often with eyelink_is_connected()
, which will return 0 if the connection has been closed. This may happen if the eye tracker software was closed, if another application opened a primary connection to the eye tracker or (in the case of a broadcast connection) if the computer with the primary connection closed its session. This function can also be used to determine the connection type, as it returns 1 for a primary connection, 2 for a broadcast connection, and -1 for a dummy "connection".
Finally, the connection should be closed when your application exits, by calling close_eyelink_connection()
. This also releases other DLL resources, and can be used with any connection type. If you simply want to close the connection but still need to do unconnected communications, or need access to the high- resolution timing, then call eyelink_close(1)
instead.
The eyelink_core library can search for all trackers and computers running EyeLink applications ("remotes") that are connected to the link, and report these. This is performed by calling a polling function, then waiting a short time and checking for a list of responses. To search for a list of trackers, call eyelink_poll_trackers()
, and call eyelink_poll_remotes()
to look for applications. Wait 100-200 milliseconds, then call eyelink_poll_responses()
to get the count of responses received (only the first 4 responses will be recorded).
Responses are retrieved by calling eyelink_get_node()
, giving the index of the response. This index ranges from 1 (for the first tracker or remote to respond) up to the count returned by eyelink_poll_responses()
. Several other indexes are defined: for example, index 0 always returns the ELINKNODE (name and address) of the computer the application is running on.
The responses are reported as an ELINKNODE data type, which contains the name and network address (as an ELINKADDR data type) of the tracker or remote. This allows an application or tracker to be selected by name, rather than having to know the IP address of the computer. For trackers, this name is set in the eyenet.ini file in the eyelink\exe directory on the eyetracker PC. For applications, this name will be the Windows computer network name. This name can also be set by the application by calling eyelink_set_name()
, allowing other applications to find a specific application independent of the computer it is running on. See comm_simple and comm_listener for an example of this.
To communicate with another EyeLink application, you must have its address in the form of an ELINKADDR. This may be done by search for it by name (as discussed above) or by the IP address of the computer it is running on. The IP address can be converted into an ELINKADDR by calling text_to_elinkaddr()
, supplying the "dotted" IP name and whether the target is a tracker or remote.
Messages can consist of any kind of text or data, of up to 400 bytes in length. The message can be sent by calling eyelink_node_send()
, giving the ELINKADDR to send to, and the location and size of the data to be sent. The message will be received by the target application in less than a millisecond, and placed into a buffer. This buffer can then be read by calling eyelink_node_receive()
, which returns 0 if no new data is present, or the size of the data if any has been received. The function can also supply the ELINKADDR of the sender for use in identification.
The inter-remote receive buffer can only hold one message, so if a new message arrives before the previous message has been read, the old message will be lost. This means that applications should transfer data carefully, with the sender waiting for the receiver to send a message acknowledging receipt before sending more data. There are some situations where this is not needed, for example, if only the most recent data is important (such as the latest gaze position data), or where data is synchronized with other events (such as a message echoing the TRIALID in an experiment).
When broadcast connections are used to let one computer listen in on real-time data, it is possible to eliminate almost all other types of communications between applications. This is done by enabling the inclusion of messages in the real-time link data stream, and having the listening application interpret these in the same way an analysis program would process the recorded EDF file. For example, messages are usually present in the EDF file (and therefore available to the listener) for trial conditions ("TRIALID"
) and display resolution ("DISPLAY_COORDS"
).
When messages are included in the real-time link data, each message sent to the tracker is sent back through the link as well. These messages tend to be sent in bursts every few milliseconds, and each burst may contain several messages. EyeLink tracker software is optimized specifically to handle large amounts of network traffic, and can usually handle messages as fast as Windows can send them over the link. However, Windows is not as good at receiving messages back, and if messages are sent too rapidly from the main application, the listener application may drop some data. Dropped data can be detected by the presence of LOST_DATA_EVENT
events when reading link data with eyelink_get_next_data()
.
You should also be aware that messages and other events may arrive out of sequence through the link. Messages tend to arrive before any other data with the same time code. In addition, if commands are sent to the tracker just before messages, it is possible that the message may be sent back through the link before the command has finished executing (especially commands that change modes). For example, a TRIALID message may arrive before the listening application has finished processing data from the previous recording block. This can be prevented by adding a short delay before messages, or preceding messages sent after a mode switch command with a call to eyelink_wait_for_mode_ready()
.
Examples of how to enable sending, receiving, and processing messages by a listening application are given in the comm_simple and comm_listener templates. To receive messages and all other data, the reception of link data is turned on by eyelink_data_switch()
, and left on thereafter.