---
phase: 15-wifi-ddp-fallback-and-transport-selection
verified: 2026-04-19T12:00:00Z
status: passed
score: 4/4 must-haves verified
overrides_applied: 0
deferred:
  - truth: "With ESP32-C3 on WiFi (USB unplugged — D-04 mid-session no-failover path), driver stays on USB reconnect loop without flipping to DDP"
    addressed_in: "Future SMOKE pass (externally-powered MagWLED-1)"
    evidence: "SMOKE.md Followups: USB-power constraint — physical unplug also kills device power. Code path proven via static analysis: no flip-to-DDP exists in OnHotplugArrival. Carries to a future hardware session with powered USB hub (option a)."
  - truth: "With transport=auto and USB unplugged at SteamVR start, driver falls through to DDP (Criterion 3 Setup C)"
    addressed_in: "Future SMOKE pass (externally-powered MagWLED-1)"
    evidence: "SMOKE.md Followups: same USB-power constraint. Code path transitively validated: tryUsb() failure with scan_no_match triggers tryDdp() (proven by Criterion 1 + Setup B). Carries to future hardware session."
  - truth: "With transport=usb and USB physically unplugged, backglow status shows conn: disabled and err: scan_no_match (Criterion 4 State 4)"
    addressed_in: "Future SMOKE pass (externally-powered MagWLED-1)"
    evidence: "SMOKE.md Followups: same USB-power constraint. State 3 (ddp_probe_timeout) proves the disabled/err output shape is correct; only the reason token differs. Code path identical. Carries to future hardware session."
---

# Phase 15: WiFi DDP Fallback and Transport Selection — Verification Report

**Phase Goal:** LEDs work over WiFi when USB is unavailable, with automatic transport selection and connection diagnostics
**Verified:** 2026-04-19
**Status:** passed
**Re-verification:** No — initial verification

---

## Goal Achievement

### Observable Truths

| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | With ESP32-C3 on WiFi, `led fill` commands drive LEDs over DDP/UDP | VERIFIED | SMOKE Criterion 1 (TRNS-02) PASS: log lines `Backglow: online via DDP on 192.168.1.88`; 4 fills returned `OK fill=<HEX> leds=10`; WLED `/json/info` confirmed `live=True, mode=DDP, lip=192.168.1.81` |
| 2 | Driver auto-detects ESP32-C3 COM port by VID/PID without manual configuration | VERIFIED | SMOKE Criterion 2 (LHWD-04) PASS: log line `scan matched VID_303A&PID_1001 -> COM11` with empty `backglow_com_port`; `ScanForUsbComPorts(0x303A, 0x1001)` call confirmed in device_provider.cpp (x2: InitBackglow + OnHotplugArrival) |
| 3 | User can select transport (USB/DDP/auto) via steamvr.vrsettings and driver uses configured transport | VERIFIED | SMOKE Criterion 3 (TRNS-03) PASS 3/4: Setup A=PASS (USB confirmed via C2), Setup B=PASS (DDP confirmed via C1), Setup D=PASS (auto+USB-plugged: log `online via USB on COM11`, no DDP attempted); Setup C deferred (USB-power constraint — see deferred section) |
| 4 | `led status` reports current transport, connection state, brightness ceiling, and current color | VERIFIED | SMOKE Criterion 4 (DIAG-01) PASS 3/4: State 1 (USB open) and State 2 (DDP open) return full multi-line format; State 3 (192.0.2.1 → `err: ddp_probe_timeout`) confirms error path; grep confirms `transport: %s`, `conn:      %s`, `ceiling:   %u`, `err:       %s` format strings in device_provider.cpp; State 4 deferred (USB-power constraint) |

**Score:** 4/4 truths verified

### Deferred Items

Items not yet fully exercised on hardware but covered by code-level analysis and adjacent test paths.

| # | Item | Addressed In | Evidence |
|---|------|-------------|----------|
| 1 | Criterion 3 Setup C — auto+USB-unplugged → DDP fallback | Future SMOKE (externally-powered) | Code path: tryUsb() scan_no_match → tryDdp() confirmed in InitBackglow; tryDdp itself validated by C1+B |
| 2 | Criterion 4 State 4 — USB disabled, err: scan_no_match in status | Future SMOKE (externally-powered) | Code path: same disabled/err branch as State 3 (proven PASS); reason token `scan_no_match` confirmed present in source |
| 3 | D-04 no-failover — mid-session USB drop stays on reconnect, not DDP flip | Future SMOKE (externally-powered) | Static analysis: OnHotplugArrival has no flip-to-DDP path; only transport-USB-AND-disabled rescan; confirmed by code review |

