# Sauna OpenVR Driver

## Project Overview

Sauna is a custom OpenVR driver that provides access to IMU (Inertial Measurement Unit) data when optical tracking is lost. It extends the standard OpenVR tracking capabilities to create a more resilient VR experience by utilizing IMU data to maintain tracking even when traditional optical tracking methods fail.

## Problem Statement

Standard VR tracking systems rely heavily on optical tracking (cameras, base stations, etc.) to determine the position and orientation of VR devices. However, optical tracking can fail in various scenarios:

- When line of sight to tracking cameras or base stations is blocked
- In environments with poor lighting conditions
- When reflective surfaces interfere with tracking
- During fast movements that optical systems struggle to track

When optical tracking fails, standard VR systems typically lose tracking completely, resulting in a poor user experience with frozen or drifting virtual objects.

## Solution Overview

The Sauna driver addresses this problem by:

1. Wrapping the existing OpenVR lighthouse driver
2. Providing access to raw IMU data (accelerometer and gyroscope)
3. Implementing fallback tracking using IMU data when optical tracking is lost
4. Exposing a custom interface for applications to access IMU data directly

This approach creates a more resilient tracking system that can maintain at least rotational tracking during optical tracking failures, significantly improving the VR experience in challenging environments.

## Architecture

The Sauna driver consists of several key components that work together to provide resilient tracking:

```mermaid
graph TD
    A[SteamVR] --> B[OpenVR API]
    B --> C[Sauna Driver]
    C --> D[Lighthouse Driver Wrapper]
    C --> E[IMU Data Provider]
    C --> F[Sauna Device Driver]
    D --> G[Original Lighthouse Driver]
    F --> H[IVRIMUComponent Interface]
    E --> F
    
    subgraph "Applications"
        I[VR Application] --> B
        I --> H
    end
    
    subgraph "Hardware"
        G --> J[VR Headset/Controllers]
        E --> J
    end
```

### IMU Data Flow

The following sequence diagram illustrates how IMU data flows through the system, especially when optical tracking is lost:

```mermaid
sequenceDiagram
    participant VR Hardware
    participant IMUDataProvider
    participant SaunaDeviceDriver
    participant Application
    
    Note over SaunaDeviceDriver: Optical tracking active
    VR Hardware->>SaunaDeviceDriver: Provide tracking data
    SaunaDeviceDriver->>Application: Normal pose updates
    
    VR Hardware->>IMUDataProvider: Provide IMU data
    IMUDataProvider->>SaunaDeviceDriver: Store IMU data
    
    Note over SaunaDeviceDriver: Optical tracking lost
    VR Hardware--xSaunaDeviceDriver: Tracking data unavailable
    SaunaDeviceDriver->>IMUDataProvider: Request latest IMU data
    IMUDataProvider->>SaunaDeviceDriver: Provide IMU data
    SaunaDeviceDriver->>SaunaDeviceDriver: Integrate IMU data
    SaunaDeviceDriver->>Application: Fallback pose updates
    
    Application->>SaunaDeviceDriver: GetIMUDataInFallbackMode()
    SaunaDeviceDriver->>IMUDataProvider: GetLatestIMUSample()
    IMUDataProvider->>SaunaDeviceDriver: IMU sample
    SaunaDeviceDriver->>Application: Raw IMU data
```

## Implementation Details

### Core Components

1. **SaunaDeviceProvider** (`driver_sauna.cpp`)
   - Main entry point for the driver
   - Initializes and manages the lighthouse driver wrapper and IMU data provider
   - Handles OpenVR driver lifecycle events

2. **LighthouseDriverWrapper** (`lighthouse_driver_wrapper.h/cpp`)
   - Loads and communicates with the existing lighthouse driver
   - Forwards calls to the lighthouse driver while adding custom functionality

3. **IMUDataProvider** (`imu_data_provider.h/cpp`)
   - Collects and manages IMU data from tracked devices
   - Provides access to IMU data through a simple interface

4. **SaunaDeviceDriver** (`sauna_device_driver.h/cpp`)
   - Wraps existing device drivers to add IMU functionality
   - Implements the custom IVRIMUComponent interface
   - Integrates IMU data when optical tracking is lost

5. **IVRIMUComponent** (defined in `sauna_device_driver.h`)
   - Custom interface for applications to access IMU data
   - Provides methods to get IMU data even when optical tracking is lost

### Key Features

- **Seamless Integration**: Works alongside the existing lighthouse driver without requiring modifications to it
- **Fallback Tracking**: Automatically switches to IMU-based tracking when optical tracking is lost
- **Custom API**: Provides a simple interface for applications to access raw IMU data
- **Minimal Performance Impact**: Designed to have minimal impact on VR performance

## Testing Approach

The Sauna driver includes a comprehensive testing framework to ensure reliability and performance:

1. **Unit Tests**: Verify that each component works correctly in isolation
2. **Integration Tests**: Verify that the complete driver works with SteamVR
3. **Performance Tests**: Measure CPU usage, memory usage, latency impact, and IMU data throughput
4. **Validation Tests**: Verify IMU data is available when optical tracking is lost

See the [Testing Guide](docs/testing_guide.md) for more details on the testing framework.

## Quick Start Guide

### Installation

1. Build the driver using the provided build script:
   ```
   cd drivers\sauna
   build.bat
   ```

2. Copy the built driver files to the SteamVR drivers directory:
   ```
   copy bin\win64\* "[SteamVR installation path]\drivers\sauna\"
   ```

3. Restart SteamVR to load the driver

### Usage

The driver will automatically activate when SteamVR starts. No additional configuration is required for basic functionality.

For applications that want to access IMU data directly, see the [API Documentation](docs/api_documentation.md).

## Documentation

- [Developer Guide](docs/developer_guide.md): Detailed information for developers
- [User Guide](docs/user_guide.md): Installation and usage instructions for end users
- [API Documentation](docs/api_documentation.md): Documentation for the custom IMU interface
- [Testing Guide](docs/testing_guide.md): Information about the testing framework