# Roadmap: Beyond 2 SteamVR Proximity Driver

## Milestones

- ✅ **v1.0 Beyond 2 SteamVR Proximity Driver** — Phases 1-9 (shipped 2026-03-23)
- ✅ **v2.0 Live IPD Change** — Phases 10-13 (shipped 2026-04-05)
- 🚧 **v3.0 Backglow Driver** — Phases 14-17 (in progress)

## Phases

<details>
<summary>✅ v1.0 Beyond 2 SteamVR Proximity Driver (Phases 1-9) — SHIPPED 2026-03-23</summary>

- [x] Phase 1: Skeleton Driver and Coexistence (2/2 plans) — completed 2026-03-21
- [x] Phase 2: HID Access Validation (2/2 plans) — completed 2026-03-22
- [x] Phase 3: Proximity Component Spike (2/2 plans) — completed 2026-03-22
- [x] Phase 3.1: Remove Virtual Tracker (2/2 plans) — completed 2026-03-22
- [x] Phase 3.2: Integrate into Official Beyond Driver Package (2/2 plans) — completed 2026-03-22
- [x] Phase 4: HID Data Pipeline (2/2 plans) — completed 2026-03-22
- [x] Phase 5: Proximity Algorithm (2/2 plans) — completed 2026-03-22
- [x] Phase 6: Standby/Wake Integration (2/2 plans) — completed 2026-03-22
- [x] Phase 7: Configuration (2/2 plans) — completed 2026-03-23
- [x] Phase 8: Robustness and Logging (2/2 plans) — completed 2026-03-23
- [x] Phase 9: Installer for Tester Distribution (2/2 plans) — completed 2026-03-23

</details>

<details>
<summary>✅ v2.0 Live IPD Change (Phases 10-13) — SHIPPED 2026-04-05</summary>

- [x] Phase 10: Feasibility Spike (2/2 plans) — completed 2026-03-24
- [x] Phase 10.1: SetDisplayEyeToHead Spike (2/2 plans) — completed 2026-03-24
- [x] Phase 11: Core IPD Pipe Command (2/2 plans) — completed 2026-03-26
- [x] Phase 11.1: Proximity Sensor App Compatibility Fix (2/3 plans) — completed 2026-03-27
- [x] Phase 12: SteamVR IPD Slider UI (2/2 plans) — completed 2026-03-28
- [x] Phase 13: Slider Persistence and Hardening (1/1 plan) — completed 2026-04-05

</details>

### 🚧 v3.0 Backglow Driver (In Progress)

**Milestone Goal:** Extend bey-closer to drive facial-interface LEDs from VR applications, digitally emulating transscleral illumination ("backglow") on prototype hardware.

- [x] **Phase 14: USB Serial Foundation and LED Control** - Safe, CLI-controllable LEDs over USB serial with brightness ceiling and dedicated writer thread (completed 2026-04-19)
- [x] **Phase 15: WiFi/DDP Fallback and Transport Selection** - Second transport validates abstraction; auto-detect COM port; transport fallback logic (completed 2026-04-19)
- [x] **Phase 16: VRChat OSC Bridge** - Driver-managed bridge daemon translates VRChat avatar OSC parameters to LED commands (completed 2026-04-20)
- [ ] **Phase 17: Avatar Prefab and Reference World** - Unity avatar prefab and VRChat world that demonstrate end-to-end world-to-LED pipeline

## Phase Details

### Phase 14: USB Serial Foundation and LED Control
**Goal**: User can control LEDs safely from CLI with brightness ceiling enforced, using USB serial to WLED ESP32-C3
**Depends on**: Phase 13 (existing driver codebase)
**Requirements**: LHWD-01, LHWD-02, LHWD-03, TRNS-01, LCTL-01, LCTL-02, LCTL-03, LCTL-04, LCTL-05, DIAG-02
**Success Criteria** (what must be TRUE):
  1. User can run `led fill 255 0 0` via beyond_prox_ctl.exe and see all 10 LEDs turn red on the physical hardware
  2. Setting brightness above the configured ceiling (default 50/255) is silently clamped -- LEDs never exceed the ceiling regardless of commands sent
  3. LEDs turn off automatically when SteamVR session ends or driver unloads, with no residual glow
  4. User can address individual LEDs by index (`led set 3 0 255 0`) and see only that LED change
  5. Backglow settings (brightness ceiling, COM port override) are readable from steamvr.vrsettings
