> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opentrack/opentrack/llms.txt
> Use this file to discover all available pages before exploring further.

# FSUIPC

> Legacy protocol for Microsoft Flight Simulator 2002 and 2004

FSUIPC (FS Universal Inter-Process Communication) is a legacy protocol for Microsoft Flight Simulator 2002 and 2004. It provides head tracking by writing camera control data to FSUIPC memory offsets.

<Warning>
  **This protocol is for legacy simulators only.**

  For modern flight simulators, use:

  * **FSX/Prepar3D**: SimConnect protocol
  * **MSFS 2020/2024**: FreeTrack protocol
  * **X-Plane**: FreeTrack with plugin
</Warning>

## How It Works

The FSUIPC protocol:

1. Opens a connection to FSUIPC using `FSUIPC_Open()`
2. Verifies the simulator version is FS2002 or FS2004
3. Writes head tracking data to FSUIPC memory offsets:
   * `0x3110` - Pitch, Yaw, Roll control values
   * `0x832E` - Zoom/FOV value
4. Processes all writes with `FSUIPC_Process()`

<Note>
  **Position tracking (X/Y) is not supported** in FS2002/2004 via FSUIPC. Only rotations (pitch, yaw, roll) and zoom are available.
</Note>

## Compatible Simulators

<CardGroup cols={2}>
  <Card title="Microsoft Flight Simulator 2002" icon="plane">
    Requires FSUIPC installed
  </Card>

  <Card title="Microsoft Flight Simulator 2004" icon="plane-departure">
    A Century of Flight - Requires FSUIPC installed
  </Card>
</CardGroup>

## Prerequisites

### FSUIPC Module Required

The FSUIPC protocol requires FSUIPC to be installed in your simulator:

