Skip to content

Developer.md

Latest commit

 

History

History
161 lines (107 loc) · 4.82 KB

Developer.md

File metadata and controls

161 lines (107 loc) · 4.82 KB
Raw

Developer Guide

Contribute to Retina-Sync Override (UtahsQuest2Upgrade) — a Python desktop + CLI tool that optimizes Meta Quest headsets via ADB.

Background reading: Technical Overview · VR Landscape

Environment setup

git clone https://github.com/utahisnotastate/UtahsQuest2Upgrade.git
cd UtahsQuest2Upgrade

python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

Requirements include CustomTkinter (GUI), PyInstaller (optional packaging), and pytest (tests).

Project structure

Path Role
main.py GUI entry (RetinaSyncApp)
quest_gui.py CustomTkinter: Overlay, lenses, Thermal Shield, Advanced
quest_logic.py ADB, batch apply/read, silicon probes, Chrono, MetaLens
quest_profiles.py Named presets + ThermalShield
quest_benchmark.py Spatial telemetry runner
quest_cli.py Headless argparse CLI
build_exe.py PyInstaller onefile build
tests/ Device-free unit tests
docs/ Audience + technical documentation

Dependency direction (keep it acyclic):

main → quest_gui → quest_logic → quest_profiles
                 → quest_benchmark → quest_logic
quest_cli → quest_logic / quest_benchmark / quest_profiles

Extending optimizations

  1. Add the property to QuestLogic.PROP_LABELS (and usually OPTIMIZATIONS / DEFAULTS).
  2. If it is a user-facing preset, add it under GAMING_PROFILES in quest_profiles.py.
  3. Expose it in Advanced UI via create_setting_row in quest_gui.py if operators need a manual control.
  4. Meta-Lens and Micro-Lens automatically score any key present in the expected matrix / labels.

Rules of thumb

  • Prefer documented Meta debug.oculus.* properties over undocumented vendor keys.
  • Always handle unauthorized / missing-device ADB states.
  • Sysfs probes must return "N/A" or None, never raise on missing paths.
  • Prefer apply_properties_batch over per-key setprop loops for latency.

Texture height

When linking width→height, use QuestLogic.linked_height() / height_for_width() (~1.1×). Square buffers are fine for aggressive presets, but stock Quest 2 proportions are rectangular.

Chrono history API

Persisted at ~/.retina_sync_chrono_history.json (capped ~200 events).

from quest_logic import QuestLogic

logic = QuestLogic()
logic.apply_preset("Max GPU")
logic.rewind_previous()      # undo to prior entry
logic.rewind_to_index(0)     # re-apply newest

Each history row stores ts, label, settings, success_count, total, and often elapsed_ms.

Thermal Shield API

logic.thermal_shield.auto_apply = True
logic.evaluate_thermal_shield()
logic.apply_thermal_profile("THERMAL_BYPASS")
logic.maybe_auto_thermal_apply()  # no-op unless auto_apply and threshold crossed

Hysteresis: enter bypass near ceiling (~82 °C); leave only after recover (~72 °C) to avoid flapping.

CLI for automation

python quest_cli.py status
python quest_cli.py deploy
python quest_cli.py preset "Competitive"
python quest_cli.py shield --auto on
python quest_cli.py benchmark

Useful for CI smoke checks (connection-dependent) and power-user scripting. Host-side unit tests should not require a headset.

Testing

pytest -q

tests/test_quest_logic.py covers MetaLens verdicts, ThermalShield hot-swap, profile catalogs, Chrono persistence, and height heuristics — no ADB required.

When adding device-touching integration tests, gate them behind an env flag (e.g. RETINA_SYNC_ADB=1) so default CI stays offline-safe.

Building the Windows executable

python build_exe.py

Output: dist/RetinaSyncOverride.exe (onefile, windowed). Hidden imports cover quest_logic, quest_gui, quest_benchmark, quest_profiles, and quest_cli.

UI concurrency notes

  • Never call blocking ADB on the Tk main thread.
  • Use threading.Thread + self.after(...) to marshal results back to the UI (existing pattern in quest_gui.py).
  • Telemetry is debounced (_debounce_ms) to coalesce device-monitor ticks.

Contributing

  1. Branch: git checkout -b feature/your-change
  2. Keep diffs focused; update docs when behavior or public CLI changes.
  3. Run pytest -q.
  4. Open a pull request with a short “why” summary.

Do not commit secrets, local Chrono JSON from your home directory, or PyInstaller build/ / dist/ artifacts unless intentionally releasing.

Related projects (inspiration, not dependencies)

  • Utah-Vidia — PC GPU middleware concepts (thermal JIT profiles, gaming presets). Retina-Sync ports the ideas to Quest ADB; it does not embed CUDA.
  • Meta Horizon docs — system properties for Quest developers (authoritative for property semantics).