---
phase: 03-proximity-component-spike
plan: 01
subsystem: driver
tags: [openvr, proximity, named-pipe, win32, ipc, cli]

# Dependency graph
requires:
  - phase: 02-hid-feasibility
    provides: HID device integration, driver DLL build system, DeviceProvider with HidDevice
provides:
  - /proximity boolean component on GenericTracker device via CreateBooleanComponent
  - Named pipe server (\\.\pipe\beyond_proximity_ctl) for debug control
  - beyond_prox_ctl.exe CLI tool for toggling proximity state
  - SetProximity()/GetProximity() API on ProximityDevice
affects: [03-proximity-component-spike, verification, testing]

# Tech tracking
tech-stack:
  added: [Win32 Named Pipes (PIPE_NOWAIT)]
  patterns: [non-blocking pipe polling in RunFrame, state-change-only component updates, fire-and-forget CLI pipe client]

key-files:
  created: [src/ctl/main.cpp]
  modified: [src/driver/proximity_device.h, src/driver/proximity_device.cpp, src/driver/device_provider.h, src/driver/device_provider.cpp, CMakeLists.txt]

key-decisions:
  - "Pipe disconnects after each command-response exchange (fire-and-forget CLI model)"
  - "SetProximity only calls UpdateBooleanComponent on state change (avoids per-frame update anti-pattern)"
  - "Prop_ContainsProximitySensor_Bool set explicitly in addition to /proximity component auto-set (belt-and-suspenders)"

patterns-established:
  - "Named pipe server: CreatePipeServer/PollPipe/HandlePipeCommand/DestroyPipeServer lifecycle in DeviceProvider"
  - "State-change guard: SetProximity returns early if new value matches current value"
  - "CLI tool pattern: validate command, connect pipe, send, read response, close"

requirements-completed: [FEAS-03, INTG-01]

# Metrics
duration: 4min
completed: 2026-03-22
---

# Phase 3 Plan 1: Proximity Component Spike Summary

**/proximity boolean component on GenericTracker with named pipe debug control and beyond_prox_ctl CLI tool**

## Performance

- **Duration:** 4 min
- **Started:** 2026-03-22T06:22:55Z
- **Completed:** 2026-03-22T06:27:22Z
- **Tasks:** 2
- **Files modified:** 6

## Accomplishments
- Driver creates /proximity boolean component in Activate() with auto Prop_ContainsProximitySensor_Bool
- Named pipe server with PIPE_NOWAIT polls non-blocking in RunFrame() for "proximity on/off/status" commands
- beyond_prox_ctl.exe CLI tool connects to pipe, sends validated commands, prints driver response
- Both driver_beyond_proximity.dll and beyond_prox_ctl.exe build successfully

## Task Commits

Each task was committed atomically:

1. **Task 1: Add /proximity component and named pipe server to driver** - `eb9f985` (feat)
2. **Task 2: Build beyond_prox_ctl CLI tool and CMake wiring** - `81172c1` (feat)

## Files Created/Modified
- `src/driver/proximity_device.h` - Added VRInputComponentHandle_t m_proximityHandle, SetProximity/GetProximity methods
- `src/driver/proximity_device.cpp` - CreateBooleanComponent("/proximity") in Activate(), UpdateBooleanComponent in SetProximity()
- `src/driver/device_provider.h` - Added HANDLE m_hPipe, m_bClientConnected, pipe helper method declarations
- `src/driver/device_provider.cpp` - Pipe server lifecycle (Create/Poll/Handle/Destroy), RunFrame() calls PollPipe()
- `src/ctl/main.cpp` - Standalone CLI pipe client for debug control
- `CMakeLists.txt` - Added beyond_prox_ctl executable target

## Decisions Made
- Pipe disconnects after each command-response exchange -- beyond_prox_ctl is a fire-and-forget tool, not a persistent connection
- SetProximity() only updates on state change to avoid per-frame UpdateBooleanComponent calls (documented anti-pattern)
- Prop_ContainsProximitySensor_Bool set explicitly in addition to /proximity auto-set for belt-and-suspenders clarity
- ShouldBlockStandbyMode() remains false (returning true would make standby testing meaningless)

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness
- Driver DLL and CLI tool ready for live SteamVR testing (Plan 03-02 verification)
- Named pipe ready for PowerShell verification scripts to toggle proximity state
- Fallback checklist (from RESEARCH.md) ready if /proximity on GenericTracker does not trigger HMD standby/wake

---
*Phase: 03-proximity-component-spike*
*Completed: 2026-03-22*