Troubleshooting

Solutions to common OpenTrack issues and error messages

This guide covers common issues you might encounter when using OpenTrack and how to resolve them.

Quick Diagnostics

Before diving into specific issues, try these general troubleshooting steps:

1. Check OpenTrack Version

   Ensure you’re running the latest version from the releases page.

2. Review Error Messages

   Check the OpenTrack console/log for error messages. On Windows, run OpenTrack from Command Prompt to see console output.

3. Test with Default Profile

   Create a new profile with default settings to rule out configuration issues.

4. Verify Hardware

   Test your camera or tracking device with other applications to ensure it’s working properly.

Tracking Issues

Camera Not Detected

Symptoms: OpenTrack doesn’t show your webcam in the camera list.

Solutions:

1. Check Camera Permissions

   Windows 10/11:

   • Go to Settings → Privacy → Camera
   • Enable “Allow apps to access your camera”
   • Enable “Allow desktop apps to access your camera”

   Linux:

   # Check if camera device exists
   ls -l /dev/video*
   
   # Add user to video group
   sudo usermod -a -G video $USER
   
   # Log out and back in for changes to take effect
   
2. Verify Camera Driver

   Windows:

   • Open Device Manager
   • Look under “Cameras” or “Imaging devices”
   • If you see a yellow warning icon, update or reinstall the driver

   Linux:

   # Install video4linux utilities
   sudo apt-get install v4l-utils
   
   # List available cameras
   v4l2-ctl --list-devices
   
3. Test Camera in Other Apps

   Try opening the camera in:

   • Windows Camera app
   • Browser (webcam test websites)
   • Skype/Zoom

   If the camera doesn’t work elsewhere, the issue is with the camera/driver, not OpenTrack.

4. Disconnect Other Applications

   Close any applications that might be using the camera:

   • Video conferencing apps (Zoom, Teams, Skype)
   • Streaming software (OBS)
   • Browser tabs with camera access

Poor Tracking Quality

Symptoms: Jittery tracking, loss of tracking, or incorrect head position.

Solutions:

Lighting

Point Tracker (LED):

• Use bright, focused LED lights
• Avoid ambient lighting in the background
• Position lights to minimize reflections
• Use at least 3 points for best results

ArUco Marker:

• Ensure even, bright lighting on the marker
• Avoid shadows on the marker
• Print marker at sufficient size (5cm+ recommended)

NeuralNet Tracker:

• Good room lighting helps face detection
• Avoid strong backlighting

Camera Settings

Optimize camera settings:

• Resolution: 640x480 is usually sufficient
• Frame Rate: 30 FPS minimum, 60 FPS preferred
• Exposure: Manual exposure prevents brightness changes
• Auto White Balance: Disable for consistent colors
• Auto Focus: Disable and set focus manually

Access camera settings in:

• OpenTrack → Options → Camera Settings

Filter Settings

Adjust filtering to improve stability:

For jittery tracking:

• Enable a smoothing filter (Accela, EMA)
• Increase filter strength

For lag:

• Reduce filter strength
• Use a faster filter (Accela instead of EMA)

For overshoot:

• Adjust mapping curves
• Reduce response sensitivity

Position

Camera placement:

• Mount camera at eye level
• Distance: 50-80cm for most trackers
• Ensure camera points directly at you

LED/Marker placement:

• Wide triangular pattern for stability
• Avoid symmetrical patterns
• Keep markers visible at all head angles

Tracking Drift

Symptoms: Head position slowly drifts over time even when stationary.

Solutions:

1. Re-center regularly:
   • Bind a key to “Center” function
   • Press when looking straight ahead
2. Disable auto-center:
   • Options → Output → Disable translation drift reduction
3. Check for heat issues:
   • Some trackers (especially webcam-based) drift when warming up
   • Let camera warm up for 5 minutes before gaming
4. Update tracker firmware:
   • For hardware trackers (TrackIR, etc.)
   • Check manufacturer’s website

High CPU Usage

