Using Plugin

How to actually use the OVR AOS Plugin once installed.

Using Plugin - Establishing Connection

Once the plugin is enabled go to “Content Drawer” and then "Settings", enable “Show Plugin Content” and “Show Engine Content”. This will allow you to view the “OVRUtilities” content folder provided by the OVR AOS plugin. Should look like the following.

Once your view options are set, you can now browse to the “OVRUtilities Content” directory BP (Blueprints) folder via the editors "Content Browser" to find the “BP_OVRConnectionManager”, this is required to establish a Bluetooth Low Energy (BLE) connection between the ION Device and HMD (Head Mounted Display).

To use the "BPOVRConnectionManager" simply drop it into your world or spawn it in.

If you want to connect over Bluetooth Low Energy (BLE) on a compatible device then you need to call BLEScan function which will start a scan to look for IONs. In the future there will more ways to connect via BLE, such as via pairing on a devices native BLE Scan interface. For the moment scanning in app is the main method and works for iOS, Mac, Windows and Android.

Shows Level Blueprint's Begin Play Binding to One ION Found and then call BLEScan

This will then trigger three potential events if an ION or IONs are found. 1. One ION Found: A single ION detected 2. Multiple Found: More than one ION found. 3. Multiple and Saved ION Found: More than one ION Found but one of the found IONs was connected to at some point during the life time of this app session.

Showing the bindings from the Connection Manager Actor

Showing the bindings from the Connection Manager blueprint

NOTE: The time it takes between one ION found and multiple IONs found depends on how you want to programmatically handle it. You can wait 1 or 5 seconds or however long you want before assuming there are no more IONs to search for. Each event above will need to be handled to accommodate your needs no assumptions are made here. Once you have your event and a reference to an ION Device you can connect to the device and stop the scan.

Connect and bind events for the Connected Callback and the Connect Fail Callbacks

The Connect to Device is not recommended as this ignores the "Setup BLE Connection Event Bindings" below which handles certain features like event dispatchers and remembering the last ION. See below for recommended BLE connection approach.

Connect and don't yet bind the callbacks mentioned in the above picture.

The Connect to Device No Event Bindings is currently the recommended approach to connect but prior to calling it be sure to call "Setup BLE Connection Event Bindings". This ensure that the Connection Managers Blueprint bindings for connect and disconnect are setup, allowing you to extend connect and disconnect events with the included Event Dispatchers and remember the last connected ION.

Call to stop BLE scanning.

A manual call to stop scanning might be required depending on your situation. Extending Connect and Disconnect Events If you would like to execute custom code on connect and disconnect you can bind to the event dispatchers as required (see below for available dispatchers). Serial and BLE Device in this context means an ION Device.

You may also bind to the connect even yourself to trigger unique "OnConnect" code

Be sure to do the binding prior to calling conect, otherwise the code meant to fire on connect will miss.

For custom created odor assets to be played back on the ION it is important to call at some point during the life cycle of your game the "CSV Multi Upload" function call. Ideally after initial connection with your app and the ION. Otherwise the ION won't know what custom odors you intend to playback during your apps runtime.

Breakpoint is on the CSV Multi Upload Function call, a custom array is made with two odor assets imported into the unreal engine project. Both those custom odor assets will get uploaded to the ION, 6 seconds after initial ION connection.

Using Plugin - Adding Odors

Enhancing your world by adding odors involves three major steps. 1. Adding an olfactory epithelium component (nose) to your VR Pawn.

2. Importing odor assets into your project

3. Adding an odorant component to the actor that needs to generate odor.

1. To add an olfactory epithelial component to your VR Pawn navigate to your VR Pawn actor, click Add Component, search for “Olf” and select “OlfactoryEpithelium”.

It is recommended to add this as a child of your “Camera” component so that the virtual nose (Olfactory Epithelium) is in line with where the actual real human nose will be. In this way sight, sound and smell will all be near the players head. The olfactory epithelium component can be moved in scene to provide an offset or alternative hard setting the desired offset by modifying the components Transform “Location” in the “Details” pane. Below the nose is moved 2 cm on the X axis to move the nose a bit closer to objects seen by the camera.

Finally make sure the “Auto Activate” checkbox of the epithelium component is checked to be sure the nose is enabled. That’s it!

2. To play back specific odors we need to import odor assets (aka .odor files) into our project. Odor Assets can be provided by us or authored using our Digital Scent Studio (DSS) application. By default the core (Odor Assets) will be included with the plugin. You can find them at

All->Plugins->OVR AOS Content -> Odors.