---

## Required Artifacts

| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| `src/led/com_port_scan.h` | ScanForUsbComPorts declaration | VERIFIED | 17 lines; exact signature `std::vector<std::string> ScanForUsbComPorts(uint16_t vid, uint16_t pid);` present; no windows.h dependency in header |
| `src/led/com_port_scan.cpp` | SetupAPI 7-step VID/PID enumeration | VERIFIED | 91 lines; all required tokens confirmed: `GUID_DEVINTERFACE_COMPORT`, `SetupDiGetClassDevsA`, `SPDRP_HARDWAREID`, `RegQueryValueExA("PortName")`, `VID_%04X&PID_%04X`, `char hwBuf[256]`, `std::sort`, `std::atoi(.c_str() + 3)`, `#include <initguid.h>` before `<Ntddser.h>` |
| `src/led/wled_ddp.h` | WledDdpTransport class declaration | VERIFIED | 75 lines; `class WledDdpTransport : public ILedTransport` confirmed; all 7 interface methods overridden; `int ReportedLedCount() const;` present; `winsock2.h` before `ws2tcpip.h`; no `<windows.h>` |
| `src/led/wled_ddp.cpp` | DDP encoder + UDP + HTTP probe | VERIFIED | 548 lines; confirmed: `0x41` and `0x07` header bytes; `htons(4048)`; `inet_pton(AF_INET`; `"\"count\":"` substring; `R"({"seg":[{"on":true,"fx":0,"col":[[0,0,0]]}]})"` segment-clear; `kBackglowMaxLeds` clamp; `m_seq = 1` in Open(); `sleep_for(std::chrono::milliseconds(20))` double-send; no WSAStartup/WSACleanup; no inet_addr/getaddrinfo/gethostbyname |
| `CMakeLists.txt` | ENABLE_BACKGLOW source list + ws2_32 + setupapi | VERIFIED | 176 lines; `wled_ddp.h/cpp` and `com_port_scan.h/cpp` in target_sources; `ws2_32` and `setupapi` in target_link_libraries inside if(ENABLE_BACKGLOW); obsolete "Do NOT add setupapi" comment removed |
| `src/driver/device_provider.h` | New BackglowXp members | VERIFIED | 125 lines; confirmed: `enum class BackglowXp { USB, DDP, AUTO };`, `BackglowXp m_backglowTransport`, `std::string m_backglowDdpHost`, `std::string m_backglowDisabledReason`, `uint8_t m_lastReportedBri`, `bool m_bWsaInitialized` |
| `src/driver/device_provider.cpp` | WSA pairing, factory, status verb, hotplug rescan | VERIFIED | 1837 lines; all critical tokens confirmed (see Key Link Verification) |
| `src/ctl/main.cpp` | 1024-byte buffer + backglow status | VERIFIED | 127 lines; `strcmp(command, "backglow status") == 0` present; `char response[1024]` present; no `char response[256]`; PrintUsage contains "backglow status" |

---

## Key Link Verification

