# Roadmap: Beyond 2 SteamVR Proximity Driver

## Overview

This roadmap delivers a SteamVR sidecar driver that reads the Beyond 2 proximity sensor over USB HID and exposes standby/wake behavior to SteamVR. The first three phases validate feasibility of the sidecar approach (driver coexistence, HID access, and proximity-triggered standby/wake) before any feature work begins. Phases 4-6 build the core data pipeline from raw HID bytes through proximity algorithm to SteamVR integration. Phases 7-8 add user configuration and production robustness.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [x] **Phase 1: Skeleton Driver and Coexistence** - Minimal driver DLL loads in SteamVR alongside lighthouse driver without breaking HMD
- [x] **Phase 2: HID Access Validation** - Driver opens Beyond 2 proprietary HID device without contention (completed 2026-03-22)
- [ ] **Phase 3: Proximity Component Spike** - Sidecar /proximity component triggers SteamVR standby/wake for lighthouse HMD
- [ ] **Phase 4: HID Data Pipeline** - Reliable reading of periodic proximity reports and calibration parameters
- [ ] **Phase 5: Proximity Algorithm** - Firmware-equivalent proximity detection with moving average and hysteresis
- [ ] **Phase 6: Standby/Wake Integration** - End-to-end proximity detection wired to SteamVR standby/wake
- [x] **Phase 7: Configuration** - User-tunable settings via steamvr.vrsettings (completed 2026-03-23)
- [ ] **Phase 8: Robustness and Logging** - Crash safety, graceful degradation, and state-change logging

## Phase Details

### Phase 1: Skeleton Driver and Coexistence
**Goal**: A minimal sidecar driver loads in SteamVR and coexists with the built-in lighthouse driver without affecting existing HMD functionality
**Depends on**: Nothing (first phase)
**Requirements**: DRIV-01, DRIV-02, DRIV-03, DRIV-04, FEAS-01
**Success Criteria** (what must be TRUE):
  1. Driver DLL builds with CMake/MSVC and produces a valid SteamVR driver package (DLL + manifest in correct directory structure)
  2. SteamVR loads the driver on startup without errors in vrserver log (HmdDriverFactory called, Init succeeds)
  3. Driver registers a tracked device via TrackedDeviceAdded
  4. Beyond 2 tracking, display, and audio continue working identically to before the driver was installed
**Plans:** 2 plans
Plans:
- [x] 01-01-PLAN.md -- Project scaffold, OpenVR SDK, driver source code, and build
- [x] 01-02-PLAN.md -- Driver registration, verification scripts, and coexistence validation

### Phase 2: HID Access Validation
**Goal**: Driver can open the Beyond 2 proprietary HID device from within vrserver.exe while SteamVR and Bigscreen companion app are running
**Depends on**: Phase 1
**Requirements**: FEAS-02, FEAS-04, HID-01
**Success Criteria** (what must be TRUE):
  1. Driver successfully calls hid_open() for the Beyond 2 proprietary HID interface (VID 0x35BD, PID 0x0101) from within vrserver.exe
  2. HID device remains accessible when Bigscreen companion app is also running (no contention)
  3. Driver manifest hmd_presence targets the correct HID interface (proprietary, not lighthouse tracking)
**Plans:** 2/2 plans complete
Plans:
- [x] 02-01-PLAN.md -- Vendor HIDAPI, CMake integration, HidDevice RAII wrapper, DeviceProvider HID lifecycle
- [x] 02-02-PLAN.md -- HID verification script and hardware validation checkpoint

### Phase 3: Proximity Component Spike
**Goal**: A /proximity boolean component on the sidecar driver triggers SteamVR standby/wake for the lighthouse-owned HMD device
**Depends on**: Phase 2
**Requirements**: FEAS-03, INTG-01
**Success Criteria** (what must be TRUE):
  1. Driver creates /proximity boolean component via IVRDriverInput::CreateBooleanComponent
  2. Toggling the /proximity component (hardcoded true/false for testing) causes SteamVR to enter and exit standby for the Beyond 2 HMD
  3. If sidecar /proximity does NOT trigger standby/wake, the failure is documented with specific behavior observed, and fallback approach is identified
**Plans:** 2/2 plans complete
Plans:
- [x] 03-01-PLAN.md -- Driver /proximity component, named pipe server, and beyond_prox_ctl CLI tool
- [x] 03-02-PLAN.md -- Proximity verification script and hardware validation checkpoint

