So you're attending a hackathon and you want to build for HoloLens? Awesome! We've got you covered with this step by step guide for working with Microsoft HoloLens at a hackathon.
1. HoloHackathon Kit
So you're attending a hackathon and you want to build for HoloLens? Awesome! We've got you
covered with this step by step guide for working with Microsoft HoloLens at a hackathon.
Before the Hackathon: Set Up Your Development
Environment
Event Wi-Fi can be spotty, so you'll be best off if you download all of the necessary tools ahead of
time. The full toolset will run best on Windows 10.
You will need:
Visual Studio 2015 with Update 3
The Windows 10 SDK
Unity HoloLens Technical Preview
Optionally, you will need:
The HoloLens Emulator to test your applications on (Requires Win 10)
2. You should go to the HoloLens Developer Site to get the most up-to-date versions of each of the
above tools. Using outdated versions of the tools may result in unexpected issues when you build or
deploy your apps.
If you do not have a Windows PC or laptop to develop on, you may have luck with one of the
following options:
Installing a Windows Partition on your machine through a tool like Bootcamp.
Setting up a Windows 10 Virtual Machine
Get Familiar with HoloLens & Holograms
If you have a chance to walk through a few sample projects for HoloLens, you will be well-prepared
for building your first Holographic application. Understanding how Gaze, Gesture, and Voice - the
three main principles of HoloLens input - work will help you design your apps.
Check out some awesome things people are building
See things from a developer perspective
You should also bookmark the HoloLens Developer main site and the Holographic Academy site,
both of which will contain useful information about getting your own holographic applications up
and running.
At the Hackathon: Getting Your Project Started
When it's time to program your application, the best way to get started with your app will probably
be a clean Unity project. You'll also likely want to grab the HoloTookKit-Unity package from GitHub
to use in your project.
Create a new Project
1. Double check that you have the latest HoloLens Technical Preview from Unity.
2. Download the HoloToolKit-Unity project as a zip folder from GitHub.
3. Open up the HoloToolKit-Unity-master project in the Unity HoloLens Technical Preview. You
should see two folders under your assets: HoloToolkit and HoloToolkit-Examples.
4. Select the HoloToolkit folder and right click to find 'Export Package'
5. Save your exported package somewhere you'll remember it and name it 'HoloToolkit'
3. 6. In Unity, go to File > New Project to create your hackathon project folder. Save this
somewhere you have access to, such as your Desktop or Documents folders.
7. In your Assets folder, right-click and Import Custom Package
8. Find your Holotoolkit.unityplugin file that you just imported and select it to import it into
your new project.
Next step: build some holograms!
Deploying to a HoloLens Device
When you have your project working in the emulator and you're ready to test on a device, you will
need to do the following steps to connect and deploy to each device you are testing with:
1. Make sure that your computer and your HoloLens are both on the same WiFi network.
2. In Visual Studio, set your deployment target to 'Release', the architecture to 'x86', and the
deployment player to 'Remote Machine'
3. On the HoloLens, make sure that the developer settings are enabled to allow project
applications to run (Settings > Developer)
4. In the Settings > Network tab on the HoloLens, air tap on "Advanced Settings" and note your
device IP Address
5. Launch your application in Visual Studio. The first time you set up a device, you will be
prompted for the IP Address. Enter the HoloLens IP Address.
6. Once your device is connected, you will be promped in Visual Studio for a PIN. You can find
this back in Settings > Developer > Pair. Once you enter the code and the device pairs to the
computer, your application will begin deployment.
Uploading to GitHub
Unity projects with 3D assets can be really large, so you should set up your source control on your
project for the following:
1. Include a Unity .gitignore to your git configuration
2. Set up Git Large File Storage to track your .scene files and models that are larger than
50.0MB
Taking Care of your Device + Tips & Tricks
When holding the HoloLens, take care to hold it by the arms of the device, not the band or
the visor. You can clean off the front of the device with a dry screen cleaning cloth.
4. Keep the device charging while not in use so that you don't have to worry about a low
battery during testing
Rest the device flat (upside-down from how you'd wear it on your head) when it isn't in use.
Ideally, it should rest in the case, too.
The HoloLens App will allow you manage your device from your computer. You'll also be able
to turn on remote capture to see the holograms as someone uses your app.
5. Planning your Project
It's a hackathon - just about anything goes! That said, you usually have a certain amount of time to
work on a project with a hackathon, so you want to make sure that you take some time to plan,
scope, and build a project that works for your team in the time frame provided. Here are some things
to get you started.
Scoping your Project
Hackathons have a variable amount of time - you may have just 24 hours or fewer, or perhaps you're
at a week-long hack event that gives you more flexibility with how large of a project you can build.
Here are a few tips for scoping your project:
Consider how much you'll need to ramp up. If this is your first experience ever using Unity or
the Universal Windows Platform, build in a little extra time to familiarize yourself with the
tools and the build process.
Balance your team's expertise and plan accordingly. Especially during overnight hackathons,
it can be easy to assume that the number of hours available to hack equals the number of
hours you will spend working. Factor in time to rest (it's important!) and debug time to your
plan.
Spend some time up front deciding what you want to build and making sure everyone on
your team is on board with it. Your team will likely need to take turns using the headset, so
make sure that all members get a chance to try it out, talk out your project requirements, and
fully understand what the hardware is capable of and what you're going to build.
Take advantage of the unique capabilities of the HoloLens right away in your project. Plan
your experience in layers so that you have several milestones to reach. Include some of the
HoloLens-specific capabilities in your early milestones so that even if you don't finish your
entire plan, you'll have something to demo that uses the unique functionality of the device.
Understanding the Device
While you're thinking about what you'd like to build for HoloLens, consider the characteristics of the
device and how you can build for it.
The core building blocks of input for HoloLens are Gaze, Gesture, and Voice. Gaze, where a
user is looking, is used to direct attention to a specific hologram within your scene, at which
point you use the air-tap Gesture to confirm an action on that item. Voice commands can be
used to perform additional tasks, contextually or globally, within your app.
6. Play around with a few HoloLens applications from the Windows Store to get a sense of how
different design options work
Consider how immersive, 3D computing adds to your idea. What scenarios do mixed reality
devices enable, and how can you build off of those? What features of the HoloLens will make
these stand out?
Adding Functionality
Think about additional services that you may want to use in your application. Take a look at some of
the following scenarios that you may want to use in your HoloLens:
Accessing the Camera
You may want to create an application that builds off of the images that the HoloLens sees. To do
this, you will want to use the Locatable Camera object. This will allow you to access the camera on
the HoloLens.
Facial Detection
You can use Microsoft's Cognitive Services to work with facial detection and emotion APIs.
Natural Language Processing
The LUIS platform allows you to train a system to understand and extract sentiments from natural
human language and spoken phrases. LUIS is currently in beta and free to use.
Using JSON
There are a number of different options for handling JSON file types or responses in Unity. One
option is to use Json.NET for Unity3D. HoloLens requires the UWP Workaround to work, so make
sure that you're using the correct versions.
7. Troubleshooting Your Application
While hackathon mentors are awesome++, there are a few things that you can do to try debugging
your applications and get a head start on fixing issues you may run into.
First Checks
Before you track down a mentor for help, go through the following checklist to make sure that you're
not hitting some of the most basic bugs:
1. Check the version of Visual Studio 2015 you're running and make sure that Update 3 is
installed.
2. Make sure that you have an up to date HoloLens Technical Preview Unity installation. You
can check that you have a HoloLens build by going to Programs & Features > Unity and
making sure that the version you are using has -HTP at the end of the name. Example: Unity
HoloLens 5.4.0f3-HTP
3. Confirm that you have the Windows 10 SDK installed. You can check this by opening up
Visual Studio, clicking 'New Project', and seeing if there is an option for Windows Universal
under Visual C# (you don't have to actually create the project, just see if the option is there)
4. Enable developer mode on your local machine
5. See if the problem reproduces when you try a different deployment option (e.g. if you can't
deploy over USB, try Wi-Fi, and vice-versa)
Emulator Errors
Unable to install emulator:
o Check that you are running a supported version of Windows by going to System in
Control Panel and making sure that you have a Pro, Enterprise, or Educational version
of Windows 10
o Make sure that your PC meets the minimum requirements for the HoloLens emulator
o Turn on Hyper-V by searching "Turn Windows Features on or off" and following the
steps for Hyper-V
o Boot into your laptop's BIOS (or ask a mentor for help!) to make sure that you have
Hardware-assisted virtualization, SLAT, and DEP turned on
8. Unity Errors
"Error building Player: IOException: Win32 IO returned 112" - this is an error that the OS will
throw in Unity if you attempt to build your app without enough available disk space. Check
that you room - sometimes applications and files build up!
Cannot convert from packagename.class.Example to Example - you may find an error similar
to this in your project if your plugins have the same class names. To check if this is the case
in your project, search your asset for the Example class that is throwing an error, and see if
more than one script result shows up. If so, you may need to refactor one of them, or,
alternatively, you can use the full packagename.class.Example class in the lines throwing an
error to differentiate.
Platform not found - if you try to build your application and see an error about the platform
not being found, check:
o That you have set up your build target correctly
o The correct version of Visual Studio is installed
o You have included the Windows 10 SDK
Unable to drag and drop objects from the Assets folder to your Hierarchy or Scene: This is
likely due to a permissions issue. Check that your project is saved somewhere you have
access, such as the Documents folder.
Unity Bad Image Format: This may happen if Unity
Visual Studio Errors
Unable to deploy to the device: Check and see that you have the correct build targets set and
that you have successfully paired your
DEP0001: -1988945906. This error may occur if you are trying to deploy over USB and the
Windows Phone IP Over USB service has been disabled in Services. Confirm that it is running
by searching "Services" with Cortana.
Cannot connect to the HoloLens: make sure that your HoloLens has enabled the developer
settings and is on the same network as your computer
You can also try checking this list for additional troubleshooting tips related to deployment and
emulator errors.
Lastly, you can search the HoloLens Development Forum to see if your error is similar to one that
someone else may have had.