| From | To | Via | Status | Details |
|------|----|-----|--------|---------|
| `device_provider.cpp InitBackglow` | `com_port_scan.h ScanForUsbComPorts` | called when backglow_com_port empty OR Open() fails | WIRED | `ScanForUsbComPorts(0x303A, 0x1001)` at line 1387 (InitBackglow) and line 1794 (OnHotplugArrival) |
| `device_provider.cpp InitBackglow` | `wled_ddp.h WledDdpTransport` | transport factory branch when transport==ddp or auto fallback | WIRED | `std::make_unique<WledDdpTransport>()` at line 1429 |
| `device_provider.cpp HandleBackglowCommand` | multi-line status output (D-13) | snprintf with `transport: %s\n`, `conn:      %s\n`, `ceiling:   %u\n`, `err:       %s\n` | WIRED | Format strings confirmed at lines 1539-1556; `status` verb routed BEFORE degraded-mode early-return |
| `device_provider.cpp OnHotplugArrival` | `com_port_scan.h ScanForUsbComPorts` | rescan when m_backglowTransport==USB/AUTO && disabled (D-11) | WIRED | `ScanForUsbComPorts(0x303A, 0x1001)` at line 1794; guard `m_backglowTransport != USB && != AUTO` at lines 1782-1783; guard `!m_backglowDisabled` at line 1787 |
| `CMakeLists.txt` | `src/led/wled_ddp.cpp + com_port_scan.cpp` | target_sources inside if(ENABLE_BACKGLOW) | WIRED | Lines 81 and 83 confirmed |
| `src/ctl/main.cpp` | 1024-byte response buffer | char response[1024] + ReadFile(sizeof(response)-1) | WIRED | Line 111; `sizeof(response) - 1` at line 113 |
| `device_provider.cpp Init` | WSAStartup/WSACleanup pair | `WSAStartup(MAKEWORD(2, 2))` before InitBackglow; `WSACleanup()` after StopHotplugWatcher | WIRED | Lines 101/175 confirmed; `m_bWsaInitialized` flag gates WSACleanup |

---

## Data-Flow Trace (Level 4)

| Artifact | Data Variable | Source | Produces Real Data | Status |
|----------|---------------|--------|--------------------|--------|
| `WledDdpTransport::SendRgbFrame` | `rgb` (10×3 byte payload) | LedController (caller injects from fill/set commands) | Yes — live RGB data from pipe commands | FLOWING |
| `WledDdpTransport::Open` | `m_reportedLedCount` | HTTP GET /json/info → `strstr("\"count\":")` → `strtoul` | Yes — real WLED device count (observed: 10) | FLOWING |
| `HandleBackglowCommand status` | `m_backglowDisabledReason` | Written by InitBackglow factory branches on failure | Yes — populated with real error tokens (`scan_no_match`, `ddp_probe_timeout`, etc.) | FLOWING |
| `HandleBackglowCommand status` | `m_lastReportedBri` | Written at `bri` verb handler line 1672 | Yes — updated on every bri command | FLOWING |

---

## Behavioral Spot-Checks

Build artifact verification (static — no server running):

| Behavior | Check | Result | Status |
|----------|-------|--------|--------|
| `com_port_scan.cpp` compiles and links with SetupAPI | SUMMARY 15-01 reports `cmake --build` exits 0 | Build clean per SUMMARY | PASS |
| `wled_ddp.cpp` compiles and links with ws2_32 | SUMMARY 15-03 reports final build exits 0 with `driver_BeyondProximity.dll` produced | DLL present per SUMMARY self-check | PASS |
| `beyond_prox_ctl.exe` accepts `backglow status` | `strcmp(command, "backglow status") == 0` in validCommand check confirmed in source | Token present | PASS |
| DDP fills drive LEDs over WiFi | SMOKE Criterion 1 — WLED `/json/info` `live=True, mode=DDP` confirmed | Hardware PASS | PASS |
| VID/PID scan finds COM11 without config | SMOKE Criterion 2 — log `scan matched VID_303A&PID_1001 -> COM11` confirmed | Hardware PASS | PASS |
| Multi-line status with err token on probe failure | SMOKE Criterion 4 State 3 — exact 7-line output with `err: ddp_probe_timeout` observed | Hardware PASS | PASS |

---

## Requirements Coverage

| Requirement | Source Plan | Description | Status | Evidence |
|-------------|------------|-------------|--------|----------|
| LHWD-04 | 15-01, 15-03 | Driver auto-detects ESP32-C3 COM port via VID/PID (0x303A/0x1001) | SATISFIED | `ScanForUsbComPorts(0x303A, 0x1001)` in com_port_scan.cpp + device_provider.cpp; SMOKE Criterion 2 PASS |
| TRNS-02 | 15-02, 15-03 | WiFi/DDP fallback transport sends per-LED RGB via UDP to WLED port 4048 | SATISFIED | `WledDdpTransport` with `htons(4048)` + DDP header `0x41/0x07` + `sendto`; SMOKE Criterion 1 PASS |
| TRNS-03 | 15-03 | User can select transport (USB or DDP) via VRSettings configuration | SATISFIED | `backglow_transport` whitelist in InitBackglow; SMOKE Criterion 3 PASS (3/4 hardware; 1 deferred USB-power) |
| DIAG-01 | 15-03 | Separate `led status` command shows connection state, transport, ceiling, current color | SATISFIED | Multi-line status verb in HandleBackglowCommand; SMOKE Criterion 4 PASS (3/4 hardware; 1 deferred USB-power); note: `color` field intentionally absent per D-14 — `bri` (last brightness) is reported instead |

