# Run Snapdragon Spaces applications

The Snapdragon Spaces SDK developer package includes an Android Service Application that will run on the device and is responsible for running perception algorithms, communicating with glasses, and running the OpenXR Runtime. The application, at this time, is included in the SDK to allow for development effort with an eventual migrated into various app stores. The service, once in stores, will be a supplemental download that will be pulled when Apps designed for Snapdragon Spaces are downloaded.

To run a Snapdragon Spaces application on Spaces ready hardware, follow these steps:

  • Install the Snapdragon Spaces Services and sample applications found in the developer package to the host device via adb install.
    • Note: Qualcomm can also push the latest Snapdragon Spaces Services application to the device by registering the serial number of the host on the Developer Portal (opens new window).
  • Connect glasses to the host device.
  • Open application on host device.

The application will start on the glasses and the "Spaces Controller" (as seen in the image below) will start on the host device simultaneously.

# 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.
    • Note: After installing or updating Snapdragon Spaces Services apk, it is currently recommended to repeat this step even if it's already showing as active, toggling "Display over other apps" off and back on again to ensure this value is fully recognized on the device.
Setting up the host as a controller


The burger icon in the navigation bar of the Spaces Controller leads to a settings pane to adjust haptic feedback and appearance (such as light and dark mode).

In the provided Snapdragon Spaces samples, the host controller (seen in the image above) is used as a pointer controller. A click on the touchpad is mapped to trigger a select or click event, and the Menu button is used to switch between the gaze and the device pointer. The rotation of the controller is also used to steer the "laser pointer" from the device pointer. The reset button on the bottom, can be used to readjust the position and orientation of the device and align it with the forward direction of the head pose.

# Application start

With the Snapdragon Spaces Services configured, open the sample application:

  • Make sure Spaces approved glasses are connected and that the Camera permission is granted to Snapdragon Spaces Services, to have all perception features in the Services process run correctly.
  • Open the Snapdragon Spaces Sample app from the App Launcher.
  • Give camera permissions separately for the application for tracking features like plane detection, image tracking, etc.

In some occurrences, the application might not start properly on the viewer. To troubleshoot the issue, Force Stop both the application and the Snapdragon Spaces Services runtime.

Here are some reasons that might lead to an unsuccessful start of the application:

  • First app start after a host device reboot.
  • Closing one Spaces app and opening another one too fast before Snapdragon Spaces Services disconnected from previous application and cleaned up.

# 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, which is not ideal if the application should be closed. The sample included in the Snapdragon Spaces Unity package showcase two different ways of closing the application gracefully:

  • Press & hold the host controller's menu button for 2 seconds (Implemented in the SampleController.cs script).
  • Addition of a dedicated UI button in the main menu scene.

Otherwise, the only option to close the application, is by (force stopping)[#application-force-stop] like described in the next section.

# Application force stop

It is common in early day development where application shutdown states are not handled correctly or sockets are left open to timeout due to abrupt application exit. These growing pains are constantly being improved as the Spaces SDK evolves. As such, it is recommended to force stop the Snapdragon Spaces Service application as well as the Spaces application being run.

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 stopping the Spaces Services

# Application freeze

# Handset events

Locking and unlocking the Host device, or any other application interruption, will lead to the application being suspended and a blank/black view being present on the Viewer. This can be resolved by (force stopping)[#application-force-stop] the applications.

# Unplugging glasses

It is recommended to close or (force stop)[#application-force-stop] all Spaces applications before unplugging the glasses. If the glasses are disconnected while a Spaces application is running, it may cause the handset to get stuck temporarily. This can be resolved by waiting a few seconds and then following the steps to force quit Spaces Service. For the best developer experience follow the Application close.