# Phase 2: HID Access Validation - Context

**Gathered:** 2026-03-21
**Status:** Ready for planning

<domain>
## Phase Boundary

Validate that the sidecar driver can open the Beyond 2 proprietary HID device (VID 0x35BD, PID 0x0101) from within vrserver.exe while SteamVR and the Bigscreen companion app are both running. This is a feasibility gate — no HID reading or proximity logic, just proving the device can be opened without contention.

</domain>

<decisions>
## Implementation Decisions

### HID library
- Use HIDAPI (C library) — matches the Python tools' hidapi binding already proven with Beyond 2
- Vendor HIDAPI source in `extern/hidapi/`, built via CMake — same pattern as `extern/openvr/`
- Zero external installs needed; self-contained build

### USB interface targeting
- Identify the proprietary HID interface by VID/PID match only (VID 0x35BD, PID 0x0101) — no usage page filtering needed
- Update driver manifest: add `"hmd_presence": ["35BD", "0101"]` so SteamVR auto-activates when Beyond 2 is connected (FEAS-04)
- Keep `alwaysActivate: true` alongside hmd_presence for Phase 2 as belt-and-suspenders; clean up in a later phase once hmd_presence is validated

### Contention behavior
- HIDAPI opens Windows HID devices in shared mode (FILE_SHARE_READ | FILE_SHARE_WRITE) by default — both driver and BeyondHID.exe companion app can access simultaneously
- If shared-mode open fails (unexpected exclusive lock): disable proximity features, log warning, keep driver running — matches RBST-01 graceful degradation pattern
- No retry loop for Phase 2; revisit if contention actually occurs in practice

### Verification approach
- Automated PowerShell script (extends existing verify_driver.ps1 pattern) that:
  - Checks if BeyondHID.exe is running
  - Verifies driver opened HID successfully (parse vrserver log for HID open success/failure)
  - Validates both processes can coexist

### Claude's Discretion
- Whether to wrap HIDAPI in a C++ RAII class or use the C API directly — choose what fits the existing codebase style best
- Where in the driver lifecycle to call hid_open() (Init vs RunFrame vs background thread)
- HID error logging format and verbosity

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### HID protocol (Beyond 2 proprietary interface)
- `code_samples/proximity_sensor_access/prox_monitor.py` — HID reader thread pattern, report rate adjustment, periodic data decoding. Shows `hid.device()` usage with Beyond 2.
- `code_samples/proximity_sensor_access/config_lib.py` — User signature flash TLV format, calibration tag definitions. Shows feature report read/write patterns.
- `code_samples/proximity_sensor_access/config_editor.py` — VID/PID constants (BIGSCREEN_VID = 0x35BD, BEYOND_PID = 0x0101), HID device open patterns.

### Existing driver code (Phase 1 output)
- `src/driver/device_provider.h` — DeviceProvider class (IServerTrackedDeviceProvider) with Init/Cleanup/RunFrame lifecycle
- `src/driver/device_provider.cpp` — DeviceProvider implementation, ProximityDevice creation
- `src/driver/proximity_device.h` — ProximityDevice class (ITrackedDeviceServerDriver), GenericTracker registration
- `driver/beyond_proximity/driver.vrdrivermanifest` — Current manifest (alwaysActivate: true, name: beyond_proximity)

### Driver manifest reference
- `code_samples/Bigscreen Beyond Driver/driver.vrdrivermanifest` — Existing resource-only manifest for reference

### Project requirements
- `.planning/REQUIREMENTS.md` — FEAS-02, FEAS-04, HID-01 define Phase 2 requirements

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `DeviceProvider::Init()` — natural place to attempt HID device open during driver initialization
- `DeviceProvider::RunFrame()` — could be used for deferred HID open or periodic reconnection attempts
- `scripts/verify_driver.ps1` — existing verification script pattern to extend with HID checks
- `extern/openvr/` — vendoring pattern to replicate for HIDAPI

### Established Patterns
- CMake build with vendored dependencies (OpenVR SDK in extern/)
- Atomic PowerShell verification scripts with numbered checks
- DriverLog for all driver-side logging

### Integration Points
- `DeviceProvider::Init()` is where HID open should be attempted
- `driver.vrdrivermanifest` needs hmd_presence field added
- `CMakeLists.txt` needs HIDAPI as additional dependency
- New source files likely in `src/hid/` per Phase 1 context decision on modular layout

</code_context>

<specifics>
## Specific Ideas

- HIDAPI chosen specifically because the Python tools already use the hidapi binding and it's proven with Beyond 2 hardware
- Shared-mode HID access is the default on Windows with HIDAPI — no special configuration needed
- Phase 2 is a feasibility gate: success means "hid_open() returns non-null from within vrserver.exe with companion app running"

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 02-hid-access-validation*
*Context gathered: 2026-03-21*