Symptoms: OpenTrack uses excessive CPU resources.

Solutions:

1. Reduce camera resolution:

   Options → Camera → Resolution → 640x480
   

2. Lower frame rate:

   Options → Camera → FPS → 30
   

3. Disable preview window:

   Hide the camera preview when not needed
   

4. Close unnecessary applications:

   • Free up CPU for gaming
   • Disable background programs

5. Update OpenCV:

   • Newer versions have better performance
   • Rebuild OpenTrack with latest OpenCV

Game Integration Issues

Game Not Detecting OpenTrack

Symptoms: Game doesn’t respond to head tracking.

Solutions by Protocol:

FreeTrack

Windows:

1. Install FreeTrack driver:

   • Download from FreeTrack website
   • Install before launching game

2. Select FreeTrack in OpenTrack:

   Output → freetrack 2.0 Enhanced
   

3. Enable TrackIR in game:

   • Check game options for head tracking
   • Enable “TrackIR” or “Head Tracking”

4. Run as administrator:

   • Right-click game executable
   • “Run as administrator”

UDP

Network output:

1. Check firewall:

   # Windows Firewall - allow UDP port
   New-NetFirewallRule -DisplayName "OpenTrack UDP" `
     -Direction Outbound -LocalPort 5550 -Protocol UDP `
     -Action Allow
   

2. Verify IP address:

   • For local: 127.0.0.1
   • For remote: Target computer’s IP

3. Test with receiver:

   # Listen on UDP port
   nc -ul 5550
   

SimConnect

Microsoft Flight Simulator:

1. Install SimConnect SDK:
   • Included with MSFS
   • Check installation
2. Run MSFS first:
   • Start the game
   • Wait for main menu
   • Then start OpenTrack
3. Check SimConnect version:
   • OpenTrack requires specific version
   • Update if necessary

X-Plane

X-Plane plugin:

1. Install Wine (Linux):

   sudo apt-get install wine
   

2. Configure output:

   Output → Wine → X-Plane plugin
   

3. Copy plugin files:

   • Follow X-Plane plugin installation guide

Inverted or Reversed Axes

Symptoms: Looking left moves camera right, etc.

Solutions:

1. Invert axes in mapping:

   Mapping → Select axis → Enable "Invert"
   

2. Check game settings:

   • Some games have invert options
   • Check for “Invert Head Tracking”

3. Verify tracker orientation:

   • Some trackers have orientation settings
   • Check tracker-specific configuration

Tracking Range Too Large/Small

Symptoms: Small head movements cause excessive camera movement, or you need to move your head too much.

Solutions:

1. Adjust mapping curves:

   Mapping → Select axis → Adjust curve
   
   • Too sensitive: Reduce output maximum
   • Not sensitive enough: Increase output maximum
   • Non-linear response: Adjust curve points

2. Use presets:

   • Try built-in curve presets
   • Import community profiles

3. Per-game profiles:

   • Create separate profiles for different games
   • Save with descriptive names

Build and Compilation Errors

CMake Configuration Fails

Error: CMake Error: Could not find Qt5

Solutions:

# Specify Qt5 path
cmake .. -DCMAKE_PREFIX_PATH=/path/to/qt5

# Or use Qt5_DIR
cmake .. -DQt5_DIR=/path/to/qt5/lib/cmake/Qt5

Error: CMake minimum version 3.13 required

Solutions:

Update CMake:

# Linux
sudo apt-get install cmake

# Or download from cmake.org
wget https://github.com/Kitware/CMake/releases/download/v3.26.0/cmake-3.26.0-linux-x86_64.sh

Missing Dependencies

Error: opencv/cv.h: No such file or directory

Solutions:

Install OpenCV:

# Debian/Ubuntu
sudo apt-get install libopencv-dev

# Fedora
sudo dnf install opencv-devel

# Windows
# Download from opencv.org and set OpenCV_DIR

Error: Eigen3/Core: No such file or directory

Solutions:

