# Requirements Archive: v1.0 Beyond 2 SteamVR Proximity Driver

**Archived:** 2026-03-23
**Status:** SHIPPED

For current requirements, see `.planning/REQUIREMENTS.md`.

---

# Requirements: Beyond 2 SteamVR Proximity Driver

**Defined:** 2026-03-20
**Core Value:** SteamVR and OpenVR applications can detect when the Beyond 2 is on or off the user's head

## v1 Requirements

### Feasibility Validation

- [x] **FEAS-01**: Sidecar driver loads in SteamVR alongside built-in generic driver without breaking existing HMD functionality (tracking, display, audio)
- [x] **FEAS-02**: Driver can open Beyond 2 proprietary HID device (VID 0x35BD, PID 0x0101) from within vrserver.exe without contention with built-in driver or Bigscreen client
- [x] **FEAS-03**: Sidecar driver's `/proximity` component triggers SteamVR standby/wake for the lighthouse-owned HMD device
- [x] **FEAS-04**: Driver manifest `hmd_presence` can target the proprietary HID interface (separate from lighthouse HID device on the Beyond USB hub chain)

### Driver Foundation

- [x] **DRIV-01**: Driver DLL exports `HmdDriverFactory` and implements `IServerTrackedDeviceProvider` (Init, Cleanup, RunFrame)
- [x] **DRIV-02**: Driver includes `driver.vrdrivermanifest` with correct name, directory, and auto-activation via `hmd_presence` VID/PID
- [x] **DRIV-03**: Driver registers a tracked device via `TrackedDeviceAdded` with appropriate device class
- [x] **DRIV-04**: Driver uses `alwaysActivate: true` to load as sidecar alongside built-in driver

### HID Communication

- [x] **HID-01**: Driver opens Beyond 2 proprietary HID device using HIDAPI in shared mode
- [x] **HID-02**: Driver reads periodic HID reports (header '#', bytes 4-5 = uint16 big-endian prox_distance)
- [x] **HID-03**: Driver reads calibration parameters from HID feature reports on startup: programmed_cal, proximity_threshold, proximity_hysteresis, user_trim (if available)
- [x] **HID-04**: Driver adjusts HID report rate from default 1000ms to a configurable value (default 100ms) via HID feature report command 'R'
- [x] **HID-05**: Driver handles HID device disconnection and reconnection gracefully without crashing vrserver.exe

### Proximity Detection

- [x] **PROX-01**: Driver computes proximity distance by subtracting programmed_cal offset from raw prox_distance (clamping to 0 if raw <= cal)
- [x] **PROX-02**: Driver validates raw samples against MIN_PROX_VALUE (100) and MAX_PROX_VALUE (16383) bounds before processing
- [x] **PROX-03**: Driver maintains 16-sample moving average of calibrated proximity distance values
- [x] **PROX-04**: Driver detects person_detected = true when averaged value >= (threshold + user_trim + hysteresis)
- [x] **PROX-05**: Driver detects person_detected = false when averaged value <= (threshold + user_trim - hysteresis)
- [x] **PROX-06**: Driver clamps effective threshold (threshold + user_trim) to >= 0 to handle negative user_trim values

### SteamVR Integration

- [x] **INTG-01**: Driver creates `/proximity` boolean component via `IVRDriverInput::CreateBooleanComponent`
- [x] **INTG-02**: Driver updates `/proximity` component via `UpdateBooleanComponent` when person_detected state changes
- [x] **INTG-03**: SteamVR auto-enters standby when headset is removed (proximity false for configured timeout)
- [x] **INTG-04**: SteamVR auto-wakes when headset is put on (proximity true)
- [x] **INTG-05**: Games/applications can query proximity state via `IVRSystem::GetTrackedDeviceActivityLevel()` and `Prop_ContainsProximitySensor_Bool`

### Configuration

- [x] **CONF-01**: Driver reads settings from `steamvr.vrsettings` on startup (report rate, threshold trim)
- [x] **CONF-02**: Driver syncs user_trim from HMD user flash on startup, falling back to 0 if not available (older firmware compatibility)
- [x] **CONF-03**: User can adjust proximity sensitivity via user_trim offset in steamvr.vrsettings