**Plans:** 3/3 plans complete
Plans:
- [x] 14-01-PLAN.md — Hardware-validation spike (D-17/D-18): pure-function harness + hardware CLI exercising v/fill/bri/unplug on MagWLED-1; produces 14.1-SPIKE-FINDINGS.md with GO/NO-GO
- [x] 14-02-PLAN.md — LED core module: ILedTransport interface, WledSerialTransport (Adalight + JSON over Win32 overlapped serial), WledTpm2Transport stub, LedController (cv+33ms writer thread, ceiling, shutdown-off), CMake ENABLE_BACKGLOW
- [x] 14-03-PLAN.md — Driver integration: DeviceProvider VRSettings read, LedController ownership, backglow pipe routing, Cleanup shutdown, RegisterDeviceNotification hotplug, beyond_prox_ctl.exe CLI extension, 14-SMOKE.md hardware verification

### Phase 15: WiFi/DDP Fallback and Transport Selection
**Goal**: LEDs work over WiFi when USB is unavailable, with automatic transport selection and connection diagnostics
**Depends on**: Phase 14
**Requirements**: LHWD-04, TRNS-02, TRNS-03, DIAG-01
**Success Criteria** (what must be TRUE):
  1. With ESP32-C3 on WiFi (USB unplugged), `led fill` commands still drive the LEDs over DDP/UDP
  2. Driver auto-detects the ESP32-C3 COM port by VID/PID without manual configuration
  3. User can select transport (USB or DDP) via steamvr.vrsettings and the driver uses the configured transport
  4. `led status` command reports current transport (USB/DDP), connection state, brightness ceiling, and current color
**Plans:** 4/4 plans complete
Plans:
- [x] 15-01-PLAN.md — com_port_scan helper: SetupAPI VID/PID enumeration with lowest-COM sort (LHWD-04)
- [x] 15-02-PLAN.md — WledDdpTransport: DDP packet encoder + /json/info probe + segment-clear POST + UDP sendto (TRNS-02)
- [x] 15-03-PLAN.md — DeviceProvider InitBackglow factory + status verb + hotplug rescan + CLI multi-line buffer + CMake link (LHWD-04, TRNS-03, DIAG-01)
- [x] 15-04-PLAN.md — 15-SMOKE.md hardware UAT + 15-VALIDATION.md per-task map flip nyquist_compliant: true

### Phase 16: VRChat OSC Bridge
**Goal**: VRChat avatar parameter changes drive LED colors in real time via a driver-managed bridge process (daemon lifecycle driven by driver load per D-01; no separate VRSettings toggle)
**Depends on**: Phase 15
**Requirements**: VRCH-01, VRCH-02
**Success Criteria** (what must be TRUE):
  1. Driver spawns beyond_backglow_ctl.exe automatically at InitBackglow success (D-02) and terminates it via Windows Job Object kill-on-close when SteamVR exits — no orphan daemons
  2. When a VRChat avatar's BackglowR0..9 / BackglowG0..9 / BackglowB0..9 / BackglowBri float parameters change (driven by world contact senders per Phase 17), the physical LEDs update within one frame at 90 Hz (D-12)
  3. Bridge daemon discovers + exposes itself via VRChat OSCQuery + mDNS on loopback (D-18 primary path); falls back to fixed UDP 127.0.0.1:9001 (D-19) if OSCQuery setup fails; never binds to 0.0.0.0 (D-20)