---

## Anti-Patterns Found

| File | Line | Pattern | Severity | Impact |
|------|------|---------|----------|--------|
| `device_provider.cpp` | 1817-1834 (write) / 1493-1693 (read) | Data race: OnHotplugArrival writes `m_backglowDisabled`, `m_backglowPort`, `m_pLedController`, `m_backglowDisabledReason` on hotplug thread; HandleBackglowCommand reads same fields on RunFrame thread; no mutex | Warning (CODE REVIEW CR-01) | C++ UB in theory; benign in practice (hotplug events rare, short critical sections); documented in 15-REVIEW.md CR-01 |
| `com_port_scan.cpp` | 55 | `std::string upper(hwBuf, hwSz)` includes embedded nulls from REG_MULTI_SZ; semantically finds any ID string in the multi-string (not just the first) | Info (CODE REVIEW WR-02) | Benign — correct behavior for matching any hardware ID; no false-positive risk for VID/PID pattern |
| `wled_ddp.cpp` | 458 | `m_seq = (m_seq % 15) + 1` wraps 1→14→1 (skips 15) | Info (CODE REVIEW IN-01) | Benign for WLED's duplicate-detection use; reduces detection window from 15 to 14 values |

No blockers found. The CR-01 data race is real but is tracked in 15-REVIEW.md with a specific fix (add `std::mutex m_backglowMtx`). It is not blocking the phase goal — the phase delivers working transport, not a production-hardened concurrent scheduler.

---

## Human Verification Required

The following items were tested on real hardware in 15-SMOKE.md but could not reach all code paths due to MagWLED-1's USB-power constraint. They are documented as deferred with explicit mitigation paths, not as gaps.

### 1. Criterion 3 Setup C — AUTO mode USB-unplug → DDP fallback at startup

**Test:** Set `backglow_transport=auto`, `backglow_ddp_host=<IP>`. Use an externally-powered MagWLED-1 (USB hub with per-port data-only switch). Start SteamVR with USB data unplugged but device powered over WiFi. Observe: log should show `scan_no_match` → `trying DDP` → `online via DDP`.
**Expected:** `Backglow: online via DDP on <IP>` after USB scan fails; fill commands work over DDP.
**Why human:** Requires USB-data-only unplug with separate 5V supply to MagWLED-1. Cannot simulate with current hardware configuration.

### 2. Criterion 4 State 4 — USB disabled status shows err: scan_no_match

**Test:** With externally-powered MagWLED-1 and USB data unplugged, set `transport=usb`, restart, run `backglow status`.
**Expected:** 7-line output ending `err: scan_no_match`.
**Why human:** Same USB-power constraint. Code path proven via State 3 (same branch, different token).

### 3. D-04 no-failover mid-session

**Test:** With `transport=auto` and USB plugged, confirm USB online. Unplug USB data (device externally powered). Run `backglow status`.
**Expected:** `conn: reconnecting` (LedController reconnect loop), NOT transport flip to DDP.
**Why human:** Same USB-power constraint. Code-level guarantee: no DDP flip path in OnHotplugArrival.

---

## Gaps Summary

No gaps. All four success criteria are verified as passing, with three sub-items deferred for a specific, documented hardware limitation (MagWLED-1 draws power from USB, making physical data unplug impossible without a separate power supply). The deferred items:

- Are covered transitively by passing adjacent tests (Criterion 1 + B prove tryDdp; State 3 proves the disabled/err output format)
- Have confirmed code paths via static grep (the relevant branches exist in device_provider.cpp)
- Have a concrete mitigation plan: powered USB hub with per-port data-only switch (15-SMOKE.md Followups, option a)
- Were reviewed by the code reviewer (15-REVIEW.md) — only code-quality issues found, no functional gaps

The special-case note from the verification prompt applies: the deferred-with-rationale approach is acceptable. The deferred items share a single physical constraint root cause, not a code defect. Status is **passed**.

---

_Verified: 2026-04-19_
_Verifier: Claude (gsd-verifier)_