Be sure to have followed the very first step to be able to view the contents of the plugin.

Otherwise to add your own, once you've downloaded or obtained an odor asset, simply drag and drop into unreal to import the odor asset. With the plugin enabled, Unreal will be able to recognize and make use of the file.

3. As covered in step 1 for adding the nose to the VR pawn, adding odor to an actor is similar. Except this time instead of adding an Olfactory Epithelium Component you will add an “Odorant” component.

Once you have an odorant component you will need to provide it with an odor asset as describe earlier by click on the "Odor Asset" section and picking from the existing imported odor assets. Or drag and drop a selected odor asset into this field.

Odor Asset Field with no odor asset selected.

Odor Asset Field with the citrus odor asset selected

As shown above, this odorant component will produce a citrus smell once a nose is in range of smelling it.

Once all three steps are done you will have added an odor to an actor, a nose to your pawn and a config file for a type of smell to produce. In the next section we will cover more details in terms of the parameters and options an odorant component has to offer.

Using Plugin - Odorant Component Configuration

In this section we will cover how to alter the behavior of an odorant component to suit your needs. For those familiar with Unreal’s native Audio Component you will see a lot of similar options, however there are some unique differences which will be covered first.

General Odorant Component Settings

Intensity for odors is what volume is for sound. The Intensity Multiplier can range from 0 (nothing) to 1 (100% max strength).

The Intensity Float is for debugging, it is the final calculated Intensity for that odorant component that can be seen but not altered.

The Odorant Config is what type of odor to have this component produce.

Burst Settings

Burst is a feature that if enabled with “Enable Burst” will have the odorant component expand to its max attenuated fall off in the amount of time set by “Diffusion Time” in seconds. Once it has reached the max, it will shrink or decay in the amount of time set by “Diffusion Decay Time” in seconds. Enabling loop burst will have that "diffusion" and "diffusion decay" time loop. Blueprint exposed function exist for each of these settings so they can be configured at runtime or a burst manually called when desired instead of a loop.

The odorant component is also compatible with Niagara Particle system to have a particle that reaches near the users virtual nose act as a source for the odorant components odor instead of the odorant components world location (by default). In order to use this feature you will need to be familiar with creating Niagara Particle Systems and emitters. Once you have a Niagara Particle system you want to use and you’ve added it as a component to your actor you can set the Odorant Components “Niagara FXName” to the name shown in the blueprint actors component hierarchy.

There is one last thing in order to get your Niagara Particle Effect to be odorized and this requires some setup on the Niagara Particle Effect itself. Inside your Niagara system, on your emitter that you want to emit particle based odor, add an "Export Particle Data to Blueprint" module to the "Particle Update" section of the emitter like so.

Then under the "User Paramters" section click the "+" icon

Then in the search field search for "Object"

It is crucial that the name of the "Object" variable is set as "OVRObject"

Last but not least, go back to the "Export Particle Data to Blueprint" module by clicking on it you will then see this in the "Details" panel.

Under "Export" you will see "Callback Handler Parameter" some of the text might be cut out. Where it says "None" click to open the drop down menu and you should now see the "OVRObject" as an option, click it to set it, it should now look like this. We aren't just done yet, one important thing to note is the "Condition To Export Data", that is currently unchecked in the picture above. That needs to get checked to tell the system when to export the data out. Otherwise no particle position data can be communicated to the odorant component. So you can just check it to have it always export or programmatically turn it on and off to suite your needs and behavior.

Don't forget to use the newly created and prepped Niagara Particle Effect by setting the "Niagara System Asset" on the Niagara component you added to your actor.

Completing all these steps will allow the Odorant Component to find a reference to your Niagara Particle System and set the OVRObject automatically. NOTE: This has only been tested and setup to work with one emitter per system. You can have more emitters but only the 1st one will be tracked/checked.

The following configuration options are options that should be familiar if you’ve ever added audio to an unreal project before.

Just like audio/sound, Odorants/Odors have attenuation settings as well which can be overwritten with “Override Attenuation” or set by creating an “Odor Attenuation” file in the content browser by navigating to “Odors” -> “Odor Attenuation”

Currently the Odorant Component offers…

Attenuation Distance with

• Attenuation Function (Linear, Log, Log Reverse, Inverse, Natural Odor and Custom)

• Attenuation Shape (Sphere, Capsule, Box, Cone)

• Inner Radius

• Falloff Distance

Attenuation Smeller Focus which will cause objects in the users view with a certain configured angle to be more intense in smell than objects outside of users view if enabled.

For more information on attenuation inside Unreal Engine, click here.