Launching Snapdragon Spaces Apps - ThinkReality A3

The Snapdragon Spaces SDK developer package includes an Android Service Application that runs on the device and is responsible for running perception algorithms, communicating with glasses, and handling the OpenXR Runtime.

Install Snapdragon Spaces Services

The Snapdragon Spaces Services apk is currently included in the SDK download. Once in app stores, this will be a supplemental download that can be pulled when apps designed for Snapdragon Spaces are run.

For now, this needs to be manually installed and set up. Follow these steps:

PREREQUISITE

This step requires installation of android debug bridge on the computer before continuing.

• Set up the mobile device to enable Developer Options and enable USB Debugging.
• Connect the mobile device into the computer and authorize USB Debugging.
• Download one of the available SDKs from the Dev Portal and extract them to a local folder.
• Find the Snapdragon Spaces Services .apk at the top level of the extracted folder and install them via adb install.
• Check subfolders for Samples apks and install those as well using adb install.

Setup Snapdragon Spaces Services

The Snapdragon Services needs to be configured to allow for a successful developer experience:

• Find the Snapdragon Spaces Services application from the App Launcher
• Press and hold (long press) on this and select "App info".
• Press to enter "Permissions" and verify Camera permission is allowed. If not, tap and set it to "Allow only while using the app".
• Open the Snapdragon Spaces Services application from the App Launcher or from "Open" in the App info settings page.
• Select "Display over other apps" and enable Snapdragon Spaces Services with this permission.

AFTER INSTALLING, REINSTALLING, OR UPDATING SNAPDRAGON SPACES SERVICES

It is currently recommended to repeat toggling "Display over other apps" off and back on again even if the setting is already showing as active to ensure this value is fully recognized on the device.

Verify Application Start

This step verifies that the device is fully set up with provided Snapdragon Spaces apps after configuring Snapdragon Spaces Services from the steps above.

• For A3 Glasses: ensure the glasses are fully connected to the phone and started up. The app may appear split across the glasses or the ThinkReality logo may appear on the glasses. Either of these is fine.
• On the mobile device, tap on the icon of a Snapdragon Spaces Samples app from the "all apps" drawer or on the home screen.
• If Snapdragon Spaces Services is not properly installed or fully set up, make sure to check the steps above for Install Snapdragon Spaces Services.
• Any necessary permission pop-ups may appear on first application run. The Camera permission is required for certain perception tracking features like plane detection, image tracking, and hand tracking, so these should be allowed. "Display over other apps" is another necessary setting for proper rendering, that should be enabled.
• After the Spaces Services and permission checks are complete, the Controller Companion app should appear on the phone immediately, while the main app should appear on the AR glasses after a small delay. (This is caused by the runtime needing to start up, which can take several seconds.)
• Verify the sample app runs before proceeding.

Install and Run Spaces Apps

After device verification, Spaces Apps are now ready to be installed and tested on device.

1. Install apps from the computer using adb install
2. Install apps from Google Play Store
3. Develop apps using Unity or Unreal Engine
4. Receive apps from the Lenovo UDC Client (requires push from Qualcomm as noted in the Hardware Setup)

Notes

Here are additional notes on these platforms.

UPGRADING SNAPDRAGON SPACES SERVICES

When installing a new version of Snapdragon Spaces Services onto a device, reboot the phone to ensure any artifacts are cleared out. If any behavior isn't working properly, try disabling and re-enabling the permissions (Camera, Display over other apps) in the Spaces Services app.

ABOUT THINKREALITY A3 APPS

ThinkReality A3 Apps are not Spaces Apps

On the A3 Glasses, note that the following apps are not part of Snapdragon Spaces, but are part of another platform, known as the ThinkReality A3 platform.

• Lenovo UDC
• Companion
• A3 Home
• AR Cast
• Model Viewer

For more on ThinkReality, check Lenovo's Support Site. Note that you do not need a Lenovo ID or Organization ID to set up your device, rather refer to the ThinkReality A3 Setup on the Spaces portal.

Additionally, the Companion App by default launches automatically. This behavior can be changed by Turning On Developer Mode.

