# Requirements: Beyond 2 SteamVR Proximity Driver

**Defined:** 2026-04-06
**Core Value:** SteamVR and OpenVR applications can detect when the Beyond 2 is on or off the user's head, enabling automatic standby/wake and correct in-game presence detection.

## v3.0 Requirements

Requirements for backglow LED control milestone. Each maps to roadmap phases.

### LED Hardware

- [ ] **LHWD-01**: Driver communicates with WLED ESP32-C3 over USB serial using Adalight binary protocol
- [ ] **LHWD-02**: Driver enforces configurable global brightness ceiling (default 50/255) before any LED output
- [ ] **LHWD-03**: All LEDs turn off automatically when driver unloads or VR session ends
- [ ] **LHWD-04**: Driver auto-detects ESP32-C3 COM port via VID/PID (0x303A/0x1001) and handles disconnect/reconnect

### LED Control

- [ ] **LCTL-01**: User can set all LEDs to a single color via named pipe command (`led fill R G B`)
- [ ] **LCTL-02**: User can set individual LEDs by index via named pipe command (`led set <index> R G B`)
- [ ] **LCTL-03**: User can set global brightness via named pipe command (`led bri <0-255>`)
- [ ] **LCTL-04**: User can turn LEDs off via named pipe command (`led off`)
- [ ] **LCTL-05**: Driver supports real-time color streaming at up to 30fps target rate

### Transport

- [ ] **TRNS-01**: LED communication uses an abstract ILedTransport interface separating core from hardware-specific code
- [ ] **TRNS-02**: WiFi/DDP fallback transport sends per-LED RGB data via UDP to WLED on port 4048
- [ ] **TRNS-03**: User can select transport (USB or DDP) via VRSettings configuration

### VRChat Integration

- [ ] **VRCH-01**: Bridge daemon (beyond_backglow_ctl.exe) is launched/stopped by the driver DLL based on an "Enable Backglow" VRSettings toggle, and listens for VRChat avatar OSC parameters on port 9001
- [ ] **VRCH-02**: Bridge maps avatar float parameters (e.g., BackglowR/G/B/Bri) to LED pipe commands
- [ ] **VRCH-03**: Reference Unity avatar prefab with VRCContactReceiver components pre-wired to backglow parameters
- [ ] **VRCH-04**: Reference VRChat world with spatial light sources that drive backglow via contact senders, demonstrating per-zone face illumination

### Diagnostics

- [ ] **DIAG-01**: Separate `led status` pipe command shows LED connection state, active transport, brightness ceiling, current color
- [ ] **DIAG-02**: Backglow settings configurable via steamvr.vrsettings (brightness ceiling, COM port override, transport preference)

## Future Requirements

Deferred to future release. Tracked but not in current roadmap.

### Ecosystem

- **ECOS-01**: World creator SDK and documentation for building backglow-enabled VRChat worlds
- **ECOS-02**: Multi-headset sync (multiple users with backglow in same world)
- **ECOS-03**: Alternative hardware backends (non-WLED, custom PCB protocols)

### Advanced Features

- **ADVN-01**: Screen color sampling (ambilight mode) for non-VRChat applications
- **ADVN-02**: Preset/effect system with named configurations (campfire, underwater, alert)
- **ADVN-03**: Avatar-based self-control via avatar menu toggles

## Out of Scope

| Feature | Reason |
|---------|--------|
| Custom WLED firmware | Breaks upgradability, adds ESP32 toolchain dependency. Use stock WLED APIs. |
| OpenVR input components for LED control | IVRDriverInput is read-only from app side. No writable channel exists. |
| Direct Udon world-to-external networking | Udon has no OSC/HTTP/WebSocket API. Avatar contact receiver pattern is the sanctioned path. |
| Per-LED brightness control | WLED seg.i does not support per-pixel brightness (GitHub #2549). Encode brightness in RGB values. |
| WiFi-only control | WiFi adds config complexity and USB 3.0 interference risk. USB-first is correct. |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| LHWD-01 | Phase 14 | Pending |
| LHWD-02 | Phase 14 | Pending |
| LHWD-03 | Phase 14 | Pending |
| LHWD-04 | Phase 15 | Pending |
| LCTL-01 | Phase 14 | Pending |
| LCTL-02 | Phase 14 | Pending |
| LCTL-03 | Phase 14 | Pending |
| LCTL-04 | Phase 14 | Pending |
| LCTL-05 | Phase 14 | Pending |
| TRNS-01 | Phase 14 | Pending |
| TRNS-02 | Phase 15 | Pending |
| TRNS-03 | Phase 15 | Pending |
| VRCH-01 | Phase 16 | Pending |
| VRCH-02 | Phase 16 | Pending |
| VRCH-03 | Phase 17 | Pending |
| VRCH-04 | Phase 17 | Pending |
| DIAG-01 | Phase 15 | Pending |
| DIAG-02 | Phase 14 | Pending |

**Coverage:**
- v3.0 requirements: 18 total
- Mapped to phases: 18
- Unmapped: 0

---
*Requirements defined: 2026-04-06*
*Last updated: 2026-04-05 after roadmap creation*