# HID Device Analyzer

A focused C++ tool for analyzing HID devices, particularly those used in VR systems like the Valve Index and HTC Vive.

## Features

- Detect and connect to HID devices
- Read raw HID reports from these devices
- Analyze and display the report IDs and raw buffer data
- Help identify the exact offsets for accelerometer and gyroscope XYZ values
- Support for Windows (with partial support for Linux and macOS)

## Purpose

This tool was created to help identify the exact structure of HID reports from lighthouse devices. The current implementation in the lighthouse driver wrapper makes assumptions about:

- Report ID 0x01 for IMU data
- Hardcoded buffer offsets (1-12) for extracting IMU data
- No parsing of the HID report descriptor

This tool helps verify these assumptions and identify the correct offsets for different devices.

## Building

### Prerequisites

- CMake 3.10 or higher
- C++ compiler with C++14 support
- Windows: Visual Studio 2017 or higher
- Linux: GCC 5.0 or higher
- macOS: Xcode command line tools

### Windows

```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
```

### Linux

```bash
mkdir build
cd build
cmake ..
make
```

### macOS

```bash
mkdir build
cd build
cmake ..
make
```

## Usage

```
HID Device Analyzer - A tool to analyze HID devices and their reports
Usage:
  -h, --help                 Show this help message
  -l, --list                 List all HID devices
  -v, --valve                List only Valve HID devices (VID: 0x28DE)
  -d, --device <path>        Open a specific device by path
  -r, --read <count>         Read a number of reports from the device
  -i, --id <report_id>       Specify the report ID to read (default: 0)
  -a, --analyze              Analyze the read reports to identify patterns
  -p, --print-descriptor     Print the HID report descriptor

Examples:
  hid_analyzer --list                     # List all HID devices
  hid_analyzer --valve                    # List only Valve HID devices
  hid_analyzer --device "HID\VID_28DE&PID_2101\123456" --print-descriptor  # Print the report descriptor for a specific device
  hid_analyzer --device "HID\VID_28DE&PID_2101\123456" --read 10 --id 1 --analyze  # Read 10 reports with ID 1 and analyze them
```

## Example Workflow

1. List all Valve HID devices:
   ```
   hid_analyzer --valve
   ```

2. Print the report descriptor for a specific device:
   ```
   hid_analyzer --device "HID\VID_28DE&PID_2101\123456" --print-descriptor
   ```

3. Read 10 reports with ID 1 and analyze them:
   ```
   hid_analyzer --device "HID\VID_28DE&PID_2101\123456" --read 10 --id 1 --analyze
   ```

4. Try different report IDs to find which ones contain IMU data:
   ```
   hid_analyzer --device "HID\VID_28DE&PID_2101\123456" --read 5 --id 0 --analyze
   hid_analyzer --device "HID\VID_28DE&PID_2101\123456" --read 5 --id 1 --analyze
   hid_analyzer --device "HID\VID_28DE&PID_2101\123456" --read 5 --id 2 --analyze
   ```

## Understanding the Output

When analyzing reports, the tool will:

1. Group reports by report ID
2. Check which bytes change between reports
3. Identify potential 16-bit values (common for IMU data)
4. Look for patterns of 3 consecutive 16-bit values (X, Y, Z)
5. Display possible interpretations of the data

For example, if bytes 1-6 change between reports and form 3 consecutive 16-bit values, they might represent accelerometer data. Similarly, bytes 7-12 might represent gyroscope data.

## Limitations

- Windows implementation is more complete than Linux/macOS
- Direct access to raw report descriptors is limited on Windows
- Some devices may require specific initialization before sending meaningful data

## License

This project is licensed under the MIT License - see the LICENSE file for details.