Skip to content

python

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

python

README.md

jspsych-tobii (Python Server)

WebSocket server for integrating Tobii eye trackers with jsPsych experiments.

Installation

# Install with Tobii SDK support
pip install jspsych-tobii[tobii]

# Or install SDK separately
pip install jspsych-tobii
pip install tobii-research

For Testing Without Hardware

# Use built-in mock tracker
pip install jspsych-tobii
jspsych-tobii-server --mock

Supported Hardware

All trackers are supported via the tobii-research package:

  • Modern Pro series (via tobii-research 2.x): Spectrum, Fusion, Nano, Spark
  • Older models (via tobii-research 1.x): X3-120, TX300, X2-60, T120, etc.
  • Mock Tracker: For testing and development without hardware

Note: If you have an older tracker like the X3-120, install tobii-research<2 (version 1.x supports these models; version 2.x dropped them).

See ADAPTER_GUIDE.md for detailed SDK information.

Quick Start

Start Server

# Basic usage (auto-detect tracker, port 8080)
jspsych-tobii-server

# Specify port
jspsych-tobii-server --port 9000

# Enable debug logging
jspsych-tobii-server --log-level DEBUG

# Log to file
jspsych-tobii-server --log-file server.log

Use with jsPsych

See the main README for JavaScript integration examples.

Command-Line Options

jspsych-tobii-server [OPTIONS]

Options:
  --host HOST           Server host address (default: localhost)
  --port PORT           Server port (default: 8080)
  --tracker ADDRESS     Specific tracker address (auto-detect if not specified)
  --buffer-size SIZE    Maximum buffer size (default: 10000)
  --log-level LEVEL     Logging level: DEBUG, INFO, WARNING, ERROR (default: INFO)
  --log-file FILE       Log file path (console if not specified)
  --version             Show version and exit
  --help                Show this help message

Python API

You can also use the server programmatically:

from jspsych_tobii import TobiiServer, ServerConfig
import asyncio

# Create configuration
config = ServerConfig(
    host='localhost',
    port=8080,
    log_level='INFO'
)

# Create and start server
server = TobiiServer(config)
asyncio.run(server.start())

Features

  • Auto-detection: Automatically finds connected Tobii eye trackers
  • WebSocket Protocol: Real-time bidirectional communication
  • Time Synchronization: Accurate timestamp alignment between client and server
  • Calibration Support: Full calibration and validation workflow
  • Data Buffering: Efficient data storage and retrieval
  • Logging: Comprehensive logging for debugging

WebSocket Protocol

The server communicates via WebSocket using JSON messages.

Message Types

Client -> Server:

  • start_tracking: Start eye tracking data collection
  • stop_tracking: Stop eye tracking
  • calibration_start: Begin calibration
  • calibration_point: Collect calibration point
  • calibration_compute: Compute calibration
  • validation_start: Begin validation
  • validation_point: Collect validation point
  • validation_compute: Compute validation
  • get_current_gaze: Get latest gaze position
  • get_data: Get gaze data for time range
  • time_sync: Synchronize time

Server -> Client:

  • gaze_data: Real-time gaze data stream
  • Response messages for each request type

Troubleshooting

Tracker Not Found

  1. Ensure tracker is connected (USB or network)
  2. Check that Tobii Eye Tracker Manager software recognizes the tracker
  3. Verify that no other applications are using the tracker
  4. Try specifying tracker address explicitly: 
    jspsych-tobii-server --tracker tet-tcp://192.168.1.100

Connection Issues

  1. Check firewall settings
  2. Verify port is not in use
  3. Try a different port: 
    jspsych-tobii-server --port 9000

Performance Issues

  1. Increase buffer size: 
    jspsych-tobii-server --buffer-size 20000

Development

Install Development Dependencies

pip install -e ".[dev]"

Run Tests

pytest

Code Formatting

black jspsych_tobii
ruff check jspsych_tobii

License

MIT

Support