UDP Network

The UDP protocol transmits raw head tracking data over a network using UDP packets. This is useful for custom applications, development, external tools, or networked tracking setups.

How It Works

The UDP protocol:

Creates a UDP socket bound to any local address
Packages 6DOF tracking data into a binary format
Sends UDP datagrams to a configured IP address and port
Data is sent in real-time with minimal overhead

Data Format

Each UDP packet contains 48 bytes of binary data:

// Six double-precision floats (8 bytes each)
double data[6] = {
    headpose[Yaw],    // 0-7:   Yaw in degrees
    headpose[Pitch],  // 8-15:  Pitch in degrees  
    headpose[Roll],   // 16-23: Roll in degrees
    headpose[TX],     // 24-31: X position in cm
    headpose[TY],     // 32-39: Y position in cm
    headpose[TZ]      // 40-47: Z position in cm
};

Byte order: Native (host) byte order Packet size: 48 bytes No header or checksum - pure tracking data

Use Cases

Custom Applications

Game Development

Integrate head tracking into your own game or application

Research Tools

Collect tracking data for analysis or machine learning

Visualization

Real-time visualization of head movements

Networked Tracking

Run OpenTrack on one PC, game on another

Integration Examples

Unity/Unreal Engine: Read UDP data for camera control
Python scripts: Process tracking data for analysis
Arduino/Raspberry Pi: Control hardware based on head position
OBS Studio: Dynamic camera control for streaming
VR applications: Hybrid tracking systems

Setup Instructions

Select UDP protocol

In OpenTrack, go to the Output dropdown and select “UDP over network”.

Configure network settings

Click the settings button next to the Output dropdown.Network configuration:

IP Address: Destination IP (where to send data)
- Default: 192.168.0.2
- For same computer: 127.0.0.1
- For network: Enter target PC’s IP
Port: UDP port number
- Default: 4242
- Choose any available port (1024-65535)

Start OpenTrack

Click Start. OpenTrack will:

Bind a UDP socket
Begin sending tracking data to configured address
Send packets at tracking input rate (typically 50-60 Hz)

Receive data in your application

Implement UDP receiver in your application. See code examples below.

Configuration

Default Settings

IP Address: 192.168.0.2
Port: 4242

Network Modes

Localhost (same computer):

IP: 127.0.0.1
Port: 4242

Local network:

IP: 192.168.1.100 (target PC's LAN IP)
Port: 4242

Remote/Internet:

IP: <public IP or hostname>
Port: <forwarded port>

For internet transmission:

Configure port forwarding on router
Use firewall exceptions
Consider security implications of exposing UDP port
Data is sent unencrypted

Receiving Data

Python Example

import socket
import struct

# Create UDP socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.bind(('0.0.0.0', 4242))  # Listen on all interfaces, port 4242

print("Listening for OpenTrack UDP data on port 4242...")

while True:
    # Receive packet
    data, addr = sock.recvfrom(1024)
    
    # Unpack 6 doubles (48 bytes)
    if len(data) == 48:
        yaw, pitch, roll, x, y, z = struct.unpack('dddddd', data)
        
        print(f"Yaw: {yaw:7.2f}°  Pitch: {pitch:7.2f}°  Roll: {roll:7.2f}°  "
              f"X: {x:6.1f}cm  Y: {y:6.1f}cm  Z: {z:6.1f}cm")

C++ Example

#include <iostream>
#include <winsock2.h>
#include <ws2tcpip.h>

#pragma comment(lib, "ws2_32.lib")

struct TrackingData {
    double yaw, pitch, roll;
    double x, y, z;
};

int main() {
    WSADATA wsaData;
    WSAStartup(MAKEWORD(2, 2), &wsaData);
    
    // Create socket
    SOCKET sock = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
    
    // Bind to port
    sockaddr_in addr{};
    addr.sin_family = AF_INET;
    addr.sin_port = htons(4242);
    addr.sin_addr.s_addr = INADDR_ANY;
    bind(sock, (sockaddr*)&addr, sizeof(addr));
    
    std::cout << "Listening on port 4242...\n";
    
    while (true) {
        TrackingData data;
        int received = recvfrom(sock, (char*)&data, sizeof(data), 
                                0, nullptr, nullptr);
        
        if (received == sizeof(data)) {
            std::cout << "Yaw: " << data.yaw 
                     << "  Pitch: " << data.pitch 
                     << "  Roll: " << data.roll << "\n";
        }
    }
    
    closesocket(sock);
    WSACleanup();
}

Unity C# Example

using UnityEngine;
using System;
using System.Net;
using System.Net.Sockets;
using System.Threading;

public class OpenTrackReceiver : MonoBehaviour
{
    private UdpClient udpClient;
    private Thread receiveThread;
    
    public float yaw, pitch, roll;
    public float x, y, z;
    
    void Start()
    {
        udpClient = new UdpClient(4242);
        receiveThread = new Thread(ReceiveData);
        receiveThread.Start();
    }
    
    void ReceiveData()
    {
        IPEndPoint endpoint = new IPEndPoint(IPAddress.Any, 0);
        
        while (true)
        {
            try
            {
                byte[] data = udpClient.Receive(ref endpoint);
                
                if (data.Length == 48)  // 6 doubles
                {
                    yaw   = BitConverter.ToDouble(data, 0);
                    pitch = BitConverter.ToDouble(data, 8);
                    roll  = BitConverter.ToDouble(data, 16);
                    x     = BitConverter.ToDouble(data, 24);
                    y     = BitConverter.ToDouble(data, 32);
                    z     = BitConverter.ToDouble(data, 40);
                }
            }
            catch (Exception e)
            {
                Debug.LogError("UDP Error: " + e.Message);
            }
        }
    }
    
    void OnDestroy()
    {
        receiveThread?.Abort();
        udpClient?.Close();
    }
    
    void Update()
    {
        // Use tracking data to control camera
        transform.rotation = Quaternion.Euler(-pitch, yaw, -roll);
        transform.position = new Vector3(x/100f, y/100f, z/100f);
    }
}

Data Interpretation

Coordinate System

Rotation (degrees):

Yaw: Left (-) / Right (+)
Pitch: Down (-) / Up (+)
Roll: Left (-) / Right (+)

Position (centimeters):

X: Left (-) / Right (+)
Y: Down (-) / Up (+)
Z: Back (-) / Forward (+)

Typical Value Ranges

Axis	Typical Range	Units
Yaw	-180 to +180	degrees
Pitch	-90 to +90	degrees
Roll	-180 to +180	degrees
X	-30 to +30	cm
Y	-20 to +20	cm
Z	-20 to +20	cm

Actual ranges depend on OpenTrack mapping settings. Users can configure custom ranges.

Troubleshooting

”Can’t bind socket” Error

Cause: Another application is using the port, or permission denied. Solution:

Check if another program is using the port:
- Windows: netstat -ano | findstr :4242
- Linux: netstat -tulpn | grep 4242
Try a different port number
Run OpenTrack as administrator
Check firewall settings

Not Receiving Data

Symptoms: Application receives no UDP packets. Solution:

Verify OpenTrack is sending:
- Check OpenTrack status shows “Running”
- Verify settings show correct IP and port
Check firewall:
- Add exception for OpenTrack
- Allow inbound UDP on chosen port
- Temporarily disable firewall to test
Network connectivity:
- Ping target IP to verify connectivity
- Ensure both PCs on same network
- Check router doesn’t block UDP
Wireshark capture:
- Use Wireshark to verify packets are being sent
- Filter: udp.port == 4242

Wrong Byte Order

Symptoms: Values are nonsensical or extremely large. Cause: Byte order mismatch between sender and receiver. Solution:

OpenTrack sends in host byte order

If sender and receiver have different architectures:

// Convert to network byte order (big-endian)
double value = ...;
uint64_t* ptr = (uint64_t*)&value;
*ptr = htobe64(*ptr);  // Host to big-endian

High Latency

Cause: Network congestion or WiFi interference. Solution:

Use wired Ethernet instead of WiFi
Reduce other network traffic
Check for packet loss with ping statistics
Consider lowering OpenTrack update rate

Packet Loss

Symptoms: Intermittent or choppy tracking. Solution:

UDP doesn’t guarantee delivery - this is normal
For critical applications, implement your own packet numbering
Monitor packet loss rate
Consider TCP if reliability is required (custom implementation needed)

Advanced Usage

Multiple Receivers

Send to multiple destinations:

Use broadcast address:
```
IP: 192.168.1.255
```
Or run multiple OpenTrack instances with different ports
Or implement UDP forwarding in your receiver

Custom Protocol Extension

Add metadata to packets:

# Example: Add timestamp and packet ID
import struct
import time

# Receive OpenTrack data
data, addr = sock.recvfrom(1024)
yaw, pitch, roll, x, y, z = struct.unpack('dddddd', data)

# Add metadata
timestamp = time.time()
packet_id = get_next_packet_id()

# Store or forward with metadata
extended_data = struct.pack('ddddddQI', 
    yaw, pitch, roll, x, y, z, 
    int(timestamp * 1000000), packet_id
)

Data Recording

Record tracking sessions:

import csv
import time

with open('tracking_log.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerow(['timestamp', 'yaw', 'pitch', 'roll', 'x', 'y', 'z'])
    
    while True:
        data, _ = sock.recvfrom(1024)
        if len(data) == 48:
            values = struct.unpack('dddddd', data)
            writer.writerow([time.time()] + list(values))

Performance Characteristics

Bandwidth Usage

At typical 60 Hz update rate:

Packet size: 48 bytes
Packets per second: 60
Bandwidth: ~23 Kbps
With IP/UDP overhead: ~31 Kbps

Very low bandwidth - suitable for network transmission.

Latency

Local (127.0.0.1):

Latency: <1ms
Perfect for same-machine applications

LAN (wired):

Latency: 1-3ms
Excellent for networked setups

LAN (WiFi):

Latency: 5-20ms
May have jitter and packet loss

Internet:

Latency: Varies greatly
Not recommended for real-time use

The UDP protocol provides maximum flexibility for custom applications and development. For standard gaming use cases, prefer FreeTrack or SimConnect protocols for better game compatibility.

Get Started

User Guides

Trackers

Output Protocols

Filters

Advanced

How It Works

Data Format

Use Cases

Custom Applications

Game Development

Research Tools

Visualization

Networked Tracking

Integration Examples

Setup Instructions

Configuration

Default Settings

Network Modes

Receiving Data

Python Example

C++ Example

Unity C# Example

Data Interpretation

Coordinate System

Typical Value Ranges

Troubleshooting

”Can’t bind socket” Error

Not Receiving Data

Wrong Byte Order

High Latency

Packet Loss

Advanced Usage

Multiple Receivers

Custom Protocol Extension

Data Recording

Performance Characteristics

Bandwidth Usage

Latency

Get Started

User Guides

Trackers

Output Protocols

Filters

Advanced

​How It Works

​Data Format

​Use Cases

​Custom Applications

Game Development

Research Tools

Visualization

Networked Tracking

​Integration Examples

​Setup Instructions

​Configuration

​Default Settings

​Network Modes

​Receiving Data

​Python Example

​C++ Example

​Unity C# Example

​Data Interpretation

​Coordinate System

​Typical Value Ranges

​Troubleshooting

​”Can’t bind socket” Error

​Not Receiving Data

​Wrong Byte Order

​High Latency

​Packet Loss

​Advanced Usage

​Multiple Receivers

​Custom Protocol Extension

​Data Recording

​Performance Characteristics

​Bandwidth Usage

​Latency

How It Works

Data Format

Use Cases

Custom Applications

Integration Examples

Setup Instructions

Configuration

Default Settings

Network Modes

Receiving Data

Python Example

C++ Example

Unity C# Example

Data Interpretation

Coordinate System

Typical Value Ranges

Troubleshooting

”Can’t bind socket” Error

Not Receiving Data

Wrong Byte Order

High Latency

Packet Loss

Advanced Usage

Multiple Receivers

Custom Protocol Extension

Data Recording

Performance Characteristics

Bandwidth Usage

Latency