Oculus VR Hello World for Android Developers
I was super excited when I found out that my Oculus Quest 2 runs Android.
Once you enable Developer Mode, all the usual Android development tools seem to be available, e.g. we can use adb to see that the Oculus Quest 2 is running Android 10 (API level 29).
$ adb shell getprop ro.build.version.release
10$ adb shell getprop ro.build.version.sdk
29
The next thing I did was find a way to run a sample app from Android Studio. This required more work than I was expecting, but I’ve tried to make it simpler for others to do. :-) Read on for how to run the OpenXR hello_xr sample app.
Install and Run the Oculus hello_xr Sample App
Get your Oculus ready
- Enable Developer Mode on your Oculus.
- Connect your Oculus to your laptop (depending on your laptop you might need a USB 2.0 to USB C cable). Put the headset on and select “Allow” to trust the connected device.
Installing the Oculus sample app APK
If you don’t want to build the app, you can follow the instructions in this section. If you do want to build it, skip ahead to the next section.
- You can download the APK I built from here and install it directly:
- Install the APK using
adb install, or SideQuest. Skip ahead below to the Run section if you don’t want to build the sample app.
Building from Android Studio
Here’s how to build the app yourself. I tested these instructions on Android Studio Arctic Fox, on macOS Big Sur.
- Clone my repo (I have applied all the manual steps that the hello_xr sample project required, so you don’t have to):
git clone git@github.com:daj/OculusHelloXR.git
- In Android Studio, choose File -> Open… and select the OculusHelloXR folder for the repo you just cloned.
- Let the Gradle build finish and then click the play button to run the app.
- You might see an “Error while Launching activity”. Don’t worry — this is benign, everything will still work! You just need to put on your headset and launch the app from the Oculus Apps menu (see next section).
Launching an APK from an unknown source
- Select the “Unknown Sources” at the top right in your Apps menu, and select the “Hello XR” app to launch it.
- Now you’ll be able to look at some cubes in the sample app. Your controllers will each directly manipulate one of them. Enjoy!
Troubleshooting
Error while Launching activity
Every time you try to launch the app from Android Studio it shows the same error that I mentioned above:
In addition to the launching error
Error type 3
Error: Activity class {com.khronos.hello_xr/com.example.oculushelloxr.MainActivity} does not exist.Error while Launching activity
…you might also notice this message:
App restart successful without requiring a re-install.
Maybe this is because Android Studio thinks that it can hot swap the changes, but it appeared to me that any of my changes to the C files were not being applied. I seemed to be more successful installing manually the APK from the command line:
$ adb install -r -t app/build/outputs/apk/debug/app-debug.apk
Performing Streamed Install
SuccessApp shows loading dots forever
I was originally following the instructions in this blog post to get the sample app running. One of the steps was to run
adb shell setprop debug.xr.graphicsPlugin OpenGLESbefore launching the app on the Oculus. When I missed this step (e.g. after restarting the Oculus), I would get stuck forever on the three loading dots.
Based on reading the code, it didn’t seem like this setprop step should be necessary, so I modified my fork of the sample project to not require it. I also raised issue #281 on the OpenXR-SDK-Source project, and a maintainer confirmed that manual config step could be safely removed with a suitable build/code change.
Behind The Scenes
In the beginning I was hoping to find a really simple hello world Oculus app, and unfortunately this turned out to be much harder than I expected! Here’s some more information about how I created my copy of the sample project.
I was originally following the instructions in this blog post, but using the newest versions of all the linked dependencies/repos. After hitting problems, I asked for help on Stackoverflow, before eventually checking out older Git releases/tags of the dependencies to get it working. Following all the manual instructions was a pain, so I created an Android Studio project and applied each instruction as a separate commit in my repo, and I also modified the sample to avoid needing a manual adb shell setprop step.
The hello_xr sample is written almost entirely in C++, using the OpenXR cross platform library (XR is an abbreviation that includes both AR and VR).
The Android app is really just a container that launches the hello_xr native library:
Futures
It would be nice to investigate why Android Studio is failing to reinstall or launch the app on the Oculus. That was very confusing and frustrating.
Now that I’ve got more familiar with the configuration and the steps required, I might try updating to all the latest dependencies to see if I have more luck following the instructions.
I plan to dig more into the sample code and make some of my own modifications to learn more about the development environment (though I might need to do some OpenXR tutorials first).
Random Fact
I enjoyed that the Oculus product name is “hollywood”.
$ adb shell getprop
[ro.product.manufacturer]: [Oculus]
[ro.product.model]: [Quest 2]
[ro.product.name]: [hollywood]
[ro.build.branch]: [releases-oculus-10.0-v34]
[ro.build.characteristics]: [nosdcard]
[ro.build.date]: [Fri Oct 29 17:01:08 PDT 2021]
[ro.build.fingerprint]: [oculus/hollywood/hollywood:10/QQ3A.200805.001/20169900217500000:user/release-keys]
[ro.build.flavor]: [hollywood-user]
[ro.build.host]: [sandcastle180.ftw5.facebook.com]
[ro.build.id]: [QQ3A.200805.001]
[ro.build.product]: [hollywood]…which is what it calls itself when you use shell access.
$ adb shell
hollywood:/ $