<Steps>
  <Step title="Download FSUIPC">
    Download FSUIPC from [http://www.schiratti.com/dowson.html](http://www.schiratti.com/dowson.html)

    Get the version appropriate for your simulator:

    * **FS2002**: FSUIPC 2.x
    * **FS2004**: FSUIPC 3.x
  </Step>

  <Step title="Install FSUIPC">
    Run the FSUIPC installer and follow the installation wizard. It will automatically detect your simulator installation.
  </Step>

  <Step title="Verify installation">
    Launch your simulator and check that FSUIPC loads. You should see an FSUIPC menu item in the simulator.
  </Step>
</Steps>

## Setup Instructions

<Steps>
  <Step title="Install FSUIPC">
    Follow the prerequisites section above to install FSUIPC in your simulator.
  </Step>

  <Step title="Select FSUIPC protocol">
    In OpenTrack, go to the **Output** dropdown and select **"FSUIPC -- Microsoft FS2002/FS2004"**.
  </Step>

  <Step title="Start OpenTrack">
    Click **Start** in OpenTrack. The protocol will wait for the simulator to launch.
  </Step>

  <Step title="Launch simulator">
    Start Microsoft Flight Simulator 2002 or 2004. OpenTrack will automatically connect via FSUIPC.
  </Step>

  <Step title="Verify tracking">
    In the simulator cockpit view, move your head. The view should rotate accordingly.
  </Step>
</Steps>

## Data Format

### Control Structure

```cpp theme={null}
#pragma pack(push,1)
struct state {
    int Control;  // Control identifier
    int Value;    // Value of DOF
};
#pragma pack(pop)
```

### FSUIPC Memory Offsets

| Offset   | Size    | Description              |
| -------- | ------- | ------------------------ |
| `0x3110` | 8 bytes | Camera control structure |
| `0x832E` | 2 bytes | Zoom/FOV value           |

### Control Identifiers

```cpp theme={null}
Pitch Control ID: 66503
Yaw Control ID:   66504  
Roll Control ID:  66505
```

## Coordinate Transformations

OpenTrack data is converted for FSUIPC:

```cpp theme={null}
// Scale function: maps [-180, 180] degrees to [-16383, 16383]
int scale(double value) {
    // Clamp to range
    if (value > 180)  value = 180;
    if (value < -180) value = -180;
    
    // Scale to FSUIPC range
    return (int)((16383 * value) / 180);
}

// Rotation values
pitch.Control = 66503;
pitch.Value = scale(-headpose[Pitch]);  // Negated

yaw.Control = 66504;
yaw.Value = scale(headpose[Yaw]);

roll.Control = 66505;
roll.Value = scale(headpose[Roll]);

// Zoom from Z position
WORD zoom = (WORD)(headpose[TZ] + 64);
```

## Limitations

<Warning>
  ### Known Limitations

  1. **No position tracking**: X and Y position are not available in FS2002/2004
  2. **Rotation only**: Only pitch, yaw, roll are transmitted
  3. **Limited zoom control**: Z position is mapped to FOV/zoom only
  4. **4 DOF instead of 6 DOF**: Not true 6-degree-of-freedom tracking
  5. **Legacy versions only**: Does not work with FSX or newer
</Warning>

## Troubleshooting

### Connection Fails

**Cause**: FSUIPC not installed or not running.

**Solution**:

1. Verify FSUIPC is installed in your simulator
2. Check FSUIPC appears in simulator menu
3. Ensure simulator is actually running (not just on menu screen)
4. Try running OpenTrack as administrator

### Version Mismatch Error

**Symptoms**: OpenTrack connects but tracking doesn't work.

**Cause**: Simulator version is not FS2002 or FS2004.

**Solution**:

* For **FSX/Prepar3D**: Use SimConnect protocol instead
* For **MSFS 2020**: Use FreeTrack protocol instead
* Verify you're actually running FS2002 or FS2004

### Tracking Is Choppy

**Cause**: FSUIPC write frequency issues.

**Solution**:

* Reduce OpenTrack filter smoothing
* Check CPU usage - ensure simulator has enough resources
* Verify FSUIPC is up to date

### View Rotates Wrong Direction

**Cause**: Axis inversion needed.

**Solution**:

1. In OpenTrack mapping settings, invert the problematic axis
2. Adjust output ranges to match your preference
3. The protocol negates pitch automatically; may need to adjust mapping

## FSUIPC Connection Details

### Connection Lifecycle

```cpp theme={null}
// Open connection
FSUIPC_Open(SIM_ANY, &result);

// Check version
if (FSUIPC_FS_Version == SIM_FS2K2 || 
    FSUIPC_FS_Version == SIM_FS2K4) {
    
    // Write tracking data
    FSUIPC_Write(0x3110, 8, &pitch, &result);
    FSUIPC_Write(0x3110, 8, &yaw, &result);
    FSUIPC_Write(0x3110, 8, &roll, &result);
    FSUIPC_Write(0x832E, 2, &zoom, &result);
    
    // Process all writes
    FSUIPC_Process(&result);
}

// Close on error
if (result == FSUIPC_ERR_SENDMSG) {
    FSUIPC_Close();
}
```

### Error Handling

The protocol handles these FSUIPC errors:

* `FSUIPC_ERR_OK` - Success
* `FSUIPC_ERR_OPEN` - Already open (not an error)
* `FSUIPC_ERR_SENDMSG` - Communication failed (triggers close)

## Migration Guide

### Upgrading From FS2004

If upgrading to a newer simulator:

<Steps>
  <Step title="Identify new simulator">
    * **FSX or Prepar3D**: Install SimConnect SDK
    * **MSFS 2020/2024**: No special requirements
    * **X-Plane**: Install head tracking plugin
  </Step>

  <Step title="Change OpenTrack protocol">
    * **FSX/P3D**: Select "Microsoft FSX SimConnect"
    * **MSFS 2020**: Select "freetrack 2.0 Enhanced"
    * **X-Plane**: Select "freetrack 2.0 Enhanced"
  </Step>

  <Step title="Reconfigure settings">
    Each protocol has different configuration options. Follow the setup guide for your new protocol.
  </Step>

  <Step title="Test and adjust">
    New simulators have full 6DOF support. You may need to adjust mapping ranges for position tracking.
  </Step>
</Steps>

## Technical Details

### FSUIPC Control System

FSUIPC uses a control-value pair system:

* **Control**: Identifier specifying which parameter to change
* **Value**: Scaled integer value representing the change amount

### Value Scaling

The protocol scales rotation values from ±180° to ±16383:

```
FSUIPC_Value = (16383 × degrees) / 180
```

This provides adequate resolution for smooth head tracking:

* **Resolution**: \~0.011° per step
* **Range**: -180° to +180°

### Write Batching

FSUIPC batches writes for efficiency:

1. Multiple `FSUIPC_Write()` calls are queued
2. Single `FSUIPC_Process()` sends all changes
3. Reduces IPC overhead

<Note>
  **Historical Note**: FSUIPC was the primary way to add head tracking to early flight simulators before native SDK support existed. While now superseded by modern protocols, it remains functional for enthusiasts running classic FS2002/2004.
</Note>

## Alternative Solutions

If you're still using FS2002/2004, consider:

1. **Upgrading simulator**: Modern simulators have better graphics, aircraft, and full 6DOF support
2. **Using FSX Steam Edition**: Available affordably, uses SimConnect
3. **Trying DCS World**: Free-to-play with excellent VR/TrackIR support
4. **X-Plane 11/12**: Modern, cross-platform with good head tracking