### Phase 03.1: Remove Virtual Tracker (INSERTED)

**Goal:** Driver runs without registering a GenericTracker device — proximity triggers HMD standby/wake via direct HMD property write only
**Depends on:** Phase 3
**Success Criteria** (what must be TRUE):
  1. No TrackedDeviceAdded call — no device appears in SteamVR device list from this driver
  2. SetBoolProperty(Prop_ContainsProximitySensor_Bool) on HMD container still prevents dashboard reset (fallback1 behavior preserved)
  3. Named pipe commands (`proximity on/off`, `status`, `fallback1 on/off`) still work
  4. HID device open (Phase 2 functionality) still works
  5. ProximityDevice class and ITrackedDeviceServerDriver implementation removed
**Plans:** 2/2 plans complete
Plans:
- [x] 03.1-01-PLAN.md -- Remove ProximityDevice, promote HMD property write, rewire pipe commands
- [x] 03.1-02-PLAN.md -- Updated verification script and hardware validation checkpoint

### Phase 03.2: Integrate into Official Beyond Driver Package (INSERTED)

**Goal:** Driver builds and deploys as part of the official Bigscreen Beyond driver package instead of a standalone sidecar
**Depends on:** Phase 3.1
**Success Criteria** (what must be TRUE):
  1. driver.vrdrivermanifest updated: resourceOnly=false, alwaysActivate=true
  2. Build outputs DLL to correct path within Beyond driver directory structure (bin/win64/)
  3. Driver loads from the official Beyond driver directory in SteamVR
  4. HMD property write (proximity on/off) still prevents dashboard reset
  5. HID access still works from the integrated driver
  6. Existing Beyond driver resources (icons) still load correctly
  7. Standalone sidecar registration removed (no duplicate driver)
**Plans:** 2/2 plans complete
Plans:
- [x] 03.2-01-PLAN.md -- Retarget CMake to bigscreenbeyond, create manifest, deploy script, update verification scripts
- [x] 03.2-02-PLAN.md -- Integration verification script and hardware validation checkpoint

### Phase 4: HID Data Pipeline
**Goal**: Driver reliably reads raw proximity data and calibration parameters from the Beyond 2 over USB HID
**Depends on**: Phase 2
**Requirements**: HID-02, HID-03, HID-04, HID-05
**Success Criteria** (what must be TRUE):
  1. Driver reads periodic HID reports and extracts raw prox_distance (uint16, big-endian from bytes 4-5 of '#' header reports)
  2. Driver reads calibration parameters (programmed_cal, proximity_threshold, proximity_hysteresis, user_trim) from HID feature reports on startup
  3. Driver adjusts HID report rate from default 1000ms to configured value via feature report command 'R'
  4. Driver survives USB cable disconnect and reconnect without crashing vrserver.exe (reconnects and resumes reading)
**Plans:** 2 plans
Plans:
- [ ] 04-01-PLAN.md -- User signature TLV parser, HidDevice reader thread, feature reports, calibration, reconnect
- [ ] 04-02-PLAN.md -- DeviceProvider wiring, verification script, and hardware validation checkpoint

### Phase 5: Proximity Algorithm
**Goal**: Driver computes person_detected boolean using the same algorithm as the Beyond 2 firmware
**Depends on**: Phase 4
**Requirements**: PROX-01, PROX-02, PROX-03, PROX-04, PROX-05, PROX-06
**Success Criteria** (what must be TRUE):
  1. Driver subtracts programmed_cal from raw prox_distance (clamping to 0), rejects samples outside valid range (100-16383), and maintains a 16-sample moving average
  2. person_detected transitions to true when averaged value >= (threshold + user_trim + hysteresis), and to false when averaged value <= (threshold + user_trim - hysteresis)
  3. Effective threshold (threshold + user_trim) is clamped to >= 0 for negative user_trim values
  4. Proximity state does not flicker when sensor reads are near the threshold boundary (hysteresis prevents oscillation)
**Plans:** 2 plans
Plans:
- [ ] 05-01-PLAN.md -- ProximityAlgorithm class (firmware port), HidDevice integration, CMake update
- [ ] 05-02-PLAN.md -- DeviceProvider status diagnostics, verification script, hardware validation