ABOUT UNPLUGGING A3 GLASSES

Close Running Spaces Apps Before Unplugging A3 Glasses

It is recommended to close or force stop all Spaces applications before unplugging the A3 glasses. If the glasses are disconnected while a Spaces application is running, it will require a restart of the phone in order to properly run OpenXR apps again. For the best developer experience follow the steps in Application Close.

Application Close

Since the main activity of the application is started on the Viewer, it won't show up on the multitasking view/recent apps list in Android.

To close the Snapdragon Spaces Unity or Unreal Engine Sample Apps, either:

• Press and hold the mobile phone controller's MENU button for 2 seconds (Implemented in the SampleController.cs script in Unity), or
• Aim at the "Exit" button in the main menu scene in the glasses and activate it.

For applications that do not provide exit functionality, the app can be closed using Force Stop on Android, described in the next section.

Application Force Stop

Since most Spaces apps are run by launching an activity on the viewer (see Architecture, the traditional Android system of gracefully closing running apps through the system is not available. As a result, Spaces apps should handle in-app UI to close the app. If this UI was not implemented or is not available, closing the app may need to be done manually.

This can be done by long pressing on the app icon in the app launcher until a context menu showing App Info appears. After opening the app info view, the application can be stopped by clicking Force Stop.

FORCE STOP MAY REQUIRE PHONE REBOOT

Note that force stopping an application does not send a shutdown signal to the app but terminates it immediately, so sockets may be left open to timeout and some perception features may no longer work properly due to an abrupt application exit. As such, any unexpected behavior on subsequent launches may be corrected by restarting the phone.

Troubleshooting

If you run into issues getting your hardware or app to run, this section contains some common issues you might run into.

CHECK YOUR SETUP

Make sure you followed the most recent version of the hardware setup and respective engine setup guides:

• Procedures for setting up your phone and glasses
• Getting started with the Snapdragon Spaces SDK for Unity
• Getting started with the Snapdragon Spaces SDK for Unreal

Symptom:	I can’t get the app to run more than once after a reboot
Behavior:	Occasionally the Snapdragon Spaces Services app fails to shut down correctly, preventing the next app from initializing the service.
Resolution:	Force Stop any applications that use Snapdragon Spaces services and try again. You might also have to Force Stop the Snapdragon Spaces Services app as well. If that fails, try rebooting the phone.

Symptom:	I can’t get my app to run at all.
Behavior:	You have the glasses plugged in and baited, but when you select your app and run it you see one of the following 1) app fails to run 2) displays on the phone 3) gives me a warning message 4) gives me a black screen
Resolution:	This is an indication that the Spaces services are not running or incompatible with your device. Check the versions you are running (phone and glasses) and make sure yours are current. Try running a SDK sample app to verify your setup on the devices.

Symptom:	A head-locked ThinkReality menu appears “stuck” after running a Spaces app
Behavior:	A head-locked ThinkReality menu appears “stuck”.
Resolution:	This sometimes happens after running Spaces apps, and Spaces apps should still run properly. To restore ThinkReality functionality, reboot the phone.

Symptom:	I don’t see anything in my glasses when I plug them in.
Behavior:	You can’t seem to get the glasses to work
Resolution:	Try unplugging and re-plugging in the glasses. If that doesn’t work, disconnect the glasses and run the Companion app. It will prompt you to plug in the glasses. Plug in the glasses. After about 15-30 seconds it should state that the glasses are connected. If this fails, try flipping the USB cable the other direction. If this continues to fail, try restarting the phone. If this still fails, reach out on the Support Forums.

If you run into an issue that isn’t solved by one of the above techniques, try the following;

1. Unplug the glasses from the phone.
2. Make sure the phone has a good charge on it.
3. Reboot the phone, wait for it to finish booting.
4. Plug in the glasses, wait for them to finish booting – about 15 seconds till you see the ThinkReality logo.
5. Try a provided Spaces app, like one of the Samples from the SDK download.
6. If that works, exit the Samples app and launch your own app.

If you are still running into issues, please contact the Support Forums for more assistance.