# Phase 1: Skeleton Driver and Coexistence - Context

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

<domain>
## Phase Boundary

Minimal SteamVR sidecar driver DLL that loads alongside the built-in lighthouse driver without breaking existing HMD functionality (tracking, display, audio). This validates feasibility of the sidecar approach before any proximity or HID work begins.

</domain>

<decisions>
## Implementation Decisions

### Driver naming & packaging
- Primary path: Add driver DLL to the existing `Bigscreen Beyond Driver` package (Steam auto-installs this when headset connects). Driver name would remain `bigscreenbeyond`. User is on the Bigscreen dev team and can modify this package and distribute to all users
- Fallback: Standalone driver package named `beyond_proximity` in `steamvr/drivers/beyond_proximity/`
- Research must investigate whether the existing resource-only package (currently `resourceOnly: true`) can be converted to an active driver with DLL while preserving its current icon/resource functionality

### Device identity
- Manufacturer string: "Bigscreen"
- Model string: "Beyond Proximity Sensor"
- Serial number: Claude's discretion (static or derived from HMD serial)

### Device visibility in SteamVR
- Strongly prefer the sidecar device to be invisible in SteamVR's device list — it should not appear alongside the HMD, controllers, and base stations
- Research must investigate whether a SteamVR driver can register a device (for /proximity component) without it appearing in the dashboard device list
- If hiding is not possible, use `TrackedDeviceClass_GenericTracker` as the least intrusive fallback
- No custom icons needed — either hidden or uses SteamVR's generic icon

### Verification approach
- Scripted verification checks as the final phase step: vrserver log parsing for errors, OpenVR API queries for device state and tracking integrity
- User performs manual UAT after scripted checks pass

### Source code layout
- Modular structure: `src/driver/` for SteamVR driver code, `src/hid/` for HID communication (Phase 2+)
- OpenVR SDK vendored in `extern/openvr/` (zero external deps, builds immediately after clone)
- CMake build outputs a complete SteamVR driver package structure (manifest + DLL in `bin/win64/` + resources) — one step from build to test

### Claude's Discretion
- Whether to register a tracked device in Phase 1 (TrackedDeviceAdded) or defer device registration to Phase 3 when /proximity is needed — depends on what makes the feasibility validation most useful
- MSVC/C++ standard and Visual Studio version selection
- Serial number format

</decisions>

<canonical_refs>
## Canonical References

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

### Existing driver package (reference for bundling investigation)
- `code_samples/Bigscreen Beyond Driver/driver.vrdrivermanifest` — Current resource-only manifest (name: bigscreenbeyond, resourceOnly: true, alwaysActivate: false)
- `code_samples/Bigscreen Beyond Driver/resources/driver.vrresources` — Icon paths and resource definitions for HMD status icons

### Firmware reference (proximity algorithm for later phases)
- `code_samples/beyond_firmware/src/Devices/prox_control.c` — Firmware proximity detection algorithm (moving average, threshold, hysteresis, calibration)
- `code_samples/beyond_firmware/src/Devices/prox_control.h` — Proximity data structures and constants (MIN_PROX_VALUE, MAX_PROX_VALUE)

### HID protocol reference
- `code_samples/proximity_sensor_access/config_lib.py` — User signature flash TLV format, calibration tag definitions (SigTag_Prox_Cal, SigTag_Prox_Threshold, etc.)
- `code_samples/proximity_sensor_access/prox_monitor.py` — HID reader thread pattern, report rate adjustment via feature report, periodic data decoding

### Project requirements
- `.planning/REQUIREMENTS.md` — DRIV-01 through DRIV-04 and FEAS-01 define Phase 1 requirements
- `.planning/ROADMAP.md` — Phase 1 success criteria

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- No existing C++ code — this is a greenfield driver project
- `code_samples/Bigscreen Beyond Driver/` — Complete reference for SteamVR driver package structure (manifest, resources, bin/ layout)
- `code_samples/proximity_sensor_access/` — Python HID tools showing the Beyond 2 HID protocol (not needed in Phase 1 but establishes patterns for Phase 2+)

### Established Patterns
- Existing driver package uses `bigscreenbeyond` as internal name across manifest and resource paths (`{bigscreenbeyond}/icons/...`)
- BeyondHID.exe companion app lives in the driver package's `bin/` directory alongside `hidapi.dll` and `libusb-1.0.dll`

### Integration Points
- SteamVR loads drivers from registered paths (vrpathreg) or steamapps/common/ for Steam-distributed packages
- The existing `Bigscreen Beyond Driver` package is the natural integration point if bundling is feasible
- If standalone, driver registers via `vrpathreg adddriver` during installation

</code_context>

<specifics>
## Specific Ideas

- User wants to explore bundling the driver DLL into the existing `Bigscreen Beyond Driver` Steam package — this is the preferred distribution path since it auto-installs for all Beyond 2 users
- The existing package is resource-only today; converting it to an active driver requires changing `resourceOnly` to false and adding `alwaysActivate` + `hmd_presence` fields
- Sidecar device should ideally be completely invisible to end users in the SteamVR dashboard

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 01-skeleton-driver-and-coexistence*
*Context gathered: 2026-03-21*