**Plans:** 4/4 plans complete
Plans:
- [x] 16-00-PLAN.md — Wave 0 scaffold: 16-SMOKE.md 10-row UAT template, tests/osc_fixture/send_backglow.py python-osc fixture, beyond_backglow_ctl CMake target wrapped in ENABLE_BACKGLOW, deploy-backglow-dev.ps1 update for D-05, extern/oscpp + extern/mdns placeholders
- [x] 16-01-PLAN.md — Daemon core (VRCH-02): oscpp vendor, ParamMap 31 atomic slots, PipeClient overlapped message-mode write with 100 ms timeout, OSC server with D-21 whitelist + bundle handling + try/catch, 90 Hz writer with frame + Bri dedup (D-12/D-13/D-14), 3 s silence-fade 500 ms ramp (D-15), 4 s startup animation (D-16), stdin-EOF graceful-exit, loopback-only bind (D-20), SetDefaultDllDirectories hardening
- [x] 16-02-PLAN.md — Driver lifecycle (VRCH-01): LedController cv-wait retune 33→11 ms (D-26), DeviceProvider SpawnBackglowDaemon via Job Object + CREATE_BREAKAWAY_FROM_JOB (D-03 + Pitfall 2), absolute-path daemon resolution via GetModuleFileNameW (D-24), watchdog with 1s/2s/4s respawn backoff cap 3 (D-04), StopBackglowDaemon 3-phase graceful-then-kill (D-06), InitBackglow success-tail call (D-02), Cleanup pre-ShutdownAllOff call
- [x] 16-03-PLAN.md — OSCQuery + mDNS (VRCH-01 OSCQuery facet): mjansson/mdns vendor, OscQueryHttpServer minimal Winsock HTTP 1.0 (GET / + GET /?HOST_INFO with pre-built static JSON, no per-request alloc), MdnsAdvertiser dual-service `_oscjson._tcp` + `_osc._udp` on 127.0.0.1, main.cpp primary-path port-0 binding with D-19 fallback to fixed 9001, 16-SMOKE.md VRCH-01f row updated

### Phase 17: Avatar Prefab and Reference World
**Goal**: World creators can build backglow-enabled VRChat worlds using a reference prefab and example world
**Depends on**: Phase 16
**Requirements**: VRCH-03, VRCH-04
**Success Criteria** (what must be TRUE):
  1. A Unity avatar prefab with VRCContactReceiver components exists and can be added to any avatar in under 5 minutes
  2. A reference VRChat world with spatial light sources drives the avatar prefab's backglow parameters, producing visible face illumination on the physical hardware
  3. Walking through different colored light zones in the reference world produces matching LED color changes on the headset
**Plans**: TBD
**UI hint**: yes

## Progress

**Execution Order:**
Phases execute in numeric order: 14 → 15 → 16 → 17

| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 1. Skeleton Driver | v1.0 | 2/2 | Complete | 2026-03-21 |
| 2. HID Access | v1.0 | 2/2 | Complete | 2026-03-22 |
| 3. Proximity Spike | v1.0 | 2/2 | Complete | 2026-03-22 |
| 3.1 Remove Tracker | v1.0 | 2/2 | Complete | 2026-03-22 |
| 3.2 Package Integration | v1.0 | 2/2 | Complete | 2026-03-22 |
| 4. HID Pipeline | v1.0 | 2/2 | Complete | 2026-03-22 |
| 5. Proximity Algorithm | v1.0 | 2/2 | Complete | 2026-03-22 |
| 6. Standby/Wake | v1.0 | 2/2 | Complete | 2026-03-22 |
| 7. Configuration | v1.0 | 2/2 | Complete | 2026-03-23 |
| 8. Robustness | v1.0 | 2/2 | Complete | 2026-03-23 |
| 9. Installer | v1.0 | 2/2 | Complete | 2026-03-23 |
| 10. Feasibility Spike | v2.0 | 2/2 | Complete | 2026-03-24 |
| 10.1 SetDisplayEyeToHead Spike | v2.0 | 2/2 | Complete | 2026-03-24 |
| 11. Core IPD Pipe Command | v2.0 | 2/2 | Complete | 2026-03-26 |
| 11.1 Proximity Fix | v2.0 | 2/3 | Complete | 2026-03-27 |
| 12. SteamVR IPD Slider UI | v2.0 | 2/2 | Complete | 2026-03-28 |
| 13. Slider Persistence | v2.0 | 1/1 | Complete | 2026-04-05 |
| 14. USB Serial Foundation | v3.0 | 3/3 | Complete    | 2026-04-19 |
| 15. WiFi/DDP Fallback | v3.0 | 4/4 | Complete    | 2026-04-19 |
| 16. VRChat OSC Bridge | v3.0 | 4/4 | Complete    | 2026-04-20 |
| 17. Avatar Prefab & World | v3.0 | 0/? | Not started | - |