mirror of
https://github.com/Droid-Deck/DroidDeck.git
synced 2026-11-21 13:55:58 +00:00
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:
1 parent
7482f797c7
commit
3d9f200a7e
66 files changed
+2974
-19
No files matched your search
Vendored
+21
@@ -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.
|
||||
Vendored
+47
@@ -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
@@ -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.
|
||||
Reference in new issue
Block a user