Plugin Install and Enabling

How to get started with using the OVR AOS Plugin for Unity

Once you have your Unity project ready to go. Create a Plugins folder inside your project under "Assets" if you don't already have one there.

Copy, cut or clone from git the OVR-Unity-Plugin folder into the Plugins folder.

Because the OVR Plugin makes use of JSON data, the plugin needs Newtonsoft's JSON plugin. Go to Windows -> Package Manager -> Click on the "+" Icon -> Add Package by name.

Add the following "com.unity.nuget.newtonsoft-json" exactly, it is case sensitive. Once you have that in the name field click "Add" It will add all the required dependencies for handling JSON data and everything is good to go. In order to scent enable your project there are a few essential aspects that I will explain below.

1. Adding a single Olfactory Epithelium component (AKA a nose component)

2. Setting up your scene for connecting to the device via BLE

3. Adding 1 or more Odorant components

1. Olfactory Epithelium - The Nose

To add the nose to your game, find the "Main Camera" of your project.

You'll know you are in the right place because you will see an "Audio Listener" component along with the "Camera" component.

You can then click "Add Component" and in the search field type "Olf" to search and find the "Olfactory Epithelium"

Once added you will see this. "Offset" is there to move the nose at an offset relative to its parent game object depending on character geometry or preference.

The reason why we put the nose on the camera is the same reason why Unity puts an Audio Listener on the camera. We bundle up the eyes, the ears and the nose all on one game object so that spatial sensory source can be detected. If you are working on a 2D game or app and don't want to make use of 3D geometry but to just fire a scent on demand then you can put the nose wherever you like as you will just need a reference to it to play a one shot scent for example.

1. Connection Setup

To enable BLE connection with a device you need to add a "Connection Manager" script to a game object, for organizational reasons we will just bundle the "Connection Manager' on the "MainCamera" where we also put our nose earlier. Adding it the same we added the nose except we after clicking "Add Component" we type "Connection Manager" in the search field.

You will then need to add 2 more scripts as you just did and we will also go ahead and add them here. Add the "Odorant Manager" script and the "Message Queue Manager" script. Once you've added all the scripts it should look something like this.

That complete the editor scene setup phase. All that remains is cover how to make use of the "Connection Manager" to actually scan and connect over BLE. There is a quick connect in editor. That can be found under Window -> OVR Quick Connect

That will give you an editor window that looks like this

While running in editor you can click "BLE Scan" to start the scan process and connect to the first ION device found. You can fine the code that runs that under "Plugins -> ovr_unity_plugin" -> Editor -> OVREditorTools

    private void OnGUI()
    {
        
        EditorGUILayout.LabelField("BLE Connect Options", EditorStyles.boldLabel);
        if (GUILayout.Button("BLE Scan"))
        {
            ConnectionManager.instance.bleFirstTime = true;
            ConnectionManager.instance.Init(DeviceState.BLE_STATE, BLEConnectionStyle.SCAN);
        }
        EditorGUI.BeginChangeCheck();
    }

For your project you can do the same thing at runtime whenever and wherever you like.

ConnectionManager.instance.Init(DeviceState.BLE_STATE, BLEConnectionStyle.SCAN")

ATM only BLE_STATE is allowed and SCAN for the connection style. In the future, we will offer more ways to connect to the device such as via OS Pairing through a scan in the operating systems native BLE UI.

1. Odorant Components Explained

Odorant Components are like Audio Components except where audio emits sound, odorant components emit.. well.. odors! They come in a few different flavors. Odorant Sphere Odorant Box Odorant Cone Odorant Particle System Odorant Burst

One thing in common with them all is they will emit an odor, have a field to set an "Odor Asset" and have a slider to change the intensity scalar (from 0 to 1) to adjust how strong the odor will present itself to a human nose (akin to volume with audio).

Note: Odor Assets are .odor files that provide context to the device on what odor to playback. The plugin comes stock with some core odors which can be found under Plugins -> ovr_unity_plugin -> Odors These odors might get updated from time to time so be sure to get the latest version of the plugin. In summary .odor files are to the nose what audio files are to the ears. Go to the "Odorant Components" page shown on the left or by clicking here to learn more about them.