commit f2689519b8582202083458b71dfa161a9b390e4a
parent 06736ea2d52b122abbcc7cff7674f50cf31761d4
Author: umhau <umhau@example.invalid>
Date: Wed, 21 Oct 2026 12:00:10 +0000
SETUP: build/run commands, no-sudo recovery helper, 90 Hz verification still pending
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Diffstat:
1 file changed, 20 insertions(+), 1 deletion(-)
diff --git a/SETUP.md b/SETUP.md
@@ -59,7 +59,25 @@ It sends (ported from Monado's `wmr_hmd_activate_reverb`):
- To the HoloLens Sensors device `045e:0659` (output report): `[0x02, 0x07]` + zero pad to 64 bytes (IMU on).
Within ~1.5 s the DP link trains (HBR3, 8.1 Gbps x 4 lanes), macOS adds the 4320x2160 display, and the headset
-reports `05 01 01 01 01 ...` (panel on), with no further `05 00` and no drops.
+reports `05 01 01 01 01 ...` (panel on). (Drops can still occur later; see NOTES.md "Link reliability".)
+The app (step 5) does this wake itself; `hmdwake` is only for diagnostics. Don't run both.
+
+### 5. Build and run the app (owns the headset, recovers it automatically)
+```sh
+zsh tools/build.sh # builds the app + the signed recovery helper
+.build/debug/VRWorkstation --run-seconds 600 # run for 10 minutes (omit for indefinite)
+```
+- `tools/build.sh` builds the app with `swift build`, then compiles `tools/hpmctl.c` into the same directory as the app
+ executable (`swift build --show-bin-path`) and ad-hoc signs it with `tools/hpmctl.entitlements`
+ (`com.apple.USBCEntitlement`).
+- The app runs as a normal non-root user. When the headset display is lost and does not return within a short
+ grace period, it runs that helper directly to send a USB-PD Data Reset to port 2's controller. No sudo, no password:
+ the kernel admits root OR that entitlement, and AMFI being off (`amfi_get_out_of_my_way=1`) lets an ad-hoc signature
+ carry it. Limits: 3 s helper timeout, at most 3 resets per minute.
+- The app captures the headset display (no desktop on it), uses its native unscaled 4320x2160 mode, and drives
+ frames from the headset display's own refresh.
+- Status: automatic recovery verified (3/3 trials at 90 Hz). 90 Hz presentation rate is **still being verified**:
+ earlier frame counts may have included skipped frames, so they are not yet counted as success.
## How the boot-arg was found
`amfi_get_out_of_my_way` controls code signing, not HDCP, so we searched this Mac's own kernel:
@@ -90,4 +108,5 @@ reports `05 01 01 01 01 ...` (panel on), with no further `05 00` and no drops.
- Never poll `ioreg -c IOPortTransportStateDisplayPort` (the old `linkwatch.sh` did; removed).
- `testpattern`: red LEFT / blue RIGHT fullscreen pattern on the headset.
- `verify.sh`: passive one-shot check (boot-args + summaries of existing logs). No ioreg/system_profiler/HID. Launches nothing.
+- `build.sh`: builds the app and the signed `hpmctl` helper beside it (SETUP step 5).
- `hpmctl` / `recovery_trials.py` / the app's LinkRecovery helper: see NOTES.md "Link reliability" (vr0 owns these).