# Debian/Ubuntu
sudo apt-get install libeigen3-dev

# Fedora  
sudo dnf install eigen3-devel

Linker Errors

Error: undefined reference to vtable

Solutions:

1. Link against opentrack-api:

   target_link_libraries(opentrack-tracker-myplugin 
     PRIVATE opentrack-api)
   

2. Run moc on Q_OBJECT classes:

   • CMake should handle this automatically
   • Ensure .h files are in source list

Error: undefined reference to 'm'

Solutions:

On Linux, ensure math library is linked:

if(UNIX)
    target_link_libraries(${target} PRIVATE m)
endif()

Runtime Errors

Missing DLL Errors (Windows)

Error: The code execution cannot proceed because <dll> was not found

Common missing DLLs:

• Qt5Core.dll, Qt5Gui.dll, Qt5Widgets.dll
• opencv_world*.dll
• MSVCP140.dll, VCRUNTIME140.dll

Solutions:

1. Install Visual C++ Redistributable:

   • Download VC++ 2015-2022 x64

2. Add Qt to PATH:

   set PATH=C:\Qt\5.15.2\msvc2019_64\bin;%PATH%
   

3. Copy DLLs to opentrack directory:

   copy C:\Qt\5.15.2\msvc2019_64\bin\Qt*.dll C:\opentrack\
   

Crash on Startup

Symptoms: OpenTrack crashes immediately or shows no window.

Solutions:

1. Delete settings:

   # Windows
   del /f /q %LOCALAPPDATA%\opentrack\settings\*
   
   # Linux
   rm -rf ~/.config/opentrack/
   

2. Check graphics drivers:

   • Update GPU drivers
   • Try software rendering:
   set QT_OPENGL=software
   opentrack.exe
   

3. Run from terminal to see errors:

   # Linux
   ./opentrack 2>&1 | tee opentrack.log
   
   # Windows
   opentrack.exe > opentrack.log 2>&1
   

Plugin Load Failures

Error: Failed to load plugin: <name>

Solutions:

1. Verify plugin exists:

   # Linux
   ls /usr/lib/opentrack/opentrack-tracker-*.so
   
   # Windows
   dir "C:\Program Files\opentrack\opentrack-tracker-*.dll"
   

2. Check dependencies:

   # Linux - check plugin dependencies
   ldd /usr/lib/opentrack/opentrack-tracker-aruco.so
   

3. Reinstall OpenTrack:

   • Download fresh installer
   • Uninstall completely first
   • Install to clean directory

Performance Issues

Stuttering or Frame Drops in Games

Solutions:

1. Lower OpenTrack update rate:
   • Options → Output → Update rate: 60 Hz
2. Reduce camera resolution:
   • Options → Camera → 640x480
3. Disable camera preview:
   • Close preview window during gaming
4. Use performance power plan:
   • Windows: High Performance mode
   • Disable CPU throttling
5. Close background apps:
   • Discord, Chrome, etc.
   • Check Task Manager for CPU usage

High Latency

Symptoms: Noticeable delay between head movement and game response.

Solutions:

1. Reduce filtering:
   • Mapping → Reduce smoothing
   • Use faster filters (Accela)
2. Check camera exposure:
   • Auto exposure adds latency
   • Set manual exposure
3. Increase camera FPS:
   • Options → Camera → 60 FPS
4. Use wired connection:
   • For UDP protocols
   • Wireless adds latency

Getting Help

If you’re still experiencing issues:

GitHub Issues

Search existing issues or create a new one

Community Wiki

Check the wiki for tracker-specific guides

IL-2 Sturmovik Forums

Russian community forum with many experienced users

Reddit

r/hotas and flight sim communities

Information to Include

When asking for help, provide:

• OpenTrack version (Help → About)
• Operating system and version
• Tracker type being used
• Game and protocol
• Error messages (full text)
• Steps to reproduce the issue

OpenTrack developers are friendly and responsive. Don’t hesitate to submit an issue or feature request!