### Robustness

- [x] **RBST-01**: Driver continues functioning (tracking, display, audio unaffected) even if HID device cannot be opened; proximity features silently disabled
- [x] **RBST-02**: Driver logs proximity state changes (on-head/off-head transitions) to SteamVR driver log without spamming raw values
- [x] **RBST-03**: Driver logs errors and warnings (HID open failure, calibration read failure, disconnection events) to SteamVR driver log
- [x] **RBST-04**: Driver does not crash vrserver.exe under any circumstance (HID errors, null pointers, USB disconnect during read)

## v2 Requirements

### Distribution

- [x] **DIST-01**: Driver packaged as installer compatible with Bigscreen's existing Beyond driver package pipeline
- [x] **DIST-02**: Driver registered with SteamVR via `vrpathreg` or equivalent mechanism during installation

### IPC Bridge (Contingent)

- **IPC-01**: If direct HID access from driver context is not possible, a lightweight client process reads HID and forwards data to driver via shared memory or named pipe
- **IPC-02**: Client process auto-starts when driver activates and auto-stops on deactivation

### Advanced Diagnostics

- **DIAG-01**: Visual diagnostic mode showing raw proximity values, averaged values, threshold, and detection state for troubleshooting

## Out of Scope

| Feature | Reason |
|---------|--------|
| Full HMD override driver | Sidecar approach avoids reimplementing tracking/display/audio; override is fallback only |
| IVRDisplayComponent implementation | Built-in driver handles display; sidecar doesn't need it |
| Tracking passthrough/reimplementation | Built-in lighthouse driver handles tracking |
| Firmware modification to expose person_detected | Plan C per project constraints; PC-side replication is the plan |
| Fan/thermal control | Existing Bigscreen tools handle this |
| Eye tracking integration | Separate hardware subsystem, separate concern |
| Raw proximity distance streaming to apps | No standard OpenVR API; proximity is inherently boolean |
| Multi-HMD support | SteamVR supports one HMD; zero user benefit |
| Auto-update mechanism | Relies on Steam's existing update mechanism |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| FEAS-01 | Phase 1 | Complete |
| FEAS-02 | Phase 2 | Complete |
| FEAS-03 | Phase 3 | Complete |
| FEAS-04 | Phase 2 | Complete |
| DRIV-01 | Phase 1 | Complete |
| DRIV-02 | Phase 1 | Complete |
| DRIV-03 | Phase 1 | Complete |
| DRIV-04 | Phase 1 | Complete |
| HID-01 | Phase 2 | Complete |
| HID-02 | Phase 4 | Complete |
| HID-03 | Phase 4 | Complete |
| HID-04 | Phase 4 | Complete |
| HID-05 | Phase 4 | Complete |
| PROX-01 | Phase 5 | Complete |
| PROX-02 | Phase 5 | Complete |
| PROX-03 | Phase 5 | Complete |
| PROX-04 | Phase 5 | Complete |
| PROX-05 | Phase 5 | Complete |
| PROX-06 | Phase 5 | Complete |
| INTG-01 | Phase 3 | Complete |
| INTG-02 | Phase 6 | Complete |
| INTG-03 | Phase 6 | Complete |
| INTG-04 | Phase 6 | Complete |
| INTG-05 | Phase 6 | Complete |
| CONF-01 | Phase 7 | Complete |
| CONF-02 | Phase 7 | Complete |
| CONF-03 | Phase 7 | Complete |
| RBST-01 | Phase 8 | Complete |
| RBST-02 | Phase 8 | Complete |
| RBST-03 | Phase 8 | Complete |
| RBST-04 | Phase 8 | Complete |
| DIST-01 | Phase 9 | Complete |
| DIST-02 | Phase 9 | Complete |

**Coverage:**
- v1 requirements: 31 total
- Mapped to phases: 31
- Unmapped: 0

---
*Requirements defined: 2026-03-20*
*Last updated: 2026-03-20 after roadmap creation*