How It Works
Any application can send orientation data to OpenTrack by broadcasting UDP packets to a specified port. The data format is simple: three rotation angles (yaw, pitch, roll) sent as floating-point values. This makes FreePIE UDP ideal for:- Smartphone IMU apps
- Custom tracking solutions
- VR/AR headset integration
- Wireless IMU devices
- Bridge from other tracking software
FreePIE is a programmable input emulator originally designed for VR and motion control. The UDP receiver in OpenTrack follows the same protocol, making it compatible with FreePIE scripts and similar tools.
Requirements
Software
- OpenTrack with FreePIE UDP tracker
- Data source (one of):
- FreePIE with tracking script
- Smartphone app (e.g., FreePIE IMU for Android)
- Custom application sending UDP data
- Another OpenTrack instance (for remote tracking)
Network
- Both devices on same network (or route between them)
- Firewall allowing UDP traffic on configured port
- Low-latency network connection (WiFi or wired)
No special hardware required beyond what your data source needs (e.g., smartphone with gyro/accelerometer).
Setup Instructions
Configure OpenTrack
In OpenTrack tracker settings:The axis indices determine which incoming data channel maps to which rotation.
Configure Firewall
Allow UDP traffic:Windows Firewall:Linux (ufw):Or add exception in your firewall GUI.
Find Your PC's IP Address
Your data source needs to know where to send data:Windows:Linux:Note the IP address (e.g., 192.168.1.100).
Configure Data Source
Option A: FreePIE (PC):Install FreePIE and create a script:Option B: Smartphone App:
- Install “FreePIE IMU” or similar app
- Enter PC’s IP address: 192.168.1.100
- Enter Port: 5555
- Start sending data
Test Connection
- Start OpenTrack with FreePIE UDP tracker
- Start your data source
- Move your tracking device
- Verify OpenTrack receives data (check output window)
- Verify IP address and port
- Check firewall settings
- Ensure both devices on same network
- Test with localhost (127.0.0.1) first
Configuration Options
Network Settings
| Option | Default | Description |
|---|---|---|
| UDP Port | 5555 | Port to listen on for incoming data |
Choose a port between 1024-65535. Avoid commonly used ports. Default 5555 works well.
Axis Mapping
| Option | Default | Description |
|---|---|---|
| Axis X Index | 0 | Which data channel for yaw (0-2) |
| Axis Y Index | 1 | Which data channel for pitch (0-2) |
| Axis Z Index | 2 | Which data channel for roll (0-2) |
Angle Offsets
| Option | Default | Description |
|---|---|---|
| Add Yaw | 0° | Offset added to yaw (heading) |
| Add Pitch | 0° | Offset added to pitch (elevation) |
| Add Roll | 0° | Offset added to roll (bank) |
Axis Index Mapping
Axis Index Mapping
The incoming UDP packet contains 3 float values. Axis indices determine which value maps to which rotation:
- Index 0: First float in packet
- Index 1: Second float in packet
- Index 2: Third float in packet
- Common: X=0, Y=1, Z=2 (yaw, pitch, roll)
- Alternative: X=2, Y=1, Z=0 (roll, pitch, yaw)
UDP Protocol Details
Packet Format
The FreePIE UDP protocol is straightforward:- Endianness: Little-endian (standard on x86/ARM)
- Units: Degrees (not radians)
- Range: Typically -180 to +180 degrees
Example Packet
Sending Data
Python:Use Cases
Smartphone Tracking
Use your phone’s gyro/accelerometer as a wireless head tracker.Apps:
- FreePIE IMU (Android)
- SensorUDP (iOS/Android)
- Custom app with gyro API
Remote Tracking
Track on one PC, send data to another PC running the game.Example:
- Laptop with webcam for tracking
- Desktop PC for gaming
- Send tracking data over LAN
Custom Hardware
Interface custom tracking hardware:
- ESP32 with IMU (wireless)
- Custom VR headset
- Modified game controller
- Experimental sensors
Software Bridge
Bridge from other tracking software:
- Convert SteamVR tracking to OpenTrack
- Relay from mobile tracking apps
- Integrate with Unity/Unreal projects
- Custom processing pipeline
Troubleshooting
No data received
No data received
- Verify IP address is correct
- Check port number matches (5555)
- Test firewall is allowing UDP
- Ensure both devices on same network/subnet
- Try localhost (127.0.0.1) first to verify OpenTrack
- Use Wireshark to verify packets are being sent
Wrong rotation axes
Wrong rotation axes
- Change axis index mapping
- Try all combinations (6 possibilities)
- Check if data source sends radians vs degrees
- Verify data source coordinate system
- Use angle offsets if axes are correct but rotated
High latency or lag
High latency or lag
- Use wired connection instead of WiFi
- Reduce update rate if network congested
- Close bandwidth-heavy applications
- Use 5GHz WiFi if available
- Check for network packet loss
Jittery or unstable
Jittery or unstable
- Enable filtering in OpenTrack filter settings
- Reduce data source noise (sensor fusion)
- Increase update rate for smoother interpolation
- Use Accela filter in OpenTrack
- Check for packet loss
Tracking drifts over time
Tracking drifts over time
- Issue is with data source (gyro drift)
- Use sensor fusion in data source
- Add magnetometer for yaw stability
- Recenter view regularly in OpenTrack
- Not an issue with UDP receiver itself
Advantages and Limitations
Advantages
- Wireless tracking possible
- Very flexible - any data source
- Network-based (can track remotely)
- Simple protocol, easy to implement
- No special hardware required
- Cross-platform compatible
- Low CPU usage
- Great for prototyping
Limitations
- Network latency (WiFi ~20-50ms)
- Rotation only (no position)
- Requires separate data source
- Network reliability affects tracking
- Must configure firewall
- Quality depends on data source
- Possible packet loss
Smartphone Apps
Android
- FreePIE IMU: Original FreePIE companion app
- SensorUDP: Sends various sensor data via UDP
- IP Webcam: Can send motion data alongside video
iOS
- SensorLog: Logs and streams sensor data
- UDP Sender: Generic UDP data sender
- Custom apps using Core Motion API
Most apps let you configure IP address, port, and update rate. Use 50-100Hz for smooth tracking.
ESP32 Wireless IMU Example
Comparison with Other Trackers
| Feature | FreePIE UDP | HATire | PointTracker |
|---|---|---|---|
| Tracking type | Rotation only | Rotation only | 6DOF |
| Connection | UDP/WiFi | Serial/USB | USB camera |
| Wireless | Yes | Optional | No |
| Latency | Medium (20-50ms) | Low (20ms) | Very Low (10ms) |
| Flexibility | Very High | Medium | Low |
| DIY friendly | Yes | Yes | Some |
| Cost | Varies | Very Low | Low-Medium |
Tips for Best Results
- Network: Use wired Ethernet or 5GHz WiFi for lowest latency
- Update Rate: 50-100Hz is sweet spot (more = higher bandwidth)
- Filtering: Enable filtering in OpenTrack to smooth network jitter
- Data Source: Use good sensor fusion algorithm for stable orientation
- Local First: Test on localhost before trying wireless
- Firewall: Add permanent firewall rule instead of temporary
- QoS: Enable QoS on router to prioritize UDP tracking packets
See Also
- HATire - Wired IMU tracking via serial
- NeuralNet - Camera-based, no markers
- Hardware Guide - General hardware information