feat: add SDK-free 3DoF tracking for VITURE Pro 2 (#1115)

* feat: itch.io store, library and installs for DRM-free Windows builds (#1064)

* feat: add experimental SDK-free VITURE Pro 2 tracking

* docs: record full-app Pro 2 hardware validation

* docs: record successful Pro 2 user game test

* fix: translate Pro 2 tracking notice for all supported locales

* fix: respect model capabilities for glasses controls

* fix: handle fold configuration during glasses probe

---------

Co-authored-by: kingokksa <47888451+kingokksa@users.noreply.github.com>
Co-authored-by: xXJsonDeruloXx <danielhimebauch@gmail.com>
This commit is contained in:
authored and GitHub committed 2026-10-22 10:28:14 -04:00
1 parent 7482f797c7
commit 3d9f200a7e
66 files changed
+2974 -19

No files matched your search

+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Holger Bartnick
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+47
View File
@@ -0,0 +1,47 @@
# VITURE protocol V2 attribution and scope
The frame builder, parser, pose/raw layouts, and commands in
`VitureV2Protocol.kt` are adapted from [elasticjava/viture-v2](https://github.com/elasticjava/viture-v2)
at commit `ece8c30485f7d357fefa362ae74f3eabac9b3899` (MIT).
Copyright (c) 2026 Holger Bartnick. The full license is in `LICENSE` here.
Sources used are upstream `PROTOCOL.md`, `src/lib.rs`, and `src/xr.rs`.
Upstream developed and measured its driver on VITURE Pro 2 XR `35ca:1301`.
Its research used captures of the proprietary SDK's USB traffic and logging;
the resulting implementation communicates directly over USB without that SDK.
This is an SDK-free implementation, not a claim of SDK-independent protocol research.
Our earlier local proprietary SDK trace was not used for this adaptation.
The Android transport and application integration are implemented in Kotlin.
Building this path requires no Rust toolchain, vendor SDK, vendor binary,
developer account, private download, or repository secret. It uses Android's
USB host permission and `UsbRequest` APIs. To explicitly build without the
optional vendor driver, pass the Gradle property `-PvitureSdkDir=`.
The application enables this experimental transport only for `35ca:1301`.
It requires valid pose samples before advertising 3DoF, uses the upstream
120 Hz pose mode, and treats the device timestamp as an uninterpreted counter.
Delivered timestamps use host `System.nanoTime()` receipt times. Bootstrap and
resume reject samples collected before the enable write completes. This host-time
cutoff does not establish when hardware produced a sample or purge device/kernel
buffers. The pose
basis conversion follows upstream's Y-up rendering convention. Hardware captures
verify changing, normalized poses during head motion; the relative rotation mapping
is unit-tested. The user also reported a successful Pro 2 game test; see the
validation notes for the scope of that report.
Raw gyro and accelerometer packets can be decoded with their complete payload
preserved, but raw data is not fused or used by the application. Upstream reports
that enabling pose and raw streams together can ACK successfully while sending
no samples, so the application requests pose alone. Accelerometer values remain
in g; gyroscope values are in radians/second according to upstream.
Brightness, volume, and display queries are supported. Setters, display switching,
6DoF, cameras, and hand tracking are not implemented by this path. Upstream's
README/protocol document and source disagree about setter coverage; this
adaptation does not use those setters without device validation.
The standalone `tools/viture/viture-v2-probe` captures descriptors, commands,
replies, and pose/raw packets for device compatibility testing. Its provenance
and license are included beside its source. Pro 2 hardware checks and their
limitations are recorded in [VALIDATION.md](VALIDATION.md).
+102
View File
@@ -0,0 +1,102 @@
# Pro 2 direct USB validation
These tests used a Samsung Galaxy Z Fold7 (SM-F976U), Android 17, with glasses
connected to the phone and wireless ADB used for installation and log collection.
The tested Pro 2 identifies as `35ca:1301`, with interface 0 exposing 64-byte
interrupt IN `0x81` and interrupt OUT `0x01`. Its firmware query returned
`30.0.00.001_20260714`. Results apply to this device and firmware.
## Protocol probe
The SDK-free Java probe in `tools/viture/viture-v2-probe` uses the attributed MIT
protocol. Every run queried firmware, enabled one stream, and sent stream-off at
completion. Each Pro 2 run received a successful firmware response and successful
start/stop acknowledgments. All three had zero malformed frames or samples.
| Run | Valid samples | Measured rate | Observation |
| --- | ---: | ---: | --- |
| Pose, initial 15-second window | 1,762 | 120.67 Hz | Normalized quaternions; components changed |
| Pose, 30-second motion window | 3,571 | 120.63 Hz | User turned, looked up/down, and tilted; all components varied |
| Raw, separate 15-second window | 1,471 | 100.77 Hz | Finite gyro and accelerometer values; acceleration magnitude 0.882–1.129 g |
Rates use host receipt time between the first and last samples. Query/setup time
reduces the sampling interval within each window. Although both stream requests
specified the upstream 120 Hz setting, the raw stream delivered approximately
101 Hz. Device counters are retained without assigning time units. Pose quaternion
norms were within 0.00000007 of one. These measurements do not establish accuracy,
drift, physical axis signs in a rendered scene, or 6DoF.
Raw gyro/accelerometer decoding is available for future work. The application uses
only the device's pose stream. Combined pose/raw streaming is deliberately excluded
because upstream observed acknowledgments without subsequent samples in that mode.
## Reproducing the checks
Build the application with `-PvitureSdkDir=` to explicitly exclude the optional
vendor SDK. No vendor SDK download, vendor account, binary upload, or repository
secret is required for Pro 2. See each tool's README/provenance document for Android
SDK/JDK requirements, build commands, USB permission, and log collection.
The protocol probe is separate from the application driver. The
`tools/viture/viture-v2-driver-check` harness packages the actual compiled
`VitureV2Link`, `VitureV2Protocol`, and `GlassesLink` classes and records their hashes.
It verifies readiness from poses and a stop/restart/stop/close sequence.
On the same Pro 2, the final production-driver check **passed**: 1,446 poses in the
12-second resumed capture at 120.65 Hz, plus three bootstrap poses. It reported one
ready callback, two tracking-on and two tracking-off callbacks, zero errors and
zero bad frames. Both 500 ms pause windows delivered zero further poses. After
close, readiness and tracking were both false. The complete sequence took 13.03 s.
This validates the production USB driver; it does not by itself exercise the full
DroidDeck UI or an in-game head-tracking session.
All 115 selected host-side tests passed. They cover wire framing/checksums,
bounded parsing, pose and raw layouts,
invalid samples, readiness without trusting ACKs, host-receipt cutoffs and
duplicate/backward device-tick rejection,
stop/restart behavior, transport failures, relative coordinate conversion, exact
USB model routing, consumer removal before the first restarted pose, and UI hiding
of unsupported hardware/display controls.
## Full application check
The complete debug APK built successfully with `:app:assembleDebug -PvitureSdkDir=`
and passed the repository's runtime-input verification and APK signature checks.
The APK contains the upstream MIT license and contains none of `libglasses.so`,
`libcarina_vio.so`, `libcloud_protocol.so`, or `libdroiddeck_viture.so`.
Installed as `com.droiddeck.launcher.xr`, version 0.5.0, on the same phone, it
recognized Pro 2 and exposed `supportsScreen3dof=true` after USB permission and
valid bootstrap samples. A five-second sample through DroidDeck's own `glasses`
agent endpoint returned **595 poses (118.98 Hz including startup)**, with quaternion
norms within 0.00000006 of one and zero bad frames. Tracking was false before the
sample, true during it, and false afterward; the connection remained ready with
no control error. This checks application integration and consumer-driven streaming,
not an in-game rendering or SteamVR session.
Tested APK SHA-256:
`f5a2484ea1708a143cb94a96e084188cb0d2b122154a2645d3127c66f6d04f21`.
## User game test
After installing the tested build, the user reported that the Pro 2 game test
passed. This adds user-reported in-game validation to the automated USB and
application checks above. The game title, test duration, and separate recentering
or SteamVR checks were not recorded.
## Local capture fingerprints
Full motion logs are local diagnostic artifacts, not required build inputs. These
SHA-256 values identify the captures behind the table above:
| Capture | SHA-256 |
| --- | --- |
| `pro2-pose-initial.jsonl` | `beb09072d8d7ce2b1378c41992b88787e0b09f3ab3ea330a413b3ef9e9f5b762` |
| `pro2-pose-motion.jsonl` | `d72f3bbd6564061e9bf4e06fec7f4c6dcdbfabeee626a99a7bff279b416ccc61` |
| `pro2-raw.jsonl` | `944ac2fe30c7b1a817bc4d3281ead620000be32aa2dbd96e6b104cf4d7063091` |
| `pro2-production-driver-final.jsonl` | `0f1c1073963a7c3052bf8bdbcb39e3ef8ec332367ab1a3e39b622d36fcd06db2` |
| `pro2-full-app.json` | `3e48d9c3e8a230ec84e09bb51395b8566618406abb93937b8e2b69c40b4854c5` |
The provenance in [README.md](README.md) applies to all these checks: the upstream
MIT project used SDK traffic captures in its research. This adaptation contains
and loads no vendor SDK; it does not claim independent protocol discovery.