### Phase 6: Standby/Wake Integration
**Goal**: SteamVR automatically enters standby when the headset is removed and wakes when put on, driven by the proximity algorithm
**Depends on**: Phase 3, Phase 5
**Requirements**: INTG-02, INTG-03, INTG-04, INTG-05
**Success Criteria** (what must be TRUE):
  1. Driver updates /proximity component only on person_detected state changes (not every frame)
  2. SteamVR display turns off within configured timeout after removing the headset from head
  3. SteamVR display turns on when putting the headset on head
  4. Games and applications can query proximity state via IVRSystem::GetTrackedDeviceActivityLevel() and Prop_ContainsProximitySensor_Bool
**Plans:** 2 plans
Plans:
- [ ] 06-01-PLAN.md -- RunFrame algorithm wiring, manual override flag, pipe command extensions, CLI update
- [ ] 06-02-PLAN.md -- Verification script and hardware validation checkpoint

### Phase 7: Configuration
**Goal**: Developer-tunable settings (report_rate_ms, log_verbosity, moving_avg_length) read from steamvr.vrsettings on startup
**Depends on**: Phase 6
**Requirements**: CONF-01, CONF-02, CONF-03
**Success Criteria** (what must be TRUE):
  1. Driver reads report rate and threshold trim settings from steamvr.vrsettings on startup
  2. Driver syncs user_trim from HMD user flash on startup, falling back to 0 for older firmware that lacks user_trim
  3. User can adjust proximity sensitivity by changing user_trim offset in steamvr.vrsettings, and the change takes effect on next driver startup
**Plans:** 2/2 plans complete
Plans:
- [ ] 07-01-PLAN.md -- VRSettings read, ProximityAlgorithm parameterization, HidDevice verbose logging, status output extension
- [ ] 07-02-PLAN.md -- Verification script and hardware validation checkpoint

### Phase 8: Robustness and Logging
**Goal**: Driver operates reliably in production conditions without crashing SteamVR or losing functionality
**Depends on**: Phase 6
**Requirements**: RBST-01, RBST-02, RBST-03, RBST-04
**Success Criteria** (what must be TRUE):
  1. If HID device cannot be opened on startup, driver continues running with proximity features silently disabled (tracking, display, audio unaffected)
  2. Driver logs proximity state changes (on-head/off-head transitions) to SteamVR driver log without logging raw values on every sample
  3. Driver logs errors and warnings (HID open failure, calibration read failure, USB disconnect) to SteamVR driver log
  4. Driver does not crash vrserver.exe under any circumstance: HID errors, null pointers, USB disconnect during read, malformed reports
**Plans:** 2 plans
Plans:
- [ ] 08-01-PLAN.md -- Crash prevention, null guards, safe arithmetic, logging format, status response
- [ ] 08-02-PLAN.md -- Verification script and hardware validation checkpoint

## Progress

**Execution Order:**
Phases execute in numeric order: 1 > 2 > 3 > 3.1 > 3.2 > 4 > 5 > 6 > 7 > 8
Note: Phase 4 can begin after Phase 2. Phase 6 requires both Phase 3 and Phase 5. Phases 7 and 8 are independent of each other.

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Skeleton Driver and Coexistence | 2/2 | Complete | 2026-03-21 |
| 2. HID Access Validation | 2/2 | Complete   | 2026-03-22 |
| 3. Proximity Component Spike | 2/2 | Complete | 2026-03-22 |
| 3.1 Remove Virtual Tracker | 2/2 | Complete   | 2026-03-22 |
| 3.2 Integrate into Official Beyond Driver Package | 2/2 | Complete | 2026-03-22 |
| 4. HID Data Pipeline | 0/2 | Not started | - |
| 5. Proximity Algorithm | 0/2 | Not started | - |
| 6. Standby/Wake Integration | 0/2 | Not started | - |
| 7. Configuration | 2/2 | Complete   | 2026-03-23 |
| 8. Robustness and Logging | 0/2 | Not started | - |
| 9. Installer for tester distribution | 2/2 | Complete | 2026-03-23 |

### Phase 9: Installer for tester distribution

**Goal:** Testers can install the BeyondProximity driver into their existing Bigscreen Beyond Driver package via a single-click .exe installer
**Requirements**: DIST-01, DIST-02
**Depends on:** Phase 8
**Plans:** 2/2 plans complete

Plans:
- [x] 09-01-PLAN.md -- Inno Setup script, CMake git versioning, and package target
- [x] 09-02-PLAN.md -- Verification script and hardware validation checkpoint