Deploying to HoloLens

Level: Basic

This tutorial guides you through the deployment of your application to HoloLens.

Preparation

Please ensure you have installed all required tools and adjusted the settings for HoloLens and Unity Development:

• Windows 10, Windows 10 SDK, developer mode activated
• HoloLens with activated developer mode
• Visual Studio 2017 (with UWP Tools installed) or higher
• Unity with IL2CPP scripting backend

This tutorial assumes you have a valid Unity scene containing VisionLib tracking and a valid VisionLib license.

Set Up the Unity Project

Some initial adjustments must be made to the Unity project:

1. Open the scene you would like to deploy to HoloLens.
2. Adjust the build settings (File/Build Settings):
   • Add your scene by clicking the Add Open Scenes button
   • Set platform to Universal Windows Platform and press Switch Platform
     
3. Adjust the player settings (Edit/Project Settings/Player):
   • Publishing Settings/Capabilities:
     • VideosLibrary: ON
     • WebCam: ON
     • Microphone: ON
       
       If you forget to set the WebCam capability or deny access to the camera, the application will trigger a breakpoint (throws an AccessDeniedException) when starting it via Visual Studio.
       
       This exception will be handled by VisionLib internally but Visual Studio will break for these exceptions by default.
4. Enable the XR Plugin Management (Edit/Project Settings/XR Plugin Management):
   • Make sure that Unity's XR Plugin Management is installed and enabled. Otherwise, the application will start in window mode.

Choosing Plugin management

In the plugin management, you can either use Windows Mixed Reality (until Unity 2020) or OpenXR (Unity 2020 or higher; OpenXR API is not supported for HoloLens (1st gen)).

Windows Mixed Reality

To use Windows Mixed Reality, select WindowsMR as Plug-in Provider in XR Plug-in Management under ProjectSettings. Make sure Initialize XR on Startup is selected.

OpenXR

To use OpenXR, follow these steps:

1. Download the Mixed Reality-Featuretool.
2. Start MixedRealityFeatureTool.exe
   1. Wait for the tool to update itself, then press Start.
   2. Select the root folder of your Unity project as Project Path and click Discover Features.
   3. Select the Mixed Reality OpenXR Plugin under Platform Support and click GetFeatures.
      
   4. Click Import and then Approve to include the Mixed Reality Toolkit.
   5. Close the Microsoft Mixed Reality Feature Tool by pressing Exit.
3. Open your Unity project.
   1. Select OpenXR as Plug-in Provider in XR Plug-in Management under ProjectSettings.
      1. Make sure Initialize XR on Startup is selected.
      2. Make sure Microsoft HoloLens feature group is selected.
         
   2. Click on the yellow exclamation mark to the right of the OpenXR checkbox. This opens the OpenXR Project Validation.
      1. Press the Fix All button to set up your project for use with OpenXR
         
   3. Open the OpenXR subsection:
      1. Select Microsoft HoloLens
      2. Add the Microsoft Hand Interaction Profile as Interaction Profile.
         

Deploy on HoloLens

Note: Development iterations can be reduced by starting your scene once in the Unity Editor before deploying. Here, you can already check if your license file is set correctly and if your scene setup is valid. You can not directly test the tracking, though. Starting the play mode should show no camera image, but some canvas elements like the description text. There should not be any error displayed but some warnings, that the scene cannot be executed in the Unity Editor.

If the editor test behaves correctly, build and deploy your application to the HoloLens by following these steps:

1. Press the Build button in the File/Build Settings window and select a folder for the HoloLens deployment.
2. Open the generated Visual Studio Solution (*.sln) in that folder.
3. Adjust the deployment settings in Visual Studio:
   • Change the dropdown settings to Release or Debug and ARM64 (on HoloLens (1st gen) to x86) as shown below.
   • Change from Local Machine to Device (deploy via USB connection) or Remote Machine (deploy via Wi-Fi).
   • If you choose Remote Machine, you will be asked to enter the IP address of the HoloLens first. (On HoloLens: Settings/Network & Internet/Hardware Properties/IPv4 address).
     
4. Ensure the HoloLens is turned on and the developer mode is activated (On HoloLens: Settings/Update/For developers).
5. Press Remote Machine or Device to deploy and run the application on the HoloLens.
6. If this is the first time you deployed to HoloLens from this computer, you will be asked to pair the devices. Find the required PIN on your HoloLens in Settings/Update&Security/For developers.
   

Once the HoloLens application starts, you will be asked for permission to use the microphone and webcam. These permissions are mandatory for tracking and the use of voice commands. Click Yes to confirm the dialog. Now look at your model to initialize tracking.

Please consider improving initialization and re-initialization speed by using the Read/Write Data commands (see HoloLens Voice and Keyboard Commands). To understand the concept of init data, refer to this article: Initialization: Fast Init & Re-initialization.

Trial License Restrictions

Please note that the trial license may only be used for evaluation purposes and does not permit application development.

With a trial license, you can only start an application up to five times after successful deployment. After the fifth deployment, the VisionLib SDK will no longer function in your application. To reset this, you must modify your project and redeploy the application to the device.
When deploying on HoloLens with Visual Studio, the application might be updated instead of completely reinstalled, which might cause the deployment counter not to be reset correctly. If you still experience license errors, try uninstalling the app on the HoloLens manually before deploying – or update the version in the package.appxmanifest:

This restriction does not apply to other license types. Once you have finished your evaluation of our SDK, you can remove the 5-time restriction by purchasing the appropriate license type for your use case.