13 KiB
Debugging WiVRn
This guide covers debugging techniques for WiVRn, including log collection, crash analysis, performance profiling, and common troubleshooting scenarios.
Table of Contents
- Prerequisites
- Collecting Logs
- Starting Components for Debugging
- Crash Debugging
- Performance Debugging
- USB Tunneling
- Game Debugging
- Environment Variables Reference
- Configuration Files
- External Resources
- Remote Native Debugging (Advanced)
Prerequisites
ADB Setup
The Android Debug Bridge (ADB) is required for debugging the HMD client. Connect your headset to your PC via a USB data cable and authorize the connection when prompted in the HMD.
Clean Installation
When debugging, ensure the HMD client matches the server version. Perform a clean reinstall:
# Find and uninstall existing installation
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb uninstall ${WIVRN_PKG}
# Install the debug APK
adb install /path/to/wivrn-standard-debug.apk
Collecting Logs
HMD Client Logs
The primary method to collect logs from the HMD is through ADB logcat.
Watch for crashes (FATAL priority):
adb logcat '*:F'
Record ERROR and above:
adb logcat '*:E' | tee -a errors-$(date "+%Y-%m-%d-%H").log
WiVRn-only logs (verbose):
adb logcat '*:S' WiVRn:V
Watch WiVRn client logs:
adb logcat | grep WiVRn
Watch Android system logs related to WiVRn:
adb logcat | grep wivrn
Server Logs
Start the server with debug logging enabled:
XRT_LOG=debug XRT_COMPOSITOR_LOG=debug wivrn-server
To also dump video frames for analysis:
XRT_LOG=debug XRT_COMPOSITOR_LOG=debug WIVRN_DUMP_VIDEO=/tmp/video-dump wivrn-server
The video dump can be played back with mpv or other media players to verify what video was being sent to the HMD.
There will be multiple files in the directory, one for each video stream per codec. For example, /tmp/video-dump-0.h264.
Starting Components for Debugging
HMD Client
The package name varies by build variant:
org.meumeu.wivrn- for app store buildsorg.meumeu.wivrn.github- for GitHub release buildsorg.meumeu.wivrn.local- for locally built APKorg.meumeu.wivrn.github.testing- for CI runsorg.meumeu.wivrn.github.nightly- for APK repo
Find your installed package with:
adb shell pm list packages | grep wivrn
Start via ADB:
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb shell am start ${WIVRN_PKG}/org.meumeu.wivrn.MainActivity
Connect to a specific server:
Replace ADDRESS=localhost with the address of the server you want to connect to.
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
ADDRESS=localhost
adb shell am start -a android.intent.action.VIEW -d "wivrn://${ADDRESS}" ${WIVRN_PKG}
Stop the client:
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb shell am force-stop ${WIVRN_PKG}
Server
Start the server with debug logging:
XRT_LOG=debug XRT_COMPOSITOR_LOG=debug wivrn-server
The server will publish itself on the network via mDNS/Zeroconf for discovery by the HMD client.
XR Applications
Basic OpenXR application:
xrgears
To run Steam games via OpenVR, make sure to add the Steam launch options presented by the server output or in the dashboard. This is required to configure the OpenVR runtime correctly.
Some games have options to control window behavior. Try adding -windowed or -window -w 1280 -h 1024 to the game launch options to allow moving/resizing the local render window. Each game may have different options, check the game's documentation.
Note: Games linked to OpenVR require OpenComposite or xrizer to translate calls to OpenXR.
Crash Debugging
Server Crashes
Systemd
Core dumps are managed by systemd-coredump.
View the most recent crash:
coredumpctl info
Start a debugger on the most recent crash:
coredumpctl -1 debug
Inside GDB/LLDB:
# Select frame 2
f 2
# View local variables
info locals
# Print backtrace
bt
Non-Systemd Systems
On systems without systemd-coredump, core dumps are handled by the kernel directly.
Check where core dumps are written:
cat /proc/sys/kernel/core_pattern
To set a simple core pattern:
sudo sysctl -w kernel.core_pattern=/tmp/core.%e.%p.%t
This writes cores to /tmp/ with the format core.<executable>.<pid>.<timestamp>.
Analyze a core dump with GDB:
gdb /usr/bin/wivrn-server /tmp/core.wivrn-server.12345.1706234567
Inside GDB:
# Print backtrace
bt
# View all threads
info threads
# Switch to thread 2
thread 2
# Print backtrace for all threads
thread apply all bt
HMD Client Crashes
Copy the traceback from the HMD logs using logcat:
adb logcat '*:F' | grep -A 50 wivrn
Performance Debugging
Timing Analysis
WiVRn can record detailed timing information for analysis.
Capture timing data:
WIVRN_DUMP_TIMINGS=/tmp/wivrn-timings.csv wivrn-server
Perfetto Profiling
Perfetto provides detailed system-wide profiling.
HMD Profiling
Enable persistent tracing on Android:
adb shell setprop persist.traced.enable 1
Open the Perfetto UI, connect to your device, and configure tracing as needed.
See the Android tracing quickstart for detailed instructions.
Server Profiling
Ensure WiVRn is built with XRT_FEATURE_TRACING=ON to enable Monado tracing with Perfetto.
Start with tracing enabled:
XRT_TRACING=true wivrn-server
USB Tunneling
For debugging network issues or testing with a wired connection, you can tunnel WiVRn over USB.
Set up the tunnel and connect:
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb reverse tcp:9757 tcp:9757
adb shell am start -a android.intent.action.VIEW -d "wivrn+tcp://localhost:9757" ${WIVRN_PKG}
You are also able to make this connection through the dashboard.
Game Debugging
Proton/Wine Games
Enable additional logging for Windows compatibility layers:
PROTON_LOG=1 WINEDEBUG=vrclient,openxr,steam %command%
OpenComposite
For games using OpenVR, and you are using OpenComposite to translate calls to OpenXR.
The OpenComposite log can be found at $HOME/.local/state/OpenComposite/logs/opencomposite.log.
XRizer
To debug xrizer, you can set the RUST_LOG environment variable to control the log level.
| Variable | Description | Default |
|---|---|---|
RUST_LOG |
Configures the logging level for Rust applications. Accepts a comma-separated list of directives in the format module::path=level, where level can be error, warn, info, debug, or trace. For example, RUST_LOG=info,my_crate=debug sets the global level to info and the my_crate module to debug. |
warn |
In xrizer, RUST_LOG follows the standard env_logger semantics described above. In addition, xrizer defines the following useful nonstandard logging targets:
| Logging Target | Description |
|---|---|
openvr_calls |
Logs the name of each OpenVR function as they are called |
tracked_property |
Logs the name and device index of each requested tracked device property |
The log is located at $XDG_STATE_HOME/xrizer/xrizer.txt, or $HOME/.local/state/xrizer/xrizer.txt if $XDG_STATE_HOME is not set.
Environment Variables Reference
Compositor Settings
| Variable | Description | Default |
|---|---|---|
XRT_LOG |
Log level (trace, debug, info, warn, error) |
warn |
XRT_COMPOSITOR_LOG |
Compositor log level (trace, debug, info, warn, error) |
info |
OXR_VIEWPORT_SCALE_PERCENTAGE |
Per-application viewport scale (set on application, not server) | 100 |
Debugging
| Variable | Description |
|---|---|
WIVRN_DUMP_VIDEO |
Path to dump video frames (e.g., /tmp/video-dump) |
WIVRN_DUMP_TIMINGS |
Path to dump timing CSV (e.g., /tmp/wivrn-timings.csv) |
WIVRN_LOGLEVEL |
Log level for the native client |
WIVRN_AUTOCONNECT |
Auto-connect to the first discovered server |
XRT_TRACING |
Enable Perfetto tracing (true/false) |
Vulkan
| Variable | Description |
|---|---|
VK_INSTANCE_LAYERS |
Vulkan validation layers (e.g., VK_LAYER_KHRONOS_validation) |
OpenXR
| Variable | Description |
|---|---|
XR_RUNTIME_JSON |
Path to OpenXR runtime configuration |
See also the Monado compositor documentation for additional options.
Configuration Files
OpenXR Runtime Configuration
Active runtime symlink:
ls -la $HOME/.config/openxr/1/active_runtime.json
Should point to /usr/share/openxr/1/openxr_wivrn.json or similar.
Check runtime configuration:
cat /usr/share/openxr/1/openxr_wivrn.json
Example output:
{
"file_format_version": "1.0.0",
"runtime": {
"name": "Monado",
"library_path": "../../../lib64/wivrn/libopenxr_wivrn.so",
"MND_libmonado_path": "../../../lib64/wivrn/libmonado_wivrn.so"
}
}
Verify library dependencies:
pushd /usr/share/openxr/1/
ldd ../../../lib64/wivrn/libopenxr_wivrn.so
popd
WiVRn Server Configuration
External Resources
Tools and Documentation
- ADB Documentation - Android Debug Bridge
- ADB Logcat - Log filtering and analysis
- coredumpctl - Core dump management
- Perfetto - System profiling and tracing
- Perfetto UI - Web-based trace viewer
Monado/OpenXR
- Monado Getting Started - Compositor configuration
- Monado Tracing with Perfetto - Server-side tracing
- OpenXR - Khronos OpenXR standard
- xrgears - OpenXR test application
Gaming
- OpenComposite - OpenVR to OpenXR translation
- xrizer - OpenVR to OpenXR translation layer (Rust)
Rust
- env_logger - Rust logging configuration via RUST_LOG
Android Debugging
- Android NDK Debugging - Native debugging with ndk-gdb
- Android Tracing Quickstart - Perfetto on Android
Remote Native Debugging (Advanced)
This section covers attaching a native debugger to the HMD client remotely. This requires the Android NDK and familiarity with LLDB/GDB.
Start the client with debugging enabled:
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb shell am start -D ${WIVRN_PKG}/org.meumeu.wivrn.MainActivity
Set up LLDB debugging:
-
Push the LLDB server to the device:
adb shell "mkdir -p /data/local/tmp/tools" adb push "$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/lib64/clang/*/lib/linux/aarch64/lldb-server" /data/local/tmp/tools/ -
Start the LLDB server on the device:
adb shell /data/local/tmp/tools/lldb-server platform --server --listen '*:5039' -
Forward the port:
adb forward tcp:5039 tcp:5039 -
Connect from your host:
lldb (lldb) platform select remote-android (lldb) platform connect connect://localhost:5039
Resume the app (required for -D flag):
adb forward tcp:12345 jdwp:$(adb shell pidof ${WIVRN_PKG})
jdb -attach localhost:12345
See the Android NDK debugging guide for more details.